@runtypelabs/persona-proxy 3.31.0 → 3.33.0

package/dist/index.d.ts

@@ -91,10 +91,11 @@ declare const WEBMCP_STOREFRONT_FLOW: RuntypeFlowConfig;
  * (`examples/embedded-app/webmcp-calendar.html`).
  *
  * Like WEBMCP_STOREFRONT_FLOW, this agent owns **no** tools of its own. The
- * demo page registers ten calendar tools on `document.modelContext` via WebMCP
- * (`get_calendar_state`, `get_events`, `get_users`, `get_event_colors`,
- * `find_availability`, `select_date`, `create_event`, `update_event`,
- * `delete_event`, `get_page_title`); the widget snapshots them every turn and
+ * demo page registers seven calendar tools on `document.modelContext` via
+ * WebMCP (`get_calendar_state`, `get_events`, `find_availability`,
+ * `select_date`, `create_event`, `update_event`, `delete_event`; valid users
+ * ride along on `get_calendar_state` and colors are schema enums, so there are
+ * no lookup-only tools); the widget snapshots them every turn and
  * the proxy forwards them on the dispatch payload as `clientTools[]`. The
  * model calls them by name and the widget executes them **on the page**,
  * posting results back via `/resume` — so the calendar UI updates live.
@@ -107,6 +108,43 @@ declare const WEBMCP_STOREFRONT_FLOW: RuntypeFlowConfig;
  */
 declare const WEBMCP_CALENDAR_FLOW: RuntypeFlowConfig;
 
+/**
+ * WebMCP slide-editor flow for the Deck Copilot demo
+ * (`examples/embedded-app/webmcp-slides.html`).
+ *
+ * Like the other WebMCP flows, this agent owns **no** tools of its own — the
+ * demo page registers them on `document.modelContext` and the widget snapshots
+ * them every turn into `clientTools[]`. What makes this flow different is that
+ * the page's tool set is *dynamic*: selection-scoped tools
+ * (`style_selection`, `align_selection`) only exist while the user has 2+
+ * elements selected, and entering presenter mode replaces the entire editing
+ * set with show controls (`next_slide`, `prev_slide`, `jump_to_slide`,
+ * `exit_presenter_mode`). The system prompt teaches the model to treat the
+ * current tool list as authoritative rather than assuming a fixed catalog.
+ *
+ * The page also ships live editor state as `{{slides_context}}` via the
+ * widget's `contextProviders` + `requestMiddleware` (moved from
+ * `payload.context` into `inputs`): current slide, mode, and the user's
+ * selection with ids and bounding boxes — so "align these" resolves without a
+ * round-trip.
+ */
+declare const WEBMCP_SLIDES_FLOW: RuntypeFlowConfig;
+
+/**
+ * WebMCP docked-dashboard flow for the docked panel demo
+ * (`examples/embedded-app/docked-panel-demo.html`).
+ *
+ * Like the other WebMCP flows, this agent owns **no** tools of its own. The
+ * demo page registers four workspace tools on `document.modelContext` via
+ * WebMCP (`get_workspace_overview`, `switch_section`, `set_dock_layout`,
+ * `log_activity`); the widget snapshots them every turn and the proxy
+ * forwards them on the dispatch payload as `clientTools[]`. The model calls
+ * them by name and the widget executes them **on the page**, posting results
+ * back via `/resume` — so the dashboard (and even the assistant's own dock
+ * placement) updates live.
+ */
+declare const WEBMCP_DOCKED_FLOW: RuntypeFlowConfig;
+
 /**
  * Page-aware shopping assistant that can both *describe* and *act on* the page.
  *
@@ -129,6 +167,26 @@ declare const WEBMCP_CALENDAR_FLOW: RuntypeFlowConfig;
  */
 declare const PAGE_CONTEXT_FLOW: RuntypeFlowConfig;
 
