thinkpool-pair 0.7.288 → 0.7.290

package/bridge.mjs

@@ -76,7 +76,7 @@ import { writeLaneArtifact, digestSlice, appendDigest, resumeLane } from './flow
 import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
 import { startPreview, stopAllPreviews, previews } from './flow-preview.mjs'
 import { ViewportManager, createViewportTools, sharedViewportBrowser } from './viewport.mjs'
-import { deleteDesignAssetDraft, designPrompt, designTranscript, materializeDesignAsset, resolveDesignSource, resolveManifestDesignSource, restoreDesignSources, syncRealtimeAuth, validateDesignBatchRequest } from './design-edit.mjs'
+import { deleteDesignAssetDraft, designPrompt, designTranscript, materializeDesignAsset, refreshDesignSource, resolveManifestDesignSource, restoreDesignSources, syncRealtimeAuth, validateDesignBatchRequest } from './design-edit.mjs'
 // FL-M9 — per-lane preview servers leak (one per done lane, never stopped until shutdown).
 // Lane previews are keyed `lane:<flowId>:<laneId>`; stop a whole flow's set when it assembles
 // (the assembled preview supersedes them) or when a lane is reverted.
@@ -1415,7 +1415,7 @@ const finishDesign = (term, state, extra = {}) => {
 const maybeVerifyDesign = (term) => {
   const active = designActive.get(term)
   if (!active?.resultOk || !active.proof) return
-  finishDesign(term, 'verified-live', { message: 'Verified at desktop and mobile.', artifact: active.proof, canRestore: true })
+  finishDesign(term, 'verified-live', { message: 'Verified at desktop and mobile.', artifact: active.proof, canRestore: active.record.sourceKind !== 'preview' })
 }
 
 function pumpDesign(term) {
@@ -1433,7 +1433,7 @@ function pumpDesign(term) {
   if (lane.session?.turnActive) return
   queue.shift()
   const current = designArtifacts.get(next.record.previewId)
-  const live = current && resolveDesignSource(current.sourcePath, current.workspaceRoot)
+  const live = current && refreshDesignSource(current)
   if (!current || !live || live.revision !== next.record.revision) {
     designStatus({ previewId: next.record.previewId, requestId: next.request.cid, state: 'stale', message: 'The artifact changed. Reselect the element.' })
     return pumpDesign(term)
@@ -1488,7 +1488,7 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
   if (!m?.slug) return
   const producer = trustedDesignSource ? sessions.get(term) : null
   const designRecord = producer
-    ? resolveManifestDesignSource(m, producer.cwd || process.cwd())
+    ? resolveManifestDesignSource(m, producer.cwd || process.cwd(), { box })
     : null
   // 2026-07-07: these used to swallow read errors silently — a transient
   // unreadable file (race with the render script, permissions, mid-write)
@@ -1542,8 +1542,11 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
       const dual = !!(paths?.html && paths?.desktop && paths?.mobile && m.desktop && m.mobile)
       const expectedRevision = active?.restoreRecord?.revision
       const revisionProvesChange = expectedRevision ? designRecord.revision === expectedRevision : designRecord.revision !== active?.record?.revision
-      if (correlated && dual && designRecord.sourcePath === active.record.sourcePath && revisionProvesChange) {
-        designRestore.set(designRecord.previewId, { priorRecord: active.record, request: active.request })
+      const sameTarget = active?.record?.sourceKind === 'preview'
+        ? designRecord.sourceKind === 'preview' && designRecord.captureKey === active.record.captureKey
+        : designRecord.sourcePath === active?.record?.sourcePath
+      if (correlated && dual && sameTarget && revisionProvesChange) {
+        if (active.record.sourceKind !== 'preview') designRestore.set(designRecord.previewId, { priorRecord: active.record, request: active.request })
         active.proof = artifact
         maybeVerifyDesign(term)
       }
@@ -2126,7 +2129,14 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   if (restoredDesigns.length) process.stderr.write(`\n  ◆ restored ${restoredDesigns.length} Thinkpool Design artifact${restoredDesigns.length === 1 ? '' : 's'} (${id.slice(0, 8)}).\n`)
   // Visual QA runs in the bridge process, outside either agent runtime's sandbox.
   // It remains scoped to this lane's cwd and private mockup outbox.
-  entry.viewport = new ViewportManager({ workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox })
+  entry.viewport = new ViewportManager({
+    workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox,
+    designContext: () => {
+      const active = designActive.get(id)
+      if (!active || active.record.sourceKind !== 'preview') return null
+      return { requestId: active.request.cid, parentRevision: active.record.revision, captureKey: active.record.captureKey }
+    },
+  })
   if (entry.log.length) process.stderr.write(`\n  ◆ restored ${entry.log.length} prior events (${id.slice(0, 8)})${resume ? ' + resuming live context' : ''}.\n`)
   // Persist the permission mode alongside the transcript so a bridge restart
   // restores the session in the SAME mode (a bypass room stays bypass on resume).
@@ -3838,8 +3848,8 @@ channel
     // inferred "working…" state (no turn → no result to clear it; the old bug).
     // Instead announce a ◆ control line both readers see. Claude /compact + any
     // other slash still flow through as a real, self-terminating turn.
-    const ctlLine = (ctlText) => {
-      const evt = { kind: 'control', text: ctlText, by: payload.by, cid: payload.cid }
+    const ctlLine = (ctlText, details = {}) => {
+      const evt = { kind: 'control', text: ctlText, by: payload.by, cid: payload.cid, ...details }
       pushLog(s, evt)
       bcast('code-event', { term: payload.term, evt })
     }
@@ -3935,7 +3945,7 @@ channel
     if (/^\/compact\s*$/.test(text)) {
       if (s.runtime === 'codex') {
         if (s.session.turnActive) {
-          ctlLine('finish or stop the current Codex turn before compacting context')
+          ctlLine('Compact after this turn ends.', { tone: 'caution' })
           return
         }
         const recap = buildRecapFromLog(s.log, RECAP_CAP, { reason: 'compact' })
@@ -4704,7 +4714,7 @@ const seenDesignRequests = new Set()
 designChannel
   .on('broadcast', { event: 'design-capability' }, ({ payload }) => {
     const record = payload?.previewId && designArtifacts.get(String(payload.previewId))
-    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    const live = record && refreshDesignSource(record)
     const ok = !!record && !!live && live.revision === record.revision && record.revision === payload?.revision && sessions.has(record.term)
     designChannel.send({ type: 'broadcast', event: 'design-capability-res', payload: { previewId: String(payload?.previewId || ''), revision: String(payload?.revision || ''), ok } })
   })
@@ -4759,7 +4769,7 @@ designChannel
     const requestId = String(payload?.cid || '').slice(0, 80)
     const record = designArtifacts.get(previewId)
     const restore = designRestore.get(previewId)
-    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    const live = record && refreshDesignSource(record)
     if (!requestId || !record || !restore?.priorRecord?.backupPath || !live || live.revision !== record.revision || payload?.revision !== record.revision) {
       designStatus({ previewId, requestId, state: 'stale', message: 'That verified revision can no longer be restored safely.' })
       return

package/design-edit.mjs

@@ -50,15 +50,49 @@ export function resolveDesignSource(file, workspaceRoot) {
   return { previewId, revision, sourcePath, workspaceRoot: root, source }
 }
 
+export function resolvePreviewDesignSource(manifest, workspaceRoot, box) {
+  if (!manifest || manifest.sourceKind !== 'preview' || !manifest.snapshot || !workspaceRoot || !box) return null
+  let sourcePath, root, outbox
+  try {
+    sourcePath = fs.realpathSync(manifest.snapshot)
+    root = fs.realpathSync(workspaceRoot)
+    outbox = fs.realpathSync(box)
+    const stat = fs.statSync(sourcePath)
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) return null
+  } catch { return null }
+  const rel = path.relative(outbox, sourcePath)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || path.extname(sourcePath).toLowerCase() !== '.html') return null
+  const route = clean(manifest.route || '/', 500)
+  const previewRoot = clean(manifest.previewRoot || 'dist', 500)
+  const captureKey = clean(manifest.captureKey, 1000)
+  if (!route.startsWith('/') || !captureKey || captureKey !== JSON.stringify([previewRoot, route])) return null
+  const source = fs.readFileSync(sourcePath, 'utf8')
+  const revision = sourceRevision(source)
+  const previewId = crypto.createHash('sha256')
+    .update(`${root}\0${captureKey}\0${revision}`)
+    .digest('base64url').slice(0, 32)
+  return { sourceKind: 'preview', previewId, revision, sourcePath, workspaceRoot: root, source, outbox, route, previewRoot, captureKey }
+}
+
 // Older lane worktrees predate the explicit `source` manifest field and emit the
 // authored mockup path as `html` only. Preserve the explicit field when present;
 // otherwise let the same containment/generated-output checks decide whether the
 // HTML path is canonical editable source or view-only render evidence.
-export function resolveManifestDesignSource(manifest, workspaceRoot) {
+export function resolveManifestDesignSource(manifest, workspaceRoot, { box } = {}) {
   if (!manifest || typeof manifest !== 'object') return null
+  if (manifest.sourceKind === 'preview') return resolvePreviewDesignSource(manifest, workspaceRoot, box)
   return resolveDesignSource(manifest.source || manifest.html, workspaceRoot)
 }
 
+export function refreshDesignSource(record) {
+  if (!record) return null
+  if (record.sourceKind !== 'preview') return resolveDesignSource(record.sourcePath, record.workspaceRoot)
+  return resolvePreviewDesignSource({
+    sourceKind: 'preview', snapshot: record.sourcePath, route: record.route,
+    previewRoot: record.previewRoot, captureKey: record.captureKey,
+  }, record.workspaceRoot, record.outbox)
+}
+
 // Design provenance is intentionally host-only, but it must survive a bridge
 // restart. Rebuild the in-memory registry from manifests already written by the
 // trusted lane render workflow; do not re-upload or re-broadcast old cards.
@@ -79,7 +113,7 @@ export function restoreDesignSources(box, workspaceRoot, term, limit = 100) {
   for (const { file } of files) {
     try {
       const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
-      const record = resolveManifestDesignSource(manifest, workspaceRoot)
+      const record = resolveManifestDesignSource(manifest, workspaceRoot, { box })
       if (!record) continue
       Object.assign(record, {
         term,
@@ -256,5 +290,8 @@ export function designPrompt({ record, request, by, restore = false, priorRecord
     : batch
       ? batch.map((edit, index) => `Edit ${index + 1} of ${batch.length} · ${edit.mode}\nSelected element:\n${JSON.stringify(edit.target, null, 2)}\n\n${designAction(edit)}`).join('\n\n---\n\n')
       : `Selected element:\n${JSON.stringify(request.target, null, 2)}\n\n${designAction(request)}`
+  if (record.sourceKind === 'preview') {
+    return `A room member used ThinkPool Design Mode on a rendered application preview. This is an authorized source edit in your current workspace.\n\nRendered snapshot (read-only evidence): ${record.sourcePath}\nApplication workspace: ${record.workspaceRoot}\nPreview root: ${record.previewRoot}\nPreview route: ${record.route}\nExpected snapshot revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the rendered snapshot and confirm the selected element still matches before editing.\n- Do not edit the snapshot. Locate the represented element in the application source inside the workspace and make the smallest source change that produces the requested result.\n- If the selector, text, or surrounding structure does not identify one application source location unambiguously, stop without editing and explain that the person must reselect it.\n${batch ? '- Apply the queued edits in order in one source pass, then build and capture once after the full batch.' : '- Apply only the requested change, then build and capture once.'}\n- Preserve the product page faithfully: keep its real copy, structure, fonts, assets, spacing, responsive behavior, and unrelated source unchanged.\n- Run the project build, then use preview_start with root ${record.previewRoot} and preview_capture with path ${record.route}, both viewports, and title ${JSON.stringify(record.title || record.slug || 'Design preview')}. The bridge correlates that capture to this request.\n- Do not claim the edit is verified until the room receives the new desktop and mobile capture.\n- If the build or capture fails, report the failure instead of substituting a screenshot-only result.`
+  }
   return `A room member used ThinkPool Design Mode on the artifact below. This is an authorized source edit in your current workspace.\n\nArtifact source: ${record.sourcePath}\nWorkspace: ${record.workspaceRoot}\nExpected source revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${restore ? 'restore the immediately previous verified Design Mode revision' : batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the exact artifact source and confirm its revision/content still matches every selected element before editing.\n${batch ? '- Apply the queued edits in order in one source pass, then render once after the full batch.' : '- Apply only the requested change, then render the result once.'}\n- Edit the canonical source above; do not search for or edit a different plausible file.\n- Preserve the represented product page faithfully: keep its real copy, structure, fonts, assets, spacing, and responsive behavior except for the selected edits. Never replace it with generic mockup content.\n- Preserve unrelated content and styling.\n- Use the existing mockup render workflow to produce both desktop and mobile captures after the edit. Run it with TP_DESIGN_REQUEST_ID=${request.cid} and TP_DESIGN_PARENT_REVISION=${record.revision} in the command environment so the proof correlates to this request.\n- Do not claim this is live until both captures succeed and the room receives the manifest.\n- If any target is stale or ambiguous, stop without editing and explain that the person must reselect it.`
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.288",
+  "version": "0.7.290",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 8,
+  "bundleVersion": 9,
   "contracts": [
     {
       "id": "room-coordination",
@@ -168,9 +168,9 @@
     },
     {
       "id": "design-workspace",
-      "version": 3,
-      "interactionPrompt": "DESIGN EDITING MODEL: a trusted source-backed mockup card offers Edit in Design. That explicit action—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, that lane edits the canonical authored HTML, and a successful desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. A preview_capture card is visual evidence, not an editable Design artifact. For direction rounds, deliver every option as its own source-backed Design card; a multi-option gallery may accompany them for comparison but must never be the only editable artifact.",
-      "turnReminder": "DESIGN ROUTE: authored HTML must produce a source-backed Thinkpool Design card with verified desktop and mobile renders. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For direction rounds, deliver every option as a separate source-backed Design card; gallery navigation is not a substitute for separately editable artifacts. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
+      "version": 4,
+      "interactionPrompt": "DESIGN EDITING MODEL: every bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For authored HTML, the producing lane edits the canonical HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. For direction rounds, deliver every option as its own Design card; a multi-option gallery may accompany the cards for comparison but must never be the only editable artifact.",
+      "turnReminder": "DESIGN ROUTE: preview_capture and authored HTML must produce editable Thinkpool Design cards with verified desktop and mobile renders. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For direction rounds, deliver every option as a separate Design card; gallery navigation is not a substitute for separately editable artifacts. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
       "impact": [
         {"path": "src/pages/code/design/"},
         {"path": "src/pages/code/structured.jsx", "diffPattern": "Edit in Design|openMockup|tp-mockup-view|sourceKnown"},

package/viewport.mjs

@@ -26,6 +26,7 @@ export const DEFAULT_VIEWPORTS = Object.freeze({
 const MAX_CAPTURE_HEIGHT = 20000
 const MAX_SETTLE_MS = 5000
 const CDP_TIMEOUT_MS = 12000
+const MAX_PORTABLE_SNAPSHOT_BYTES = 1_900_000
 
 const isInside = (parent, child) => {
   const rel = path.relative(parent, child)
@@ -267,6 +268,79 @@ export class CdpBrowser {
     })
   }
 
+  async snapshot({ url, viewport = DEFAULT_VIEWPORTS.desktop, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      // Freeze the rendered DOM, not the build entry document. A Vite/React entry
+      // depends on root-relative chunks and often boots to an empty shell in a
+      // sandboxed srcDoc; the settled DOM plus same-origin CSS/assets is portable.
+      const expression = `(async () => {
+        const clone = document.documentElement.cloneNode(true);
+        clone.querySelectorAll('script,link[rel="modulepreload"],link[rel="preload"]').forEach((node) => node.remove());
+        clone.querySelectorAll('*').forEach((node) => {
+          for (const attr of [...node.attributes]) if (/^on/i.test(attr.name)) node.removeAttribute(attr.name);
+          if (node instanceof HTMLInputElement) node.removeAttribute('value');
+          if (node instanceof HTMLTextAreaElement) node.textContent = '';
+        });
+        const css = [];
+        for (const sheet of [...document.styleSheets]) {
+          try { css.push([...sheet.cssRules].map((rule) => rule.cssText).join('\\n')); } catch {}
+        }
+        clone.querySelectorAll('style,link[rel="stylesheet"]').forEach((node) => node.remove());
+        const head = clone.querySelector('head') || clone.insertBefore(document.createElement('head'), clone.firstChild);
+        const style = document.createElement('style');
+        style.setAttribute('data-thinkpool-snapshot', '');
+        style.textContent = css.join('\\n');
+        head.appendChild(style);
+
+        const assetUrls = new Set();
+        const remember = (raw) => {
+          if (!raw || /^(data:|blob:|#)/i.test(raw)) return;
+          try {
+            const absolute = new URL(raw, location.href);
+            if (absolute.origin === location.origin) assetUrls.add(absolute.href);
+          } catch {}
+        };
+        clone.querySelectorAll('[src],[poster]').forEach((node) => {
+          remember(node.getAttribute('src'));
+          remember(node.getAttribute('poster'));
+        });
+        for (const match of style.textContent.matchAll(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi)) remember(match[2]);
+
+        const replacements = new Map();
+        let inlinedBytes = 0;
+        for (const absolute of assetUrls) {
+          try {
+            const response = await fetch(absolute);
+            const buffer = await response.arrayBuffer();
+            if (!response.ok || buffer.byteLength > 512000 || inlinedBytes + buffer.byteLength > 1000000) continue;
+            const bytes = new Uint8Array(buffer);
+            let binary = '';
+            for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+            replacements.set(absolute, 'data:' + (response.headers.get('content-type') || 'application/octet-stream') + ';base64,' + btoa(binary));
+            inlinedBytes += buffer.byteLength;
+          } catch {}
+        }
+        const replaceAsset = (raw) => {
+          try { return replacements.get(new URL(raw, location.href).href) || raw; } catch { return raw; }
+        };
+        clone.querySelectorAll('[src],[poster]').forEach((node) => {
+          for (const name of ['src', 'poster']) if (node.hasAttribute(name)) node.setAttribute(name, replaceAsset(node.getAttribute(name)));
+          node.removeAttribute('srcset');
+        });
+        style.textContent = style.textContent.replace(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi, (_all, quote, raw) => 'url("' + replaceAsset(raw) + '")');
+        return '<!doctype html>\\n' + clone.outerHTML;
+      })()`
+      const result = await pipe.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId)
+      if (result.exceptionDetails || typeof result.result?.value !== 'string') {
+        const detail = result.exceptionDetails?.exception?.description || result.exceptionDetails?.text || result.result?.description
+        throw new Error(`Could not freeze the rendered preview for Design${detail ? `: ${detail}` : '.'}`)
+      }
+      const html = result.result.value
+      if (!html.trim() || Buffer.byteLength(html) > MAX_PORTABLE_SNAPSHOT_BYTES) throw new Error('The rendered preview is too large to make editable.')
+      return html
+    })
+  }
+
   async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
     return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
       const expression = `(() => {
@@ -302,12 +376,13 @@ export class CdpBrowser {
 export const sharedViewportBrowser = new CdpBrowser()
 
 export class ViewportManager {
-  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview } = {}) {
+  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null } = {}) {
     this.workspaceRoot = path.resolve(workspaceRoot || process.cwd())
     this.ownerId = ownerId || randomUUID()
     this.outbox = outbox || path.join(os.tmpdir(), 'thinkpool-viewport-captures', this.ownerId)
     this.browser = browser
     this.startPreviewImpl = startPreviewImpl
+    this.designContext = typeof designContext === 'function' ? designContext : () => null
     this.previewId = `viewport:${this.ownerId}`
     this.preview = null
     this.root = null
@@ -344,7 +419,8 @@ export class ViewportManager {
   }
 
   async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300 } = {}) {
-    const url = this.pageUrl(route)
+    const normalizedRoute = normalizeRoute(route)
+    const url = this.pageUrl(normalizedRoute)
     const names = viewports === 'both' ? ['desktop', 'mobile'] : [viewports]
     if (names.some((name) => !DEFAULT_VIEWPORTS[name])) throw new Error('viewports must be "both", "desktop", or "mobile".')
     await fsp.mkdir(this.outbox, { recursive: true })
@@ -356,20 +432,28 @@ export class ViewportManager {
       await fsp.writeFile(file, result.png)
       captures[name] = { ...result, file }
     }
-    // A preview root may be a multi-file build. Its index.html is not a portable
-    // artifact: root-relative chunks cannot reliably boot when that text is later
-    // injected into a sandboxed srcDoc (Windows Edge exposed the permanent loader).
-    // preview_capture is therefore screenshot-only evidence. Editable mockups use
-    // render.sh's explicit trusted `source` contract instead.
+    const snapshotViewport = names.includes('desktop') ? DEFAULT_VIEWPORTS.desktop : DEFAULT_VIEWPORTS[names[0]]
+    const snapshot = await this.browser.snapshot({ url, viewport: snapshotViewport, waitMs })
+    const snapshotPath = path.join(this.outbox, `${slug}--source.html`)
+    await fsp.writeFile(snapshotPath, snapshot)
+    const workspace = await fsp.realpath(this.workspaceRoot)
+    const previewRoot = path.relative(workspace, this.root) || '.'
+    const captureKey = JSON.stringify([previewRoot, normalizedRoute])
+    const active = this.designContext() || null
+    const correlation = active?.captureKey === captureKey
+      ? { designRequestId: active.requestId, parentRevision: active.parentRevision }
+      : {}
     const manifest = {
       slug, title: String(title || 'Viewport capture').slice(0, 120),
       desktop: captures.desktop?.file || '', mobile: captures.mobile?.file || '', ts: Date.now(),
+      sourceKind: 'preview', snapshot: snapshotPath, previewRoot, route: normalizedRoute, captureKey,
+      ...correlation,
     }
     const manifestPath = path.join(this.outbox, `${slug}.json`)
     const tmp = `${manifestPath}.tmp`
     await fsp.writeFile(tmp, JSON.stringify(manifest))
     await fsp.rename(tmp, manifestPath)
-    return { url, slug, manifestPath, captures }
+    return { url, slug, manifestPath, captures, snapshotPath }
   }
 
   inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {