@agent-native/core 0.127.3 → 0.128.1

package/docs/content/template-design-collaboration-and-full-apps.mdx

@@ -11,6 +11,21 @@ Once a prototype is in good shape, this page covers what happens next: pulling i
 
 Design isn't only for prototypes generated from a prompt — a coding agent can install `/visual-edit` to bring a real, already-running local app into Design as its own screens. Each requested path or URL becomes its own screen on the canvas, and a numbered flow (an onboarding step 1, 2, 3) stays as separate ordered screens instead of collapsing into one. The entry route renders before sign-in, and a shared design link works read-only without an account — but saving the layout, generating new screens, or sharing still requires signing in first.
 
+### Keep the canvas beside your chat
+
+When your coding app has an inline browser, ask `/visual-edit` to open the returned Design URL there. In Codex Desktop, that means the built-in Browser; in Claude Code Desktop's Code tab, it means the Browser pane. Both can keep the canvas inside the coding app beside the conversation. In VS Code, the Agent Native extension opens the same Design URL in its side-panel webview. Browser panes can be disabled or unavailable in CLI, remote, or restricted sessions, so `/visual-edit` falls back to an **Open design** link instead of claiming the canvas opened.
+
+Once Design is open, choose **Show/Hide UI** from the `Cmd+K` menu or press `Cmd+Shift+\` on Apple devices / `Ctrl+Shift+\` elsewhere to toggle all editing chrome so only the canvas remains. The same action is available by right-clicking empty canvas space.
+
+These are especially useful canvas sets:
+
+- **A multi-step flow:** `/visual-edit localhost:5173 — cart, shipping, payment, confirmation; open it beside this chat`
+- **Several pages:** `/visual-edit localhost:5173 — home, pricing, docs, and settings`
+- **One page at several sizes:** `/visual-edit localhost:5173/dashboard — desktop, tablet, and mobile side by side`
+- **Several states of one page:** `/visual-edit localhost:5173/inbox — empty, selected, and compose-open states`
+
+The agent keeps named steps in order and places responsive variants in aligned columns, so the canvas reads like a flow or comparison board rather than a pile of screenshots. Name the routes and sizes you care about; requesting every discovered route at every viewport can create a noisy canvas.
+
 <Diagram id="doc-block-design8" title="Three source modes" summary={"A design's source is inline, localhost, or fusion — the mode decides where an edit actually lands."}>
 
 ```html

package/docs/content/toolkit-org-team.mdx

@@ -21,17 +21,21 @@ connections, service tokens, and app switching.
 
 ## Pieces {#pieces}
 
-| Piece                 | Purpose                                                                                         |
-| --------------------- | ----------------------------------------------------------------------------------------------- |
-| `<TeamPage>`          | Standard team management page for members, invites, roles, and organization preferences.        |
-| `<OrgSwitcher>`       | Current organization picker for sidebars and headers.                                           |
-| `<InvitationBanner>`  | One-click invite and domain-match join prompts.                                                 |
-| `<RequireActiveOrg>`  | Guard for pages that need an active organization before rendering app data.                     |
-| `useOrgRole()`        | Shared role booleans for member, invite, settings, and domain controls.                         |
-| Organization handlers | Create, rename, switch, invite, accept, remove, and update roles/domains.                       |
-| Roles                 | Owner, admin, and member gates for sharing, settings, service tokens, and provider connections. |
-| Allowed domains       | Automatic join and domain-scoped access policy.                                                 |
-| App links             | Workspace app-link parsing and visible app-switcher helpers.                                    |
+| Piece                   | Purpose                                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `<TeamPage>`            | Standard team management page for members, invites, roles, and organization preferences.        |
+| `<OrgSwitcher>`         | Current organization picker for sidebars and headers.                                           |
+| `<InvitationBanner>`    | One-click invite and domain-match join prompts.                                                 |
+| `<RequireActiveOrg>`    | Guard for pages that need an active organization before rendering app data.                     |
+| `useOrgRole()`          | Shared role booleans for member, invite, settings, and domain controls.                         |
+| `appRoles` prop         | Adds a per-app role column and picker to `<TeamPage>` from a `defineAppRoles` descriptor.       |
+| `useAppRoles()`         | An app's role vocabulary, its assignments in the active org, and whether the viewer may edit.   |
+| `useAppRole()`          | The current user's role in one app, or `null` when unassigned.                                  |
+| `useSetAppMemberRole()` | Assign or clear one member's app role. Org owner/admin only, enforced server-side.              |
+| Organization handlers   | Create, rename, switch, invite, accept, remove, and update roles/domains.                       |
+| Roles                   | Owner, admin, and member gates for sharing, settings, service tokens, and provider connections. |
+| Allowed domains         | Automatic join and domain-scoped access policy.                                                 |
+| App links               | Workspace app-link parsing and visible app-switcher helpers.                                    |
 
 ## API {#api}
 
