@agent-native/core 0.92.9 → 0.92.11

package/dist/cli/design-connect.js

@@ -557,11 +557,11 @@ export async function prepareDesignConnectManifest(options = {}) {
             status: "available",
             reason: operation === "resolveNodeToFile"
                 ? // resolveNodeToFile maps a runtime DOM node id (from the editor's
-                    // 'select' payload) to { file, line, component } provenance.  The
-                    // bridge endpoint exists; per-element provenance data must be
-                    // emitted by the connected app at build time — see the provenance
-                    // note in the help text below.
-                    "Requires the connected app to emit data-source-file / data-source-line / data-component-name attributes (e.g. via @vitejs/plugin-react jsxDEV or a Babel source plugin)."
+                    // 'select' payload) to { file, line, component } provenance.
+                    // React development builds expose jsxDEV call sites through the
+                    // Fiber debug stack; other runtimes/builds can emit explicit DOM
+                    // provenance attributes — see the help text below.
+                    "React development builds resolve jsxDEV call sites automatically; other runtimes can emit data-source-file / data-source-line / data-component-name attributes."
                 : undefined,
         })),
     };
@@ -626,9 +626,10 @@ function sendText(res, statusCode, body, contentType) {
     });
     res.end(body);
 }
-function sendBytes(res, statusCode, body, headers) {
+function sendBytes(res, statusCode, body, headers, contentLength = body.length) {
     const responseHeaders = {
         ...bridgeCorsHeaders(res),
+        "content-length": String(contentLength),
     };
     for (const name of [
         "content-type",
@@ -664,6 +665,23 @@ function readHeader(req, name) {
     const value = req.headers[name];
     return typeof value === "string" ? value : "";
 }
+/**
+ * Preserve only the browser request metadata a local dev server needs to
+ * classify Vite source-module and stylesheet requests. Agent Native's dev
+ * gateway intentionally varies source-file handling by `Sec-Fetch-Dest`; if
+ * the bridge drops it, React Router module URLs such as `/app/root.tsx` fall
+ * through to Nitro and 404. Keep this allowlist narrow: cookies, authorization,
+ * bridge tokens, origins, and referrers must never be forwarded upstream.
+ */
+function previewProxyRequestHeaders(req) {
+    const headers = {};
+    for (const name of ["accept", "sec-fetch-dest"]) {
+        const value = readHeader(req, name);
+        if (value)
+            headers[name] = value;
+    }
+    return headers;
+}
 function resolvePreviewSnapshotUrl(devServerUrl, rawUrl) {
     const base = normalizeHttpUrl(devServerUrl);
     const parsed = new URL(rawUrl?.trim() || "/", `${base}/`);
@@ -721,7 +739,7 @@ async function fetchPreviewSnapshot(devServerUrl, targetUrl, redirects = 0) {
         clearTimeout(timeout);
     }
 }
-async function fetchPreviewProxyResource(devServerUrl, targetUrl, redirects = 0) {
+async function fetchPreviewProxyResource(devServerUrl, targetUrl, requestHeaders = {}, redirects = 0) {
     if (redirects > 5) {
         throw new Error("Too many redirects while proxying preview resource.");
     }
@@ -732,6 +750,7 @@ async function fetchPreviewProxyResource(devServerUrl, targetUrl, redirects = 0)
             method: "GET",
             redirect: "manual",
             signal: controller.signal,
+            headers: requestHeaders,
         });
         const location = response.headers.get("location");
         if (location && response.status >= 300 && response.status < 400) {
@@ -740,7 +759,7 @@ async function fetchPreviewProxyResource(devServerUrl, targetUrl, redirects = 0)
             if (!sameOrigin(redirected.toString(), devServerUrl)) {
                 throw new Error("Proxy redirect left the connected dev server.");
             }
-            return fetchPreviewProxyResource(devServerUrl, redirected.toString(), redirects + 1);
+            return fetchPreviewProxyResource(devServerUrl, redirected.toString(), requestHeaders, redirects + 1);
         }
         return {
             url: response.url || targetUrl,
@@ -867,6 +886,175 @@ async function assertPathInside(rootPath, targetPath) {
         }
     }
 }
+/**
+ * Resolve a bridge file to a stable lock key without following a leaf
+ * symlink. Missing parent directories are represented beneath their nearest
+ * existing real ancestor, so aliases through in-root directory symlinks share
+ * one mutex while first-time file creation remains supported.
+ */
+async function resolveSafeBridgeFileTarget(rootPath, targetPath) {
+    await assertPathInside(rootPath, targetPath);
+    const resolvedRoot = await fs.realpath(rootPath);
+    const absolutePath = path.resolve(rootPath, targetPath);
+    let existingAncestor = path.dirname(absolutePath);
+    let resolvedAncestor = null;
+    for (let depth = 0; depth < 32; depth += 1) {
+        try {
+            resolvedAncestor = await fs.realpath(existingAncestor);
+            break;
+        }
+        catch {
+            const parent = path.dirname(existingAncestor);
+            if (parent === existingAncestor)
+                break;
+            existingAncestor = parent;
+        }
+    }
+    if (!resolvedAncestor) {
+        throw new Error(`Cannot resolve parent directory: ${absolutePath}`);
+    }
+    // Existing regular files get their own realpath as the lock key. Besides
+    // resolving in-root directory aliases, this canonicalizes case on the
+    // default macOS filesystem so `Button.tsx` and `button.tsx` cannot acquire
+    // separate mutexes for the same inode. assertPathInside already rejected a
+    // symlink leaf before this point.
+    const canonicalPath = (await fs.realpath(absolutePath).catch(() => null)) ??
+        path.resolve(resolvedAncestor, path.relative(existingAncestor, absolutePath));
+    if (canonicalPath !== resolvedRoot &&
+        !canonicalPath.startsWith(resolvedRoot + path.sep)) {
+        throw new Error("Path traversal detected: resolved target is outside root");
+    }
+    return { absolutePath, canonicalPath };
+}
+const bridgeWriteLocks = new Map();
+/** Serialize read-check-write sequences for one canonical local file. */
+async function withBridgeWriteLock(canonicalPath, work) {
+    const previous = bridgeWriteLocks.get(canonicalPath) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const queued = previous.catch(() => undefined).then(() => gate);
+    bridgeWriteLocks.set(canonicalPath, queued);
+    await previous.catch(() => undefined);
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (bridgeWriteLocks.get(canonicalPath) === queued) {
+            bridgeWriteLocks.delete(canonicalPath);
+        }
+    }
+}
+function contentVersionHash(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+/** Read an existing regular file without ever following a leaf symlink. */
+async function readBridgeFileSnapshot(absolutePath) {
+    const noFollow = fsSync.constants.O_NOFOLLOW ?? 0;
+    let handle = null;
+    try {
+        handle = await fs.open(absolutePath, fsSync.constants.O_RDONLY | noFollow);
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            throw new Error(`Bridge target is not a regular file: ${absolutePath}`);
+        }
+        const bytes = await handle.readFile();
+        return {
+            content: bytes.toString("utf8"),
+            versionHash: contentVersionHash(bytes),
+            mode: stat.mode & 0o777,
+        };
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT")
+            return null;
+        throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+class BridgeVersionConflictError extends Error {
+    currentVersionHash;
+    constructor(currentVersionHash) {
+        super("version conflict");
+        this.currentVersionHash = currentVersionHash;
+    }
+}
+class BridgePreconditionRequiredError extends Error {
+    constructor() {
+        super("expectedVersionHash is required");
+    }
+}
+function assertExpectedBridgeVersion(expectedVersionHash, currentVersionHash, requireExpectedVersionHash = false) {
+    // Preserve compatibility: callers that omit a hash retain the existing
+    // last-write-wins behavior, including creation. Compiled-source callers opt
+    // into exact compare-and-swap by sending the hash returned by read-file.
+    if (requireExpectedVersionHash && expectedVersionHash === undefined) {
+        throw new BridgePreconditionRequiredError();
+    }
+    if (expectedVersionHash !== undefined &&
+        (currentVersionHash !== undefined
+            ? currentVersionHash !== expectedVersionHash
+            : requireExpectedVersionHash)) {
+        throw new BridgeVersionConflictError(currentVersionHash);
+    }
+}
+/**
+ * Replace a file durably without exposing a partial write: create an
+ * O_EXCL/O_NOFOLLOW temp sibling, fsync it, revalidate confinement and the
+ * expected content hash, rename atomically, then fsync the parent directory.
+ */
+async function atomicWriteBridgeFile(args) {
+    const parent = path.dirname(path.resolve(args.rootPath, args.relPath));
+    await fs.mkdir(parent, { recursive: true });
+    const revalidated = await resolveSafeBridgeFileTarget(args.rootPath, args.relPath);
+    if (revalidated.canonicalPath !== args.lockedCanonicalPath) {
+        throw new Error("Bridge target changed while waiting for the write lock");
+    }
+    const basename = path.basename(revalidated.absolutePath);
+    const tempPath = path.join(parent, `.${basename}.agent-native-${process.pid}-${crypto.randomBytes(8).toString("hex")}.tmp`);
+    const noFollow = fsSync.constants.O_NOFOLLOW ?? 0;
+    let tempHandle = null;
+    try {
+        tempHandle = await fs.open(tempPath, fsSync.constants.O_CREAT |
+            fsSync.constants.O_EXCL |
+            fsSync.constants.O_WRONLY |
+            noFollow, args.originalMode ?? 0o666);
+        await tempHandle.writeFile(args.content, "utf8");
+        await tempHandle.sync();
+        await tempHandle.close();
+        tempHandle = null;
+        // Re-check after the potentially slow temp write/fsync. This catches a
+        // parent/leaf symlink swap and an external content edit before rename.
+        const beforeRenameTarget = await resolveSafeBridgeFileTarget(args.rootPath, args.relPath);
+        if (beforeRenameTarget.canonicalPath !== args.lockedCanonicalPath) {
+            throw new Error("Bridge target changed during atomic write");
+        }
+        const current = await readBridgeFileSnapshot(beforeRenameTarget.absolutePath);
+        assertExpectedBridgeVersion(args.expectedVersionHash, current?.versionHash, args.requireExpectedVersionHash);
+        await fs.rename(tempPath, beforeRenameTarget.absolutePath);
+        const directoryHandle = await fs.open(parent, "r").catch(() => null);
+        if (directoryHandle) {
+            try {
+                await directoryHandle.sync();
+            }
+            finally {
+                await directoryHandle.close();
+            }
+        }
+        return contentVersionHash(args.content);
+    }
+    finally {
+        await tempHandle?.close().catch(() => undefined);
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+    }
+}
 /** Allowed file extensions for write/apply-edit operations. */
 const ALLOWED_WRITE_EXTENSIONS = new Set([
     ".html",
@@ -929,19 +1117,6 @@ function assertNotBlockedSecretPath(relPath) {
         throw new Error(`Access rejected: "${relPath}" matches a blocked secret-file pattern.`);
     }
 }
-/**
- * Compute a cheap, stable version identifier for a file from its stat: mtime
- * plus size. Not a content hash — it is only meant to detect "did this file
- * change on disk since the caller last read it", the same tradeoff the inline
- * (SQL-backed) workspace provider's versionHash already makes. Returns
- * undefined when the file does not exist (new-file case).
- */
-async function computeVersionHash(absolutePath) {
-    const stat = await fs.stat(absolutePath).catch(() => null);
-    if (!stat)
-        return undefined;
-    return `${stat.mtimeMs}-${stat.size}`;
-}
 function countOccurrences(haystack, needle) {
     if (!needle)
         return 0;
@@ -1236,6 +1411,18 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
     // 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();
+    // Identifies THIS bridge process's in-memory registry, minted fresh every
+    // time the bridge boots. `liveEditBridgeScripts` above only lives in
+    // process memory, so a bridge restart (crash, machine sleep/wake, manual
+    // restart) silently empties it: any screen that registered a bridgeKey
+    // before the restart now gets a 409 "unknown bridge key" from `/live-edit`
+    // even though nothing about that screen actually changed. Echoing this id
+    // on both the registration response and the 409 lets a client tell the two
+    // cases apart — "this exact process never saw my key" (stale/typo, id
+    // matches what it already has cached) vs. "the process restarted since I
+    // registered" (id changed, safe to transparently re-POST `/live-edit-bridge`
+    // and retry) — instead of guessing from the error text or retrying forever.
+    const bridgeInstanceId = crypto.randomBytes(16).toString("hex");
     const server = http.createServer((req, res) => {
         const corsApproved = configureBridgeCors(req, res, configuredOrigins);
         if (req.method === "OPTIONS") {
@@ -1284,6 +1471,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                 ok: true,
                 source: manifest.source,
                 appFingerprint: designConnectAppFingerprint(manifest),
+                bridgeInstanceId,
             });
             return;
         }
@@ -1334,6 +1522,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                     }
                     sendJson(res, 200, {
                         ok: true,
+                        bridgeInstanceId,
                         ...(bridgeKey ? { bridgeKey } : {}),
                     });
                 }
@@ -1366,8 +1555,17 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                     if (includeEditorBridge &&
                         requestedBridgeKey &&
                         !editorBridgeScript) {
+                        // Machine-readable `code` + echoed `bridgeKey`/`bridgeInstanceId`
+                        // let a client distinguish "this bridge process restarted since
+                        // I last registered — safe to silently re-POST
+                        // /live-edit-bridge and retry" from a genuine caller bug,
+                        // instead of string-matching `error` (see bridgeInstanceId's
+                        // doc comment above for the full rationale).
                         sendJson(res, 409, {
                             ok: false,
+                            code: "unknown-bridge-key",
+                            bridgeKey: requestedBridgeKey,
+                            bridgeInstanceId,
                             error: "The requested live-edit bridge script is not registered. Reload the Design frame to register it again.",
                         });
                         return;
@@ -1467,155 +1665,154 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                         sendJson(res, 400, { ok: false, error: "relPath is required" });
                         return;
                     }
-                    await assertPathInside(manifest.rootPath, relPath);
                     assertNotBlockedSecretPath(relPath);
-                    const absolutePath = path.resolve(manifest.rootPath, relPath);
+                    const initialTarget = await resolveSafeBridgeFileTarget(manifest.rootPath, relPath);
                     if (pathname === "/read-file") {
                         // Read-file: no extension restriction (agents need to read any
                         // non-secret file), but the secret-path blocklist above still
                         // applies to .env*, *.pem, *.key, id_rsa*, and anything under .git/.
-                        let content;
-                        try {
-                            content = await fs.readFile(absolutePath, "utf8");
-                        }
-                        catch (err) {
-                            const code = err instanceof Error &&
-                                "code" in err &&
-                                err.code;
-                            if (code === "ENOENT") {
-                                sendJson(res, 404, { ok: false, error: "file not found" });
-                            }
-                            else {
-                                sendJson(res, 500, {
-                                    ok: false,
-                                    error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
-                                });
-                            }
+                        const snapshot = await readBridgeFileSnapshot(initialTarget.absolutePath);
+                        if (!snapshot) {
+                            sendJson(res, 404, { ok: false, error: "file not found" });
                             return;
                         }
-                        const versionHash = await computeVersionHash(absolutePath);
-                        sendJson(res, 200, { ok: true, content, versionHash });
+                        sendJson(res, 200, {
+                            ok: true,
+                            content: snapshot.content,
+                            versionHash: snapshot.versionHash,
+                        });
                         return;
                     }
                     // write-file and apply-edit only allow known text/code extensions.
                     assertAllowedExtension(relPath);
-                    // Optional optimistic-concurrency check: when the caller supplies
-                    // expectedVersionHash, compare it against the file's CURRENT hash
-                    // before writing. A missing file is treated as no-conflict (new
-                    // file case) so first-time writes always succeed.
                     const expectedVersionHash = typeof body["expectedVersionHash"] === "string"
                         ? body["expectedVersionHash"]
                         : undefined;
-                    if (expectedVersionHash !== undefined) {
-                        const currentVersionHash = await computeVersionHash(absolutePath);
-                        if (currentVersionHash !== undefined &&
-                            currentVersionHash !== expectedVersionHash) {
-                            sendJson(res, 409, {
-                                ok: false,
-                                error: "version conflict",
-                                currentVersionHash,
+                    const requireExpectedVersionHash = body["requireExpectedVersionHash"] === true;
+                    await withBridgeWriteLock(initialTarget.canonicalPath, async () => {
+                        const lockedTarget = await resolveSafeBridgeFileTarget(manifest.rootPath, relPath);
+                        if (lockedTarget.canonicalPath !== initialTarget.canonicalPath) {
+                            throw new Error("Bridge target changed while waiting for the write lock");
+                        }
+                        const existing = await readBridgeFileSnapshot(lockedTarget.absolutePath);
+                        assertExpectedBridgeVersion(expectedVersionHash, existing?.versionHash, requireExpectedVersionHash);
+                        if (pathname === "/write-file") {
+                            const content = typeof body["content"] === "string"
+                                ? body["content"]
+                                : undefined;
+                            if (content === undefined) {
+                                sendJson(res, 400, {
+                                    ok: false,
+                                    error: "content is required for write-file",
+                                });
+                                return;
+                            }
+                            const versionHash = await atomicWriteBridgeFile({
+                                rootPath: manifest.rootPath,
+                                relPath,
+                                lockedCanonicalPath: initialTarget.canonicalPath,
+                                content,
+                                expectedVersionHash,
+                                requireExpectedVersionHash,
+                                originalMode: existing?.mode,
                             });
+                            sendJson(res, 200, { ok: true, relPath, versionHash });
                             return;
                         }
-                    }
-                    if (pathname === "/write-file") {
-                        const content = typeof body["content"] === "string"
-                            ? body["content"]
+                        // /apply-edit supports either full replace ({content}) or one
+                        // exact search-and-replace. Both stay within this file's lock.
+                        if (typeof body["content"] === "string") {
+                            const versionHash = await atomicWriteBridgeFile({
+                                rootPath: manifest.rootPath,
+                                relPath,
+                                lockedCanonicalPath: initialTarget.canonicalPath,
+                                content: body["content"],
+                                expectedVersionHash,
+                                requireExpectedVersionHash,
+                                originalMode: existing?.mode,
+                            });
+                            sendJson(res, 200, {
+                                ok: true,
+                                relPath,
+                                method: "replace",
+                                versionHash,
+                            });
+                            return;
+                        }
+                        const search = typeof body["search"] === "string" ? body["search"] : undefined;
+                        const replace = typeof body["replace"] === "string"
+                            ? body["replace"]
                             : undefined;
-                        if (content === undefined) {
+                        if (search === undefined || replace === undefined) {
                             sendJson(res, 400, {
                                 ok: false,
-                                error: "content is required for write-file",
+                                error: "apply-edit requires either {content} for a full replace, or {search, replace} for a patch",
                             });
                             return;
                         }
-                        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-                        await fs.writeFile(absolutePath, content, "utf8");
-                        const versionHash = await computeVersionHash(absolutePath);
-                        sendJson(res, 200, { ok: true, relPath, versionHash });
-                        return;
-                    }
-                    // /apply-edit: supports either full replace ({content}) or
-                    // search-and-replace ({search, replace}).
-                    if (typeof body["content"] === "string") {
-                        // Full-file replace via apply-edit — same as write-file but keeps
-                        // the endpoint semantically separate for callers that want to
-                        // distinguish intent.
-                        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-                        await fs.writeFile(absolutePath, body["content"], "utf8");
-                        const versionHash = await computeVersionHash(absolutePath);
-                        sendJson(res, 200, {
-                            ok: true,
-                            relPath,
-                            method: "replace",
-                            versionHash,
-                        });
-                        return;
-                    }
-                    const search = typeof body["search"] === "string" ? body["search"] : undefined;
-                    const replace = typeof body["replace"] === "string" ? body["replace"] : undefined;
-                    if (search === undefined || replace === undefined) {
-                        sendJson(res, 400, {
-                            ok: false,
-                            error: "apply-edit requires either {content} for a full replace, or {search, replace} for a patch",
-                        });
-                        return;
-                    }
-                    let existing;
-                    try {
-                        existing = await fs.readFile(absolutePath, "utf8");
-                    }
-                    catch (err) {
-                        const code = err instanceof Error &&
-                            "code" in err &&
-                            err.code;
-                        if (code === "ENOENT") {
+                        if (!existing) {
                             sendJson(res, 404, {
                                 ok: false,
                                 error: "file not found — use write-file to create new files",
                             });
+                            return;
                         }
-                        else {
-                            sendJson(res, 500, {
+                        if (search.length === 0) {
+                            sendJson(res, 400, {
                                 ok: false,
-                                error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+                                error: "search string must not be empty",
                             });
+                            return;
                         }
-                        return;
-                    }
-                    if (search.length === 0) {
-                        sendJson(res, 400, {
-                            ok: false,
-                            error: "search string must not be empty",
+                        const occurrenceCount = countOccurrences(existing.content, search);
+                        if (occurrenceCount === 0) {
+                            sendJson(res, 422, {
+                                ok: false,
+                                error: "search string not found in file",
+                            });
+                            return;
+                        }
+                        if (occurrenceCount > 1) {
+                            sendJson(res, 422, {
+                                ok: false,
+                                error: "search string is ambiguous; it appears more than once in the file",
+                            });
+                            return;
+                        }
+                        const updated = existing.content.replace(search, replace);
+                        const versionHash = await atomicWriteBridgeFile({
+                            rootPath: manifest.rootPath,
+                            relPath,
+                            lockedCanonicalPath: initialTarget.canonicalPath,
+                            content: updated,
+                            expectedVersionHash,
+                            requireExpectedVersionHash,
+                            originalMode: existing.mode,
                         });
-                        return;
-                    }
-                    const occurrenceCount = countOccurrences(existing, search);
-                    if (occurrenceCount === 0) {
-                        sendJson(res, 422, {
+                        sendJson(res, 200, {
+                            ok: true,
+                            relPath,
+                            method: "patch",
+                            versionHash,
+                        });
+                    });
+                }
+                catch (err) {
+                    if (err instanceof BridgePreconditionRequiredError) {
+                        sendJson(res, 428, {
                             ok: false,
-                            error: "search string not found in file",
+                            error: "expectedVersionHash is required",
                         });
                         return;
                     }
-                    if (occurrenceCount > 1) {
-                        sendJson(res, 422, {
+                    if (err instanceof BridgeVersionConflictError) {
+                        sendJson(res, 409, {
                             ok: false,
-                            error: "search string is ambiguous; it appears more than once in the file",
+                            error: "version conflict",
+                            currentVersionHash: err.currentVersionHash,
                         });
                         return;
                     }
-                    const updated = existing.replace(search, replace);
-                    await fs.writeFile(absolutePath, updated, "utf8");
-                    const versionHash = await computeVersionHash(absolutePath);
-                    sendJson(res, 200, {
-                        ok: true,
-                        relPath,
-                        method: "patch",
-                        versionHash,
-                    });
-                }
-                catch (err) {
                     sendJson(res, 500, {
                         ok: false,
                         error: err instanceof Error ? err.message : String(err),
@@ -1636,8 +1833,8 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
             void (async () => {
                 try {
                     const targetUrl = resolvePreviewProxyUrl(manifest.devServerUrl, req.url);
-                    const proxied = await fetchPreviewProxyResource(manifest.devServerUrl, targetUrl);
-                    sendBytes(res, proxied.status >= 400 ? proxied.status : 200, req.method === "HEAD" ? Buffer.alloc(0) : proxied.body, proxied.headers);
+                    const proxied = await fetchPreviewProxyResource(manifest.devServerUrl, targetUrl, previewProxyRequestHeaders(req));
+                    sendBytes(res, proxied.status >= 400 ? proxied.status : 200, req.method === "HEAD" ? Buffer.alloc(0) : proxied.body, proxied.headers, proxied.body.length);
                 }
                 catch (err) {
                     sendJson(res, 400, {
@@ -1657,7 +1854,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
             resolve();
         });
     });
-    return { server, manifest, bridgeToken, previewToken };
+    return { server, manifest, bridgeToken, previewToken, bridgeInstanceId };
 }
 /**
  * Resolve the design app URL from an explicit value or environment variables.
@@ -1786,12 +1983,11 @@ Options:
 
 Element provenance (resolveNodeToFile):
   The design editor can map a selected DOM element back to its source file,
-  line, and React component name when the connected app emits provenance
-  attributes at build time.  Add one of the following to your app's build:
+  line, and component name using one of these provenance sources:
 
-  • @vitejs/plugin-react with jsxDEV enabled (development mode default):
-      Sets data-source-file and data-source-line on each JSX element
-      automatically when using the Babel transform.
+  • React development builds with jsxDEV enabled (the default):
+      Design reads the selected element's development-only Fiber debug stack.
+      React does not emit data-source-* DOM attributes automatically.
 
   • A Babel source plugin (e.g. babel-plugin-react-source or a custom plugin):
       Emits data-source-file="src/Button.tsx" data-source-line="12"
@@ -1800,7 +1996,8 @@ Element provenance (resolveNodeToFile):
   • data-loc="src/Button.tsx:12:4" shorthand attribute (Babel source convention):
       The bridge parses this as { sourceFile, line, column } automatically.
 
-  Without these attributes the editor still works; provenance is simply absent.
+  In production React builds and other runtimes without explicit attributes,
+  the editor still works but exact element provenance may be absent.
   Cross-origin localhost iframes cannot be read regardless of attributes (CSP).`);
 }
 function removeDaemonFlag(argv) {