@agent-native/core 0.92.4 → 0.92.6

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2154
-- template files: 5047
+- core files: 2155
+- template files: 5057

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @agent-native/core
 
+## 0.92.6
+
+### Patch Changes
+
+- 5f187db: Highlight run-code source snippets in chat and keep raw tool output popovers within the available viewport.
+- 5f187db: Fix duplicate in-progress chat output during reconnect handoff so streaming text and tool calls render once while the live assistant message catches up. Also stop a reconnect tool spinner from rendering a second card beside its live pending tool card when their reader-local and server-scoped ids don't match, in every reconnect/handoff window.
+- 5f187db: Focus the settings search field automatically when desktop users open settings.
+- 5f187db: Improve organization settings so invites stay above the fold and members appear in a separate table card.
+- 6a29ba0: `ssrfSafeFetch` hardening: a new `httpsOnly` option validates the URL scheme on the initial request and on every redirect hop, so HTTPS-only callers cannot be downgraded to plain HTTP by a redirect from the untrusted origin. Followed redirect responses now also have their bodies cancelled so each hop's connection is released immediately instead of being held until GC.
+- 5f187db: Remove the divider between settings tabs and their tab content.
+- 5f187db: Preserve dashboard, chart, and label names in demo mode while continuing to anonymize free-text/contact names, emails, and numbers.
+- c32c174: add preset-driven-flow to asset template docs
+
+## 0.92.5
+
+### Patch Changes
+
+- eed1710: Fix `/visual-edit` live-edit 401s. The design server now mints the bridge token in `connect-localhost` and returns it from `open-visual-edit`, and `design connect` adopts it via a new `--bridge-token` flag (or `AGENT_NATIVE_BRIDGE_TOKEN`) instead of minting its own. The local bridge and the user's connection row now share the secret without the CLI needing its own auth to self-register — which was impossible under OAuth-based MCP and was the root cause of the 401s. The `visual-edit` skill is updated to call `open-visual-edit` first and start the bridge with the returned token.
+
 ## 0.92.4
 
 ### Patch Changes

package/corpus/core/docs/content/template-assets.mdx