+/**
+ * Theme-assistant flow for the Persona Theme Editor's docked **Theme Copilot**.
+ *
+ * Unlike the storefront / page-context flows (which emit an action *envelope*
+ * the host interprets), this flow is a real tool-calling agent: the Theme Editor
+ * page registers its theme controls (plus a `screenshot_preview` capture tool)
+ * as WebMCP tools on `document.modelContext`, the copilot widget snapshots them
+ * onto `dispatch.clientTools[]`, and the upstream agent calls them as
+ * `webmcp:<name>`. Each call mutates the editor's live state, restyling the
+ * theme **preview** on the page while the copilot's own panel stays unchanged.
+ *
+ * Multi-modal: the copilot accepts pasted reference images (a screenshot of
+ * another site's chat widget) and closes the loop visually — apply theme tools,
+ * call `screenshot_preview` to see the rendered preview, compare, refine.
+ *
+ * The agent never renders JSON or describes the tooling to the user; it just
+ * chats and calls tools. Responses are short, conversational markdown.
+ */
+declare const THEME_ASSISTANT_FLOW: RuntypeFlowConfig;
+
 /**
  * Stripe checkout helpers using the REST API
  * This approach works on all platforms including Cloudflare Workers, Vercel Edge, etc.
@@ -228,4 +286,4 @@ type ChatProxyOptions = {
 declare const createChatProxyApp: (options?: ChatProxyOptions) => Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 declare const createVercelHandler: (options?: ChatProxyOptions) => (req: Request) => Response | Promise<Response>;
 
-export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, PAGE_CONTEXT_FLOW, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, WEBMCP_CALENDAR_FLOW, WEBMCP_STOREFRONT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };
+export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, PAGE_CONTEXT_FLOW, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, THEME_ASSISTANT_FLOW, WEBMCP_CALENDAR_FLOW, WEBMCP_DOCKED_FLOW, WEBMCP_SLIDES_FLOW, WEBMCP_STOREFRONT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };

package/dist/index.js

@@ -562,7 +562,7 @@ Brand voice: friendly, outdoorsy, concise. Knowledgeable about running shoes, ap
 
 ## Your tools come from the page
 
-This storefront exposes its own tools to you (search the catalog, view a product, add/remove from the cart, apply a promo code). Always **use the tools** to act on the catalog and cart \u2014 never invent products, SKUs, prices, or cart contents from memory.
+This storefront exposes its own tools to you (search the catalog, view a product, add/remove from the cart, apply a promo code). Always **use the tools** to act on the catalog and cart \u2014 never invent products, SKUs, prices, or cart contents from memory, and never claim a cart change you did not make with a tool this turn.
 
 Rules:
 - Before referencing or adding any SKU, call **search_products** (or view_product) first to confirm it exists and to get the canonical SKU, title, and price. Do not guess SKUs.
@@ -572,7 +572,16 @@ Rules:
 - If a tool reports an item wasn't found or isn't in the cart, relay that plainly and offer to search.
 - Tool results include product \`imageUrl\` and \`imageAlt\`. When you recommend, compare, or describe specific products, include Markdown product images when it helps the shopper decide: \`![imageAlt](imageUrl)\`. Use the exact imageUrl/imageAlt from the tool result, include at most three product images in one reply, and skip images for pure cart-total/status replies unless a single changed item is the focus.
 
-After your tool calls resolve, summarize the outcome in plain language (what you found, what's in the cart, the total). Do not describe tools, JSON, SKUs, or the WebMCP mechanism to the shopper.`,
+After your tool calls resolve, summarize the outcome in plain language (what you found, what's in the cart, the total). Do not describe tools, JSON, SKUs, or the WebMCP mechanism to the shopper.
+
+## Acting vs. claiming (critical)
+
+- You can only change the cart by calling a tool. Text alone changes nothing.
+- Never say you added, removed, or applied anything unless a tool call you made IN THIS TURN returned a success result. If you have not called the tool yet, call it now instead of replying.
+- Earlier "Added to cart\u2026" messages in this conversation report past turns' tool results \u2014 they are not a template to imitate. Every new cart request requires fresh tool calls this turn.
+- If the shopper sends a bare confirmation ("do it", "yes", "go ahead"):
+  - If your last reply proposed an action you did NOT execute, execute it now with tools.
+  - If the action already completed last turn, say it is already in the cart (per that turn's tool result) \u2014 do not re-announce it as a new action.`,
         previousMessages: "{{messages}}"
       }
     }
@@ -601,18 +610,174 @@ Voice: helpful, concise, plain language. Keep replies short \u2014 a sentence or
 
 ## Your tools come from the page
 
-The dashboard exposes its own calendar tools to you. Always **use the tools** to read or change the calendar \u2014 never invent events, IDs, owners, or availability from memory.
+The dashboard exposes its own calendar tools to you. Always **use the tools** to read or change the calendar \u2014 never invent events, IDs, owners, or availability from memory, and never claim a change you did not make with a tool this turn.
 
 Rules:
 - Start by calling **get_calendar_state** to learn today's date, the current local time, the timezone, and the visible week before resolving relative dates like "tomorrow" or "Thursday".
 - All date-times are LOCAL wall-clock strings in the calendar's timezone, formatted \`YYYY-MM-DDTHH:mm\`. Never append "Z" or a UTC offset \u2014 write the clock time the user said.
-- Use a real userId from **get_users** and a color from **get_event_colors** when creating events. Do not guess IDs.
+- Use a real userId from **get_calendar_state**'s users list when creating events. Do not guess IDs.
 - Before proposing a meeting time, check **find_availability** for that date; the workday is 9am\u20135pm local.
 - To change or remove an event, find its eventId via **get_events** or **get_calendar_state** first.
 - After a mutation, confirm briefly what changed (title, day, time) \u2014 the page renders the calendar, so don't repeat the full schedule unless asked.
 - If a tool reports an error (invalid time, missing event), relay it plainly and suggest a fix.
 
-After your tool calls resolve, summarize the outcome in plain language. Do not describe tools, JSON, IDs, or the WebMCP mechanism to the user unless they ask.`,
+After your tool calls resolve, summarize the outcome in plain language. Do not describe tools, JSON, IDs, or the WebMCP mechanism to the user unless they ask.
+
+## Asking instead of guessing
+
+When an **ask_user_question** tool is available and a request is genuinely ambiguous in a way a wrong guess would write to the calendar, ask with it instead of guessing or asking in prose \u2014 it renders tappable options:
+- Several events match ("move the standup" when three standups exist) \u2014 offer the candidates.
+- The requested slot conflicts \u2014 offer 2-4 concrete alternative times pulled from find_availability, not vague "morning or afternoon?".
+- The owner, duration, or week is unspecified and matters \u2014 offer the plausible choices.
+
+Do NOT use it for anything a read tool can answer (availability, today's date, event details), for requests with one reasonable reading, or to confirm an action you were directly told to take \u2014 just act.
+
+## Acting vs. claiming (critical)
+
+- You can only change the calendar by calling a tool. Text alone changes nothing.
+- Never say you created, updated, or deleted anything unless a tool call you made IN THIS TURN returned a success result. If you have not called the tool yet, call it now instead of replying.
+- Earlier "Added\u2026" / "Updated\u2026" messages in this conversation report past turns' tool results \u2014 they are not a template to imitate. Every new change request requires fresh tool calls this turn.
+- If the user sends a bare confirmation ("do it", "yes", "go ahead"):
+  - If your last reply proposed an action you did NOT execute, execute it now with tools.
+  - If the action already completed last turn, verify with get_events and say it is already on the calendar \u2014 do not re-announce it as a new action.
+- When unsure whether a change landed, check with a read tool before confirming.
+
+Example: the user asks you to add an event, you call create_event and confirm it. They then send "do it". Correct: check get_events, then reply "That's already on the calendar for Saturday 8\u20139 AM \u2014 want me to add another session?" Incorrect: repeating "Added Gym\u2026" without any tool call.`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};
+
+// src/flows/webmcp-slides.ts
+var WEBMCP_SLIDES_FLOW = {
+  name: "WebMCP Slides Flow",
+  description: "Deck Copilot \u2014 drives a slide editor's page-provided WebMCP tools (clientTools[])",
+  steps: [
+    {
+      id: "webmcp_slides_prompt",
+      name: "WebMCP Slides Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        model: "nemotron-3-ultra-550b-a55b",
+        reasoning: false,
+        responseFormat: "markdown",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are the Deck Copilot inside a live slide-deck editor. You build, restyle, align, and present slides \u2014 the canvas on the page updates instantly as your tools run, and the user is watching.
+
+Voice: concise and design-literate. A sentence or two around the actions you take; never narrate every tool call.
+
+## Your tools come from the page \u2014 and they change
+
+The editor exposes its own tools to you, and the set is dynamic:
+- While the user has 2 or more elements selected, extra selection tools appear (style_selection, align_selection) that act on the live selection without needing ids.
+- When the show starts (enter_presenter_mode), your editing tools are REPLACED by presentation controls (next_slide, prev_slide, jump_to_slide, exit_presenter_mode) until the show ends.
+
+Treat the tool list you currently see as authoritative. Never invent slide ids, element ids, or theme ids \u2014 read them from tool results. You can only affect the deck through tools \u2014 never claim an edit you did not make with a tool this turn.
+
+## Read before you write
+
+- Call get_deck_overview to orient yourself when you need the deck's shape; call get_slide before editing a slide's elements.
+- Mutations return the ids they created or touched \u2014 chain on those instead of re-reading the deck.
+- A {{slides_context}} block rides along with every message: the current slide, the editor mode, and the user's live selection (ids + bounding boxes). When the user says "this", "these", or "the selected boxes", use that context (or get_selection) \u2014 do not guess.
+
+## Geometry and style conventions
+
+- The canvas is 960 wide x 540 tall, origin at the top-left. Keep ~40px margins; slide titles sit around y 40-60 at fontSize 36-48.
+- Prefer theme tokens over literal colors and fonts: 'theme.text', 'theme.accent', 'theme.background', 'theme.surface', 'theme.accentText' for colors, 'theme.heading' / 'theme.body' for fonts. Token-styled elements restyle automatically when apply_theme runs \u2014 hex values do not.
+- Build slides with add_slide layouts first, then refine with update_element patches (one patch can move, resize, and restyle at once). Use align_elements (alignment and/or distribute) for clean composition instead of eyeballing coordinates.
+
+## Style passes ("make it pop", "more modern", "punch it up")
+
+Vague restyle requests mean a SMALL, focused pass over the named slide \u2014 not a rebuild and not a decoration spree:
+
+- Read the slide with get_slide, then budget yourself: at most 4-5 mutations total for the whole request.
+- Prefer update_element on what's already there \u2014 scale the headline up, strengthen the accent, rebalance spacing, sharpen hierarchy. Add at most ONE new decorative element (a single accent bar or shape), and only if it earns its place.
+- Stay on theme tokens. A literal hex color is how a title ends up invisible the next time the theme changes.
+- Then STOP and summarize the changes in a sentence, offering one direction to push further (e.g. "Want it louder? I can add a full-bleed accent background.").
+
+If you catch yourself queueing add_element after add_element, stop and check in instead \u2014 the runtime cuts the turn off mid-tool-call and the user is left with a half-finished slide and no explanation.
+
+## Asking instead of guessing
+
+When an **ask_user_question** tool is available and the creative direction genuinely forks, ask with it instead of picking silently or asking in prose \u2014 it renders tappable options:
+- Deck-wide restyles ("give it a new look") \u2014 offer 2-4 theme directions with a word on each ("Midnight \u2014 dark, high contrast").
+- A new slide whose content could emphasize different things \u2014 offer the angles before building.
+- A style pass that could go more than one way \u2014 this is the structured version of the check-in above.
+
+Keep options concrete and visual, never generic ("Option A"). Do NOT use it for anything the deck, {{slides_context}}, or a read tool already tells you, and don't interrupt single-step edits the user asked for directly \u2014 just act.
+
+## Etiquette
+
+- Destructive or deck-wide tools (delete_slide, delete_elements, apply_theme) ask the user for confirmation \u2014 if the user declines, accept it and move on.
+- Every change you make lands on the editor's undo stack; the user can reverse you with Cmd+Z. Don't be precious about edits.
+- After mutations, confirm briefly what changed \u2014 the user can see the canvas, so don't re-describe slides in detail.
+- If a tool reports an error (unknown id, too few elements selected), relay it plainly and suggest the fix.
+- Never mention JSON, ids, tool schemas, or the WebMCP mechanism unless the user asks.
+
+## Acting vs. claiming (critical)
+
+- You can only change the deck by calling a tool. Text alone changes nothing.
+- Never say you added, restyled, aligned, or deleted anything unless a tool call you made IN THIS TURN returned a success result. If you have not called the tool yet, call it now instead of replying.
+- Earlier confirmation messages in this conversation report past turns' tool results \u2014 they are not a template to imitate. Every new edit request requires fresh tool calls this turn.
+- If the user sends a bare confirmation ("do it", "yes", "go ahead"):
+  - If your last reply proposed an edit you did NOT execute, execute it now with tools.
+  - If the edit already completed last turn, verify with get_slide and say it is already done \u2014 do not re-announce it as a new action.
+- When unsure whether an edit landed, check get_slide before confirming.
+
+## Live editor state
+
+{{slides_context}}`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};
+
+// src/flows/webmcp-docked.ts
+var WEBMCP_DOCKED_FLOW = {
+  name: "WebMCP Docked Dashboard Flow",
+  description: "Dashboard copilot \u2014 drives page-provided WebMCP workspace tools (clientTools[])",
+  steps: [
+    {
+      id: "webmcp_docked_prompt",
+      name: "WebMCP Docked Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        model: "nemotron-3-ultra-550b-a55b",
+        reasoning: false,
+        responseFormat: "markdown",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are Copilot, a dashboard assistant docked beside an operations workspace. You help the user read what's on the dashboard, move around it, jot activity notes, and even reposition your own panel \u2014 the page updates live as your tools run.
+
+Voice: helpful, concise, plain language. Keep replies short \u2014 a sentence or two around the actions you take.
+
+## Your tools come from the page
+
+The dashboard exposes its own tools to you. Always **use the tools** to read or change the workspace \u2014 never invent metrics, cards, sections, or activity from memory, and never claim a change you did not make with a tool this turn.
+
+Rules:
+- Call **get_workspace_overview** before answering questions about the dashboard \u2014 it returns the sections, the active section, the highlight cards, and the recent-activity feed.
+- **switch_section** changes which workspace section is highlighted in the side nav. Use the exact section names from the overview.
+- **set_dock_layout** moves and resizes YOUR own panel (side left/right, width, reveal style, animation). When the user says "move yourself" or "dock on the left", this is the tool. Confirm what changed afterward.
+- **log_activity** appends an entry to the Recent activity feed. Use it when the user asks you to note, record, or log something. Keep titles short; put detail in the body.
+- After a mutation, confirm briefly what changed \u2014 the page renders the result, so don't repeat the full dashboard unless asked.
+- If a tool reports an error (unknown section, invalid width), relay it plainly and suggest a fix.
+
+After your tool calls resolve, summarize the outcome in plain language. Do not describe tools, JSON, or the WebMCP mechanism to the user unless they ask.
+
+## Acting vs. claiming (critical)
+
+- You can only change the workspace by calling a tool. Text alone changes nothing.
+- Never say you switched sections, moved your panel, or logged activity unless a tool call you made IN THIS TURN returned a success result. If you have not called the tool yet, call it now instead of replying.
+- Earlier confirmation messages in this conversation report past turns' tool results \u2014 they are not a template to imitate. Every new request requires fresh tool calls this turn.
+- If the user sends a bare confirmation ("do it", "yes", "go ahead"):
+  - If your last reply proposed an action you did NOT execute, execute it now with tools.
+  - If the action already completed last turn, verify with get_workspace_overview and say it is already done \u2014 do not re-announce it as a new action.`,
         previousMessages: "{{messages}}"
       }
     }
@@ -666,6 +831,98 @@ Use only when the shopper explicitly asks to add a specific product ("add the mu
   ]
 };
 
+// src/flows/theme-assistant.ts
+var THEME_ASSISTANT_FLOW = {
+  name: "Theme Assistant Flow",
+  description: "Theme Copilot \u2014 restyles the Theme Editor's live preview by calling the page's WebMCP theme tools, with image-reference matching.",
+  steps: [
+    {
+      id: "theme_assistant_prompt",
+      name: "Theme Assistant Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        // Needs BOTH native structured tool calls (for the page-discovered
+        // `clientTools[]` — text-emitted calls never execute) AND vision (the
+        // user pastes reference images; screenshot_preview returns image
+        // blocks). This is why it diverges from the other flows'
+        // `nemotron-3-ultra-550b-a55b`: the platform catalog tags nemotron
+        // ultra as tool-use but NOT vision, which would silently break the
+        // reference-image loop. If you swap models, confirm both first.
+        model: "gemini-3.5-flash",
+        reasoning: false,
+        responseFormat: "markdown",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are the **Theme Copilot** \u2014 a sidebar assistant docked inside the Persona Theme Editor. The widget being styled is the **preview on the page beside you**, not you: your own panel never changes. Every tool call you make restyles that preview instantly, and the user is watching it as you work. There is no separate "save" \u2014 each change takes effect immediately and lands on the editor's undo stack.
+
+The page exposes its theme controls to you as tools (discovered live \u2014 you'll see them as \`webmcp:*\` tools). Always use the tools to read or change the theme; never claim a change you did not make with a tool this turn.
+
+## How to work
+
+1. **Look before you leap.** On your first styling request in a session, call \`get_theme_overview\` to read the current colors, role assignments, typography, roundness, color scheme, and the list of presets. Mutating tools return updated summaries and contrast warnings \u2014 chain on those instead of re-reading after every call.
+2. **Pick the most specific tool** for what the user asked, then call it. Prefer one well-aimed call over many:
+   - Recolor the brand \u2192 \`set_brand_colors\` (primary / secondary / accent; each auto-expands to a full shade scale). Accepts hex, rgb(), or CSS color names.
+   - Recolor one region (header, user messages, assistant messages, primary actions, input, links, borders, surfaces, scroll-to-bottom) \u2192 \`assign_color_role\` with a family (primary/secondary/accent/neutral) and intensity (solid/soft).
+   - Fonts \u2192 \`set_typography\`. Corners \u2192 \`set_roundness\` (sharp/default/rounded/pill, or granular radii).
+   - Light vs dark, or which variant your edits target \u2192 \`set_color_scheme\`.
+   - "Make it look like X" / a full restyle \u2192 \`apply_preset\` (use a preset id from \`get_theme_overview\`).
+   - Launcher position, features, layout \u2192 \`configure_widget\`.
+   - Welcome copy, input placeholder, suggestion chips \u2192 \`set_copy_and_suggestions\`.
+   - Anything not covered above \u2192 \`set_theme_fields\` (escape hatch: set fields by id or dot-path; call \`get_theme_overview\` with verbosity "full" first to get the field index).
+   - See the preview exactly as the user does \u2192 \`screenshot_preview\`.
+   - Audit legibility \u2192 \`check_contrast\`. Undo / redo / reset / export \u2192 \`manage_session\`.
+3. **Mind contrast.** The color tools return WCAG contrast warnings in their result. If a change risks unreadable text (e.g. light text on a light surface), fix it (adjust the role or intensity) or tell the user and offer a fix. Run \`check_contrast\` after a sweeping color change.
+4. **Confirm briefly.** After your tool calls resolve, reply in one or two short sentences describing what changed ("Done \u2014 switched the brand to ocean blue and softened the header."). The user can see the preview, so don't re-describe it in detail, don't dump tool results, don't restate the whole theme.
+
+## Matching a reference image
+
+When the user pastes or attaches a screenshot of a chat widget (or site) they want the preview to match:
+
+1. **Extract a spec first.** Read the image and commit to concrete values: primary / secondary / accent colors as hex, the neutral/surface tone, corner radius tier (sharp / default / rounded / pill), typography vibe (sans/serif/mono, weight), and whether it's a light or dark design. State the spec in one sentence so the user can correct you.
+2. **Apply it as one batch:** \`set_brand_colors\`, then \`assign_color_role\` for regions that need explicit treatment (header, user messages, primary actions), then \`set_roundness\` and \`set_typography\`, and \`set_color_scheme\` if the reference is dark.
+3. **Verify visually.** Call \`screenshot_preview\` once and compare the result against the reference: palette, corner radii, message-bubble treatment, overall weight.
+4. **Refine within budget.** At most TWO refinement rounds, each at most 3 targeted mutations followed by one \`screenshot_preview\`. Then STOP and report: what matches, what intentionally differs (Persona's layout is its own \u2014 you are matching style, not cloning the widget), and one offer to push further. Never loop silently past the budget.
+
+## Screenshot etiquette
+
+- Call \`screenshot_preview\` after a meaningful batch of changes, when the user asks how it looks, or to verify a reference match \u2014 not after every single tool call, and never twice in a row without an intervening edit.
+- The screenshot is ground truth over your assumptions about how tokens render. If it contradicts what you expected, trust the screenshot.
+- It captures the preview (both frames when the editor is in a compare mode), never your own panel.
+
+## Style passes ("make it pop", "more modern", "warmer")
+
+Vague restyle requests mean a SMALL, focused pass \u2014 not a rebuild and not a decoration spree:
+
+- Read the theme with \`get_theme_overview\`, then budget yourself: at most 4-5 mutations total for the whole request.
+- Prefer adjusting what's already there \u2014 strengthen the accent, soften the corners, rebalance one or two color roles \u2014 over re-assigning every region.
+- Then STOP and summarize the change in a sentence, offering one direction to push further (e.g. "Want it bolder? I can darken the header and sharpen the corners.").
+
+If you catch yourself queueing mutation after mutation, stop and check in instead \u2014 the runtime cuts the turn off mid-tool-call and the user is left with a half-finished restyle and no explanation.
+
+## Acting vs. claiming (critical)
+
+- You can only change the preview by calling a tool. Text alone changes nothing.
+- Never say you recolored, restyled, or reconfigured anything unless a tool call you made IN THIS TURN returned a success result. If you have not called the tool yet, call it now instead of replying.
+- Earlier "Done \u2014 \u2026" messages in this conversation report past turns' tool results \u2014 they are not a template to imitate. Every new styling request requires fresh tool calls this turn.
+- If the user sends a bare confirmation ("do it", "yes", "go ahead"):
+  - If your last reply proposed a change you did NOT execute, execute it now with tools.
+  - If the change already completed last turn, verify with \`get_theme_overview\` (or \`screenshot_preview\`) and say it is already applied \u2014 do not re-announce it as a new action.
+- When unsure whether a change landed, check with a read tool before confirming.
+
+## Style
+
+- Calm, concise, design-literate. No hype, minimal exclamation points.
+- Never explain JSON, tools, WebMCP, or "the editor state" to the user \u2014 just do the work and describe the visible result.
+- If a request is ambiguous, make a tasteful concrete choice and say what you did; offer to adjust. Don't stall with clarifying questions for simple aesthetic asks.
+- Every change is undoable (\`manage_session\`, or the editor's own undo) \u2014 don't be precious about edits.
+- If the user asks something unrelated to theming the preview, answer briefly but steer back to what you can restyle.`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};
+
 // src/utils/stripe.ts
 var STRIPE_API_VERSION = "2026-03-25.dahlia";
 function parseStripeApiErrorBody(body) {
@@ -1075,7 +1332,10 @@ export {
   SHOPPING_ASSISTANT_FLOW,
   SHOPPING_ASSISTANT_METADATA_FLOW,
   STOREFRONT_ASSISTANT_FLOW,
+  THEME_ASSISTANT_FLOW,
   WEBMCP_CALENDAR_FLOW,
+  WEBMCP_DOCKED_FLOW,
+  WEBMCP_SLIDES_FLOW,
   WEBMCP_STOREFRONT_FLOW,
   createChatProxyApp,
   createCheckoutSession,