rivet-design 0.9.7 → 0.9.8

package/dist/mcp/agent-variants/WorktreeOrchestrator.js

@@ -17,6 +17,7 @@ const errors_1 = require("./errors");
 const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
 const viteReactTs_1 = require("../../services/templates/viteReactTs");
+const StaticPreviewServer_1 = require("../../services/StaticPreviewServer");
 const designCatalog_1 = require("../../services/templates/designCatalog");
 const previewQa_1 = require("./previewQa");
 const VariantHistoryService_1 = require("../../services/VariantHistoryService");
@@ -234,7 +235,9 @@ class AgentVariantsOrchestrator {
     materializeProject;
     previewQaRunner;
     switchPreviewPort;
+    setCommittedDevServerHealth;
     variantHistory;
+    startStaticPreviewServerImpl;
     resources = new Map();
     /**
      * Committed dev servers from prior sessions that survived teardown. The
@@ -274,7 +277,10 @@ class AgentVariantsOrchestrator {
             deps.materializeProject ?? defaultMaterializeProject;
         this.previewQaRunner = deps.previewQaRunner ?? defaultPreviewQaRunner;
         this.switchPreviewPort = deps.switchPreviewPort;
+        this.setCommittedDevServerHealth = deps.setCommittedDevServerHealth;
         this.variantHistory = deps.variantHistory ?? new VariantHistoryService_1.VariantHistoryService();
+        this.startStaticPreviewServerImpl =
+            deps.startStaticPreviewServer ?? StaticPreviewServer_1.startStaticPreviewServer;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -539,6 +545,79 @@ class AgentVariantsOrchestrator {
         const artifact = findDesignContextArtifact(this.store.getProjectContext(sessionId), artifactId);
         return artifact ? buildDesignContextViewerDocument(artifact) : undefined;
     }
+    /**
+     * `true` when the variant has a non-empty `assetBase` — i.e. its inlined
+     * HTML references sibling files served by the asset route. The route
+     * uses this to decide whether to inject a `<base href>` (only needed
+     * when relative URLs in the HTML must resolve against the asset
+     * sub-path). Self-contained HTML keeps its natural URL resolution.
+     */
+    hasStaticPreviewAssets(sessionId, workItemId) {
+        const record = this.resources
+            .get(sessionId)
+            ?.staticPreviews.get(workItemId);
+        return Boolean(record?.assetBase);
+    }
+    /**
+     * Resolve an absolute, sandboxed path for a sibling asset that the
+     * variant's inlined HTML references (e.g. `./avatar.glb`, `./hero.png`).
+     * Returns `undefined` when the variant has no `assetBase`, the requested
+     * path escapes the base (path traversal), or the file does not exist.
+     *
+     * Used by the `/api/variants/:sessionId/static/:variantId/<asset>` route
+     * to serve assets from the agent's on-disk variant workspace pre-commit.
+     */
+    resolveStaticPreviewAssetPath(sessionId, workItemId, requestedPath) {
+        const record = this.resources
+            .get(sessionId)
+            ?.staticPreviews.get(workItemId);
+        if (!record?.assetBase)
+            return undefined;
+        if (!requestedPath || requestedPath.length === 0)
+            return undefined;
+        // Express has already URL-decoded `req.params.assetPath` for us — calling
+        // decodeURIComponent again would mangle filenames that legitimately
+        // contain `%` (e.g. `100%25.png` on disk → `100%.png` after the second
+        // pass, 404). Use the path as Express delivered it.
+        //
+        // `record.assetBase` is already a realpath'd, within-workspace directory
+        // (see `resolveStaticPreviewAssetBase`). Resolve the requested target
+        // through `realpathSync` too — without this, an attacker who manages to
+        // plant a symlink under the base (e.g. via a follow-up Write tool call)
+        // could pivot outside the sandbox.
+        const target = path_1.default.resolve(record.assetBase, '.' + path_1.default.sep + requestedPath);
+        if (target !== record.assetBase && !target.startsWith(record.assetBase + path_1.default.sep)) {
+            return undefined;
+        }
+        let realTarget;
+        try {
+            realTarget = fs_1.default.realpathSync(target);
+        }
+        catch {
+            return undefined;
+        }
+        if (realTarget !== record.assetBase &&
+            !realTarget.startsWith(record.assetBase + path_1.default.sep)) {
+            return undefined;
+        }
+        try {
+            const stat = fs_1.default.statSync(realTarget);
+            if (!stat.isFile())
+                return undefined;
+            // Hardlinks aren't dereferenced by `realpath` — they ARE the file from
+            // a path-resolution perspective, so the realpath check above can't
+            // detect them. An agent could `ln /path/to/.env assetBase/x.glb`
+            // (hardlink, not symlink) and the resolver would happily serve the
+            // secret. Reject anything with multiple links — legitimate
+            // agent-generated assets always have nlink === 1.
+            if (stat.nlink !== 1)
+                return undefined;
+            return realTarget;
+        }
+        catch {
+            return undefined;
+        }
+    }
     getStaticPreviewByBriefId(sessionId, briefId) {
         const resources = this.resources.get(sessionId);
         if (!resources)
@@ -690,6 +769,22 @@ class AgentVariantsOrchestrator {
         };
     }
     async reportComplete(args) {
+        // Contract validation: a `succeeded` static_preview report MUST carry the
+        // deliverable inline as `output.html` (with optional `css` / `js`). Agents
+        // sometimes default to writing files to disk and reporting back a file
+        // list — that leaves the orchestrator with no HTML to serve, the variant
+        // shows "Preview unavailable" in the panel, and `/api/variants/.../static`
+        // returns 404. Reject loudly so the agent self-corrects on retry instead
+        // of silently producing an empty-preview run.
+        if (args.status === 'succeeded' &&
+            this.store.hasSession(args.sessionId) &&
+            this.store.getWorkItemKind(args.sessionId, args.workItemId) ===
+                'static_preview' &&
+            !parseStaticPreviewOutput(normalizeOutput(args.output))) {
+            throw new errors_1.AgentVariantsError('SCHEMA_VALIDATION_FAILED', 'static_preview report_variant_complete requires output.html (string, non-empty). ' +
+                'Pass the full HTML inline as output: { html: "<!doctype html>...", css?: "...", js?: "..." }. ' +
+                'Do NOT write the HTML to a file and report a file list — Rivet renders the HTML inline; on-disk files are not read.');
+        }
         // QA gate: for `succeeded` static_preview reports, run preview QA
         // synchronously before recording success in the store. A failed QA
         // verdict converts the report to `failed` with code `VARIANT_QA_FAILED`
@@ -895,6 +990,12 @@ class AgentVariantsOrchestrator {
                     log.warn(`persistVariantHistoryAtCommit (duplicate retry) failed for session ${args.sessionId}`, err);
                 });
             }
