@agent-native/core 0.92.6 → 0.92.8

package/dist/cli/design-connect.js

@@ -39,6 +39,19 @@ const MANIFEST_CAPABILITIES = {
     readTextFiles: true,
     writeTextFiles: true,
 };
+const PREVIEW_TOKEN_DOMAIN = "agent-native-design-preview-v1\0";
+/**
+ * Derive a read-only preview credential from the stronger filesystem token.
+ * The one-way hash keeps old `--bridge-token` launch commands compatible while
+ * ensuring a leaked preview credential cannot be promoted into write access.
+ */
+export function deriveDesignPreviewToken(bridgeToken) {
+    return crypto
+        .createHash("sha256")
+        .update(PREVIEW_TOKEN_DOMAIN)
+        .update(bridgeToken)
+        .digest("hex");
+}
 function stringFlagValue(argv, index, flag) {
     const value = argv[index + 1];
     if (!value || value.startsWith("-")) {
@@ -117,6 +130,13 @@ export function parseDesignConnectArgs(argv) {
         else if (arg.startsWith("--bridge-token=")) {
             parsed.bridgeToken = arg.slice("--bridge-token=".length);
         }
+        else if (arg === "--preview-token") {
+            parsed.previewToken = stringFlagValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg.startsWith("--preview-token=")) {
+            parsed.previewToken = arg.slice("--preview-token=".length);
+        }
         else if (arg === "--json") {
             parsed.json = true;
             parsed.once = true;
@@ -149,14 +169,34 @@ export function parseDesignConnectArgs(argv) {
     return parsed;
 }
 function routeId(routePath) {
-    if (routePath === "/")
-        return "route-root";
-    const slug = routePath
+    const normalized = routePath.trim() || "/";
+    const slug = normalized
         .replace(/^\/+/, "")
+        .replace(/\*/g, "w")
+        .replace(/:/g, "p")
+        .replace(/[[\]]/g, "")
         .replace(/[^a-zA-Z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .toLowerCase();
-    return slug ? `route-${slug}` : "route-wildcard";
+    // Slugs are intentionally readable but necessarily lossy: `/foo/bar`,
+    // `/foo-bar`, and `/foo_bar` all collapse to the same text, while `/` and
+    // `/*` can collide with literal `/root` and `/wildcard` paths. Suffix every
+    // route with a stable hash of its normalized path so URL/query states and
+    // router patterns can never silently replace one another in the manifest.
+    const readable = normalized === "/"
+        ? "root"
+        : /^\/\*+$/.test(normalized) || !slug
+            ? "wildcard"
+            : slug;
+    return `route-${readable}-${stableRoutePathHash(normalized)}`;
+}
+function stableRoutePathHash(value) {
+    let hash = 0xcbf29ce484222325n;
+    for (const character of value) {
+        hash ^= BigInt(character.codePointAt(0));
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(36);
 }
 function titleFromRoutePath(routePath) {
     if (routePath === "/")
@@ -315,8 +355,11 @@ function isDesignConnectManifest(value) {
         typeof manifest.bridgeUrl === "string" &&
         typeof manifest.rootPath === "string");
 }
-async function fetchRunningBridgeManifest(bridgeUrl) {
-    const manifestUrl = new URL("/manifest.json", bridgeUrl).toString();
+async function fetchRunningBridgeManifest(bridgeUrl, previewToken) {
+    const manifestUrl = new URL("/manifest.json", bridgeUrl);
+    if (previewToken) {
+        manifestUrl.searchParams.set("previewToken", previewToken);
+    }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 800);
     try {
@@ -349,6 +392,46 @@ export function designConnectManifestsTargetSameApp(running, requested) {
     return (runningUrl === requestedUrl &&
         path.resolve(running.rootPath) === path.resolve(requested.rootPath));
 }
+/** Non-sensitive stable identifier used by /health so daemon reruns can detect
+ * an already-running bridge for the same app without exposing its root path or
+ * route manifest. */
+export function designConnectAppFingerprint(manifest) {
+    let devServerUrl = manifest.devServerUrl;
+    try {
+        devServerUrl = normalizeHttpUrl(devServerUrl);
+    }
+    catch {
+        // Hash the original string for malformed legacy manifests.
+    }
+    return crypto
+        .createHash("sha256")
+        .update(`${devServerUrl}\n${path.resolve(manifest.rootPath)}`)
+        .digest("base64url")
+        .slice(0, 24);
+}
+async function fetchRunningBridgeFingerprint(bridgeUrl) {
+    const healthUrl = new URL("/health", bridgeUrl).toString();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 800);
+    try {
+        const response = await fetch(healthUrl, {
+            method: "GET",
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body["appFingerprint"] === "string"
+            ? body["appFingerprint"]
+            : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 async function resolveDevServerUrl(url) {
     if (url)
         return normalizeHttpUrl(url);
@@ -363,7 +446,65 @@ async function ensureRouteManifest(options) {
         ? options.routeManifestPath
         : path.join(options.root, options.routeManifestPath);
     if (fsSync.existsSync(manifestPath)) {
-        return { path: manifestPath, created: false };
+        try {
+            const parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+            const savedRoutes = Array.isArray(parsed.routes)
+                ? parsed.routes.flatMap((value) => {
+                    if (!value || typeof value !== "object" || Array.isArray(value)) {
+                        return [];
+                    }
+                    const route = value;
+                    if (typeof route.path !== "string" || !route.path.trim())
+                        return [];
+                    const sourceKind = route.sourceKind === "react-router" ||
+                        route.sourceKind === "html" ||
+                        route.sourceKind === "manual"
+                        ? route.sourceKind
+                        : "manual";
+                    return [
+                        {
+                            id: typeof route.id === "string" && route.id.trim()
+                                ? route.id
+                                : routeId(route.path),
+                            path: route.path,
+                            title: typeof route.title === "string" && route.title.trim()
+                                ? route.title
+                                : titleFromRoutePath(route.path),
+                            sourceFile: typeof route.sourceFile === "string"
+                                ? route.sourceFile
+                                : undefined,
+                            sourceKind,
+                            screenshotUrl: typeof route.screenshotUrl === "string"
+                                ? route.screenshotUrl
+                                : undefined,
+                            metadata: route.metadata &&
+                                typeof route.metadata === "object" &&
+                                !Array.isArray(route.metadata)
+                                ? route.metadata
+                                : undefined,
+                        },
+                    ];
+                })
+                : [];
+            if (savedRoutes.length > 0) {
+                const savedPaths = new Set(savedRoutes.map((route) => route.path));
+                return {
+                    path: manifestPath,
+                    created: false,
+                    // Keep manual/custom route order and metadata while still surfacing
+                    // newly discovered routes on subsequent bridge starts.
+                    routes: [
+                        ...savedRoutes,
+                        ...options.routes.filter((route) => !savedPaths.has(route.path)),
+                    ],
+                };
+            }
+        }
+        catch {
+            // Never overwrite a malformed/custom file. Route discovery remains a
+            // safe runtime fallback and the user can repair the manifest in place.
+        }
+        return { path: manifestPath, created: false, routes: options.routes };
     }
     if (!options.dryRun) {
         await fs.mkdir(path.dirname(manifestPath), { recursive: true });
@@ -376,22 +517,27 @@ async function ensureRouteManifest(options) {
             generatedAt: new Date().toISOString(),
         }, null, 2)}\n`, "utf8");
     }
-    return { path: manifestPath, created: !options.dryRun };
+    return {
+        path: manifestPath,
+        created: !options.dryRun,
+        routes: options.routes,
+    };
 }
 export async function prepareDesignConnectManifest(options = {}) {
     const root = path.resolve(options.root ?? process.cwd());
     const port = options.port ?? DEFAULT_BRIDGE_PORT;
     const devServerUrl = await resolveDevServerUrl(options.url);
     const bridgeUrl = `http://127.0.0.1:${port}`;
-    const routes = discoverDesignRoutes(root);
+    const discoveredRoutes = discoverDesignRoutes(root);
     const routeManifest = await ensureRouteManifest({
         root,
         routeManifestPath: options.routeManifest ?? ROUTE_MANIFEST_FILE,
-        routes,
+        routes: discoveredRoutes,
         devServerUrl,
         dryRun: Boolean(options.dryRun),
     });
     const generatedAt = new Date().toISOString();
+    const routes = routeManifest.routes;
     return {
         version: 1,
         source: "agent-native-design-connect",
@@ -420,32 +566,69 @@ export async function prepareDesignConnectManifest(options = {}) {
         })),
     };
 }
+const BRIDGE_CORS_HEADERS = Symbol("agent-native-design-bridge-cors");
+function isLoopbackOrigin(parsed) {
+    const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return (hostname === "localhost" ||
+        hostname === "::1" ||
+        /^127(?:\.\d{1,3}){3}$/.test(hostname));
+}
+function isApprovedDesignOrigin(rawOrigin, configuredOrigins) {
+    let parsed;
+    try {
+        parsed = new URL(rawOrigin);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.origin !== rawOrigin)
+        return false;
+    if (configuredOrigins.has(parsed.origin))
+        return true;
+    if ((parsed.protocol === "http:" || parsed.protocol === "https:") &&
+        isLoopbackOrigin(parsed)) {
+        return true;
+    }
+    return (parsed.protocol === "https:" &&
+        (parsed.hostname === "design.agent-native.com" ||
+            parsed.hostname.endsWith(".design.agent-native.com")));
+}
+function configureBridgeCors(req, res, configuredOrigins) {
+    const origin = typeof req.headers.origin === "string" ? req.headers.origin : "";
+    const approved = origin
+        ? isApprovedDesignOrigin(origin, configuredOrigins)
+        : false;
+    res[BRIDGE_CORS_HEADERS] = approved
+        ? {
+            "access-control-allow-origin": origin,
+            "access-control-allow-methods": "GET, HEAD, POST, OPTIONS",
+            "access-control-allow-headers": "content-type, x-bridge-token, x-design-preview-token",
+            "access-control-allow-private-network": "true",
+            vary: "Origin",
+        }
+        : {};
+    return approved;
+}
+function bridgeCorsHeaders(res) {
+    return res[BRIDGE_CORS_HEADERS] ?? {};
+}
 function sendJson(res, statusCode, body) {
     res.writeHead(statusCode, {
         "content-type": "application/json; charset=utf-8",
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, POST, OPTIONS",
-        "access-control-allow-headers": "content-type, x-bridge-token",
-        "access-control-allow-private-network": "true",
+        ...bridgeCorsHeaders(res),
     });
     res.end(`${JSON.stringify(body, null, 2)}\n`);
 }
 function sendText(res, statusCode, body, contentType) {
     res.writeHead(statusCode, {
         "content-type": contentType,
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, POST, OPTIONS",
-        "access-control-allow-headers": "content-type, x-bridge-token",
-        "access-control-allow-private-network": "true",
+        ...bridgeCorsHeaders(res),
     });
     res.end(body);
 }
 function sendBytes(res, statusCode, body, headers) {
     const responseHeaders = {
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, HEAD, POST, OPTIONS",
-        "access-control-allow-headers": "content-type, x-bridge-token",
-        "access-control-allow-private-network": "true",
+        ...bridgeCorsHeaders(res),
     };
     for (const name of [
         "content-type",
@@ -468,6 +651,19 @@ function sameOrigin(a, b) {
         return false;
     }
 }
+function constantTimeTokenMatches(providedToken, expectedToken) {
+    try {
+        return (providedToken.length === expectedToken.length &&
+            crypto.timingSafeEqual(Buffer.from(providedToken, "utf8"), Buffer.from(expectedToken, "utf8")));
+    }
+    catch {
+        return false;
+    }
+}
+function readHeader(req, name) {
+    const value = req.headers[name];
+    return typeof value === "string" ? value : "";
+}
 function resolvePreviewSnapshotUrl(devServerUrl, rawUrl) {
     const base = normalizeHttpUrl(devServerUrl);
     const parsed = new URL(rawUrl?.trim() || "/", `${base}/`);
@@ -1011,27 +1207,68 @@ async function walkBridgeFiles(rootPath) {
     await walk(resolvedRoot, "");
     return { files, truncated };
 }
-export async function startDesignConnectBridge(manifest, seedToken) {
+export async function startDesignConnectBridge(manifest, seedOrOptions) {
     // 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 ||
+    const options = typeof seedOrOptions === "string"
+        ? { bridgeToken: seedOrOptions }
+        : (seedOrOptions ?? {});
+    const bridgeToken = options.bridgeToken ||
         process.env["AGENT_NATIVE_BRIDGE_TOKEN"] ||
         crypto.randomBytes(32).toString("hex");
+    const previewToken = options.previewToken ||
+        process.env["AGENT_NATIVE_PREVIEW_TOKEN"] ||
+        deriveDesignPreviewToken(bridgeToken);
+    const configuredOrigins = new Set((options.allowedOrigins ?? []).flatMap((raw) => {
+        try {
+            return [new URL(raw).origin];
+        }
+        catch {
+            return [];
+        }
+    }));
     let liveEditBridgeScript = "";
+    // One bridge process serves every URL-backed screen in an overview. The
+    // editor script carries screen-specific state (notably screenId), so a
+    // single global slot lets parallel iframe registrations overwrite each
+    // other and boot a frame with another frame's identity. Keep keyed scripts
+    // for modern clients while retaining the unkeyed slot for older clients.
+    const liveEditBridgeScripts = new Map();
     const server = http.createServer((req, res) => {
+        const corsApproved = configureBridgeCors(req, res, configuredOrigins);
         if (req.method === "OPTIONS") {
-            sendJson(res, 204, {});
+            sendJson(res, corsApproved ? 204 : 403, corsApproved
+                ? {}
+                : { ok: false, error: "origin is not allowed by this bridge" });
             return;
         }
-        const pathname = new URL(req.url ?? "/", manifest.bridgeUrl).pathname;
-        // ── Public read-only routes (no token required) ──────────────────────
+        const requestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
+        const pathname = requestUrl.pathname;
+        const providedPreviewToken = readHeader(req, "x-design-preview-token") ||
+            requestUrl.searchParams.get("previewToken") ||
+            "";
+        const previewTokenValid = constantTimeTokenMatches(providedPreviewToken, previewToken);
+        const rejectInvalidPreviewToken = () => {
+            if (previewTokenValid)
+                return false;
+            sendJson(res, 401, {
+                ok: false,
+                error: "invalid or missing preview token",
+            });
+            return true;
+        };
+        // ── Read-only preview routes (preview token required) ────────────────
         if (pathname === "/" || pathname === "/manifest.json") {
+            if (rejectInvalidPreviewToken())
+                return;
             sendJson(res, 200, manifest);
             return;
         }
         if (pathname === "/routes.json") {
+            if (rejectInvalidPreviewToken())
+                return;
             sendJson(res, 200, {
                 version: 1,
                 sourceType: "localhost",
@@ -1043,7 +1280,11 @@ export async function startDesignConnectBridge(manifest, seedToken) {
             return;
         }
         if (pathname === "/health") {
-            sendJson(res, 200, { ok: true, source: manifest.source });
+            sendJson(res, 200, {
+                ok: true,
+                source: manifest.source,
+                appFingerprint: designConnectAppFingerprint(manifest),
+            });
             return;
         }
         if (pathname === "/live-edit-bridge") {
@@ -1051,38 +1292,50 @@ export async function startDesignConnectBridge(manifest, seedToken) {
                 sendJson(res, 405, { ok: false, error: "method not allowed" });
                 return;
             }
-            const tokenHeader = req.headers["x-bridge-token"];
-            const providedToken = typeof tokenHeader === "string" ? tokenHeader : "";
-            let tokenValid = false;
-            try {
-                tokenValid =
-                    providedToken.length === bridgeToken.length &&
-                        crypto.timingSafeEqual(Buffer.from(providedToken, "utf8"), Buffer.from(bridgeToken, "utf8"));
-            }
-            catch {
-                tokenValid = false;
-            }
-            if (!tokenValid) {
-                sendJson(res, 401, {
-                    ok: false,
-                    error: "invalid or missing bridge token",
-                });
+            if (rejectInvalidPreviewToken())
                 return;
-            }
             void (async () => {
                 try {
                     const raw = await readRequestBody(req);
                     const body = JSON.parse(raw);
                     const script = typeof body["script"] === "string" ? body["script"] : "";
-                    if (!script.includes("agent-native:editor-chrome-ready")) {
+                    const bridgeKey = typeof body["bridgeKey"] === "string"
+                        ? body["bridgeKey"].trim()
+                        : "";
+                    const installsSupportedDesignBridge = script.includes("agent-native:editor-chrome-ready") ||
+                        script.includes("embedded-canvas-pan");
+                    if (!installsSupportedDesignBridge) {
                         sendJson(res, 400, {
                             ok: false,
-                            error: "script must install the Agent Native editor bridge",
+                            error: "script must install an approved Agent Native editor or canvas-pan bridge",
+                        });
+                        return;
+                    }
+                    if (bridgeKey &&
+                        (!/^[a-zA-Z0-9:._-]+$/.test(bridgeKey) || bridgeKey.length > 128)) {
+                        sendJson(res, 400, {
+                            ok: false,
+                            error: "bridgeKey must be 1-128 safe identifier characters",
                         });
                         return;
                     }
                     liveEditBridgeScript = script;
-                    sendJson(res, 200, { ok: true });
+                    if (bridgeKey) {
+                        liveEditBridgeScripts.delete(bridgeKey);
+                        liveEditBridgeScripts.set(bridgeKey, script);
+                        // Bound the in-memory cache. Normal editor usage has one key per
+                        // visible screen; 128 also leaves ample room for mode changes.
+                        while (liveEditBridgeScripts.size > 128) {
+                            const oldest = liveEditBridgeScripts.keys().next().value;
+                            if (typeof oldest !== "string")
+                                break;
+                            liveEditBridgeScripts.delete(oldest);
+                        }
+                    }
+                    sendJson(res, 200, {
+                        ok: true,
+                        ...(bridgeKey ? { bridgeKey } : {}),
+                    });
                 }
                 catch (err) {
                     sendJson(res, 400, {
@@ -1098,19 +1351,33 @@ export async function startDesignConnectBridge(manifest, seedToken) {
                 sendJson(res, 405, { ok: false, error: "method not allowed" });
                 return;
             }
+            if (rejectInvalidPreviewToken())
+                return;
             void (async () => {
                 try {
-                    const requestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
                     const targetUrl = resolvePreviewSnapshotUrl(manifest.devServerUrl, requestUrl.searchParams.get("url") ??
                         requestUrl.searchParams.get("path"));
                     const snapshot = await fetchPreviewSnapshot(manifest.devServerUrl, targetUrl);
                     const includeEditorBridge = requestUrl.searchParams.get("bridge") !== "0";
+                    const requestedBridgeKey = requestUrl.searchParams.get("bridgeKey")?.trim() ?? "";
+                    const editorBridgeScript = requestedBridgeKey
+                        ? (liveEditBridgeScripts.get(requestedBridgeKey) ?? "")
+                        : liveEditBridgeScript;
+                    if (includeEditorBridge &&
+                        requestedBridgeKey &&
+                        !editorBridgeScript) {
+                        sendJson(res, 409, {
+                            ok: false,
+                            error: "The requested live-edit bridge script is not registered. Reload the Design frame to register it again.",
+                        });
+                        return;
+                    }
                     // The dev server route the SPA must boot on (e.g. "/todo"), taken
                     // from the resolved snapshot target rather than the bridge's own
                     // "/live-edit" request path.
                     const targetParsed = new URL(targetUrl);
                     const targetPath = `${targetParsed.pathname}${targetParsed.search}` || "/";
-                    const html = injectLiveEditBridge(snapshot.html, new URL("/", manifest.bridgeUrl).toString(), includeEditorBridge ? liveEditBridgeScript : "", targetPath);
+                    const html = injectLiveEditBridge(snapshot.html, new URL("/", manifest.bridgeUrl).toString(), includeEditorBridge ? editorBridgeScript : "", targetPath);
                     sendText(res, snapshot.status >= 400 ? snapshot.status : 200, html, snapshot.contentType.includes("html")
                         ? snapshot.contentType
                         : "text/html; charset=utf-8");
@@ -1129,9 +1396,10 @@ export async function startDesignConnectBridge(manifest, seedToken) {
                 sendJson(res, 405, { ok: false, error: "method not allowed" });
                 return;
             }
+            if (rejectInvalidPreviewToken())
+                return;
             void (async () => {
                 try {
-                    const requestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
                     const targetUrl = resolvePreviewSnapshotUrl(manifest.devServerUrl, requestUrl.searchParams.get("url") ??
                         requestUrl.searchParams.get("path"));
                     const snapshot = await fetchPreviewSnapshot(manifest.devServerUrl, targetUrl);
@@ -1163,17 +1431,8 @@ export async function startDesignConnectBridge(manifest, seedToken) {
                 return;
             }
             // Authenticate with constant-time comparison to prevent timing attacks.
-            const tokenHeader = req.headers["x-bridge-token"];
-            const providedToken = typeof tokenHeader === "string" ? tokenHeader : "";
-            let tokenValid = false;
-            try {
-                tokenValid =
-                    providedToken.length === bridgeToken.length &&
-                        crypto.timingSafeEqual(Buffer.from(providedToken, "utf8"), Buffer.from(bridgeToken, "utf8"));
-            }
-            catch {
-                tokenValid = false;
-            }
+            const providedToken = readHeader(req, "x-bridge-token");
+            const tokenValid = constantTimeTokenMatches(providedToken, bridgeToken);
             if (!tokenValid) {
                 sendJson(res, 401, {
                     ok: false,
@@ -1366,6 +1625,14 @@ export async function startDesignConnectBridge(manifest, seedToken) {
             return;
         }
         if (req.method === "GET" || req.method === "HEAD") {
+            const sameOriginPreviewSubresource = readHeader(req, "sec-fetch-site") === "same-origin";
+            if (!previewTokenValid && !sameOriginPreviewSubresource) {
+                sendJson(res, 401, {
+                    ok: false,
+                    error: "invalid or missing preview token",
+                });
+                return;
+            }
             void (async () => {
                 try {
                     const targetUrl = resolvePreviewProxyUrl(manifest.devServerUrl, req.url);
@@ -1390,7 +1657,7 @@ export async function startDesignConnectBridge(manifest, seedToken) {
             resolve();
         });
     });
-    return { server, manifest, bridgeToken };
+    return { server, manifest, bridgeToken, previewToken };
 }
 /**
  * Resolve the design app URL from an explicit value or environment variables.
@@ -1441,7 +1708,7 @@ function resolveAuthToken() {
  */
 export async function registerConnectionWithServer(appUrl, bridge, authToken) {
     const endpoint = `${appUrl}/_agent-native/actions/connect-localhost`;
-    const { manifest, bridgeToken } = bridge;
+    const { manifest, bridgeToken, previewToken } = bridge;
     const payload = {
         devServerUrl: manifest.devServerUrl,
         bridgeUrl: manifest.bridgeUrl,
@@ -1459,6 +1726,7 @@ export async function registerConnectionWithServer(appUrl, bridge, authToken) {
         // row.  grant-localhost-write-consent then reads it from the row instead of
         // minting its own unrelated token, which would always produce a 401.
         bridgeToken,
+        previewToken,
         status: "connected",
     };
     const headers = {
@@ -1507,6 +1775,10 @@ Options:
                           /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)
+  --preview-token <token> Adopt the paired read-only browser preview token.
+                          Optional when --bridge-token is present: compatible
+                          clients derive the same one-way token automatically.
+                          (also reads AGENT_NATIVE_PREVIEW_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
@@ -1553,13 +1825,18 @@ function resolveCurrentCliInvocation(argv) {
         args: [...cliPrefix, "design", ...removeDaemonFlag(argv)],
     };
 }
-async function startDetachedDesignBridge(argv, manifest) {
+async function startDetachedDesignBridge(argv, manifest, previewToken) {
     if (await waitForBridgeHealth(manifest.bridgeUrl, 800)) {
-        const runningManifest = await fetchRunningBridgeManifest(manifest.bridgeUrl);
-        if (runningManifest &&
-            designConnectManifestsTargetSameApp(runningManifest, manifest)) {
+        const [runningManifest, runningFingerprint] = await Promise.all([
+            fetchRunningBridgeManifest(manifest.bridgeUrl, previewToken),
+            fetchRunningBridgeFingerprint(manifest.bridgeUrl),
+        ]);
+        const fingerprintMatches = runningFingerprint === designConnectAppFingerprint(manifest);
+        if ((runningManifest &&
+            designConnectManifestsTargetSameApp(runningManifest, manifest)) ||
+            fingerprintMatches) {
             console.error(`Design localhost bridge already running at ${manifest.bridgeUrl}`);
-            console.log(JSON.stringify(runningManifest, null, 2));
+            console.log(JSON.stringify(runningManifest ?? manifest, null, 2));
             return 0;
         }
         console.error([
@@ -1607,21 +1884,29 @@ export async function runDesign(argv) {
         return 0;
     }
     const manifest = await prepareDesignConnectManifest(parsed);
+    const seedBridgeToken = parsed.bridgeToken || process.env["AGENT_NATIVE_BRIDGE_TOKEN"] || undefined;
+    const seedPreviewToken = parsed.previewToken ||
+        process.env["AGENT_NATIVE_PREVIEW_TOKEN"] ||
+        (seedBridgeToken ? deriveDesignPreviewToken(seedBridgeToken) : undefined);
+    const appUrl = resolveAppUrl(parsed.appUrl);
     if (parsed.daemon) {
-        return startDetachedDesignBridge(argv, manifest);
+        return startDetachedDesignBridge(argv, manifest, seedPreviewToken);
     }
     if (parsed.json || parsed.once || parsed.dryRun) {
         console.log(JSON.stringify(manifest, null, 2));
         return 0;
     }
-    const seedToken = parsed.bridgeToken || process.env["AGENT_NATIVE_BRIDGE_TOKEN"] || undefined;
-    const bridge = await startDesignConnectBridge(manifest, seedToken);
+    const bridge = await startDesignConnectBridge(manifest, {
+        bridgeToken: seedBridgeToken,
+        previewToken: seedPreviewToken,
+        allowedOrigins: appUrl ? [appUrl] : [],
+    });
     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}`);
-    if (seedToken) {
+    if (seedBridgeToken) {
         // 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] Using server-provided bridge token; skipping self-registration.");
@@ -1629,13 +1914,12 @@ export async function runDesign(argv) {
     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.");
+            console.error("[design connect] No bridge token or app URL resolved (pass --bridge-token, or --app-url / AGENT_NATIVE_URL); skipping self-registration — browser preview and live-edit will fail to authorize.");
         }
     }
     return await new Promise((resolve) => {