@@ -102,6 +102,145 @@ Live demo: [assets.agent-native.com](https://assets.agent-native.com).
 4. **Use the asset elsewhere.** Copy the export, embed the picker in another
    app, or let another agent call Assets over A2A.
 
+## The preset-driven workflow
+
+Assets produces its best, most repeatable results when work is split into two
+jobs that need very different skills:
+
+1. **Designing the recipe** — slow, craft-heavy, done once per use case. A
+   designer works with the agent to build a **generation preset**: the rules,
+   references, locked-in model, and a prompt template that has been QA'd until
+   it reliably produces on-brand output.
+2. **Running the recipe** — fast and repeatable. A marketer pastes a campaign
+   brief, tags the preset, and gets a finished, brand-safe asset without
+   touching model settings, aspect ratios, masks, or prompt wording.
+
+A preset is the contract between these two people. The designer encodes taste
+and technical judgment once; everyone else inherits it on every generation.
+Think of presets as the design system for AI-generated assets: a raw prompt is
+a throwaway that drifts every time it is retyped, while a preset is durable,
+shared, and carries the decisions (model, aspect ratio, text and reference
+rules, logo handling, fixed layout) that actually determine whether the output
+is usable.
+
+### Designers: build one preset per use case
+
+Create a separate preset for each repeatable format rather than one generic
+"social post" preset that tries to do everything. Specific presets give the
+model clearer rules and produce better output. Good examples:
+
+- LinkedIn ad
+- Webinar announcement
+- Event speaker card
+- Podcast guest card
+- Customer story quote card
+- Blog hero
+- Blog body diagram
+
+The primary way to build one is **conversationally**: describe the use case to
+the agent and let it create the preset and fill in sensible defaults — model,
+aspect ratio and size, a first prompt template, and text/reference/logo
+policies — then refine in the same conversation ("make it darker", "tighten the
+text policy", "try a square variant"). Because that reasoning shows up directly
+in the defaults the agent picks, run this design conversation on the strongest
+available model.
+
+Each preset locks down:
+
+| Setting             | What it controls                                                                                                     |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Prompt template     | The QA'd creative recipe, with slots for the campaign brief                                                          |
+| Model               | The right image engine for this job (see below)                                                                      |
+| Aspect ratio + size | Output format for the target channel                                                                                 |
+| Text policy         | Whether and how literal copy is rendered vs suppressed                                                               |
+| Reference policy    | Which brand references anchor the look                                                                               |
+| Reference board     | Named fixed or per-run visual references, such as a usual host, guest speaker, product, backdrop, or composition cue |
+| Logo                | Composites the library's canonical logo pixel-perfect after generation, so the model never redraws it                |
+| Skeleton / mask     | A fixed brand plate the subject is composited or inpainted into, for locked layouts                                  |
+
+### Choosing the model per preset
+
+Pick the model in the preset so downstream users never have to:
+
+- **A general high-quality image model** for hero images, rich scenes, and
+  complex compositions, when you need broad aspect-ratio flexibility.
+- **A fast image model** for high-volume social where turnaround matters more
+  than maximum polish.
+- **gpt-image-2** for customer-facing, text-heavy, and identity-sensitive work.
+  It renders crisp literal copy inside the image, and it is the engine used for
+  **mask inpainting** into a fixed layout.
+- **gpt-image-1** for transparent **cutout** subjects that are composited onto a
+  brand plate afterward.
+
+When a use case has a **fixed brand frame** that must survive every generation
+(a webinar template with a locked header and logo, an ad plate with a reserved
+product area), build a preset skeleton: upload the background plate, choose
+gpt-image-2, and optionally add a same-size mask. **Opaque areas are preserved,
+transparent areas are editable**, so the logo, framing, and existing copy come
+back untouched while only the art region changes. Note that gpt-image edits are
+guided semantic rewrites, not pixel-only patches, so the prompt should still
+describe the whole intended image and restate what must not change.
+
+Use the **reference board** when a preset needs annotated visual inputs that
+ride along with each run. Each board entry names one thing — a person, product,
+style, background, or composition example — and can pin up to four images plus a
+plain-language description. Fixed entries attach automatically. Variable
+entries can be replaced per run with `presetReferenceFills`, and required
+variable entries block generation until the agent supplies images from user
+attachments or the library.
+
+For example, a Webinar Announcement preset might use a skeleton plate and mask
+for the locked event chrome, a fixed "Steve" subject entry for the usual host,
+and a required variable "Guest speaker" entry for each event. Use a
+`background` entry for setting context. Use a `composition` entry for layout
+inspiration from a past poster; exact placement belongs in the skeleton plate,
+not a reference image.
+
+### QA the prompt until it is reliable
+
+The model, references, and skeleton set the stage, but the prompt template is
+what turns a brief into a consistently good asset. Have the agent generate
+several candidates against realistic briefs and tighten the template until it
+holds. Techniques worth baking in:
+
+- **Structure the prompt in a fixed order**: scene, subject, key details,
+  constraints. Name the intended use so the model picks the right polish level.
+- **For literal copy, be surgical**: put exact text in quotes or ALL CAPS,
+  specify font, size, color, and placement, and for tricky brand names spell
+  them out. Ask for the text exactly once with no extra characters.
+- **For skeleton or inpainting presets, restate the invariants every run**:
+  "change only the center region, preserve the header, logo, and framing."
+
+Before handing a preset to the wider team, run realistic QA generations
+(including briefs you did not write) and confirm it: follows the use case,
+respects the mask, preserves fixed text and logos, avoids inventing extra
+headlines or badges, uses references correctly, places the subject in the right
+region, handles short and long briefs, and still holds up after a refinement.
+
+### Everyone else: paste the brief, tag the preset, generate
+
+Once a preset exists, running it is three moves: paste the campaign brief, tag
+the preset with `@`, and generate. The tagged preset injects its full aesthetic
+brief into the agent, and the saved model, format, tier, logo, and skeleton all
+apply automatically.
+
+```text
+Create a LinkedIn ad for our webinar on AI landing pages.
+Audience: B2B marketing teams.
+Message: launch campaign pages faster while staying on brand.
+CTA: Register now.
+
+@Webinar Announcement
+```
+
+No model picking, no aspect-ratio math, no mask files, no prompt engineering.
+Rule of thumb: designers own the preset, everyone else owns the brief. If a
+user finds themselves choosing models, masks, or layout rules during normal
+use, the preset is not specific enough yet.
+
+For deeper prompting guidance on the underlying models, see OpenAI's
+[GPT Image prompting guide](https://developers.openai.com/cookbook/examples/multimodal/image-gen-models-prompting-guide).
+
 ## Useful prompts
 
 - "Generate three blog hero options using the Acme product references."

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.92.4",
+  "version": "0.92.6",
   "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": {

package/corpus/core/src/agent/production-agent.ts

@@ -4193,7 +4193,7 @@ export async function runAgentLoop(opts: {
         // `_agentImages` result field (stripped from the JSON the model
         // reads, even in demo mode). Demo mode drops the images themselves —
         // text redaction can't scrub pixels, and a screenshot would leak the
-        // real names/emails the redaction exists to hide. The images array
+        // real contact names/emails/numbers the redaction exists to hide. The images array
         // never touches the ledger — only the compact text notes appended
         // below are persisted.
         let imageNotes: string[] = [];
@@ -4664,7 +4664,40 @@ export function backgroundContinuationReasonForRun(
 }
 
 export async function runAgentLoopWithMainChatInternalContinuations(
-  opts: Parameters<typeof runAgentLoop>[0],
+  opts: Parameters<typeof runAgentLoop>[0] & {
+    /**
+     * Opt-in: also catch a thrown `isResumableEngineError` (gateway drop /
+     * transport interruption surviving engine retries) and retry it in-process
+     * — the same "continue from where you left off" treatment already applied
+     * to in-loop `auto_continue` events below — instead of letting it
+     * propagate out to the caller. Default false/omitted preserves the exact
+     * prior behavior: such an error is NOT caught here and propagates to
+     * `startRun`'s outer catch, which marks the run "errored" and (for a
+     * background worker) hands off to `chainServerDrivenContinuation` for a
+     * fresh invocation.
+     *
+     * Only safe to enable when the CALLER is a proven durable-background
+     * worker (`isInBackgroundFunctionRuntime()`): such a worker has minutes of
+     * remaining budget on this same invocation, so resuming in-process avoids
+     * a self-dispatch entirely — critically, it avoids the bg-function
+     * self-dispatch 404 (a background function cannot invoke its own public
+     * URL from inside a live invocation) that this same recoverable-error
+     * path would otherwise hit via `chainServerDrivenContinuation`. A
+     * foreground turn (~40s budget) must NOT set this — it keeps depending on
+     * the existing cross-invocation recovery (foreground self-chain or the
+     * client's `auto_continue` re-POST), unchanged.
+     */
+    resumeResumableErrorsInProcess?: boolean;
+    /**
+     * Override for the per-invocation continuation attempt cap. Defaults to
+     * `MAIN_CHAT_INTERNAL_CONTINUATION_LIMIT` (6) when omitted — unchanged for
+     * every existing caller. A proven background-function worker (15-min
+     * budget) can pass a higher cap (e.g. `MAX_BACKGROUND_RUN_CONTINUATIONS`)
+     * so a run that needs several resumable-error recoveries within one
+     * 13-minute chunk isn't cut off at the foreground-sized limit.
+     */
+    maxContinuations?: number;
+  },
 ): Promise<Awaited<ReturnType<typeof runAgentLoop>>> {
   const usage: Awaited<ReturnType<typeof runAgentLoop>> = {
     inputTokens: 0,
@@ -4681,11 +4714,18 @@ export async function runAgentLoopWithMainChatInternalContinuations(
     usage.model = next.model;
   };
 
+  const resumeResumableErrorsInProcess =
+    opts.resumeResumableErrorsInProcess === true;
+  const maxContinuations =
+    typeof opts.maxContinuations === "number" && opts.maxContinuations > 0
+      ? opts.maxContinuations
+      : MAIN_CHAT_INTERNAL_CONTINUATION_LIMIT;
+
   const localTurnEvents: AgentChatEvent[] = [];
   let lastAttemptWasUnfinishedContinuation = false;
   for (
     let attempt = 0;
-    !opts.signal.aborted && attempt < MAIN_CHAT_INTERNAL_CONTINUATION_LIMIT;
+    !opts.signal.aborted && attempt < maxContinuations;
     attempt++
   ) {
     lastAttemptWasUnfinishedContinuation = false;
@@ -4703,8 +4743,23 @@ export async function runAgentLoopWithMainChatInternalContinuations(
       opts.send(event);
     };
 
-    const nextUsage = await runAgentLoop({ ...opts, send });
-    addUsage(nextUsage);
+    try {
+      const nextUsage = await runAgentLoop({ ...opts, send });
+      addUsage(nextUsage);
+    } catch (err) {
+      // Preserve exact prior behavior unless explicitly opted in: an aborted
+      // signal (real soft-timeout / user stop) or a non-resumable error is
+      // always rethrown, and when `resumeResumableErrorsInProcess` is not
+      // set, EVERY thrown error is rethrown exactly as before.
+      if (
+        !resumeResumableErrorsInProcess ||
+        opts.signal.aborted ||
+        !isResumableEngineError(err)
+      ) {
+        throw err;
+      }
+      continuationReason = continuationReasonForResumableError(err);
+    }
 
     if (!continuationReason || opts.signal.aborted) {
       return usage;
@@ -6525,10 +6580,25 @@ export function createProductionAgentHandler(
                   // chaining via the regular function — the Netlify
                   // `-background` function is only emitted into the deploy
                   // output when the durable flag is on.
+                  //
+                  // `&& !runsInBackgroundFunction`: a worker PROVEN to already
+                  // be executing inside the real `-background` function must
+                  // never dispatch back to that same function's own URL — a
+                  // background function invoking itself by URL from inside a
+                  // live invocation is a documented Netlify platform
+                  // limitation (404), unlike the initial foreground→background
+                  // dispatch or a worker that landed on the regular function
+                  // (a genuinely different function calling the background
+                  // one, which works). This only changes the dispatch TARGET
+                  // for that one proven-in-bg-function case — by this point
+                  // (with the in-process resumable-error resume above) it is
+                  // reached only when the chunk genuinely exhausted its
+                  // budget, so falling back to the regular `_process-run`
+                  // function (40s clamp) here is the correct, safe target.
                   chainViaDurableBackground:
                     isAgentChatDurableBackgroundEnabled({
                       appOptIn: options.durableBackgroundRuns === true,
-                    }),
+                    }) && !runsInBackgroundFunction,
                 });
               }
             } finally {
@@ -6946,6 +7016,26 @@ export function createProductionAgentHandler(
                   .slice(0, 200),
               }
             : {}),
+          // A worker PROVEN to be running inside the real 15-min Netlify
+          // `-background` function (`runsInBackgroundFunction`) has minutes of
+          // budget left on THIS invocation. Let it catch a recoverable
+          // transport/gateway error (isResumableEngineError) and resume the
+          // agent loop in-process instead of unwinding out to `startRun`'s
+          // outer catch, which would otherwise hand off to
+          // `chainServerDrivenContinuation` — and for a worker already inside
+          // the background function, that hand-off is a same-function
+          // self-dispatch that 404s on Netlify (a background function cannot
+          // invoke its own public URL from inside a live invocation). A
+          // foreground turn or a worker that landed on the regular ~60s
+          // function (runsInBackgroundFunction false) must NOT set this — it
+          // keeps depending on the existing cross-invocation recovery
+          // (foreground self-chain / client auto_continue re-POST), unchanged.
+          ...(runsInBackgroundFunction
+            ? {
+                resumeResumableErrorsInProcess: true,
+                maxContinuations: MAX_BACKGROUND_RUN_CONTINUATIONS,
+              }
+            : {}),
         };
 
         send({ type: "activity", label: "Contacting model" });

package/corpus/core/src/cli/design-connect.ts

@@ -60,6 +60,10 @@ export interface DesignConnectArgs {
    *  are present) the CLI POSTs to `/_agent-native/actions/connect-localhost`
    *  with the real bridge token so the server can store it for grant minting. */
   appUrl?: string;
+  /** Server-minted bridge token to adopt instead of minting one, so the bridge
+   *  matches the token already stored on the user's connection row (no
+   *  self-registration). Also read from AGENT_NATIVE_BRIDGE_TOKEN. */
+  bridgeToken?: string;
   json: boolean;
   once: boolean;
   dryRun: boolean;
@@ -174,6 +178,11 @@ export function parseDesignConnectArgs(argv: string[]): DesignConnectArgs {
       index += 1;
     } else if (arg.startsWith("--app-url=")) {
       parsed.appUrl = arg.slice("--app-url=".length);
+    } else if (arg === "--bridge-token") {
+      parsed.bridgeToken = stringFlagValue(args, index, arg);
+      index += 1;
+    } else if (arg.startsWith("--bridge-token=")) {
+      parsed.bridgeToken = arg.slice("--bridge-token=".length);
     } else if (arg === "--json") {
       parsed.json = true;
       parsed.once = true;
@@ -1215,12 +1224,16 @@ async function walkBridgeFiles(rootPath: string): Promise<ListFilesResult> {
 
 export async function startDesignConnectBridge(
   manifest: DesignConnectManifest,
+  seedToken?: string,
 ): Promise<DesignConnectBridge> {
-  // Mint a cryptographically random per-rootPath bridge token.  This token is
-  // kept in-process only and is never emitted via the public GET routes so that
-  // an unauthenticated caller cannot read it.  The server-side grant action
-  // obtains it out-of-band (via the exported bridge reference).
-  const bridgeToken = crypto.randomBytes(32).toString("hex");
+  // Shared secret the browser sends (x-bridge-token) to unlock live-edit/read/
+  // write. Bridge and the user's connection row must agree on it. Adopt a
+  // server-minted seed when given (MCP flow); otherwise mint one and rely on
+  // --app-url self-registration to push it up. Kept in-process, never served.
+  const bridgeToken =
+    seedToken ||
+    process.env["AGENT_NATIVE_BRIDGE_TOKEN"] ||
+    crypto.randomBytes(32).toString("hex");
   let liveEditBridgeScript = "";
 
   const server = http.createServer(
@@ -1795,6 +1808,12 @@ Options:
   --route-manifest <path> Non-destructive route manifest output path
   --app-url <url>         Deployed design app URL for self-registration
                           (also reads AGENT_NATIVE_URL / DESIGN_APP_URL env)
+  --bridge-token <token>  Adopt a bridge token minted server-side by the
+                          authenticated connect-localhost / open-visual-edit
+                          action instead of minting one. Used by the remote-MCP
+                          /visual-edit flow so the bridge and the user's stored
+                          connection token match with no self-registration.
+                          (also reads AGENT_NATIVE_BRIDGE_TOKEN env)
   --daemon                Start the bridge detached, wait for /health, then exit
   --json                  Print the manifest JSON and exit
   --once                  Prepare/scaffold the manifest and exit
@@ -1931,25 +1950,33 @@ export async function runDesign(argv: string[]) {
     return 0;
   }
 
-  const bridge = await startDesignConnectBridge(manifest);
+  const seedToken =
+    parsed.bridgeToken || process.env["AGENT_NATIVE_BRIDGE_TOKEN"] || undefined;
+  const bridge = await startDesignConnectBridge(manifest, seedToken);
   console.error("Design localhost bridge running");
   console.error(`Bridge:   ${manifest.bridgeUrl}`);
   console.error(`Manifest: ${manifest.bridgeUrl}/manifest.json`);
   console.error(`Routes:   ${manifest.routeCount}`);
   console.error(`Dev URL:  ${manifest.devServerUrl}`);
 
-  // Self-register with the design app server (best-effort): POST the bridge
-  // token to connect-localhost so the server row stores the real token. Without
-  // it, the bridge and server tokens diverge and every write returns 401.
-  const appUrl = resolveAppUrl(parsed.appUrl);
-  if (appUrl) {
-    void registerConnectionWithServer(appUrl, bridge, resolveAuthToken());
-  } else {
-    // No app URL means the token never reaches the DB — surface it instead of
-    // silently skipping, since live-edit will then 401.
+  if (seedToken) {
+    // Server already stored this token on the row; bridge matches it, so no
+    // self-registration needed. Zero-config path for the remote-MCP flow.
     console.error(
-      "[design connect] No app URL resolved (pass --app-url or set AGENT_NATIVE_URL); skipping self-registration — live-edit will fail to authorize.",
+      "[design connect] Using server-provided bridge token; skipping self-registration.",
     );
+  } else {
+    // No seed: fall back to self-registration — POST the minted token to
+    // connect-localhost. Needs an auth token in env or it 401s (the old gap).
+    const appUrl = resolveAppUrl(parsed.appUrl);
+    if (appUrl) {
+      void registerConnectionWithServer(appUrl, bridge, resolveAuthToken());
+    } else {
+      // No token source at all — warn rather than 401 silently at edit time.
+      console.error(
+        "[design connect] No bridge token or app URL resolved (pass --bridge-token, or --app-url / AGENT_NATIVE_URL); skipping self-registration — live-edit will fail to authorize.",
+      );
+    }
   }
 
   return await new Promise<number>((resolve) => {

package/corpus/core/src/cli/skills.ts

@@ -486,34 +486,66 @@ iframe-backed screens on the infinite canvas.
 
 ## Required Local Bridge
 
-From the target app repo, make sure its dev server is running, then run:
+The live-edit bridge is unlocked by a shared secret (the "bridge token") that
+must match on two sides: the local bridge process, and the user's connection row
+in Design (which the browser reads to authorize \`/live-edit-bridge\`,
+\`/read-file\`, \`/write-file\`). Get them to match by letting the
+**authenticated** \`open-visual-edit\` action mint the token, then starting the
+bridge with it. This is the only ordering that works for the remote-MCP flow —
+the bridge cannot push its own token to the server without a CLI auth token, so
+the server mints instead and the bridge adopts.
+
+From the target app repo, make sure its dev server is running, then:
+
+**1. Discover routes without starting a durable bridge** (one-shot, exits):
 
 \`\`\`bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
 \`\`\`
 
-Use the app's real port. The command starts a detached local bridge on
-\`http://127.0.0.1:7331\` by default, waits for \`/health\`, prints the
-manifest JSON, and keeps the bridge alive after the agent command exits.
+This prints the manifest (routes + capabilities). Parse it to build
+\`routeManifest\` for the next step. (Skip this if the user already gave explicit
+paths/URLs to place.)
+
+**2. Call \`open-visual-edit\`** (see Action Flow below) with NO \`bridgeToken\`.
+The server mints one, stores it on the user's connection row, copies it into the
+placed screens' metadata, and returns it to you as \`bridgeToken\`. Capture it.
 
-For a manual health/manifest check:
+**3. Start the persistent bridge adopting that token** (single line; prefer the
+env var so the secret does not appear in \`ps\`):
+
+\`\`\`bash
+AGENT_NATIVE_BRIDGE_TOKEN="<bridgeToken from step 2>" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon
+\`\`\`
+
+(Equivalently, pass \`--bridge-token <token>\`.) This starts a detached bridge on
+\`http://127.0.0.1:7331\`, adopts the server-minted token — so bridge and row
+agree and live-edit authorizes with no self-registration — and stays alive after
+the command exits.
+
+For a manual health/manifest check on the running bridge:
 
 \`\`\`bash
 curl http://127.0.0.1:7331/manifest.json
 \`\`\`
 
-Do not use \`--json\` for an editable session. \`--json\`, \`--once\`, and
-\`--dry-run\` print the manifest and exit, so Design will fall back to a
-non-editable live iframe as soon as it tries to refresh the snapshot.
+Only use \`--json\` for the step-1 route probe. Never use \`--json\`, \`--once\`,
+or \`--dry-run\` for the durable step-3 bridge: they print the manifest and exit,
+so Design falls back to a non-editable live iframe.
 
 ## Action Flow
 
 Prefer the single authenticated \`open-visual-edit\` action. It registers or
-refreshes the localhost bridge, creates or reuses a Design project, places
-URL-backed screens, stores the active visual-edit context, and navigates to
-overview mode in one call. This avoids creating a private design under a
-synthetic CLI user and then handing the browser a tokenized URL that may be
-shadowed by an existing session.
+refreshes the localhost bridge connection, mints and stores the bridge token,
+creates or reuses a Design project, places URL-backed screens, stores the active
+visual-edit context, and navigates to overview mode in one call. This avoids
+creating a private design under a synthetic CLI user and then handing the browser
+a tokenized URL that may be shadowed by an existing session.
+
+Call it BEFORE starting the durable bridge (step 3 above): it does not contact
+the bridge, so the bridge need not be running yet, and you need its returned
+\`bridgeToken\` to start the bridge with a matching secret. Omit \`bridgeToken\`
+on the call so the server mints one.
 
 \`\`\`bash
 pnpm action open-visual-edit '{
@@ -526,8 +558,12 @@ pnpm action open-visual-edit '{
 }'
 \`\`\`
 
-The action returns \`designId\`, \`connectionId\`, \`screens\`, \`urlPath\`, and
-\`openUrl\`. Keep those IDs in the chat context for follow-ups.
+The action returns \`designId\`, \`connectionId\`, \`bridgeToken\`, \`screens\`,
+\`urlPath\`, and \`openUrl\`. Keep \`designId\`/\`connectionId\` in the chat context
+for follow-ups, and pass \`bridgeToken\` to \`design connect\` (step 3) to start
+the bridge. On follow-up calls reusing an existing \`connectionId\`, the same
+token is returned (it is minted once and reused), so the running bridge stays
+valid.
 
 For a numbered flow the user describes in chat, keep the labels and order: