@agent-native/core 0.127.3 → 0.128.1

package/corpus/templates/design/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/corpus/templates/design/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/design/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

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

package/corpus/templates/design/.generated/bridge/editor-chrome.generated.ts

@@ -3177,17 +3177,19 @@ export const editorChromeBridgeScript: string = `"use strict";
           // Cmd/Ctrl+R rename / Cmd/Ctrl+Shift+R paste-to-replace (onRename /
           // onPasteToReplace) — both live under bare primary+r.
           "r",
-          // Cmd/Ctrl+\\ — toggle UI (onToggleUi).
-          "\\\\"
+          // Cmd/Ctrl+K — open the host command menu even while the iframe has
+          // focus. DesignEditor routes this chord to openCommandMenu().
+          "k"
         ].indexOf(normalized) !== -1 || e.code === "Digit1" || e.code === "Digit2" || key === "1" || key === "2" || // Cmd/Ctrl+Shift+H / +L — toggle hidden / toggle locked
         // (onToggleHidden / onToggleLocked). Gated on shiftKey so bare
         // Cmd+H / Cmd+L — common OS "Hide app" / browser "focus address bar"
         // shortcuts the host has no bare-primary binding for — are left
         // alone (see useDesignHotkeys.ts: both require event.shiftKey).
-        e.shiftKey && (normalized === "h" || normalized === "l") || // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
+        e.shiftKey && (normalized === "h" || normalized === "l") || // Cmd/Ctrl+Shift+\\ — minimize UI (onToggleUi). Keep the Shift gate
+        // here so the iframe never intercepts a desktop host's bare Cmd/Ctrl+\\.
+        e.shiftKey && normalized === "\\\\" || // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
         // (onDetachInstance / onCreateComponent). Gated on altKey so bare
-        // Cmd+B / Cmd+K are left alone — the host has no bare-primary
-        // binding for either.
+        // Cmd+B is left alone — the host has no bare-primary binding for it.
         e.altKey && (normalized === "b" || normalized === "k") || // Ctrl+Alt+H / Ctrl+Alt+T — distribute horizontal / tidy up
         // (onDistributeSelection / onTidyUp). useDesignHotkeys.ts keeps these
         // on LITERAL Control on every platform (never remapped to Cmd), so

package/corpus/templates/design/_gitignore

@@ -8,8 +8,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/design/app/components/design/CanvasContextMenu.tsx

@@ -52,7 +52,7 @@ import type { CanvasLayerHitCandidate } from "./types";
 // EMPTY canvas (no selection):
 //   Paste here
 //   [sep]
-//   Show/Hide UI ⌘\ · Show/Hide comments ⇧C
+//   Show/Hide UI ⇧⌘\ · Show/Hide comments ⇧C
 //
 // Real Figma has no Duplicate/Delete/Select-all/Zoom items on either canvas
 // menu (all keyboard-only there) — those are intentionally NOT rendered here
@@ -461,7 +461,7 @@ const DEFAULT_SHORTCUTS: CanvasContextMenuShortcuts = {
   rotateClockwise: "",
   flipHorizontal: "⇧H",
   flipVertical: "⇧V",
-  toggleUi: "⌘\\",
+  toggleUi: "⇧⌘\\",
   toggleComments: "⇧C",
 };
 

package/corpus/templates/design/app/components/design/bridge/editor-chrome.bridge.ts

@@ -4672,8 +4672,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
           // Cmd/Ctrl+R rename / Cmd/Ctrl+Shift+R paste-to-replace (onRename /
           // onPasteToReplace) — both live under bare primary+r.
           "r",
-          // Cmd/Ctrl+\ — toggle UI (onToggleUi).
-          "\\",
+          // Cmd/Ctrl+K — open the host command menu even while the iframe has
+          // focus. DesignEditor routes this chord to openCommandMenu().
+          "k",
         ].indexOf(normalized) !== -1 ||
         e.code === "Digit1" ||
         e.code === "Digit2" ||
@@ -4685,10 +4686,12 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         // shortcuts the host has no bare-primary binding for — are left
         // alone (see useDesignHotkeys.ts: both require event.shiftKey).
         (e.shiftKey && (normalized === "h" || normalized === "l")) ||
+        // Cmd/Ctrl+Shift+\ — minimize UI (onToggleUi). Keep the Shift gate
+        // here so the iframe never intercepts a desktop host's bare Cmd/Ctrl+\.
+        (e.shiftKey && normalized === "\\") ||
         // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
         // (onDetachInstance / onCreateComponent). Gated on altKey so bare
-        // Cmd+B / Cmd+K are left alone — the host has no bare-primary
-        // binding for either.
+        // Cmd+B is left alone — the host has no bare-primary binding for it.
         (e.altKey && (normalized === "b" || normalized === "k")) ||
         // Ctrl+Alt+H / Ctrl+Alt+T — distribute horizontal / tidy up
         // (onDistributeSelection / onTidyUp). useDesignHotkeys.ts keeps these

package/corpus/templates/design/app/components/design/keyboard-shortcuts.ts

@@ -142,7 +142,7 @@ export const DESIGN_SHORTCUTS: readonly DesignShortcutDefinition[] = [
   shortcut({
     id: "toggle-ui",
     category: "view",
-    bindings: ["$mod+\\"],
+    bindings: ["$mod+shift+\\"],
     labelKey: "designEditor.keyboardShortcuts.commands.toggleUi",
     handler: "onToggleUi",
   }),

package/corpus/templates/design/app/hooks/useDesignHotkeys.ts

@@ -203,8 +203,8 @@ export interface UseDesignHotkeysProps {
    * modifiers held) or SHIFT_TOOL_SHORTCUTS (which has no "a" entry).
    */
   onAddAutoLayout?: DesignHotkeyHandler;
-  /** Figma's Cmd+\ — toggle Show/Hide UI (left rail, right panel, bottom
-   *  toolbar chrome). */
+  /** Figma's Cmd/Ctrl+Shift+\ "Minimize UI" shortcut, applied here to the
+   *  full Design chrome (left rail, right panel, and bottom toolbar). */
   onToggleUi?: DesignHotkeyHandler;
   /** Figma's Shift+C — toggle Show/Hide comments (comment pins). */
   onToggleComments?: DesignHotkeyHandler;
@@ -725,8 +725,14 @@ export function handleDesignHotkey(
     return run(props.onAddAutoLayout);
   }
 
-  // Figma: Cmd+\ — Show/Hide UI (empty-canvas context-menu item).
-  if (primary && key === "\\") {
+  // Figma's "Minimize UI" chord avoids the bare Cmd+\ shortcut that desktop
+  // coding hosts can reserve for closing their focused pane.
+  if (
+    isPlatformPrimaryModifier(event) &&
+    !event.altKey &&
+    event.shiftKey &&
+    key === "\\"
+  ) {
     return run(props.onToggleUi);
   }
 

package/corpus/templates/design/app/i18n-data.ts

@@ -1422,6 +1422,7 @@ const enUS = {
     figmaParsingTitle: "Starting Builder DSI indexing...",
     figmaParsingDescription:
       "Builder will extract tokens, components, assets, and usage guidance",
+    figmaDecodeFailed: "Decoding failed: {{error}}",
     uploadFig: "Connect Figma with a .fig file",
     figmaSaveLocalCopy:
       "Upload a local copy from Figma: File -> Save local copy",
@@ -1891,6 +1892,7 @@ const designLocaleOverrides = {
         "通过 Builder DSI 连接 Figma、代码和可选的 design.md 指引。上下文越多，代理得到的系统越准确。",
       figmaParsingTitle: "正在启动 Builder DSI 索引...",
       figmaParsingDescription: "Builder 会提取令牌、组件、资产和使用指引",
+      figmaDecodeFailed: "解码失败：{{error}}",
       uploadFig: "连接 Figma .fig 文件",
       figmaSaveLocalCopy: "上传 Figma 本地副本：File -> Save local copy",
       websiteUrl: "网站URL",
@@ -2295,6 +2297,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Iniciando indexación de Builder DSI...",
       figmaParsingDescription:
         "Builder extraerá tokens, componentes, recursos y guía de uso.",
+      figmaDecodeFailed: "Error al decodificar: {{error}}",
       uploadFig: "Conectar Figma con un archivo .fig",
       figmaSaveLocalCopy:
         "Sube una copia local de Figma: File -> Save local copy",
@@ -2720,6 +2723,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Démarrage de l’indexation Builder DSI...",
       figmaParsingDescription:
         "Builder extraira les jetons, composants, ressources et consignes d’utilisation",
+      figmaDecodeFailed: "Échec du décodage : {{error}}",
       uploadFig: "Connecter Figma avec un fichier .fig",
       figmaSaveLocalCopy:
         "Importez une copie locale Figma : File -> Save local copy",
@@ -3145,6 +3149,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Builder-DSI-Indizierung wird gestartet...",
       figmaParsingDescription:
         "Builder extrahiert Tokens, Komponenten, Assets und Nutzungsanweisungen",
+      figmaDecodeFailed: "Dekodierung fehlgeschlagen: {{error}}",
       uploadFig: "Figma mit einer .fig-Datei verbinden",
       figmaSaveLocalCopy:
         "Lade eine lokale Figma-Kopie hoch: File -> Save local copy",
@@ -3570,6 +3575,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Builder DSI のインデックス作成を開始しています...",
       figmaParsingDescription:
         "Builder がトークン、コンポーネント、アセット、利用ガイドを抽出します",
+      figmaDecodeFailed: "デコードに失敗しました: {{error}}",
       uploadFig: "Figma .fig ファイルを接続",
       figmaSaveLocalCopy:
         "Figma のローカルコピーをアップロード: File -> Save local copy",
@@ -3990,6 +3996,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Builder DSI 색인 생성을 시작하는 중...",
       figmaParsingDescription:
         "Builder가 토큰, 컴포넌트, 자산, 사용 지침을 추출합니다",
+      figmaDecodeFailed: "디코딩에 실패했습니다: {{error}}",
       uploadFig: "Figma .fig 파일 연결",
       figmaSaveLocalCopy: "Figma 로컬 사본 업로드: File -> Save local copy",
       websiteUrl: "웹사이트 URL",
@@ -4404,6 +4411,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Iniciando indexação do Builder DSI...",
       figmaParsingDescription:
         "Builder extrairá tokens, componentes, recursos e orientações de uso",
+      figmaDecodeFailed: "Falha na decodificação: {{error}}",
       uploadFig: "Conectar Figma com um arquivo .fig",
       figmaSaveLocalCopy:
         "Envie uma cópia local do Figma: File -> Save local copy",
@@ -4824,6 +4832,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "Builder DSI indexing शुरू की जा रही है...",
       figmaParsingDescription:
         "Builder टोकन, कंपोनेंट, एसेट और उपयोग मार्गदर्शन निकालेगा",
+      figmaDecodeFailed: "डिकोडिंग विफल: {{error}}",
       uploadFig: "Figma .fig फ़ाइल कनेक्ट करें",
       figmaSaveLocalCopy: "Figma स्थानीय कॉपी अपलोड करें: File -> Save local copy",
       websiteUrl: "वेबसाइट URL",
@@ -5234,6 +5243,7 @@ const designLocaleOverrides = {
       figmaParsingTitle: "جارٍ بدء فهرسة Builder DSI...",
       figmaParsingDescription:
         "سيستخرج Builder الرموز والمكونات والأصول وإرشادات الاستخدام",
+      figmaDecodeFailed: "فشل فك الترميز: {{error}}",
       uploadFig: "ربط Figma بملف .fig",
       figmaSaveLocalCopy: "حمّل نسخة Figma محلية: File -> Save local copy",
       websiteUrl: "موقع URL",

package/corpus/templates/design/app/lib/builder-design-system-upload.ts

@@ -0,0 +1,280 @@
+import { appApiPath } from "@agent-native/core/client/api-path";
+
+// GCS resumable uploads require every chunk except the last to be a multiple
+// of 256 KiB. 16 MiB is the recommended default and keeps very large `.fig`
+// files off a single request body (the serverless host caps bodies well below
+// Figma export sizes).
+const GCS_CHUNK_SIZE = 16 * 1024 * 1024;
+const MAX_CHUNK_RETRIES = 5;
+
+interface UploadSlot {
+  idx: number;
+  uploadUrl: string;
+  uploadToken: string;
+}
+
+export interface BuilderIndexResult {
+  designSystemId: string;
+  localDesignSystemId?: string;
+  builderUrl?: string;
+  suggestedTitle?: string | null;
+  status?: string;
+  uploadedFileCount?: number;
+  [key: string]: unknown;
+}
+
+async function readJson(res: Response): Promise<any> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+async function requestUploadSlots(files: File[]): Promise<UploadSlot[]> {
+  const res = await fetch(appApiPath("/api/design-system-upload-start"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      attachments: files.map((file) => ({
+        name: file.name,
+        mimetype: file.type || "application/octet-stream",
+        declaredSize: file.size,
+      })),
+    }),
+  });
+  const json = await readJson(res);
+  if (!res.ok || json?.error) {
+    throw new Error(json?.error || `Failed to start upload (${res.status})`);
+  }
+  const slots = Array.isArray(json?.uploads)
+    ? ([...json.uploads] as UploadSlot[]).sort((a, b) => a.idx - b.idx)
+    : [];
+  if (slots.length !== files.length) {
+    throw new Error("Upload could not be started for all files.");
+  }
+  return slots;
+}
+
+async function initiateResumableSession(
+  uploadUrl: string,
+  mimetype: string,
+  fileSize: number,
+): Promise<string> {
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: {
+      "x-goog-resumable": "start",
+      // The signed URL commits to the exact declared size; echo it back
+      // byte-for-byte or GCS rejects the session.
+      "x-goog-content-length-range": `0,${fileSize}`,
+      "Content-Type": mimetype,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to initiate upload session (${response.status})`);
+  }
+  const sessionUri = response.headers.get("Location");
+  if (!sessionUri) {
+    throw new Error("Upload session URI missing from storage response");
+  }
+  return sessionUri;
+}
+
+// GCS reports the highest committed byte in a `Range: bytes=0-<end>` header.
+function committedOffsetFromRange(response: Response): number | null {
+  const match = response.headers.get("Range")?.match(/bytes=0-(\d+)/);
+  return match ? parseInt(match[1], 10) + 1 : null;
+}
+
+async function queryCommittedOffset(
+  sessionUri: string,
+  total: number,
+): Promise<number> {
+  const response = await fetch(sessionUri, {
+    method: "PUT",
+    headers: { "Content-Range": `bytes */${total}` },
+  });
+  if (response.status === 200 || response.status === 201) return total;
+  if (response.status === 308) return committedOffsetFromRange(response) ?? 0;
+  throw new Error(`Failed to query upload status (${response.status})`);
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(new DOMException("Aborted", "AbortError"));
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true },
+    );
+  });
+}
+
+async function streamFileToStorage(
+  slot: UploadSlot,
+  file: File,
+  onProgress: (uploadedBytes: number) => void,
+): Promise<void> {
+  const mimetype = file.type || "application/octet-stream";
+  const sessionUri = await initiateResumableSession(
+    slot.uploadUrl,
+    mimetype,
+    file.size,
+  );
+  const total = file.size;
+
+  if (total === 0) {
+    const response = await fetch(sessionUri, {
+      method: "PUT",
+      headers: { "Content-Range": "bytes */0" },
+      body: new Uint8Array(0),
+    });
+    if (response.status !== 200 && response.status !== 201) {
+      throw new Error(
+        `Failed to finalize zero-byte upload (${response.status})`,
+      );
+    }
+    onProgress(0);
+    return;
+  }
+
+  let offset = 0;
+  let retries = 0;
+  while (offset < total) {
+    const end = Math.min(offset + GCS_CHUNK_SIZE, total);
+    const isLast = end === total;
+    try {
+      const response = await fetch(sessionUri, {
+        method: "PUT",
+        headers: { "Content-Range": `bytes ${offset}-${end - 1}/${total}` },
+        body: file.slice(offset, end),
+      });
+      if (response.status === 200 || response.status === 201) {
+        offset = total;
+      } else if (!isLast && response.status === 308) {
+        const nextOffset = committedOffsetFromRange(response) ?? offset;
+        if (nextOffset <= offset) {
+          throw new Error(`Upload stalled at byte ${offset}`);
+        }
+        offset = nextOffset;
+      } else {
+        throw new Error(`Unexpected upload status ${response.status}`);
+      }
+      retries = 0;
+      onProgress(offset);
+    } catch (err) {
+      if (++retries > MAX_CHUNK_RETRIES) throw err;
+      await delay(500 * retries);
+      try {
+        offset = await queryCommittedOffset(sessionUri, total);
+      } catch {
+        // If the offset query also fails, retry from the last local offset —
+        // GCS's resumable PUT safely re-acknowledges bytes it already has.
+      }
+      onProgress(offset);
+    }
+  }
+}
+
+export interface UploadAndIndexOptions {
+  projectName?: string;
+  onProgress?: (fraction: number) => void;
+}
+
+/**
+ * Streams `.fig`/design files straight to storage in resumable chunks, then
+ * finalizes Builder DSI indexing with the resulting upload tokens. No file
+ * bytes pass through the app server, so arbitrarily large Figma files work.
+ */
+export async function uploadAndIndexFigmaFiles(
+  files: File[],
+  options: UploadAndIndexOptions = {},
+): Promise<BuilderIndexResult> {
+  if (files.length === 0) throw new Error("No files to upload.");
+
+  const slots = await requestUploadSlots(files);
+
+  const totalBytes = files.reduce((sum, file) => sum + file.size, 0) || 1;
+  const uploadedPerFile = new Array<number>(files.length).fill(0);
+  for (let i = 0; i < files.length; i++) {
+    await streamFileToStorage(slots[i], files[i], (uploaded) => {
+      uploadedPerFile[i] = uploaded;
+      const done = uploadedPerFile.reduce((sum, n) => sum + n, 0);
+      options.onProgress?.(Math.min(done / totalBytes, 1));
+    });
+  }
+
+  const res = await fetch(appApiPath("/api/index-design-system-sources"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      projectName: options.projectName,
+      uploadTokens: slots.map((slot) => slot.uploadToken),
+    }),
+  });
+  const json = await readJson(res);
+  if (!res.ok || json?.error) {
+    throw new Error(json?.error || `Indexing failed (${res.status})`);
+  }
+  return json as BuilderIndexResult;
+}
+
+export interface DecodeJobStatus {
+  status: "pending" | "processing" | "complete" | "error";
+  branchUrl: string | null;
+  error: string | null;
+  framesProcessed: number;
+  totalFrames: number;
+}
+
+const DECODE_JOB_POLL_INTERVAL_MS = 5_000;
+const DECODE_JOB_MAX_POLLS = 120; // ~10 min at 5s, so a stuck job can't loop forever
+
+export interface PollDecodeJobOptions {
+  signal?: AbortSignal;
+  onUpdate?: (status: DecodeJobStatus) => void;
+}
+
+/**
+ * After indexing returns a jobId, the `.fig` decode job is still `pending` with
+ * no branchUrl. Poll until the branch appears or the job reaches a terminal
+ * state. A job that reports `status: "error"` resolves so the caller can read
+ * `status.error`; network failures, timeouts, and aborts reject.
+ */
+export async function pollDecodeJobStatus(
+  jobId: string,
+  options: PollDecodeJobOptions = {},
+): Promise<DecodeJobStatus> {
+  const { signal, onUpdate } = options;
+  const path = appApiPath(
+    `/api/design-system-decode-job-status?jobId=${encodeURIComponent(jobId)}`,
+  );
+  for (let i = 0; i < DECODE_JOB_MAX_POLLS; i++) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    const res = await fetch(path, { signal });
+    const json = await readJson(res);
+    if (!res.ok || json?.error) {
+      throw new Error(json?.error || `Status check failed (${res.status})`);
+    }
+    const status = json as DecodeJobStatus;
+    onUpdate?.(status);
+    if (
+      status.branchUrl ||
+      status.status === "complete" ||
+      status.status === "error"
+    ) {
+      return status;
+    }
+    await delay(DECODE_JOB_POLL_INTERVAL_MS, signal);
+  }
+  throw new Error(
+    "Timed out waiting for the design system to finish decoding.",
+  );
+}

package/corpus/templates/design/app/lib/design-ui-events.ts

@@ -0,0 +1,5 @@
+export const DESIGN_UI_TOGGLE_EVENT = "agent-native:toggle-design-ui";
+
+export function requestDesignUiToggle(): void {
+  window.dispatchEvent(new Event(DESIGN_UI_TOGGLE_EVENT));
+}