opendevbrowser 0.0.32 → 0.0.34

package/dist/{chunk-HBK56JST.js → chunk-XRDCSHKZ.js}

@@ -46,20 +46,23 @@ import {
   CANVAS_VALIDATION_TARGET_BLOCK_ON_CODES,
   CANVAS_VISUAL_DIRECTION_PROFILES,
   ChallengeOrchestrator,
+  buildCanvasCommandValidationEnvelope,
+  buildCanvasRepairEnvelope,
   canonicalizeUrl,
   createDefaultRuntime,
   extractStructuredContent,
   inspectChallengePlanFromRuntime,
   resolveChallengeAutomationPolicy,
   resolveProviderRuntimePolicy,
+  resolveWorkflowArtifactRoot,
   toSnippet
-} from "./chunk-RO3SMXF3.js";
+} from "./chunk-5FDXH4CS.js";
 import {
   buildBlockerArtifacts,
   classifyBlockerSignal,
   createLogger,
   createRequestId
-} from "./chunk-WHQZBUNY.js";
+} from "./chunk-3WLCWHIV.js";
 import {
   ProviderRuntimeError
 } from "./chunk-FUSXMW3G.js";
@@ -3660,9 +3663,9 @@ function createCoreRuntimeAssemblies(args2) {
 import { parse, resolve as resolve6 } from "path";
 
 // src/browser/browser-manager.ts
-import { randomUUID as randomUUID10 } from "crypto";
+import { randomUUID as randomUUID11 } from "crypto";
 import { access as access2, mkdir as mkdir5, rm as rm3, writeFile as writeFile3 } from "fs/promises";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import { freemem, totalmem } from "os";
 import { Mutex } from "async-mutex";
 
@@ -4950,6 +4953,28 @@ function sanitizeWsEndpoint(wsEndpoint) {
   }
 }
 
+// src/providers/browser-output-artifacts.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join7 } from "path";
+var BROWSER_SCREENSHOT_ARTIFACT_NAMESPACE = "screenshot";
+var BROWSER_SCREENCAST_ARTIFACT_NAMESPACE = "screencast";
+var SAFE_BROWSER_ARTIFACT_NAMESPACE_PATTERN = /^[a-z0-9_-]+$/;
+function createBrowserOutputArtifactDirectory(input) {
+  const namespace = input.namespace.trim();
+  if (namespace.length === 0) {
+    throw new Error("Browser output artifact namespace cannot be empty.");
+  }
+  if (!SAFE_BROWSER_ARTIFACT_NAMESPACE_PATTERN.test(namespace)) {
+    throw new Error("Browser output artifact namespace can only contain lowercase letters, numbers, underscores, and hyphens.");
+  }
+  const root = resolveWorkflowArtifactRoot(void 0, { workspaceRoot: input.workspaceRoot });
+  const runId = randomUUID7();
+  const artifactPath = join7(root, namespace, runId);
+  mkdirSync2(artifactPath, { recursive: true, mode: 448 });
+  return { artifactPath, namespace, runId };
+}
+
 // src/browser/manager-types.ts
 var SCREENCAST_RETENTION_MS = 10 * 6e4;
 