@@ -66,12 +70,68 @@ export function AdminOnlyControl() {
 
 Server code imports the same role helpers from `@agent-native/core/org-team`.
 The route plugin mounts `/_agent-native/org/*` for org creation, switching,
-invites, domains, member roles, and A2A secret sync.
+invites, domains, member roles, app roles, and A2A secret sync.
+
+### Per-app roles {#app-roles}
+
+When an app needs its own permission vocabulary on top of team membership,
+declare it with `defineAppRoles` and pass the descriptor to `TeamPage`. The
+descriptor is the serializable half of the declaration — no database imports —
+so the same object can be handed to `defineAppRoles` on the server and to the
+component in the browser bundle:
+
+```tsx
+import {
+  RequireActiveOrg,
+  TeamPage,
+  useAppRole,
+  useAppRoles,
+  useSetAppMemberRole,
+} from "@agent-native/core/client/org-team";
+import { coachRoles } from "../shared/coach-roles";
+
+export function SettingsTeamTab() {
+  return (
+    <RequireActiveOrg>
+      <TeamPage appRoles={coachRoles} />
+    </RequireActiveOrg>
+  );
+}
+
+export function CoachOnlyControl() {
+  const { role } = useAppRole("coach");
+  return role === "coach-admin" ? <button type="button">Archive</button> : null;
+}
+
+export function RoleAdmin() {
+  const { data } = useAppRoles("coach");
+  const setRole = useSetAppMemberRole("coach");
+  if (!data?.canManage) return null;
+  return (
+    <button
+      type="button"
+      onClick={() => setRole.mutate({ email: "dana@acme.com", role: null })}
+    >
+      Clear role
+    </button>
+  );
+}
+```
+
+`role`, `myRole`, and `canManage` are progressive disclosure only. The server
+re-resolves the caller's app role on every guarded operation, and assignment
+edits require the org `owner`/`admin` role regardless of what the client
+believes. See
+[Organizations, Teams & Permissions → App roles](/docs/organizations-teams-permissions#app-roles-per-app-rbac)
+for the role model and [Actions → Authorization](/docs/actions#authorize) for
+the server-side `authorize` guard.
 
 ## UX Standard {#ux-standard}
 
 - Users can see which organization they are in before creating or sharing data.
 - Invites and roles live in the team settings surface, not per-resource dialogs.
+- App-specific roles appear as another column on that same team surface, never
+  as a separate permissions page or a second organization.
 - Org domain changes are owner-only and explain who can auto-join.
 - App switching lists workspace/default app links. Active-org continuity comes
   from the target app sharing the same auth and organization state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.127.3",
+  "version": "0.128.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -327,6 +327,7 @@
     "@assistant-ui/react-markdown": "^0.12.6",
     "@assistant-ui/store": ">=0.2.9 <0.2.14",
     "@assistant-ui/tap": "^0.5.14",
+    "@builder.io/ai-utils": "^0.84.0",
     "@clack/prompts": "^1.4.0",
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/theme-one-dark": "^6.1.3",

package/src/a2a/artifact-response.ts

@@ -50,6 +50,11 @@ const ARTIFACT_IDENTITY_WRITE_TOOLS = new Set([
   "create-deck",
   "duplicate-deck",
   "add-slide",
+  "update-slide",
+  "patch-deck",
+  "save-deck",
+  "import-pptx",
+  "restore-deck-version",
   "update-dashboard",
   "rename-dashboard",
   "save-analysis",
@@ -513,27 +518,43 @@ function addImageArtifact(
   });
 }
 
-function isReadyDeckArtifact(parsed: Record<string, unknown>): boolean {
-  const slideCount = numberValue(parsed.slideCount);
-  if (slideCount !== undefined) return slideCount > 0;
-  if (Array.isArray(parsed.slides)) return parsed.slides.length > 0;
-  return true;
-}
-
 function addDeckArtifact(
   decks: Map<string, CreatedDeckArtifact>,
   parsed: Record<string, unknown>,
-  options: { requireReady: boolean },
 ): void {
   const id = deckIdValue(parsed);
   if (!id) return;
-  if (options.requireReady && !isReadyDeckArtifact(parsed)) return;
   decks.set(id, {
     id,
     url: stringValue(parsed.url) ?? stringValue(parsed.urlPath),
   });
 }
 
+// Deck writes are spread across a dozen actions (create-deck, add-slide,
+// patch-deck, save-deck, update-slide, import-*, restore-deck-version), so a
+// per-tool allow-list refuses a real deck URL every time an action is added.
+// Trust any successful result that names a deck the way the deck routes do: an
+// explicit deckId, or a canonical /deck/<id> URL the action itself returned.
+function addDeckArtifactFromAnyResult(
+  decks: Map<string, CreatedDeckArtifact>,
+  parsed: Record<string, unknown>,
+): void {
+  const url = stringValue(parsed.url) ?? stringValue(parsed.urlPath);
+  const deckId = stringValue(parsed.deckId);
+  if (deckId) {
+    decks.set(deckId, {
+      id: deckId,
+      url:
+        url && artifactUrlReferencesId(url, "deck", deckId) ? url : undefined,
+    });
+  }
+
+  const reference = url ? parseArtifactReferenceUrl(url) : null;
+  if (reference?.kind === "deck") {
+    decks.set(reference.id, { id: reference.id, url });
+  }
+}
+
 function addListedDeckArtifacts(
   decks: Map<string, CreatedDeckArtifact>,
   parsed: Record<string, unknown>,
@@ -543,7 +564,7 @@ function addListedDeckArtifacts(
   for (const item of items) {
     const deck = asRecord(item);
     if (!deck) continue;
-    addDeckArtifact(decks, deck, { requireReady: false });
+    addDeckArtifact(decks, deck);
   }
 }
 
@@ -617,6 +638,8 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
     const parsed = parseToolResultJson(toolResult.result);
     if (!parsed) continue;
 
+    addDeckArtifactFromAnyResult(decks, parsed);
+
     if (toolResult.tool === "save-monitor") {
       const id = stringValue(parsed.id);
       const url = stringValue(parsed.monitorAppUrl);
@@ -711,14 +734,10 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
 
     if (
       toolResult.tool === "create-deck" ||
-      toolResult.tool === "duplicate-deck"
+      toolResult.tool === "duplicate-deck" ||
+      toolResult.tool === "get-deck"
     ) {
-      addDeckArtifact(decks, parsed, { requireReady: true });
-      continue;
-    }
-
-    if (toolResult.tool === "get-deck") {
-      addDeckArtifact(decks, parsed, { requireReady: false });
+      addDeckArtifact(decks, parsed);
       continue;
     }
 
@@ -727,18 +746,6 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
       continue;
     }
 
-    if (toolResult.tool === "add-slide") {
-      const id = stringValue(parsed.deckId);
-      const slideCount = numberValue(parsed.slideCount);
-      if (id && slideCount !== undefined && slideCount > 0) {
-        decks.set(id, {
-          id,
-          url: stringValue(parsed.url) ?? stringValue(parsed.urlPath),
-        });
-      }
-      continue;
-    }
-
     if (
       toolResult.tool === "update-dashboard" ||
       toolResult.tool === "rename-dashboard" ||

package/src/action.ts

@@ -123,6 +123,19 @@ export interface ActionRunContext {
   turnId?: string;
 }
 
+/**
+ * Pre-run authorization gate. Throw to deny with a specific message (the
+ * framework's `ForbiddenError` carries a 403), or return `false` for a generic
+ * denial. Returning `undefined` allows the call — a guard that forgets to
+ * return is therefore permissive, which is why `false` is honoured at all:
+ * `(args) => someCheck(args)` written against a boolean helper would otherwise
+ * pass silently on every denial.
+ */
+export type ActionAuthorize<TArgs> = (
+  args: TArgs,
+  ctx?: ActionRunContext,
+) => void | boolean | Promise<void | boolean>;
+
 export interface AgentActionStopOptions {
   /** Optional stable code surfaced in run metadata and tests. */
   errorCode?: string;
@@ -466,6 +479,30 @@ interface DefineActionWithSchema<
         args: StandardSchemaV1.InferOutput<TSchema>,
         ctx?: ActionRunContext,
       ) => boolean | Promise<boolean>);
+  /**
+   * Authorization gate that runs before `run()` on **every** caller — agent
+   * tool, HTTP, frontend, MCP, A2A, and CLI. It wraps `run` itself rather than
+   * hanging off the action entry, because a flag consulted by the dispatcher
+   * only guards the dispatchers that remember to consult it.
+   *
+   * This is *authorization*, not approval: `needsApproval` asks a human to
+   * bless one call the caller is already allowed to make, while `authorize`
+   * decides whether they are allowed at all. It also does not replace
+   * `accessFilter` / `assertAccess` — those scope which rows a permitted caller
+   * may see; this decides whether the operation is open to them.
+   *
+   * ```ts
+   * import { coachAccess } from "../lib/access.js";
+   *
+   * export default defineAction({
+   *   description: "Archive a training plan.",
+   *   schema,
+   *   authorize: coachAccess.requireAny("coach-admin"),
+   *   run: async (args) => { ... },
+   * });
+   * ```
+   */
+  authorize?: ActionAuthorize<StandardSchemaV1.InferOutput<TSchema>>;
   /**
    * Audit-log configuration. **Default-on for mutating actions** — you only
    * need this to tune capture: declare the mutated `target` (so the change
@@ -556,6 +593,9 @@ interface DefineActionWithParams<
         args: InferParams<TParams>,
         ctx?: ActionRunContext,
       ) => boolean | Promise<boolean>);
+  /** Pre-run authorization gate applied to every caller. See the schema
+   *  overload above for full semantics. */
+  authorize?: ActionAuthorize<InferParams<TParams>>;
   /** Audit-log configuration (default-on for mutations). See the schema
    *  overload above and the `audit-log` skill. */
   audit?: ActionAuditConfig;
@@ -714,12 +754,21 @@ export function defineAction(options: any) {
     );
   }
 
+  // Authorization sits INSIDE input validation, so a gate that inspects `args`
+  // is handed the parsed, coerced value its type promises rather than whatever
+  // shape the caller sent. Putting it outside would have every guard reading
+  // attacker-shaped input while typed as though it were validated.
+  const guardedRun =
+    typeof options.authorize === "function"
+      ? wrapRunWithAuthorize(options.run, options.authorize)
+      : options.run;
+
   // Wrap run() with INPUT validation when schema is provided.
   // Pass toolParameters so the validation error can echo the expected signature
   // (required vs optional fields) and help the caller self-correct.
   const inputValidatedRun = hasSchema
-    ? wrapWithValidation(options.schema, options.run, toolParameters)
-    : options.run;
+    ? wrapWithValidation(options.schema, guardedRun, toolParameters)
+    : guardedRun;
 
   // Then wrap with OUTPUT validation when an outputSchema is provided. This
   // composes AROUND the input-validated run so the order is: validate input →
@@ -877,6 +926,38 @@ export function defineAction(options: any) {
   };
 }
 
+/**
+ * Wrap an action's run with its `authorize` gate.
+ *
+ * The gate is applied here, around `run`, rather than exposed as a flag on the
+ * action entry: `run` is the one thing all six dispatch sites (agent loop, HTTP
+ * route, frontend, MCP, A2A, CLI) go through, so there is no caller that can
+ * reach the body without passing the check. `needsApproval` took the flag route
+ * and is consequently honoured only inside the agent loop.
+ *
+ * Composed so the full order is: validate input → authorize → run → validate
+ * output → audit. The audit wrapper is outermost, so a denial is still recorded
+ * as an attempt — which is precisely what an audit trail is for.
+ *
+ * A guard that throws denies with its own message. A guard that returns `false`
+ * denies generically. Anything else — including `undefined` — allows.
+ */
+function wrapRunWithAuthorize(
+  run: (args: any, ctx?: ActionRunContext) => any,
+  authorize: ActionAuthorize<any>,
+): (args: any, ctx?: ActionRunContext) => Promise<any> {
+  return async function authorizedRun(args: any, ctx?: ActionRunContext) {
+    const verdict = await authorize(args, ctx);
+    if (verdict === false) {
+      const err = new Error("Not authorized") as Error & { statusCode: number };
+      err.name = "ForbiddenError";
+      err.statusCode = 403;
+      throw err;
+    }
+    return run(args, ctx);
+  };
+}
+
 /**
  * Wrap an action's (already input/output-validated) run so each call records an
  * audit event after it resolves — on success and on error. Best-effort: the

package/src/chat-threads/store.ts

@@ -159,9 +159,6 @@ async function ensureTable(): Promise<void> {
           "chat_thread_shares_resource_idx",
           CHAT_THREAD_SHARES_RESOURCE_INDEX_SQL,
         );
-        // One-time backfill of message_count for legacy rows written before
-        // the column was maintained.
-        await backfillLegacyMessageCounts(client);
         return;
       }
 
@@ -221,15 +218,6 @@ async function ensureTable(): Promise<void> {
           // Index already exists or the dialect rejected a duplicate.
         }
       }
-      // One-time backfill of message_count for legacy rows written before
-      // the column was maintained. The list/summary path now reads
-      // message_count directly (instead of re-parsing the thread_data blob)
-      // and filters on `message_count > 0`, so any legacy row that has
-      // messages but a stale `message_count = 0` would otherwise vanish from
-      // the sidebar. Recompute the count from thread_data and persist it so
-      // the hot path can stay blob-free. Idempotent: only touches rows where
-      // the count is still 0 but the blob clearly contains a messages array.
-      await backfillLegacyMessageCounts(client);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;
@@ -240,28 +228,47 @@ async function ensureTable(): Promise<void> {
 }
 
 /**
- * Recompute `message_count` from `thread_data` for legacy rows that still
- * have a stale `message_count = 0` despite carrying a messages array in the
- * blob. Without this, dropping the `thread_data` payload (and the
- * `OR thread_data LIKE '%"messages"%'` filter) from the list path would make
- * those rows disappear from the sidebar. Runs once at table bootstrap and is
- * idempotent — after the first pass no row matches the WHERE clause again.
+ * Explicitly repair `message_count` for legacy rows written before the count
+ * was maintained. This must never run from table/bootstrap initialization:
+ * serverless isolates would each scan the full `thread_data` blob column on
+ * cold start. Operators may invoke it once when upgrading an old database.
  */
-async function backfillLegacyMessageCounts(
-  client: ReturnType<typeof getDbExec>,
-): Promise<void> {
-  const { rows } = await client.execute({
-    sql: `SELECT id, thread_data, message_count FROM chat_threads WHERE message_count = 0 AND thread_data LIKE '%"messages"%'`,
-    args: [],
-  });
-  for (const r of rows) {
-    const count = deriveMessageCount(r.thread_data, 0);
-    if (count <= 0) continue;
-    await client.execute({
-      sql: `UPDATE chat_threads SET message_count = ? WHERE id = ? AND message_count = 0`,
-      args: [count, r.id as string],
+export async function repairLegacyChatThreadMessageCounts(
+  options: {
+    batchSize?: number;
+  } = {},
+): Promise<{ scanned: number; updated: number }> {
+  await ensureTable();
+  const client = getDbExec();
+  const batchSize = Math.max(1, Math.min(options.batchSize ?? 100, 1_000));
+  let afterId = "";
+  let scanned = 0;
+  let updated = 0;
+  while (true) {
+    const { rows } = await client.execute({
+      sql: `SELECT id, thread_data, message_count FROM chat_threads
+            WHERE message_count = 0
+              AND thread_data LIKE '%"messages"%'
+              AND id > ?
+            ORDER BY id
+            LIMIT ?`,
+      args: [afterId, batchSize],
     });
+    if (rows.length === 0) break;
+    for (const row of rows) {
+      afterId = String(row.id);
+      scanned++;
+      const count = deriveMessageCount(row.thread_data, 0);
+      if (count <= 0) continue;
+      const result = await client.execute({
+        sql: `UPDATE chat_threads SET message_count = ? WHERE id = ? AND message_count = 0`,
+        args: [count, afterId],
+      });
+      if (result.rowsAffected > 0) updated++;
+    }
+    if (rows.length < batchSize) break;
   }
+  return { scanned, updated };
 }
 
 function generateId(): string {
@@ -407,8 +414,8 @@ function rowToThread(r: Record<string, unknown>): ChatThread {
 
 function rowToSummary(r: Record<string, unknown>): ChatThreadSummary | null {
   // The summary path never loads `thread_data`; the count comes from the
-  // dedicated `message_count` column (maintained on write, backfilled for
-  // legacy rows at bootstrap). Empty threads are filtered out of the list.
+  // dedicated `message_count` column maintained on write. Empty threads are
+  // filtered out of the list.
   const messageCount = Number(r.message_count);
   if (!Number.isFinite(messageCount) || messageCount <= 0) return null;
   return {
@@ -475,9 +482,8 @@ const THREAD_COLUMNS = `id, owner_email, title, preview, thread_data, message_co
 // message-history JSON blob and selecting it for every row turns "open the
 // sidebar" into "download every conversation". The summary derives nothing
 // from the blob anymore — preview and message_count are dedicated columns
-// (message_count is maintained on write and backfilled for legacy rows at
-// bootstrap). The detail path (`THREAD_COLUMNS` / `getThread`) still returns
-// the full blob.
+// (message_count is maintained on write). The detail path (`THREAD_COLUMNS` /
+// `getThread`) still returns the full blob.
 const SUMMARY_COLUMNS = `id, title, preview, message_count, created_at, updated_at, scope_type, scope_id, scope_label, pinned_at, archived_at, org_id, visibility`;
 
 export function registerChatThreadsShareable(): void {
@@ -684,10 +690,9 @@ export async function listThreads(
   const limit = opts.limit ?? 50;
   const offset = opts.offset ?? 0;
   const client = getDbExec();
-  // `message_count > 0` is the authoritative "has messages" signal: it is
-  // maintained on every write and backfilled for legacy rows at bootstrap,
-  // so the old `OR thread_data LIKE '%"messages"%'` substring scan over the
-  // full blob is no longer needed here.
+  // `message_count > 0` is the authoritative "has messages" signal maintained
+  // on every write, so the old `OR thread_data LIKE '%"messages"%'` substring
+  // scan over the full blob is no longer needed here.
   const access = chatThreadAccessSql(
     ownerEmail,
     opts.orgId ?? getRequestOrgId(),
@@ -731,9 +736,9 @@ export async function searchThreads(
   await ensureTable();
   const client = getDbExec();
   const pattern = `%${escapeLike(query)}%`;
-  // The count-guard uses the maintained/backfilled `message_count` column
-  // (same as listThreads). The content match still scans `thread_data` —
-  // search legitimately needs to look inside message history.
+  // The count-guard uses the maintained `message_count` column (same as
+  // listThreads). The content match still scans `thread_data` — search
+  // legitimately needs to look inside message history.
   const access = chatThreadAccessSql(
     ownerEmail,
     options.orgId ?? getRequestOrgId(),

package/src/cli/skills-content/design-visual-edit-skill.ts

@@ -25,6 +25,32 @@ hosted Design MCP connector together. The open Skills CLI path
 (\`npx skills@latest add BuilderIO/agent-native --skill visual-edit\`) installs
 exported instructions only, with no MCP connector registration.
 
+## Put Design Beside The Chat
+
+After \`open-visual-edit\` returns \`openUrl\`, open that URL in the coding host's
+inline browser when one is available. This is the preferred working surface:
+the user can keep Design's canvas beside the conversation, inspect the same
+screens as the agent, and iterate without switching apps.
+
+- In Codex Desktop, use the in-app Browser tool to open \`openUrl\`. The built-in
+  browser is the right surface for localhost and public pages that should stay
+  inside the app.
+- In Claude Code Desktop's Code tab, open or preview \`openUrl\` in the Browser
+  pane. Ask Claude to preview it rather than opening the system browser.
+- In VS Code, use the Agent Native Design webview/deep link described below.
+- Inline browser availability is host-dependent. CLI, remote, or restricted
+  sessions may not expose one. If the inline surface is unavailable or disabled,
+  return the normal **Open design** link instead of claiming it opened.
+
+Prefer the host's browser/preview tool over telling the user to press a keyboard
+shortcut. Keep the canvas pane beside chat when the host supports rearrangeable
+panes.
+
+Inside Design, use **Show/Hide UI** from the \`Cmd+K\` menu or press
+\`Cmd+Shift+\\\` on Apple platforms / \`Ctrl+Shift+\\\` elsewhere to toggle all
+editing chrome so only the canvas remains. The same action is available from
+Design's empty-canvas context menu.
+
 ## Core Model
 
 - Each screen is a URL-backed iframe, not copied HTML.
@@ -54,6 +80,23 @@ exported instructions only, with no MCP connector registration.
   \`localhost:1234/onboarding/1\` means
   \`http://localhost:1234/onboarding/1\`.
 
+## Useful Canvas Sets
+
+Translate the user's requested review into the smallest useful set of frames:
+
+- **Multi-step flow:** one ordered frame per route or query state, such as cart,
+  shipping, payment, and confirmation.
+- **Multiple pages:** one frame per meaningful route, such as home, pricing,
+  docs, and account settings.
+- **Responsive comparison:** repeat the same route at the requested desktop,
+  tablet, and mobile viewports so they align in one row.
+- **State review:** repeat a route for meaningful URL-addressable states such as
+  empty, loading, error, modal-open, or selected-item views.
+
+Do not expand every discovered route or every viewport unless the user asks for
+an exhaustive audit. Preserve the user's labels and sequence so the canvas reads
+like the workflow they described.
+
 ## Select And Reprompt
 
 When a chat message begins with \`[Reprompt selection]\`, the selected subtree is
@@ -275,9 +318,9 @@ Fallback, only when \`open-visual-edit\` is unavailable:
 ## Open The Design Surface
 
 - Use the \`link\`, \`deepLink\`, or MCP App embed returned by Design actions so
-  the user sees the canvas. In Codex Desktop or VS Code, prefer opening that
-  Design URL in the available preview/webview panel; otherwise surface the
-  "Open design" link.
+  the user sees the canvas. Follow **Put Design Beside The Chat**: prefer the
+  host's inline Browser, preview, or webview panel; otherwise surface the
+  **Open design** link.
 - Return or open the \`openUrl\` / action link, not a hand-built
   \`/design/:id?_session=...\` URL.
 - If the user is working in VS Code, the Agent Native extension can open the