generative-ui

name	generative-ui
description	Generate transient or saved inline chat UI with Alpine/Tailwind controls, outputs, app state, and extensions. Use for knobs, pickers, calculators, dashboards, widgets, or reusable mini-apps.

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).

<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:

<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:

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:

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.