@@ -5573,7 +5598,7 @@ var SessionStore = class {
 };
 
 // src/browser/target-manager.ts
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 var TARGET_INFO_TIMEOUT_MS = 2e3;
 var TargetManager = class {
   targets = /* @__PURE__ */ new Map();
@@ -5581,7 +5606,7 @@ var TargetManager = class {
   nameToTarget = /* @__PURE__ */ new Map();
   targetToName = /* @__PURE__ */ new Map();
   registerPage(page, name) {
-    const targetId = randomUUID7();
+    const targetId = randomUUID8();
     this.targets.set(targetId, page);
     if (!this.activeTargetId) {
       this.activeTargetId = targetId;
@@ -5899,7 +5924,7 @@ import { execFileSync } from "child_process";
 import { createDecipheriv, createHash as createHash3, pbkdf2Sync } from "crypto";
 import { cp, mkdtemp as mkdtemp2, mkdir as mkdir3, rm as rm2, stat as stat3 } from "fs/promises";
 import { tmpdir } from "os";
-import { dirname, join as join7 } from "path";
+import { dirname, join as join8 } from "path";
 var ROOT_COPY_ENTRIES = ["Local State"];
 var PROFILE_COPY_ENTRIES = [
   "Preferences",
@@ -5957,7 +5982,7 @@ async function stageSystemChromeProfile(source, stagingRoot) {
   let copiedCookieStore = false;
   for (const entry of ROOT_COPY_ENTRIES) {
     try {
-      await copyEntry(join7(source.userDataDir, entry), join7(stagingRoot, entry));
+      await copyEntry(join8(source.userDataDir, entry), join8(stagingRoot, entry));
     } catch (error) {
       warnings.push(`Chrome bootstrap skipped ${entry}: ${getErrorMessage(error)}`);
     }
@@ -5965,8 +5990,8 @@ async function stageSystemChromeProfile(source, stagingRoot) {
   for (const entry of PROFILE_COPY_ENTRIES) {
     try {
       const copied = await copyEntry(
-        join7(source.profilePath, entry),
-        join7(stagingRoot, source.profileDirectory, entry)
+        join8(source.profilePath, entry),
+        join8(stagingRoot, source.profileDirectory, entry)
       );
       if (copied && COOKIE_STORE_ENTRY_SET.has(entry)) {
         copiedCookieStore = true;
@@ -6072,8 +6097,8 @@ async function loadSystemChromeCookiesFromSqlite(source, platform = process.plat
     return { cookies: [], warnings: [], attempted: false };
   }
   const cookieDbCandidates = [
-    join7(source.profilePath, "Cookies"),
-    join7(source.profilePath, "Network", "Cookies")
+    join8(source.profilePath, "Cookies"),
+    join8(source.profilePath, "Network", "Cookies")
   ];
   const cookieDbPath = await firstExistingPath(cookieDbCandidates);
   if (!cookieDbPath) {
@@ -6143,7 +6168,7 @@ async function loadSystemChromeCookies(executablePath) {
       warnings: direct.warnings
     };
   }
-  const stagingRoot = await mkdtemp2(join7(tmpdir(), "opendevbrowser-chrome-cookie-bootstrap-"));
+  const stagingRoot = await mkdtemp2(join8(tmpdir(), "opendevbrowser-chrome-cookie-bootstrap-"));
   try {
     const staged = await stageSystemChromeProfile(source, stagingRoot);
     if (!staged.copiedCookieStore) {
@@ -6201,7 +6226,7 @@ function getErrorMessage(error) {
 }
 
 // src/browser/global-challenge-coordinator.ts
-import { randomUUID as randomUUID8 } from "crypto";
+import { randomUUID as randomUUID9 } from "crypto";
 var PRESERVE_WINDOW_MS = 15 * 60 * 1e3;
 var VERIFY_WINDOW_MS = 5 * 60 * 1e3;
 var toIso = (value) => value.toISOString();
@@ -6223,7 +6248,7 @@ var GlobalChallengeCoordinator = class {
   claimOrRefresh(args2) {
     const now = args2.now ?? /* @__PURE__ */ new Date();
     const existing = this.bySessionId.get(args2.sessionId);
-    const challengeId = existing?.summary.challengeId ?? randomUUID8();
+    const challengeId = existing?.summary.challengeId ?? randomUUID9();
     const previousTimeline = existing?.timeline ?? [];
     const nextEntry = {
       at: toIso(now),
@@ -6315,8 +6340,8 @@ var GlobalChallengeCoordinator = class {
 
 // src/browser/screencast-recorder.ts
 import { copyFile, mkdir as mkdir4, readdir, writeFile as writeFile2 } from "fs/promises";
-import { randomUUID as randomUUID9 } from "crypto";
-import { isAbsolute as isAbsolute2, join as join8, resolve } from "path";
+import { randomUUID as randomUUID10 } from "crypto";
+import { isAbsolute as isAbsolute2, join as join9, resolve } from "path";
 var DEFAULT_SCREENCAST_INTERVAL_MS = 1e3;
 var MIN_SCREENCAST_INTERVAL_MS = 250;
 var DEFAULT_SCREENCAST_MAX_FRAMES = 300;
@@ -6363,12 +6388,16 @@ async function ensureEmptyDirectory(path4) {
   }
   await mkdir4(path4, { recursive: true });
 }
-function resolveOutputDir(worktree, sessionId, screencastId, outputDir) {
+function resolveOutputDir(worktree, outputDir) {
   if (typeof outputDir === "string" && outputDir.trim().length > 0) {
     const trimmed = outputDir.trim();
-    return isAbsolute2(trimmed) ? trimmed : resolve(worktree, trimmed);
+    return { outputDir: isAbsolute2(trimmed) ? trimmed : resolve(worktree, trimmed) };
   }
-  return join8(worktree, ".opendevbrowser", "replays", "screencasts", sessionId, screencastId);
+  const artifact = createBrowserOutputArtifactDirectory({
+    workspaceRoot: worktree,
+    namespace: BROWSER_SCREENCAST_ARTIFACT_NAMESPACE
+  });
+  return { outputDir: artifact.artifactPath, artifactPath: artifact.artifactPath };
 }
 function renderReplayHtml(manifest) {
   const encodedManifest = JSON.stringify(manifest).replaceAll("<", "\\u003c");
@@ -6468,6 +6497,7 @@ var BrowserScreencastRecorder = class {
   sessionId;
   targetId;
   outputDir;
+  artifactPath;
   startedAt;
   intervalMs;
   maxFrames;
@@ -6488,18 +6518,20 @@ var BrowserScreencastRecorder = class {
   finalPage;
   frames = [];
   constructor(args2) {
-    this.screencastId = args2.screencastId ?? randomUUID9();
+    this.screencastId = args2.screencastId ?? randomUUID10();
     this.sessionId = args2.sessionId;
     this.targetId = args2.targetId;
-    this.outputDir = resolveOutputDir(args2.worktree, args2.sessionId, this.screencastId, args2.options?.outputDir);
+    const output = resolveOutputDir(args2.worktree, args2.options?.outputDir);
+    this.outputDir = output.outputDir;
+    this.artifactPath = output.artifactPath;
     this.intervalMs = resolveIntervalMs(args2.options?.intervalMs);
     this.maxFrames = resolveMaxFrames(args2.options?.maxFrames);
     this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.startedAtMs = Date.parse(this.startedAt);
-    this.framesDir = join8(this.outputDir, FRAMES_DIRECTORY);
-    this.manifestPath = join8(this.outputDir, MANIFEST_FILENAME);
-    this.replayHtmlPath = join8(this.outputDir, REPLAY_FILENAME);
-    this.previewPath = join8(this.outputDir, PREVIEW_FILENAME);
+    this.framesDir = join9(this.outputDir, FRAMES_DIRECTORY);
+    this.manifestPath = join9(this.outputDir, MANIFEST_FILENAME);
+    this.replayHtmlPath = join9(this.outputDir, REPLAY_FILENAME);
+    this.previewPath = join9(this.outputDir, PREVIEW_FILENAME);
     this.captureFrameImpl = args2.captureFrame;
     this.completionPromise = new Promise((resolvePromise) => {
       this.resolveCompletion = resolvePromise;
@@ -6537,6 +6569,7 @@ var BrowserScreencastRecorder = class {
       sessionId: this.sessionId,
       targetId: this.targetId,
       outputDir: this.outputDir,
+      ...this.artifactPath ? { artifact_path: this.artifactPath } : {},
       startedAt: this.startedAt,
       intervalMs: this.intervalMs,
       maxFrames: this.maxFrames,
@@ -6581,7 +6614,7 @@ var BrowserScreencastRecorder = class {
   async captureFrame() {
     const index = this.frames.length + 1;
     const frameFilename = `${String(index).padStart(6, "0")}.png`;
-    const framePath = join8(this.framesDir, frameFilename);
+    const framePath = join9(this.framesDir, frameFilename);
     const task = Promise.resolve().then(async () => {
       const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
       const result = await this.captureFrameImpl(framePath);
@@ -6597,7 +6630,7 @@ var BrowserScreencastRecorder = class {
         index,
         capturedAt,
         elapsedMs: Math.max(Date.parse(capturedAt) - this.startedAtMs, 0),
-        relativePath: normalizeRelativePath(join8(FRAMES_DIRECTORY, frameFilename))
+        relativePath: normalizeRelativePath(join9(FRAMES_DIRECTORY, frameFilename))
       });
       if (this.frames.length === 1) {
         await copyFile(framePath, this.previewPath);
@@ -6662,6 +6695,7 @@ var BrowserScreencastRecorder = class {
       sessionId: this.sessionId,
       targetId: this.targetId,
       outputDir: this.outputDir,
+      ...this.artifactPath ? { artifact_path: this.artifactPath } : {},
       startedAt: this.startedAt,
       endedAt,
       endedReason: reason,
@@ -7058,7 +7092,7 @@ var BrowserManager = class {
       warnings.push("System Chrome not found. Downloaded Chrome for Testing.");
       executablePath = download.executablePath;
     }
-    const profileDir = persistProfile ? cachePaths.profileDir : join9(cachePaths.projectRoot, "temp-profiles", randomUUID10());
+    const profileDir = persistProfile ? cachePaths.profileDir : join10(cachePaths.projectRoot, "temp-profiles", randomUUID11());
     await mkdir5(profileDir, { recursive: true });
     let context = null;
     try {
@@ -7073,7 +7107,7 @@ var BrowserManager = class {
       if (!browser) {
         throw new Error("Browser instance unavailable");
       }
-      const sessionId = randomUUID10();
+      const sessionId = randomUUID11();
       const targets = new TargetManager();
       const pages = context.pages();
       if (pages.length === 0) {
@@ -8180,9 +8214,18 @@ var BrowserManager = class {
       throw new Error("Screenshot ref and fullPage options are mutually exclusive.");
     }
     return this.runTargetScoped(sessionId, options.targetId, async ({ managed, page, targetId: resolvedTargetId }) => {
+      let artifact;
+      let outputPath = options.path;
+      if (typeof outputPath !== "string") {
+        artifact = createBrowserOutputArtifactDirectory({
+          workspaceRoot: this.worktree,
+          namespace: BROWSER_SCREENSHOT_ARTIFACT_NAMESPACE
+        });
+        outputPath = join10(artifact.artifactPath, "capture.png");
+      }
       const screenshotOptions = {
         type: "png",
-        path: options.path
+        path: outputPath
       };
       if (options.ref) {
         await this.callFunctionOnResolvedRef(managed, options.ref, DOM_SCROLL_INTO_VIEW_DECLARATION, [], resolvedTargetId);
@@ -8192,30 +8235,26 @@ var BrowserManager = class {
         screenshotOptions.fullPage = true;
       }
       try {
-        if (options.path) {
-          await this.withLegacyExtensionOperationTimeout(
-            managed,
-            page.screenshot(screenshotOptions),
-            `page.screenshot: Timeout ${LEGACY_EXTENSION_OPERATION_TIMEOUT_MS}ms exceeded.`
-          );
-          return { path: options.path };
-        }
-        const buffer = await this.withLegacyExtensionOperationTimeout(
+        await this.withLegacyExtensionOperationTimeout(
           managed,
           page.screenshot(screenshotOptions),
           `page.screenshot: Timeout ${LEGACY_EXTENSION_OPERATION_TIMEOUT_MS}ms exceeded.`
         );
-        return { base64: buffer.toString("base64") };
+        return {
+          path: outputPath,
+          ...artifact ? { artifact_path: artifact.artifactPath } : {}
+        };
       } catch (error) {
         const fallback = await this.captureScreenshotViaCdp(managed, page, error, options);
         if (!fallback) {
           throw error;
         }
-        if (options.path) {
-          await writeFile3(options.path, Buffer.from(fallback.base64, "base64"));
-          return fallback.warnings ? { path: options.path, warnings: fallback.warnings } : { path: options.path };
-        }
-        return fallback;
+        await writeFile3(outputPath, Buffer.from(fallback.base64, "base64"));
+        return {
+          path: outputPath,
+          ...artifact ? { artifact_path: artifact.artifactPath } : {},
+          ...fallback.warnings ? { warnings: fallback.warnings } : {}
+        };
       }
     });
   }
@@ -10510,7 +10549,7 @@ var BrowserManager = class {
         }
         context = await browser.newContext();
       }
-      const sessionId = randomUUID10();
+      const sessionId = randomUUID11();
       const targets = new TargetManager();
       const pages = context.pages();
       if (pages.length === 0) {
@@ -10703,7 +10742,8 @@ function truncateText(value, maxChars) {
 
 // src/browser/ops-browser-manager.ts
 import { writeFile as writeFile4 } from "fs/promises";
-import { randomUUID as randomUUID11 } from "crypto";
+import { randomUUID as randomUUID12 } from "crypto";
+import { join as join11 } from "path";
 var OpsBrowserManager = class {
   base;
   config;
@@ -10837,7 +10877,7 @@ var OpsBrowserManager = class {
       config: this.config
     });
     const client = await this.ensureOpsClient(connectEndpoint);
-    const leaseId = randomUUID11();
+    const leaseId = randomUUID12();
     const result = await client.request(
       "session.connect",
       {
@@ -11309,11 +11349,21 @@ var OpsBrowserManager = class {
       throw new Error("Screenshot failed");
     }
     const warnings = Array.isArray(result.warnings) ? result.warnings : typeof result.warning === "string" ? [result.warning] : void 0;
-    if (options.path) {
-      await writeFile4(options.path, Buffer.from(result.base64, "base64"));
-      return warnings ? { path: options.path, warnings } : { path: options.path };
+    let artifact;
+    let outputPath = options.path;
+    if (typeof outputPath !== "string") {
+      artifact = createBrowserOutputArtifactDirectory({
+        workspaceRoot: this.worktree,
+        namespace: BROWSER_SCREENSHOT_ARTIFACT_NAMESPACE
+      });
+      outputPath = join11(artifact.artifactPath, "capture.png");
     }
-    return warnings ? { base64: result.base64, warnings } : { base64: result.base64 };
+    await writeFile4(outputPath, Buffer.from(result.base64, "base64"));
+    return {
+      path: outputPath,
+      ...artifact ? { artifact_path: artifact.artifactPath } : {},
+      ...warnings ? { warnings } : {}
+    };
   }
   async startScreencast(sessionId, options = {}) {
     if (!this.opsSessions.has(sessionId)) {
@@ -12208,7 +12258,7 @@ var normalizeRecoverableOpsUrl = (url) => {
 };
 
 // src/browser/annotation-manager.ts
-import { randomUUID as randomUUID13 } from "crypto";
+import { randomUUID as randomUUID14 } from "crypto";
 import { WebSocket as WebSocket2 } from "ws";
 
 // src/annotate/timeout-messages.ts
@@ -12219,9 +12269,9 @@ var getAnnotationTimeoutMessage = (readySeen) => {
 };
 
 // src/annotate/direct-annotator.ts
-import { randomUUID as randomUUID12 } from "crypto";
+import { randomUUID as randomUUID13 } from "crypto";
 import { existsSync as existsSync2 } from "fs";
-import { join as join10 } from "path";
+import { join as join12 } from "path";
 var DEFAULT_TIMEOUT_MS = 12e4;
 var DIRECT_ANNOTATE_REQUIRED_FILES = [
   "dist/annotate-content.js",
@@ -12236,15 +12286,15 @@ function resolveDirectAnnotateAssets(resolvePath = () => getExtensionRuntimePath
   if (!extensionPath) {
     return { error: "Extension assets unavailable." };
   }
-  const scriptPath = join10(extensionPath, "dist", "annotate-content.js");
-  const stylePath = join10(extensionPath, "dist", "annotate-content.css");
+  const scriptPath = join12(extensionPath, "dist", "annotate-content.js");
+  const stylePath = join12(extensionPath, "dist", "annotate-content.css");
   if (!existsSync2(scriptPath) || !existsSync2(stylePath)) {
     return { error: "Direct annotate assets missing. Run `npm run extension:build` and retry." };
   }
   return { assets: { scriptPath, stylePath } };
 }
 async function runDirectAnnotate(manager, assets, request) {
-  const requestId = randomUUID12();
+  const requestId = randomUUID13();
   const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   return manager.withPage(request.sessionId, request.targetId ?? null, async (page) => {
     await ensureBindings(page);
@@ -12544,7 +12594,7 @@ var AnnotationManager = class {
     return this.requestRelay(options, false);
   }
   async requestStored(options) {
-    const requestId = randomUUID13();
+    const requestId = randomUUID14();
     const sharedPayload = this.agentInbox?.latestPayload();
     if (sharedPayload) {
       return {
@@ -12589,7 +12639,7 @@ var AnnotationManager = class {
     return this.relay?.getAnnotationUrl?.() ?? (this.config.relayPort > 0 ? `ws://127.0.0.1:${this.config.relayPort}/annotation` : null);
   }
   async requestDirect(options) {
-    const requestId = randomUUID13();
+    const requestId = randomUUID14();
     if (!options.sessionId) {
       return {
         version: 1,
@@ -12637,7 +12687,7 @@ var AnnotationManager = class {
     }
   }
   async requestRelay(options, requireExtension, commandName = "start") {
-    const requestId = randomUUID13();
+    const requestId = randomUUID14();
     const timeoutMs = options.timeoutMs ?? 12e4;
     let resolvedTabId = options.tabId;
     if (requireExtension && options.sessionId && this.manager) {
@@ -12864,12 +12914,12 @@ var parseJson2 = (data) => {
 };
 
 // src/browser/canvas-manager.ts
-import { randomUUID as randomUUID18 } from "crypto";
+import { randomUUID as randomUUID19 } from "crypto";
 import { mkdir as mkdir9 } from "fs/promises";
 import { dirname as dirname5 } from "path";
 
 // src/browser/canvas-client.ts
-import { randomUUID as randomUUID14 } from "crypto";
+import { randomUUID as randomUUID15 } from "crypto";
 import { WebSocket as WebSocket3 } from "ws";
 var CanvasClient = class {
   url;
@@ -13045,7 +13095,7 @@ var CanvasClient = class {
     if (!this.socket || this.socket.readyState !== WebSocket3.OPEN) {
       await this.connect();
     }
-    const requestId = randomUUID14();
+    const requestId = randomUUID15();
     const request = {
       type: "canvas_request",
       requestId,
@@ -13191,7 +13241,7 @@ var CanvasClient = class {
     if (!this.socket || this.socket.readyState !== WebSocket3.OPEN) {
       return;
     }
-    const id2 = randomUUID14();
+    const id2 = randomUUID15();
     const ping = { type: "canvas_ping", id: id2 };
     await new Promise((resolve7, reject) => {
       const timeoutId = setTimeout(() => {
@@ -13258,7 +13308,7 @@ var isCanvasEvent = (value) => {
 var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 
 // src/canvas/document-store.ts
-import { randomUUID as randomUUID15 } from "crypto";
+import { randomUUID as randomUUID16 } from "crypto";
 
 // node_modules/lib0/map.js
 var create = () => /* @__PURE__ */ new Map();
@@ -21565,7 +21615,7 @@ function createDefaultNode(pageId, nodeId, name) {
     metadata: {}
   };
 }
-function createDefaultCanvasDocument(documentId = `dc_${randomUUID15()}`) {
+function createDefaultCanvasDocument(documentId = `dc_${randomUUID16()}`) {
   const createdAt = nowIso();
   const rootNodeId = `node_root_${documentId.slice(-8)}`;
   const pageId = "page_home";
@@ -21613,7 +21663,7 @@ function normalizeCanvasDocument(input) {
   const updatedAt = typeof base.updatedAt === "string" ? base.updatedAt : createdAt;
   return {
     schemaVersion: typeof base.schemaVersion === "string" ? base.schemaVersion : CANVAS_SCHEMA_VERSION,
-    documentId: typeof base.documentId === "string" ? base.documentId : `dc_${randomUUID15()}`,
+    documentId: typeof base.documentId === "string" ? base.documentId : `dc_${randomUUID16()}`,
     title: typeof base.title === "string" && base.title.trim() ? base.title : "Untitled Design Canvas",
     createdAt,
     updatedAt,
@@ -21646,7 +21696,7 @@ function normalizeCanvasDocument(input) {
     componentInventory: normalizeArray(base.componentInventory, normalizeCanvasComponentInventoryItem),
     tokens: normalizeCanvasTokenStore(base.tokens),
     assets: Array.isArray(base.assets) ? base.assets.map((asset) => ({
-      id: typeof asset.id === "string" ? asset.id : `asset_${randomUUID15()}`,
+      id: typeof asset.id === "string" ? asset.id : `asset_${randomUUID16()}`,
       sourceType: typeof asset.sourceType === "string" ? asset.sourceType : void 0,
       kind: typeof asset.kind === "string" ? asset.kind : void 0,
       repoPath: typeof asset.repoPath === "string" ? asset.repoPath : null,
@@ -21878,7 +21928,7 @@ function buildInventoryItemFromNode(document2, nodeId, options = {}) {
   const origin = options.origin && CANVAS_INVENTORY_ORIGINS.has(options.origin) ? options.origin : baseOrigin;
   const template = buildInventoryTemplate(document2, nodeId);
   return normalizeCanvasComponentInventoryItem({
-    id: options.itemId ?? `inventory_${randomUUID15().slice(0, 8)}`,
+    id: options.itemId ?? `inventory_${randomUUID16().slice(0, 8)}`,
     name: options.name ?? node.name,
     componentName: binding?.componentName ?? node.name,
     description: options.description ?? null,
@@ -22871,7 +22921,7 @@ var CanvasDocumentStore = class {
     }
     this.replaceDocument(nextDocument, this.revision + 1, "canvas.store.apply-patches");
     return {
-      transactionId: `txn_${randomUUID15()}`,
+      transactionId: `txn_${randomUUID16()}`,
       appliedRevision: this.revision,
       warnings: evaluateCanvasWarnings(this.document),
       evidenceRefs: []
@@ -22886,7 +22936,7 @@ var CanvasDocumentStore = class {
     }
     this.replaceDocument(normalizeCanvasDocument(document2), this.revision + 1, "canvas.store.replace-document");
     return {
-      transactionId: `txn_${randomUUID15()}`,
+      transactionId: `txn_${randomUUID16()}`,
       appliedRevision: this.revision,
       warnings: evaluateCanvasWarnings(this.document),
       evidenceRefs: []
@@ -23381,7 +23431,7 @@ function duplicateNodeSubtree(document2, nodeId, parentId, index, idMapInput) {
       throw new Error(`Unknown node: ${sourceNodeId}`);
     }
     const mappedId = isRecord4(idMapInput) ? idMapInput[sourceNode.id] : null;
-    const duplicateId = typeof mappedId === "string" && mappedId.trim().length > 0 ? mappedId : `${sourceNode.id}_copy_${randomUUID15().slice(0, 8)}`;
+    const duplicateId = typeof mappedId === "string" && mappedId.trim().length > 0 ? mappedId : `${sourceNode.id}_copy_${randomUUID16().slice(0, 8)}`;
     idMap.set(sourceNode.id, duplicateId);
     const nextMetadata = clone(sourceNode.metadata);
     if (isRecord4(nextMetadata.codeSync)) {
@@ -24933,7 +24983,7 @@ function listBuiltInCanvasKitIds() {
 
 // src/canvas/repo-store.ts
 import { access as access3, mkdir as mkdir6, readFile as readFile2 } from "fs/promises";
-import { join as join11, dirname as dirname2, isAbsolute as isAbsolute3, resolve as resolve2 } from "path";
+import { join as join13, dirname as dirname2, isAbsolute as isAbsolute3, resolve as resolve2 } from "path";
 
 // src/canvas/code-sync/manifest.ts
 var isRecord6 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -25117,20 +25167,20 @@ function resolveCanvasRepoPath(worktree, documentId, repoPath) {
   if (repoPath && repoPath.trim()) {
     return isAbsolute3(repoPath) ? repoPath : resolve2(worktree, repoPath);
   }
-  return join11(worktree, ".opendevbrowser", "canvas", `${documentId}.canvas.json`);
+  return join13(worktree, ".opendevbrowser", "canvas", `${documentId}.canvas.json`);
 }
 function resolveCanvasCodeSyncManifestPath(worktree, documentId, bindingId, repoPath) {
   if (repoPath && repoPath.trim()) {
     return isAbsolute3(repoPath) ? repoPath : resolve2(worktree, repoPath);
   }
-  return join11(worktree, ".opendevbrowser", "canvas", "code-sync", documentId, `${bindingId}.json`);
+  return join13(worktree, ".opendevbrowser", "canvas", "code-sync", documentId, `${bindingId}.json`);
 }
 function resolveCanvasFigmaAssetDir(worktree, fileKey) {
-  return join11(worktree, ".opendevbrowser", "canvas", "assets", "figma", fileKey);
+  return join13(worktree, ".opendevbrowser", "canvas", "assets", "figma", fileKey);
 }
 function resolveCanvasFigmaAssetPath(worktree, fileKey, assetId, extension) {
   const normalizedExtension = extension.startsWith(".") ? extension : `.${extension}`;
-  return join11(resolveCanvasFigmaAssetDir(worktree, fileKey), `${assetId}${normalizedExtension}`);
+  return join13(resolveCanvasFigmaAssetDir(worktree, fileKey), `${assetId}${normalizedExtension}`);
 }
 async function saveCanvasDocument(worktree, document2, repoPath) {
   const resolvedPath = resolveCanvasRepoPath(worktree, document2.documentId, repoPath);
@@ -25538,7 +25588,7 @@ import { resolve as resolve5, isAbsolute as isAbsolute5 } from "path";
 // src/canvas/adapter-plugins/loader.ts
 import { createHash as createHash4 } from "crypto";
 import { access as access4, readFile as readFile3 } from "fs/promises";
-import { dirname as dirname3, isAbsolute as isAbsolute4, join as join12, resolve as resolve4 } from "path";
+import { dirname as dirname3, isAbsolute as isAbsolute4, join as join14, resolve as resolve4 } from "path";
 import { pathToFileURL } from "url";
 
 // src/canvas/adapter-plugins/manifest.ts
@@ -25634,7 +25684,7 @@ async function readJson(filePath) {
   return JSON.parse(await readFile3(filePath, "utf8"));
 }
 async function loadPackageJson(worktree) {
-  const packagePath = join12(worktree, "package.json");
+  const packagePath = join14(worktree, "package.json");
   try {
     return await readJson(packagePath);
   } catch (error) {
@@ -25682,14 +25732,14 @@ function applyDeclarationOverrides(manifest, declaration) {
 async function resolveDeclarationRef(worktree, ref) {
   const direct = isAbsolute4(ref) ? ref : resolve4(worktree, ref);
   if (await exists(direct)) {
-    const manifestPath2 = direct.endsWith(".json") ? direct : join12(direct, "canvas-adapter.plugin.json");
+    const manifestPath2 = direct.endsWith(".json") ? direct : join14(direct, "canvas-adapter.plugin.json");
     return {
       packageRoot: direct.endsWith(".json") ? dirname3(direct) : direct,
       manifestPath: manifestPath2
     };
   }
-  const nodeModulesPath = join12(worktree, "node_modules", ref);
-  const manifestPath = join12(nodeModulesPath, "canvas-adapter.plugin.json");
+  const nodeModulesPath = join14(worktree, "node_modules", ref);
+  const manifestPath = join14(nodeModulesPath, "canvas-adapter.plugin.json");
   return {
     packageRoot: nodeModulesPath,
     manifestPath
@@ -25700,7 +25750,7 @@ async function readDeclarationSource(worktree) {
   const openDevBrowserConfig = isRecord7(packageJson.opendevbrowser) ? packageJson.opendevbrowser : null;
   const canvasConfig = openDevBrowserConfig && isRecord7(openDevBrowserConfig.canvas) ? openDevBrowserConfig.canvas : null;
   const packageDeclarations = Array.isArray(canvasConfig?.adapterPlugins) ? canvasConfig.adapterPlugins : [];
-  const repoFile = join12(worktree, ".opendevbrowser", "canvas", "adapters.json");
+  const repoFile = join14(worktree, ".opendevbrowser", "canvas", "adapters.json");
   const repoDeclarations = await exists(repoFile) ? (await readJson(repoFile)).adapterPlugins ?? [] : [];
   return { packageDeclarations, repoDeclarations };
 }
@@ -25746,7 +25796,7 @@ function applyCapabilityOverridesToRegisteredAdapters(params2) {
 async function fingerprintPluginFiles(manifestPath, packageRoot, manifest) {
   const entryPath = resolve4(packageRoot, manifest.entry);
   const fixturePath = resolve4(packageRoot, manifest.fixtureDir);
-  const packageJsonPath = join12(packageRoot, "package.json");
+  const packageJsonPath = join14(packageRoot, "package.json");
   const [manifestContent, entryContent, packageJsonContent] = await Promise.all([
     readFile3(manifestPath, "utf8"),
     readFile3(entryPath, "utf8"),
@@ -27100,7 +27150,7 @@ function collectGraphOrder(graph, nodeKey) {
 }
 
 // src/canvas/code-sync/import.ts
-import { randomUUID as randomUUID16 } from "crypto";
+import { randomUUID as randomUUID17 } from "crypto";
 
 // src/canvas/code-sync/graph.ts
 function locatorKey(locator) {
@@ -27230,7 +27280,7 @@ function buildNodeName(graphNode) {
   return graphNode.tagName ?? "Element";
 }
 function buildNodeId(graphNode, manifestLookup) {
-  return manifestLookup.get(locatorKey(graphNode.locator)) ?? `node_sync_${randomUUID16().slice(0, 8)}`;
+  return manifestLookup.get(locatorKey(graphNode.locator)) ?? `node_sync_${randomUUID17().slice(0, 8)}`;
 }
 function preorder(graph, nodeKey) {
   const node = graph.nodes[nodeKey];
@@ -28198,11 +28248,11 @@ function maxIso(values) {
 }
 
 // src/browser/canvas-session-sync-manager.ts
-import { randomUUID as randomUUID17 } from "crypto";
+import { randomUUID as randomUUID18 } from "crypto";
 var CanvasSessionSyncManager = class {
   sessions = /* @__PURE__ */ new Map();
   initializeSession(canvasSessionId, leaseId, clientId) {
-    const initialClientId = normalizeClientId(clientId) ?? `canvas_owner_${randomUUID17().slice(0, 8)}`;
+    const initialClientId = normalizeClientId(clientId) ?? `canvas_owner_${randomUUID18().slice(0, 8)}`;
     const attachedAt = (/* @__PURE__ */ new Date()).toISOString();
     const attachedClients = /* @__PURE__ */ new Map();
     attachedClients.set(initialClientId, {
@@ -28230,7 +28280,7 @@ var CanvasSessionSyncManager = class {
     if (!state) {
       throw new Error(`Unknown canvas session for attach: ${canvasSessionId}`);
     }
-    const resolvedClientId = normalizeClientId(clientId) ?? `canvas_client_${randomUUID17().slice(0, 8)}`;
+    const resolvedClientId = normalizeClientId(clientId) ?? `canvas_client_${randomUUID18().slice(0, 8)}`;
     const previous = state.attachedClients.get(resolvedClientId);
     const attachedAt = previous?.attachedAt ?? (/* @__PURE__ */ new Date()).toISOString();
     let role = "observer";
@@ -29432,14 +29482,22 @@ function optionalString4(value) {
 }
 
 // src/canvas/guidance.ts
-var PREPLAN_CANVAS_GUIDANCE = {
+var withRepairEnvelope = (guidance, envelope) => ({
+  ...guidance,
+  nextStepGuidance: envelope.nextStepGuidance,
+  paramsExamples: envelope.paramsExamples,
+  fieldExamples: envelope.fieldExamples,
+  validationChecks: envelope.validationChecks,
+  doNotProceedIf: envelope.doNotProceedIf
+});
+var PREPLAN_CANVAS_GUIDANCE = withRepairEnvelope({
   recommendedNextCommands: ["canvas.plan.set"],
   reason: "Handshake is complete. Submit a complete generationPlan before mutation."
-};
-var INVALID_PLAN_CANVAS_GUIDANCE = {
+}, buildCanvasRepairEnvelope({ reasonCode: "plan_required" }));
+var INVALID_PLAN_CANVAS_GUIDANCE = withRepairEnvelope({
   recommendedNextCommands: ["canvas.plan.set"],
   reason: "generationPlan is invalid. Submit a supported plan before mutation."
-};
+}, buildCanvasRepairEnvelope({ reasonCode: "generation_plan_invalid" }));
 var PLAN_ACCEPTED_CANVAS_GUIDANCE = {
   recommendedNextCommands: ["canvas.document.patch", "canvas.preview.render", "canvas.feedback.poll", "canvas.document.save"],
   reason: "generationPlan is accepted. Patch the document, render the preview, inspect feedback, and save when the iteration is stable."
@@ -29482,7 +29540,12 @@ var CANVAS_REQUIRED_COMMANDS_BY_BLOCKER = {
 };
 var cloneCanvasGuidance = (guidance) => ({
   recommendedNextCommands: [...guidance.recommendedNextCommands],
-  reason: guidance.reason
+  reason: guidance.reason,
+  ...guidance.nextStepGuidance ? { nextStepGuidance: structuredClone(guidance.nextStepGuidance) } : {},
+  ...guidance.paramsExamples ? { paramsExamples: structuredClone(guidance.paramsExamples) } : {},
+  ...guidance.fieldExamples ? { fieldExamples: structuredClone(guidance.fieldExamples) } : {},
+  ...guidance.validationChecks ? { validationChecks: structuredClone(guidance.validationChecks) } : {},
+  ...guidance.doNotProceedIf ? { doNotProceedIf: [...guidance.doNotProceedIf] } : {}
 });
 var buildCanvasCommandGuidance = (input) => {
   if (input.planStatus === "invalid") {
@@ -29571,6 +29634,13 @@ var CanvasManager = class {
     });
   }
   async execute(command, params2 = {}) {
+    const validationEnvelope = buildCanvasCommandValidationEnvelope(command, params2);
+    if (validationEnvelope) {
+      throw attachDetails(new Error(validationEnvelope.message), {
+        code: validationEnvelope.code,
+        details: validationEnvelope
+      });
+    }
     switch (command) {
       case "canvas.session.open":
         return await this.openSession(params2);
@@ -29653,8 +29723,8 @@ var CanvasManager = class {
     const repoRoot = optionalString5(params2.repoRoot) ?? this.worktree;
     const mode = requireCanvasSessionMode(params2.mode);
     const document2 = repoPath ? normalizeCanvasDocument(await loadCanvasDocument(repoRoot, repoPath)) : createDefaultCanvasDocument(requestedDocumentId ?? void 0);
-    const sessionId = `canvas_${randomUUID18()}`;
-    const leaseId = `lease_${randomUUID18()}`;
+    const sessionId = `canvas_${randomUUID19()}`;
+    const leaseId = `lease_${randomUUID19()}`;
     const planState = resolveGenerationPlanState(document2.designGovernance.generationPlan);
     const session = {
       canvasSessionId: sessionId,
@@ -29696,7 +29766,7 @@ var CanvasManager = class {
   attachSession(params2) {
     const session = this.requireSession(params2);
     const attachMode = requireAttachMode(params2.attachMode);
-    const nextLeaseId = attachMode === "lease_reclaim" ? `lease_${randomUUID18()}` : session.leaseId;
+    const nextLeaseId = attachMode === "lease_reclaim" ? `lease_${randomUUID19()}` : session.leaseId;
     const attached = this.sessionSyncManager.attach(
       session.canvasSessionId,
       nextLeaseId,
@@ -29769,10 +29839,9 @@ var CanvasManager = class {
   setPlan(params2) {
     const session = this.requireSession(params2);
     this.assertLease(session, params2);
-    const plan = requireRecord(params2.generationPlan, "generationPlan");
     session.planStatus = "submitted";
     session.preflightState = "plan_submitted";
-    const validation = validateGenerationPlan(plan);
+    const validation = validateGenerationPlan(params2.generationPlan);
     if (!validation.ok) {
       session.planStatus = "invalid";
       session.preflightState = "plan_invalid";
@@ -30054,7 +30123,7 @@ var CanvasManager = class {
     const session = this.requireSession(params2);
     this.assertLease(session, params2);
     const nodeId = requireString2(params2.nodeId, "nodeId");
-    const bindingId = optionalString5(params2.bindingId) ?? `binding_sync_${randomUUID18().slice(0, 8)}`;
+    const bindingId = optionalString5(params2.bindingId) ?? `binding_sync_${randomUUID19().slice(0, 8)}`;
     const binding = createCodeSyncBinding(params2, nodeId, bindingId);
     const baseRevision = session.store.getRevision();
     await this.applyDocumentPatches(session, baseRevision, [{
@@ -30838,7 +30907,7 @@ var CanvasManager = class {
         prototypeId
       });
     } else if (status.mode === "extension" && this.supportsOpsOverlayTransport(session) && typeof this.browserManager.mountCanvasOverlay === "function") {
-      const mountId2 = `mount_${randomUUID18()}`;
+      const mountId2 = `mount_${randomUUID19()}`;
       result = await this.browserManager.mountCanvasOverlay(session.browserSessionId, targetId, {
         mountId: mountId2,
         title: session.store.getDocument().title,
@@ -30848,7 +30917,7 @@ var CanvasManager = class {
     } else {
       result = await this.mountDirectOverlay(session.browserSessionId, targetId, session.store.getDocument(), prototypeId);
     }
-    const mountId = typeof result.mountId === "string" ? result.mountId : `mount_${randomUUID18()}`;
+    const mountId = typeof result.mountId === "string" ? result.mountId : `mount_${randomUUID19()}`;
     session.overlayMounts.set(mountId, { mountId, targetId, mountedAt: (/* @__PURE__ */ new Date()).toISOString() });
     const previewState = session.activeTargets.get(targetId)?.previewState ?? "background";
     if (!usesCanvasRelayOverlay) {
@@ -31188,7 +31257,7 @@ var CanvasManager = class {
   subscribeFeedback(params2) {
     const session = this.requireSession(params2);
     const polled = this.pollFeedback(params2);
-    const subscriptionId = `canvas_sub_${randomUUID18()}`;
+    const subscriptionId = `canvas_sub_${randomUUID19()}`;
     const heartbeatMs = FEEDBACK_HEARTBEAT_MS;
     const subscription = {
       id: subscriptionId,
@@ -31680,7 +31749,14 @@ var CanvasManager = class {
       latestRevision: session.store.getRevision(),
       message: "generationPlan must be accepted before mutation."
     };
-    return attachDetails(new Error(blocker.message), { code: blocker.code, blocker, details: { auditId: "CANVAS-01" } });
+    return attachDetails(new Error(blocker.message), {
+      code: blocker.code,
+      blocker,
+      details: {
+        auditId: "CANVAS-01",
+        ...buildCanvasRepairEnvelope({ reasonCode: "plan_required" })
+      }
+    });
   }
   invalidGenerationPlan(session, missingFields, issues, command = "canvas.plan.set") {
     const blocker = {
@@ -31696,7 +31772,13 @@ var CanvasManager = class {
       details: {
         auditId: "CANVAS-03",
         missingFields,
-        issues
+        issues,
+        ...buildCanvasRepairEnvelope({
+          reasonCode: "generation_plan_invalid",
+          missingFields,
+          issues,
+          message: blocker.message
+        })
       }
     });
   }
@@ -32473,7 +32555,7 @@ function readInsertPlacement(params2) {
 }
 function materializeInventoryItem(item, pageId, parentId, placement) {
   const template = readInventoryTemplate(item);
-  const idMap = new Map(template.nodes.map((node) => [node.id, `node_inventory_${randomUUID18().slice(0, 8)}`]));
+  const idMap = new Map(template.nodes.map((node) => [node.id, `node_inventory_${randomUUID19().slice(0, 8)}`]));
   const root = template.nodes.find((node) => node.id === template.rootNodeId) ?? template.nodes[0];
   const offsetX = (placement.x ?? root.rect.x) - root.rect.x;
   const offsetY = (placement.y ?? root.rect.y) - root.rect.y;
@@ -32649,11 +32731,11 @@ function buildStarterInventoryUpsertPatches(kitIds, frameworkId, adapterId) {
   }));
 }
 function buildStarterShell(definition, pageId, parentId, placement) {
-  const rootNodeId = `node_starter_${randomUUID18().slice(0, 8)}`;
-  const eyebrowNodeId = `node_starter_${randomUUID18().slice(0, 8)}`;
-  const headlineNodeId = `node_starter_${randomUUID18().slice(0, 8)}`;
-  const bodyNodeId = `node_starter_${randomUUID18().slice(0, 8)}`;
-  const actionNodeId = definition.shell.actionLabel ? `node_starter_${randomUUID18().slice(0, 8)}` : null;
+  const rootNodeId = `node_starter_${randomUUID19().slice(0, 8)}`;
+  const eyebrowNodeId = `node_starter_${randomUUID19().slice(0, 8)}`;
+  const headlineNodeId = `node_starter_${randomUUID19().slice(0, 8)}`;
+  const bodyNodeId = `node_starter_${randomUUID19().slice(0, 8)}`;
+  const actionNodeId = definition.shell.actionLabel ? `node_starter_${randomUUID19().slice(0, 8)}` : null;
   const rect = {
     ...definition.shell.rect,
     x: placement.x ?? definition.shell.rect.x,
@@ -33111,12 +33193,6 @@ function normalizeOptionalString(value) {
 function normalizeStringArray(value) {
   return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
 }
-function requireRecord(value, name) {
-  if (!isRecord12(value)) {
-    throw new Error(`Missing ${name}`);
-  }
-  return value;
-}
 function requirePatches(value) {
   if (!Array.isArray(value)) {
     throw new Error("Missing patches");
@@ -33310,7 +33386,7 @@ function ensureDuplicatePatchIds(document2, patch) {
   }
   const subtreeNodeIds = collectSubtreeNodeIds(document2, patch.nodeId);
   const idMap = Object.fromEntries(
-    subtreeNodeIds.map((nodeId) => [nodeId, `${nodeId}_copy_${randomUUID18().slice(0, 8)}`])
+    subtreeNodeIds.map((nodeId) => [nodeId, `${nodeId}_copy_${randomUUID19().slice(0, 8)}`])
   );
   return {
     ...patch,
@@ -33329,7 +33405,7 @@ function buildCanvasHistoryEntry(beforeDocument, patches, options) {
     scratchStore.applyPatches(scratchStore.getRevision(), [patch]);
   }
   return {
-    id: `history_${randomUUID18().slice(0, 8)}`,
+    id: `history_${randomUUID19().slice(0, 8)}`,
     source: options.source,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     forwardPatches: structuredClone(patches),
@@ -33560,7 +33636,7 @@ function attachDetails(error, details) {
 
 // src/relay/relay-server.ts
 import { createServer } from "http";
-import { timingSafeEqual, randomUUID as randomUUID19 } from "crypto";
+import { timingSafeEqual, randomUUID as randomUUID20 } from "crypto";
 import { WebSocket as WebSocket4, WebSocketServer } from "ws";
 var DEFAULT_DISCOVERY_PORT = 8787;
 var CONFIG_PATH = "/config";
@@ -33568,7 +33644,7 @@ var PAIR_PATH = "/pair";
 var STATUS_PATH = "/status";
 var CDP_TOKEN_QUERY_KEY = "token";
 var RelayServer = class _RelayServer {
-  instanceId = randomUUID19();
+  instanceId = randomUUID20();
   epoch = Date.now();
   running = false;
   baseUrl = null;
@@ -33701,7 +33777,7 @@ var RelayServer = class _RelayServer {
       });
     });
     this.opsWss.on("connection", (socket, _request) => {
-      const clientId = randomUUID19();
+      const clientId = randomUUID20();
       this.opsClients.set(clientId, socket);
       socket.on("message", (data) => {
         this.handleOpsClientMessage(clientId, data);
@@ -33725,7 +33801,7 @@ var RelayServer = class _RelayServer {
       void _request;
     });
     this.canvasWss.on("connection", (socket, _request) => {
-      const clientId = randomUUID19();
+      const clientId = randomUUID20();
       this.canvasClients.set(clientId, socket);
       socket.on("message", (data) => {
         this.handleCanvasClientMessage(clientId, data);
@@ -35407,4 +35483,4 @@ export {
   createOpenDevBrowserCore
 };
 /* v8 ignore next -- @preserve */
-//# sourceMappingURL=chunk-HBK56JST.js.map
+//# sourceMappingURL=chunk-XRDCSHKZ.js.map