+            // If the committed dev/static server is still running (either tracked
+            // on resources, or handed off to the lingering registry), surface its
+            // URL so a retry restores the iframe to the live project.
+            const lingering = this.lingeringCommittedDevServers.get(args.sessionId);
+            const live = this.resources.get(args.sessionId)?.committedDevServer;
+            const replayPort = lingering?.port ?? live?.port;
             return {
                 enqueued: false,
                 duplicate: true,
@@ -903,6 +1004,9 @@ class AgentVariantsOrchestrator {
                     ? 'project-created'
                     : existingPick.payload.kind,
                 destinationPath: existingPick.destinationPath,
+                ...(replayPort
+                    ? { previewUrl: `http://${FRESH_DEV_SERVER_HOST}:${replayPort}` }
+                    : {}),
             };
         }
         const resources = this.resources.get(args.sessionId);
@@ -920,12 +1024,65 @@ class AgentVariantsOrchestrator {
         let envelopeDestination;
         let changedFilesCount;
         let runnablePaths;
+        // Port of the committed dev/static server, when one was spawned during
+        // this commit. Surfaced on the response as `previewUrl` so the UI can
+        // restore the iframe to the committed project without falling through to
+        // the auto-static fallback.
+        let committedPreviewPort;
         if (projectContext.kind === 'fresh') {
             const destinationPath = projectContext.workspacePath;
-            this.assertDestinationAvailable(destinationPath);
+            // Realpath the destination ONCE for both the empty-check (below) and
+            // the static_preview flatten step (further down). Computing it twice
+            // could diverge if the path's realpath status changes between calls
+            // (e.g. the directory was a symlink during the empty check but got
+            // resolved between then and `mkdirSync`). `undefined` means realpath
+            // failed — caller branches treat that as "no canonical form known".
+            let realDestination;
+            try {
+                realDestination = fs_1.default.realpathSync(destinationPath);
+            }
+            catch {
+                realDestination = undefined;
+            }
             const freshMode = projectContext.executionPlan?.mode === 'vite_app'
                 ? 'vite_app'
                 : 'static_preview';
+            // vite_app: strict emptiness check — that lane renames a worktree into
+            // destinationPath and would clobber user files.
+            // static_preview: the agent intentionally wrote sibling assets under
+            // workspacePath (via `output.assetBase`) before reporting succeeded —
+            // those per-variant subdirs ARE the deliverable. Allow exactly the
+            // assetBase entries known to this session; anything else still
+            // triggers DESTINATION_NOT_EMPTY.
+            if (freshMode === 'vite_app') {
+                this.assertDestinationAvailable(destinationPath);
+            }
+            else {
+                // Compare assetBase entries (which are realpath'd by
+                // resolveStaticPreviewAssetBase) against the realpath'd destination
+                // — on macOS `/tmp` is a symlink to `/private/tmp`, and a raw
+                // string comparison would falsely reject every entry.
+                const compareBase = realDestination ?? destinationPath;
+                // When ANY variant's assetBase is the destination itself (the agent
+                // wrote files directly at the workspace root rather than under a
+                // per-variant subdir), the empty-check would treat the agent's own
+                // deliverable as foreign content. Skip the check in that case — the
+                // workspace IS the deliverable; commit will overwrite index.html
+                // below.
+                const anyAssetBaseIsDestination = [
+                    ...resources.staticPreviews.values(),
+                ].some((sp) => sp.assetBase === compareBase);
+                if (!anyAssetBaseIsDestination) {
+                    const allowed = new Set();
+                    for (const sp of resources.staticPreviews.values()) {
+                        if (sp.assetBase &&
+                            isStrictlyInside(sp.assetBase, compareBase)) {
+                            allowed.add(path_1.default.basename(sp.assetBase));
+                        }
+                    }
+                    this.assertDestinationAvailable(destinationPath, allowed);
+                }
+            }
             if (freshMode === 'vite_app') {
                 // Vite_app: the deliverable is the entire variant worktree, not a
                 // single HTML file. When the worktree lives on the same volume as
@@ -983,6 +1140,16 @@ class AgentVariantsOrchestrator {
                     // install — the agent's commit_variant call should return
                     // immediately — but chain the dev-server start to it so the iframe
                     // recovers without manual intervention once deps are ready.
+                    //
+                    // NOTE: `committedPreviewPort` stays undefined on this branch by
+                    // design — the install + start sequence takes minutes, far longer
+                    // than the response can wait. The iframe's `switchPreviewPort`
+                    // callback (invoked from `startCommittedDevServer` when the
+                    // server finally comes up) retargets the proxy then, so the
+                    // iframe reaches the new server without the URL being on the
+                    // commit response. The response surface stays `previewUrl?:` (the
+                    // field is optional) and consumers fall back to the proxy
+                    // upstream when it's absent.
                     void this.installDependencies(destinationPath)
                         .then(() => this.startCommittedDevServer({
                         resources,
@@ -1015,9 +1182,10 @@ class AgentVariantsOrchestrator {
                     // destination the user would see "preview disconnected" the moment
                     // they commit. Spawn one and retarget the proxy. Best-effort: if
                     // it fails, the user can `npm run dev` themselves at destination.
-                    await this.startCommittedDevServer({
+                    committedPreviewPort = await this.startCommittedDevServer({
                         resources,
                         destinationPath,
+                        mode: 'vite_app',
                     });
                 }
                 payload = {
@@ -1047,13 +1215,94 @@ class AgentVariantsOrchestrator {
                 }
                 try {
                     fs_1.default.mkdirSync(destinationPath, { recursive: true });
+                    // If the chosen variant has an `assetBase` subdir under
+                    // destinationPath (e.g. `<workspace>/var-1` containing
+                    // `avatar.glb`), move its contents up to the destination root so
+                    // the committed HTML can reference them as `./avatar.glb`. Then
+                    // delete every OTHER static_preview record's assetBase — the
+                    // unchosen variants' sibling assets are no longer relevant once
+                    // the user picked. Both steps run before the canonical index.html
+                    // is written so the chosen variant's on-disk index.html (if any)
+                    // gets overwritten by the inlined version below.
+                    // assetBase entries are realpath'd; compare against the realpath
+                    // of destinationPath so symlink-stripped paths line up (macOS:
+                    // `/tmp` → `/private/tmp`). `realDestination` was computed once
+                    // at the top of the fresh branch — re-realpath in case `mkdirSync`
+                    // above just created the directory (the initial computation may
+                    // have returned undefined when the dir didn't yet exist).
+                    let flattenBase = realDestination;
+                    if (!flattenBase) {
+                        try {
+                            flattenBase = fs_1.default.realpathSync(destinationPath);
+                        }
+                        catch {
+                            flattenBase = destinationPath;
+                        }
+                    }
+                    const chosenAssetBase = staticPreview?.assetBase;
+                    // Skip flattening when assetBase IS the destination — the agent
+                    // wrote files directly at the workspace root, so there's no subdir
+                    // to flatten. Only move when assetBase is a strict descendant.
+                    if (chosenAssetBase &&
+                        isStrictlyInside(chosenAssetBase, flattenBase)) {
+                        for (const entry of fs_1.default.readdirSync(chosenAssetBase)) {
+                            const src = path_1.default.join(chosenAssetBase, entry);
+                            const dst = path_1.default.join(flattenBase, entry);
+                            // Self-collision guard: when an agent names a child the same
+                            // as the parent dir (e.g. `var-1/var-1/`), `dst` resolves to
+                            // `chosenAssetBase` itself. The rmSync below would then delete
+                            // the parent — including every remaining entry we're about to
+                            // move — and the next iteration's `renameSync` would fail
+                            // with ENOENT. The agent's last attempted variant would also
+                            // be silently dropped. Skip this entry; we still rm the
+                            // parent at the end of the loop.
+                            if (path_1.default.resolve(dst) === path_1.default.resolve(chosenAssetBase)) {
+                                continue;
+                            }
+                            if (fs_1.default.existsSync(dst)) {
+                                fs_1.default.rmSync(dst, { recursive: true, force: true });
+                            }
+                            // Cross-volume safety: rename fails with EXDEV when src and
+                            // dst are on different mounts (possible when the user's
+                            // workspacePath crosses a symlink to another volume). Fall
+                            // back to recursive copy + remove so the commit doesn't die.
+                            try {
+                                fs_1.default.renameSync(src, dst);
+                            }
+                            catch (err) {
+                                const code = err.code;
+                                if (code !== 'EXDEV')
+                                    throw err;
+                                fs_1.default.cpSync(src, dst, { recursive: true });
+                                fs_1.default.rmSync(src, { recursive: true, force: true });
+                            }
+                        }
+                        fs_1.default.rmSync(chosenAssetBase, { recursive: true, force: true });
+                    }
+                    for (const other of resources.staticPreviews.values()) {
+                        if (other.workItemId === args.variantId)
+                            continue;
+                        if (other.assetBase &&
+                            isStrictlyInside(other.assetBase, flattenBase)) {
+                            fs_1.default.rmSync(other.assetBase, { recursive: true, force: true });
+                        }
+                    }
                     fs_1.default.writeFileSync(path_1.default.join(destinationPath, 'index.html'), staticPreview?.html ?? htmlFromSnapshot ?? '', 'utf8');
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
                     throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to write static preview to ${destinationPath}: ${message}`);
                 }
-                changedFilesCount = 1;
+                changedFilesCount = countWorktreeFiles(destinationPath);
+                // Spawn a static file server at destinationPath and retarget the
+                // proxy so the iframe stays live across commit (parity with the
+                // vite_app rename path). Best-effort: a failure leaves the iframe
+                // showing "preview disconnected" but doesn't fail the commit.
+                committedPreviewPort = await this.startCommittedDevServer({
+                    resources,
+                    destinationPath,
+                    mode: 'static_preview',
+                });
                 payload = {
                     kind: 'project-created',
                     destinationPath,
@@ -1176,6 +1425,9 @@ class AgentVariantsOrchestrator {
             changedFilesCount,
             payloadKind: payload.kind,
             destinationPath: envelopeDestination,
+            ...(committedPreviewPort
+                ? { previewUrl: `http://${FRESH_DEV_SERVER_HOST}:${committedPreviewPort}` }
+                : {}),
         };
     }
     async cleanupCommittedSession(sessionId) {
@@ -1190,11 +1442,22 @@ class AgentVariantsOrchestrator {
      * at success time) are both tolerated — neither is user-authored content
      * that would be clobbered by the materialize step.
      */
-    assertDestinationAvailable(destinationPath) {
+    assertDestinationAvailable(destinationPath, 
+    /**
+     * Top-level entries the caller knows it owns and can safely overwrite.
+     * Used by the fresh static_preview commit path so a directory holding
+     * only this session's per-variant `assetBase` subdirs still counts as
+     * "available" — those came from the agent during generation. Any entry
+     * NOT in this set (and not the standard `.rivet`/`.gitignore` exemptions)
+     * still triggers DESTINATION_NOT_EMPTY.
+     */
+    additionalAllowedEntries = new Set()) {
         if (!fs_1.default.existsSync(destinationPath))
             return;
         const entries = fs_1.default.readdirSync(destinationPath);
-        const userVisibleEntries = entries.filter((entry) => entry !== '.rivet' && entry !== '.gitignore');
+        const userVisibleEntries = entries.filter((entry) => entry !== '.rivet' &&
+            entry !== '.gitignore' &&
+            !additionalAllowedEntries.has(entry));
         if (userVisibleEntries.length === 0)
             return;
         throw new errors_1.AgentVariantsError('DESTINATION_NOT_EMPTY', `Destination ${destinationPath} is not empty (${userVisibleEntries.length} entries) — refuse to materialize.`);
@@ -1485,10 +1748,15 @@ class AgentVariantsOrchestrator {
             if (staticPreview) {
                 const input = this.store.getWorkItemInput(sessionId, workItemId);
                 if (input.briefId) {
+                    const resolvedAssetBase = resolveStaticPreviewAssetBase({
+                        assetBase: staticPreview.assetBase,
+                        projectContext: this.store.getProjectContext(sessionId),
+                    });
                     const record = {
                         workItemId,
                         briefId: input.briefId,
                         html: staticPreview.html,
+                        ...(resolvedAssetBase ? { assetBase: resolvedAssetBase } : {}),
                     };
                     resources.staticPreviews.set(workItemId, record);
                     if (this.store.getProjectContext(sessionId).kind === 'fresh') {
@@ -2120,34 +2388,61 @@ class AgentVariantsOrchestrator {
      * lingering registry instead of killing it. Best-effort: a failure here is
      * non-fatal — the commit still succeeds; the user just has to run
      * `npm run dev` themselves to bring the preview back.
+     *
+     * `mode` selects the server flavor: `vite_app` spawns Vite via `npm run
+     * dev`; `static_preview` spawns the in-tree static file server bound to
+     * the destination directory (no install, no build, ~ms startup).
      */
     async startCommittedDevServer(args) {
+        const mode = args.mode ?? 'vite_app';
         try {
             const port = await this.worktrees.getFreePort();
-            const proc = await this.worktrees.startDevServer(args.destinationPath, port, 'npm', [
-                'run',
-                'dev',
-                '--',
-                '--port',
-                String(port),
-                '--host',
-                FRESH_DEV_SERVER_HOST,
-            ], { PORT: String(port) });
+            const proc = mode === 'static_preview'
+                ? await this.startStaticPreviewServerImpl({
+                    rootPath: args.destinationPath,
+                    port,
+                    host: FRESH_DEV_SERVER_HOST,
+                })
+                : await this.worktrees.startDevServer(args.destinationPath, port, 'npm', [
+                    'run',
+                    'dev',
+                    '--',
+                    '--port',
+                    String(port),
+                    '--host',
+                    FRESH_DEV_SERVER_HOST,
+                ], { PORT: String(port) });
             args.resources.committedDevServer = {
                 proc,
                 port,
                 path: args.destinationPath,
             };
+            // Advertise the Rivet-owned server on devServerHealth so the iframe's
+            // upstream probe stops reporting `ownership: 'none'`. Distinct from
+            // switchPreviewPort: this updates health metadata, switchPreviewPort
+            // retargets the proxy. Both fire here because the commit-handoff is
+            // the only place Rivet legitimately takes ownership of the dev
+            // server — variant cycling and cancel only retarget, they don't
+            // touch health (which the user's external dev server owns during a
+            // regular session).
+            try {
+                this.setCommittedDevServerHealth?.(port);
+            }
+            catch (err) {
+                log.warn(`setCommittedDevServerHealth(${port}) after committed dev server start failed`, err);
+            }
             try {
                 this.switchPreviewPort?.(port);
             }
             catch (err) {
                 log.warn(`switchPreviewPort(${port}) after committed dev server start failed`, err);
             }
-            log.info(`Committed dev server up at ${args.destinationPath} on port ${port}`);
+            log.info(`Committed ${mode} dev server up at ${args.destinationPath} on port ${port}`);
+            return port;
         }
         catch (err) {
-            log.warn(`Failed to start committed dev server at ${args.destinationPath} — iframe may show "preview disconnected" until user runs npm run dev`, err);
+            log.warn(`Failed to start committed ${mode} dev server at ${args.destinationPath} — iframe may show "preview disconnected" until user runs the dev server manually`, err);
+            return undefined;
         }
     }
     /**
@@ -2160,6 +2455,17 @@ class AgentVariantsOrchestrator {
     async stopLingeringCommittedDevServers() {
         const entries = [...this.lingeringCommittedDevServers.entries()];
         this.lingeringCommittedDevServers.clear();
+        // Clear the Rivet-owned-server advertisement on `devServerHealth` so the
+        // probe doesn't keep reporting a port that's about to stop listening.
+        // Safe to call even when no committed server existed for this process.
+        if (entries.length > 0) {
+            try {
+                this.setCommittedDevServerHealth?.(null);
+            }
+            catch (err) {
+                log.warn('setCommittedDevServerHealth(null) on lingering teardown failed', err);
+            }
+        }
         await Promise.all(entries.map(async ([sessionId, entry]) => {
             try {
                 await this.worktrees.stopDevServer(entry.proc);
@@ -2268,6 +2574,91 @@ function normalizeOutput(output) {
     }
     return output;
 }
+/**
+ * `true` when `child` is a strict descendant of `parent` (resolved). Used by
+ * the static_preview commit branch before rm/rename to make sure we never
+ * touch anything outside the variant's workspace.
+ */
+function isStrictlyInside(child, parent) {
+    const c = path_1.default.resolve(child);
+    const p = path_1.default.resolve(parent);
+    return c !== p && c.startsWith(p + path_1.default.sep);
+}
+/**
+ * Sandbox the agent's `output.assetBase` to a path inside the session
+ * workspace. Accepts either an absolute path (used as-is after the
+ * within-workspace check) or a path relative to the fresh-session
+ * `workspacePath`. Returns `undefined` for non-fresh sessions, missing
+ * directories, or paths that escape the workspace via `..` or symlinks.
+ *
+ * `assetBase` is agent-controlled, so a prompt-injected variant could point
+ * it at a symlink whose real target is outside `workspacePath` — and the
+ * asset endpoint would then happily serve files like `~/.ssh/id_rsa` or
+ * `.env`. Resolving with `fs.realpathSync` collapses symlinks before the
+ * containment check, so the check applies to the real target, not the link.
+ */
+function resolveStaticPreviewAssetBase(args) {
+    if (!args.assetBase)
+        return undefined;
+    if (args.projectContext.kind !== 'fresh')
+        return undefined;
+    let workspace;
+    let resolved;
+    try {
+        // Defense against an agent that subverts the sandbox by replacing the
+        // Rivet-created `workspacePath` directory with a symlink. Plain
+        // `realpath` would silently follow that symlink and the containment
+        // check below would then trust the wrong root.
+        //
+        // Two layers:
+        //   1. `lstat` the workspacePath itself — if it's a symlink (rather
+        //      than a real directory Rivet created), reject outright. This
+        //      catches the obvious swap `ln -sf $HOME <workspacePath>` and the
+        //      subtler swap to a sibling like `<workspaceRoot>` itself
+        //      (which would pass any subsequent containment check based on
+        //      ancestor matching).
+        //   2. realpath both and require the resolved workspacePath to be a
+        //      STRICT descendant of the resolved workspaceRoot — equal is not
+        //      enough (a symlink to workspaceRoot would otherwise be accepted
+        //      and the asset route would then serve files at the project
+        //      root, e.g. `.env`).
+        const wsStat = fs_1.default.lstatSync(args.projectContext.workspacePath);
+        if (wsStat.isSymbolicLink()) {
+            log.warn(`Static preview workspacePath ${args.projectContext.workspacePath} is a symlink — refusing assetBase`);
+            return undefined;
+        }
+        const realWorkspaceRoot = fs_1.default.realpathSync(args.projectContext.workspaceRoot);
+        workspace = fs_1.default.realpathSync(args.projectContext.workspacePath);
+        if (!workspace.startsWith(realWorkspaceRoot + path_1.default.sep)) {
+            log.warn(`Static preview workspacePath ${workspace} is not a strict descendant of workspaceRoot ${realWorkspaceRoot} — refusing assetBase`);
+            return undefined;
+        }
+        const candidate = path_1.default.isAbsolute(args.assetBase)
+            ? args.assetBase
+            : path_1.default.join(workspace, args.assetBase);
+        resolved = fs_1.default.realpathSync(candidate);
+    }
+    catch {
+        log.warn(`Static preview assetBase ${args.assetBase} could not be resolved — ignoring`);
+        return undefined;
+    }
+    if (resolved !== workspace && !resolved.startsWith(workspace + path_1.default.sep)) {
+        log.warn(`Static preview assetBase ${args.assetBase} escapes workspace ${workspace} — ignoring`);
+        return undefined;
+    }
+    try {
+        const stat = fs_1.default.statSync(resolved);
+        if (!stat.isDirectory()) {
+            log.warn(`Static preview assetBase ${resolved} is not a directory — ignoring`);
+            return undefined;
+        }
+        return resolved;
+    }
+    catch {
+        log.warn(`Static preview assetBase ${resolved} does not exist — ignoring`);
+        return undefined;
+    }
+}
 function parseStaticPreviewOutput(output) {
     if (!output || typeof output !== 'object')
         return null;
@@ -2276,12 +2667,16 @@ function parseStaticPreviewOutput(output) {
         return null;
     const css = output.css;
     const js = output.js;
+    const assetBase = output.assetBase;
     return {
         html: buildStaticPreviewDocument({
             html,
             css: typeof css === 'string' ? css : undefined,
             js: typeof js === 'string' ? js : undefined,
         }),
+        ...(typeof assetBase === 'string' && assetBase.length > 0
+            ? { assetBase }
+            : {}),
     };
 }
 function buildStaticPreviewDocument(input) {