generative-ui

# Generative UI Generative UI is sandboxed Alpine.js HTML rendered inline in chat. It is not a source-code change and does not go through Builder. ## Pick the Lifetime - Use `render-inline-extension` for one-off UI that belongs only in the current chat: knobs, controls, pickers, calculators, temporary charts, and previews. - Use `create-extension` when the UI should be saved, reusable, or visible in the Extensions view. It also renders inline after creation. - Use `show-extension-inline` to reopen a saved extension inside chat. - Use `update-extension` to edit an existing saved extension. ## Inputs From Chat Pass initial values through the action `context` argument. The iframe reads them from `window.slotContext` and can subscribe to changes with `window.onSlotContext(fn)`. ```html <script> Alpine.data("controls", () => ({ threshold: 50, init() { this.threshold = Number(window.slotContext?.threshold ?? 50); window.onSlotContext?.((ctx) => { if (ctx.threshold !== undefined) { this.threshold = Number(ctx.threshold); } }); }, })); </script> ``` ## Outputs To The Agent Use passive output when a control's current value should be visible to the agent on the next turn without requiring a submit click: ```html <input type="range" min="0" max="100" x-model.number="threshold" @input="agentNative.ui.output({ threshold }, { label: 'Threshold' })" /> ``` `agentNative.ui.output(value, opts?)` writes application state at: ```txt inline-ui:<extensionId>:output ``` The id is scoped automatically; the HTML author must not pass it. When the user says "use that value", "apply the current setting", or "run it with the current selection", read the value with: ```ts const output = await readAppState("inline-ui:<id>:output"); ``` The stored payload includes `value`, `updatedAt`, `extensionId`, and `source: "inline-ui"`, plus optional `label`, `context`, or `meta`. Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)` for a visible Apply/Submit button that should send a prompt or selected value into the chat. Pass `{ submit: true }` explicitly for that user-triggered action; extension messages are draft-only otherwise. Never call these helpers from polling, refresh, or error handlers. ## App Data And State - Prefer `appAction(name, params)` for template data and operations. - Use `appFetch(path, options)` only for allowed framework endpoints under `/_agent-native/*`, including application-state reads and writes. - Do not call template `/api/*` routes from generated UI. - Use `dbQuery`/`dbExec` only for known existing SQL tables when no action fits. - Use `extensionFetch` for external APIs through the sandbox proxy and secrets. ## Transient extensionData Boundary For saved extensions, `extensionData` uses the authenticated database-backed extension data API. For transient inline UIs, `extensionData` is host `localStorage`. The agent cannot read it, it does not sync across devices, it does not migrate when a UI is promoted to a saved Extension, and the server does not garbage-collect it. Use it only for throwaway local UI state. For anything the agent or app must observe, use `agentNative.ui.output`, application state through `appFetch`, an `appAction`, or `agentNative.chat.send`. ## Styling Use semantic Tailwind classes so the iframe inherits the parent app theme: - `bg-background`, `text-foreground`, `border-border` - `bg-card`, `text-card-foreground` - `bg-primary`, `text-primary-foreground` - `text-muted-foreground`, `bg-accent` Do not hardcode provider tokens, private data, or internal secrets in generated HTML. Do not call an LLM directly from the iframe; route AI work through the agent chat.