feat(widget): embeddable, brandable chat widget — one script tag from pipeline to production chat on any website

[nihalnihalani]

Problem Statement

A finished RocketRide pipeline cannot become something an end user touches. The engine already generates a public chat surface per pipeline — the chat source node publishes {host}/chat?auth={public_auth} with a public auth key deliberately separated from the private token — but the only consumer of that surface is the standalone chat-ui app. There is no way to put that conversation on your own website: no embed snippet, no web component, no theming, no floating chat bubble.

This is the conversion moment where competitors win:

• Flowise ships flowise-embed — a fully brandable widget that is arguably its main distribution channel.
• Langflow has an embeddable chat web component in its Share pane; Dify publishes a chat widget/iframe alongside the API on every app; n8n embeds its Chat Trigger UI; Zapier sells Chatbots as a product.
• The sharpest 2026 signal: OpenAI retired its visual Agent Builder but kept ChatKit — packaged chat frontends are the table stakes that survive.

A July 2026 competitive review of this repo rated the embeddable widget a P0 ecosystem gap ("the number-one way teams ship an AI pipeline to users is dropping a chat widget on a site"). It also compounds recent upstream work: server-side deployments (cron/on-demand) landed, so pipelines now run persistently — but still have no end-user front door.

Proposed Solution

A framework-agnostic, brandable chat widget, distributed as a single-file bundle:

1. Web component — <rocketride-chat engine-url="https://…" auth="<public_auth>"> (custom element, shadow DOM for style isolation). Renders inline wherever it's placed. Connects over the existing WebSocket protocol by reusing the browser-compatible TypeScript SDK (exactly how chat-ui connects today, with the public auth key — never the API key or private token).

2. One-script floating bubble — the classic embed for non-developers:

<script src="https://…/rocketride-chat.js"
        data-engine-url="https://engine.example.com:5565"
        data-auth="PUBLIC_AUTH_KEY"
        data-title="Ask our docs"
        data-accent="#5f2167"
        data-position="bottom-right" defer></script>

launcher bubble → opens the same web component in a panel.

3. Branding/theming — attributes + CSS custom properties: accent color, title, welcome message, placeholder, launcher position, light/dark, host-page font opt-in. No iframe; shadow DOM keeps host CSS out and widget CSS in.

4. Streaming-ready — renders live status/"thinking" updates the protocol already delivers, and picks up token streaming transparently when the engine ships it (#1578 review noted the plumbing landed).

5. Security posture — public_auth only; README states plainly that the API key and private token must never appear in a page; document CORS/TLS expectations for exposing an engine to browsers.

Packaging: a new workspace package (e.g. packages/chat-widget) building a single ESM/IIFE bundle; demo page + docs with copy-paste snippets.

Alternatives Considered

• iframe the existing /chat page — works today but can't be branded, sized, or composed into a product page; no bubble mode; iframe UX (focus, scroll, mobile keyboards) is notoriously poor for chat.
• Tell users to build on the TS SDK — that's the status quo; every team rebuilds the same widget.
• React component library — excludes every non-React site; a web component wraps trivially into React/Vue anyway.

Affected Modules

• New package (chat widget) — additive
• server / engine — no changes (uses the existing public-auth chat protocol)
• docs

Acceptance Criteria

• <rocketride-chat> custom element connects to a pipeline with engine-url + public auth, sends questions, renders answers and live status updates.
• Script-tag bubble mode with data-* config; both modes from one bundle.
• Theming via attributes/CSS custom properties (accent, title, welcome, placeholder, position, light/dark); shadow-DOM isolated.
• Unit tests (jsdom, mocked client) for config parsing, theming, message flow, error/reconnect states; protocol-level test against a real engine.
• Demo page + embed documentation with security guidance (public_auth only).
• No modifications to existing apps/packages beyond workspace registration.

Happy to implement — PR to follow shortly.

[github-actions]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[nihalnihalani]

Implementation is up in #1586 — all acceptance criteria covered: both consumption modes from one ~72 KB React-free bundle, live-updating theming attributes + --rr-* CSS custom properties, shadow-DOM isolation, the escape-first safe renderer, jsdom test suite (112 tests incl. the XSS corpus), demo page, and docs with the public-key-only security guidance.

Verification highlights: three independent XSS audits against the built bundle (implementation suite + devil's-advocate's 35+ fresh fixtures + verifier's DOM-parsed payloads — all inert); two live end-to-end runs where the built widget connected to a real engine (published ghcr image AND an engine built from develop) using only the pipeline's public pk_ key, sent a question, and received the answer; and a browser visual check of both modes including the error+Retry state.

Together with the deployments subsystem this completes the publish story: deploy a pipeline server-side, drop one script tag on a site.