@bettercms-ai/preview-runtime 0.2.0 → 0.4.0

package/dist/cli.js

@@ -36,6 +36,25 @@ function readJson(file) {
     fail(`could not read ${file}: ${error.message}`);
   }
 }
+var LANDMARKS = /* @__PURE__ */ new Set(["header", "footer", "nav"]);
+var isStringRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
+function pageSource(id, source) {
+  const { route, blockId, groupKey, layoutSectionId, landmark } = source;
+  if (typeof route !== "string" || !route.startsWith("/") || route.startsWith("//") || /[\s?#\\]/.test(route) || route.split("/").includes("..")) {
+    fail(`component ${id} has an unsafe page route: ${String(route)}`);
+  }
+  if (typeof blockId === "string" && blockId) {
+    if (groupKey != null && typeof groupKey !== "string") fail(`component ${id}: groupKey must be a string`);
+    if (source.source != null && !isStringRecord(source.source)) fail(`component ${id}: source must map prop keys to page paths`);
+    return { kind: "page", route, blockId, groupKey: groupKey ?? null, source: source.source ?? null };
+  }
+  if (typeof layoutSectionId === "string" && layoutSectionId) {
+    if (landmark != null && !LANDMARKS.has(landmark)) fail(`component ${id}: unknown landmark ${String(landmark)}`);
+    if (source.bindings != null && !isStringRecord(source.bindings)) fail(`component ${id}: bindings must map input ids to layout field ids`);
+    return { kind: "page", route, layoutSectionId, landmark: landmark ?? null, bindings: source.bindings ?? {} };
+  }
+  fail(`component ${id}: a page source names neither a placement (blockId) nor a layout section (layoutSectionId)`);
+}
 function validateManifest(root, manifest) {
   if (!manifest || !Array.isArray(manifest.components) || manifest.components.length === 0) {
     fail("the manifest lists no components");
@@ -45,6 +64,7 @@ function validateManifest(root, manifest) {
     if (!entry || typeof entry.id !== "string" || !entry.id.trim()) fail("a manifest entry has no id");
     if (seen.has(entry.id)) fail(`component ${entry.id} is listed twice`);
     seen.add(entry.id);
+    if (entry.source?.kind === "page") return { id: entry.id, source: pageSource(entry.id, entry.source) };
     const path = entry.source?.path;
     if (typeof path !== "string" || path.startsWith("/") || path.includes("\\") || path.split("/").includes("..")) {
       fail(`component ${entry.id} has an unsafe source path: ${String(path)}`);
@@ -80,14 +100,20 @@ function registrySource(fromDir, root, entries) {
   const imports = [];
   const keys = [];
   const kinds = [];
+  const pages = [];
   entries.forEach((entry, index) => {
-    let specifier = relative(fromDir, join(root, entry.source.path)).split(sep).join("/");
+    const source = entry.source;
+    kinds.push(`  ${JSON.stringify(entry.id)}: ${JSON.stringify(source.kind ?? "file")},`);
+    if (source.kind === "page") {
+      pages.push(`  ${JSON.stringify(entry.id)}: ${JSON.stringify(source)},`);
+      return;
+    }
+    let specifier = relative(fromDir, join(root, source.path)).split(sep).join("/");
     if (!specifier.startsWith(".")) specifier = `./${specifier}`;
     if ([".tsx", ".ts", ".jsx", ".js"].includes(extname(specifier))) specifier = specifier.slice(0, -extname(specifier).length);
     const local = `Component${index}`;
-    imports.push(entry.source.export === "default" ? `import ${local} from ${JSON.stringify(specifier)};` : `import { ${entry.source.export} as ${local} } from ${JSON.stringify(specifier)};`);
+    imports.push(source.export === void 0 || source.export === "default" ? `import ${local} from ${JSON.stringify(specifier)};` : `import { ${source.export} as ${local} } from ${JSON.stringify(specifier)};`);
     keys.push(`  ${JSON.stringify(entry.id)}: ${local},`);
-    kinds.push(`  ${JSON.stringify(entry.id)}: ${JSON.stringify(entry.source.kind ?? "file")},`);
   });
   return `${imports.join("\n")}
 
@@ -95,11 +121,16 @@ export const registry: Record<string, any> = {
 ${keys.join("\n")}
 };
 
-export const kinds: Record<string, "file" | "section"> = {
+export const kinds: Record<string, "file" | "section" | "page"> = {
 ${kinds.join("\n")}
 };
 
-export const has = (componentId: string): boolean => Object.prototype.hasOwnProperty.call(registry, componentId);
+export const pages: Record<string, any> = {
+${pages.join("\n")}
+};
+
+const own = (map: object, componentId: string) => Object.prototype.hasOwnProperty.call(map, componentId);
+export const has = (componentId: string): boolean => own(registry, componentId) || own(pages, componentId);
 `;
 }
 function writeRuntimeLibrary(dir) {
@@ -107,6 +138,8 @@ function writeRuntimeLibrary(dir) {
   const types = join(here, "server.d.ts");
   if (existsSync(types)) writeFileSync(join(dir, "server.d.mts"), readFileSync(types, "utf8"));
   writeFileSync(join(dir, "shell.ts"), `export default ${JSON.stringify(readFileSync(join(here, "shell.global.js"), "utf8"))};
+`);
+  writeFileSync(join(dir, "scope.ts"), `export default ${JSON.stringify(readFileSync(join(here, "scope-client.global.js"), "utf8"))};
 `);
 }
 function astroGlobalStyles(root) {
@@ -136,7 +169,8 @@ function ensureAstroNodeAdapter(root) {
   } catch {
   }
   const astroVersion = readJson(require2.resolve("astro/package.json")).version;
-  const range = ASTRO_NODE_ADAPTER[astroVersion.split(".")[0]];
+  const [major, minor] = astroVersion.split(".").map(Number);
+  const range = major === 7 && minor < 3 ? ">=11.0.0 <11.1.3" : ASTRO_NODE_ADAPTER[String(major)];
   if (!range) fail(`Astro ${astroVersion} is not supported for component previews yet`);
   run(root, "npm", ["install", "--no-save", "--no-audit", "--no-fund", `@astrojs/node@${range}`]);
 }
@@ -168,11 +202,13 @@ ${handler("GET", "() => handleHealth()")}`);
     const styles = astroGlobalStyles(root).map((file) => `import ${JSON.stringify(relative(gen, file).split(sep).join("/"))};`).join("\n");
     writeFileSync(join(gen, "render.astro"), `---
 ${styles}
-import { renderEntry, renderHeaders } from "./server.mjs";
-import { registry, kinds } from "./registry";
+import { renderEntry, renderHeaders, renderPageSection } from "./server.mjs";
+import { registry, kinds, pages } from "./registry";
+import scope from "./scope";
 export const prerender = false;
 const headers = renderHeaders();
 const entry = renderEntry(Astro.url.searchParams.get("id"));
+if (entry && pages[entry.componentId]) return await renderPageSection(Astro.request, entry, pages[entry.componentId], scope);
 const Component = entry ? registry[entry.componentId] : undefined;
 const section = entry ? kinds[entry.componentId] === "section" : false;
 for (const [name, value] of Object.entries(headers)) Astro.response.headers.set(name, value);
@@ -266,17 +302,30 @@ export function POST(request: Request) {
 export function GET() {
   return handleHealth();
 }
+`);
+    route("render-page", `import { renderEntry, renderPageSection } from "../server.mjs";
+import { pages } from "../registry";
+import scope from "../scope";
+export function GET(request: Request) {
+  const entry = renderEntry(new URL(request.url).searchParams.get("id"));
+  const page = entry ? pages[entry.componentId] : undefined;
+  if (!entry || !page) return new Response("Not found", { status: 404 });
+  return renderPageSection(request, entry, page, scope);
+}
 `);
     mkdirSync(join(gen, "render"), { recursive: true });
-    writeFileSync(join(gen, "render", "page.tsx"), `import { notFound } from "next/navigation";
+    writeFileSync(join(gen, "render", "page.tsx"), `import { notFound, redirect } from "next/navigation";
 import { renderEntry } from "../server.mjs";
-import { registry, kinds } from "../registry";
+import { registry, kinds, pages } from "../registry";
 
 export const dynamic = "force-dynamic";
 
 export default async function BetterCMSComponentPreview({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   const { id } = await searchParams;
   const entry = renderEntry(id);
+  // A page-kind component answers with a whole document, which a page inside the root layout cannot be.
+  // Relative on purpose: Next prefixes basePath onto a "/"-rooted redirect, and the browser resolves this one.
+  if (entry && pages[entry.componentId]) redirect(\`render-page?id=\${encodeURIComponent(id!)}\`);
   const Component = entry ? registry[entry.componentId] : undefined;
   if (!entry || !Component) notFound();
   // The marker the runtime page checks before acknowledging: a 404 or an error page never carries it.
@@ -363,6 +412,28 @@ import { tmpdir } from "os";
 import { dirname as dirname2, join as join2 } from "path";
 var PREVIEW_ROUTE_BASE = "/__bettercms/component-preview/__bcms";
 var RUNTIME_PATH = `${PREVIEW_ROUTE_BASE}/runtime`;
+var API_TIMEOUT_MS = 6e4;
+var LOCAL_FETCH_TIMEOUT_MS = 3e4;
+var HEALTH_PROBE_TIMEOUT_MS = 5e3;
+var RENDER_TIMEOUT_PER_VIEWPORT_MS = 9e4;
+var BUNDLE_UPLOAD_TIMEOUT_MS = 5 * 6e4;
+var DEFAULT_BATCH_BUDGET_MS = 15 * 6e4;
+async function bounded(what, ms, run2) {
+  const controller = new AbortController();
+  let timer;
+  const expired = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      const limit = ms >= 1e3 ? `${Math.round(ms / 1e3)} seconds` : `${ms} ms`;
+      reject(new ValidationFailure("COMPONENT_VALIDATION_STEP_TIMEOUT", `${what} did not finish within ${limit}.`));
+    }, ms);
+  });
+  try {
+    return await Promise.race([run2(controller.signal), expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 var ValidationFailure = class extends Error {
   constructor(code, message) {
     super(message);
@@ -371,11 +442,49 @@ var ValidationFailure = class extends Error {
   }
   code;
 };
-function required(name) {
-  const value = process.env[name]?.trim();
+function required(name, env = process.env) {
+  const value = env[name]?.trim();
   if (!value) throw new CliFailure(`${name} is not set. This command runs inside the BetterCMS component validation workflow.`);
   return value;
 }
+var isViewport = (value) => !!value && typeof value === "object" && typeof value.name === "string" && Number.isFinite(value.width) && Number.isFinite(value.height);
+var isBatchItem = (value) => {
+  if (!value || typeof value !== "object") return false;
+  const item = value;
+  return ["requestId", "componentId", "familyKey"].every((key) => typeof item[key] === "string" && item[key].trim() !== "") && Array.isArray(item.nativeViewports) && item.nativeViewports.length > 0 && item.nativeViewports.every(isViewport);
+};
+var invalidBatch = (detail) => new CliFailure(`COMPONENT_VALIDATION_BATCH_INVALID: ${detail}`);
+function resolveBatch(env = process.env) {
+  const raw = env.BCMS_BATCH?.trim();
+  if (raw && raw !== "null") {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw invalidBatch("BCMS_BATCH is not valid JSON.");
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isBatchItem)) {
+      throw invalidBatch("BCMS_BATCH must be a non-empty array of { requestId, componentId, familyKey, nativeViewports }.");
+    }
+    if (new Set(parsed.map((item2) => item2.requestId)).size !== parsed.length) {
+      throw invalidBatch("BCMS_BATCH names the same request twice.");
+    }
+    return parsed;
+  }
+  const requestId = required("BCMS_REQUEST_ID", env);
+  const componentId = required("BCMS_COMPONENT_ID", env);
+  const familyKey = required("BCMS_FAMILY_KEY", env);
+  let nativeViewports;
+  try {
+    nativeViewports = JSON.parse(required("BCMS_NATIVE_VIEWPORTS", env));
+  } catch (error) {
+    if (error instanceof CliFailure) throw error;
+    throw invalidBatch("BCMS_NATIVE_VIEWPORTS is not valid JSON.");
+  }
+  const item = { requestId, componentId, familyKey, nativeViewports };
+  if (!isBatchItem(item)) throw invalidBatch("BCMS_NATIVE_VIEWPORTS must be a non-empty array of { name, width, height }.");
+  return [item];
+}
 var sha256 = (data) => createHash("sha256").update(data).digest("hex");
 function canonical(value) {
   if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
@@ -384,6 +493,191 @@ function canonical(value) {
   }
   return JSON.stringify(value);
 }
+var toCliFailure = (error) => new CliFailure(`${error instanceof ValidationFailure ? error.code : "COMPONENT_VALIDATION_FAILED"}: ${error.message.slice(0, 2e3)}`);
+async function runValidationBatch(batch, ctx, deps) {
+  const now = deps.now ?? Date.now;
+  const deadline = now() + (deps.budgetMs ?? DEFAULT_BATCH_BUDGET_MS);
+  const propsMs = deps.timeouts?.propsMs ?? LOCAL_FETCH_TIMEOUT_MS;
+  const renderPerViewportMs = deps.timeouts?.renderPerViewportMs ?? RENDER_TIMEOUT_PER_VIEWPORT_MS;
+  const apiMs = deps.timeouts?.apiMs ?? API_TIMEOUT_MS;
+  const seconds = (ms) => `${Math.ceil(Math.max(ms, 0) / 1e3)}s`;
+  const log = deps.log ?? ((line) => console.log(line));
+  const logError = deps.error ?? ((line) => console.error(line));
+  const requestPath = (item) => `/api/v1/projects/${ctx.projectId}/component-implementation/implementation-requests/${item.requestId}`;
+  const completed = [];
+  const failed = [];
+  const claim = (item) => deps.api(`${requestPath(item)}/claim`, {
+    method: "POST",
+    body: {
+      componentId: item.componentId,
+      commitSha: ctx.commitSha,
+      adapter: {
+        protocol: "bcms-component-runtime-v1",
+        kind: "project-route",
+        path: RUNTIME_PATH,
+        familyKey: item.familyKey,
+        previewOrigin: ctx.previewOrigin,
+        nativeViewports: item.nativeViewports
+      },
+      providerRunId: ctx.run.providerRunId,
+      providerRunAttempt: ctx.run.providerRunAttempt,
+      providerRunUrl: ctx.run.providerRunUrl,
+      workflowRef: ctx.run.workflowRef,
+      // The server caps this at the request's own expiry and at ten minutes.
+      credentialExpiresAt: new Date(Date.now() + 10 * 6e4 - 5e3).toISOString()
+    }
+  });
+  const report = async (item, held, error) => {
+    const code = error instanceof ValidationFailure ? error.code : "COMPONENT_VALIDATION_FAILED";
+    const message = error.message.slice(0, 2e3);
+    failed.push(item.componentId);
+    logError(`bcms-preview: ${code}: ${message} (component ${item.componentId})`);
+    const reported = held ?? await claim(item).catch((claimError) => {
+      logError(`bcms-preview: could not claim request ${item.requestId} to report the failure: ${claimError.message}`);
+      return null;
+    });
+    if (!reported) return;
+    await deps.api(`${requestPath(item)}/fail`, {
+      method: "POST",
+      claim: reported.claimCapability,
+      body: { componentId: item.componentId, errorCode: code, errorMessage: message }
+    }).catch((reportError) => logError(`bcms-preview: could not report the failure: ${reportError.message}`));
+  };
+  let manifest;
+  try {
+    manifest = await deps.api(`/api/v1/projects/${ctx.projectId}/component-preview/manifest?kinds=page`);
+  } catch (error) {
+    for (const item of batch) await report(item, null, error);
+    throw toCliFailure(error);
+  }
+  const hintFor = (componentId) => {
+    const entry = manifest.components.find((c) => c.id === componentId);
+    return entry?.fallback && entry.source.kind !== "page" ? [`Clear the recorded source: this component renders from page ${entry.fallback.route} without one.`] : [];
+  };
+  const pending = [];
+  for (const item of batch) {
+    if (manifest.components.some((c) => c.id === item.componentId)) {
+      pending.push(item);
+    } else {
+      await report(item, null, new ValidationFailure(
+        "COMPONENT_SOURCE_NOT_RECORDED",
+        "No file is recorded and this component is neither placed on a page nor used in the layout, so there is nothing to render. Place it, add it to the layout, or record its file."
+      ));
+    }
+  }
+  if (pending.length === 0) return { completed, failed, exitCode: 1 };
+  let runtime = null;
+  try {
+    runtime = await deps.prepare(manifest);
+    const upload = await deps.api(`/api/v1/projects/${ctx.projectId}/artifacts/upload-url`, { method: "POST" });
+    const put = await deps.putBundle(upload.uploadUrl, runtime.bundle);
+    if (!put.ok) {
+      throw new ValidationFailure("COMPONENT_PREVIEW_BUNDLE_UPLOAD_FAILED", `Storage refused the preview bundle (HTTP ${put.status}).`);
+    }
+    await deps.api(`/api/v1/projects/${ctx.projectId}/component-preview/bundles`, {
+      method: "POST",
+      body: { commitSha: ctx.commitSha, uploadKey: upload.uploadKey, checksum: `sha256:${sha256(runtime.bundle)}`, sizeBytes: runtime.bundle.byteLength }
+    });
+  } catch (error) {
+    await runtime?.close().catch(() => {
+    });
+    for (const item of pending) {
+      const hint = error instanceof ValidationFailure && error.code === "COMPONENT_PREVIEW_BUILD_FAILED" ? hintFor(item.componentId) : [];
+      await report(item, null, hint.length ? new ValidationFailure(error.code, [error.message, ...hint].join(" ")) : error);
+    }
+    throw toCliFailure(error);
+  }
+  const ready = runtime;
+  try {
+    for (const item of pending) {
+      const worstCase = propsMs + renderPerViewportMs * item.nativeViewports.length + 2 * apiMs;
+      const left = deadline - now();
+      if (left < worstCase) {
+        await report(item, null, new ValidationFailure(
+          "COMPONENT_VALIDATION_BATCH_TIMEOUT",
+          `The validation batch did not have enough time left for this component (needs up to ${seconds(worstCase)}, ${seconds(left)} left). Request validation again.`
+        ));
+        continue;
+      }
+      const entry = manifest.components.find((c) => c.id === item.componentId);
+      const hint = hintFor(item.componentId);
+      let held = null;
+      try {
+        const mark = ready.serverErrorCount();
+        const renderId = await bounded(
+          `The preview runtime's props endpoint for ${item.componentId}`,
+          propsMs,
+          (signal) => ready.storeProps(item.componentId, entry.defaultProps, signal)
+        );
+        const render = await bounded(
+          `Rendering ${item.componentId}`,
+          renderPerViewportMs * item.nativeViewports.length,
+          (signal) => ready.render(
+            renderId,
+            item.nativeViewports,
+            manifest.brandTokenNames,
+            // A page-kind render lifts a section too, and stamps its root.
+            { section: ready.kinds[item.componentId] !== "file" },
+            signal
+          )
+        );
+        const serverErrors = ready.serverErrorsSince(mark).slice(0, 5);
+        held = await claim(item);
+        const target = held.request;
+        const checks = {
+          brandKit: {
+            status: render.missingTokens.length === 0 ? "passed" : "failed",
+            contractHash: target.brandContractHash,
+            missingTokens: render.missingTokens
+          },
+          runtime: {
+            status: render.runtimeErrors === 0 && render.consoleErrors === 0 ? "passed" : "failed",
+            runtimeErrors: render.runtimeErrors,
+            consoleErrors: render.consoleErrors,
+            // Only on a failure, and bounded: the server's own error lines first (the real cause), then what the
+            // browser saw. The database stores them and the panel shows the first one.
+            ...render.runtimeErrors + render.consoleErrors > 0 ? { problems: [...hint, ...serverErrors.map((line) => `server: ${line}`), ...render.problems].slice(0, 10).map((line) => line.slice(0, 200)) } : {}
+          },
+          visual: { status: "baseline-missing", reviewRequired: true, viewports: render.results }
+        };
+        const evidenceDigest = `sha256:${sha256(canonical({ requestId: item.requestId, commitSha: target.commitSha, checks }))}`;
+        await deps.api(`${requestPath(item)}/complete`, {
+          method: "POST",
+          claim: held.claimCapability,
+          body: {
+            componentId: target.componentId,
+            candidateId: target.candidateId,
+            componentVersion: target.componentVersion,
+            familyKey: target.familyKey,
+            familyContractHash: target.familyContractHash,
+            schemaHash: target.schemaHash,
+            brandContractHash: target.brandContractHash,
+            dependenciesHash: target.dependenciesHash,
+            commitSha: target.commitSha,
+            adapterHash: target.adapterHash,
+            familyManifestHash: target.familyManifestHash,
+            nativeViewports: target.nativeViewports,
+            checks,
+            evidenceDigest
+          }
+        });
+        completed.push(item.componentId);
+        const passed = checks.brandKit.status === "passed" && checks.runtime.status === "passed";
+        log(`bcms-preview: validation ${passed ? "PASSED" : "FAILED"} for ${item.componentId}`);
+        if (!passed) {
+          if (render.missingTokens.length) log(`  brand tokens used but not defined: ${render.missingTokens.join(", ")}`);
+          for (const problem of [...hint, ...render.problems]) log(`  ${problem}`);
+        }
+      } catch (error) {
+        await report(item, held, error);
+      }
+    }
+  } finally {
+    await ready.close().catch(() => {
+    });
+  }
+  return { completed, failed, exitCode: failed.length > 0 ? 1 : 0 };
+}
 function freePort() {
   return new Promise((resolve2, reject) => {
     const server = createServer();
@@ -399,7 +693,7 @@ async function waitForOk(url, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
-      if ((await fetch(url)).ok) return true;
+      if ((await fetch(url, { signal: AbortSignal.timeout(HEALTH_PROBE_TIMEOUT_MS) })).ok) return true;
     } catch {
     }
     await new Promise((r) => setTimeout(r, 500));
@@ -416,18 +710,22 @@ function ensureBrowser() {
     throw new ValidationFailure("COMPONENT_VALIDATION_BROWSER_UNAVAILABLE", "A headless browser could not be installed on this runner.");
   }
 }
-async function renderInBrowser(url, viewports, tokenNames, options) {
-  ensureBrowser();
-  const { chromium } = await import("playwright");
-  const browser = await chromium.launch();
-  try {
-    let consoleErrors = 0;
-    let runtimeErrors = 0;
-    const missingTokens = /* @__PURE__ */ new Set();
-    const results = [];
-    const problems = [];
-    for (const viewport of viewports) {
-      const page = await browser.newPage({ viewport: { width: viewport.width, height: viewport.height } });
+async function renderInBrowser(browser, url, viewports, tokenNames, options, signal) {
+  let consoleErrors = 0;
+  let runtimeErrors = 0;
+  const missingTokens = /* @__PURE__ */ new Set();
+  const results = [];
+  const problems = [];
+  for (const viewport of viewports) {
+    if (signal?.aborted) break;
+    const page = await browser.newPage({ viewport: { width: viewport.width, height: viewport.height } });
+    const onAbort = () => {
+      page.close().catch(() => {
+      });
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    try {
       page.on("console", (message) => {
         if (message.type() === "error") {
           consoleErrors += 1;
@@ -475,34 +773,51 @@ async function renderInBrowser(url, viewports, tokenNames, options) {
         status: "baseline-missing",
         candidateDigest: `sha256:${sha256(png)}`
       });
-      await page.close();
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+      await page.close().catch(() => {
+      });
     }
-    return { results, consoleErrors, runtimeErrors, missingTokens: [...missingTokens].sort(), problems };
-  } finally {
-    await browser.close();
   }
+  return { results, consoleErrors, runtimeErrors, missingTokens: [...missingTokens].sort(), problems };
 }
 async function validateComponent() {
   const apiUrl = required("BCMS_API_URL");
   const apiKey = required("BCMS_API_KEY");
-  const projectId = required("BCMS_PROJECT_ID");
-  const requestId = required("BCMS_REQUEST_ID");
-  const componentId = required("BCMS_COMPONENT_ID");
-  const commitSha = required("BCMS_COMMIT_SHA");
-  const familyKey = required("BCMS_FAMILY_KEY");
-  const previewOrigin = required("BCMS_PREVIEW_ORIGIN");
-  const nativeViewports = JSON.parse(required("BCMS_NATIVE_VIEWPORTS"));
+  const batch = resolveBatch();
+  const ctx = {
+    projectId: required("BCMS_PROJECT_ID"),
+    commitSha: required("BCMS_COMMIT_SHA"),
+    previewOrigin: required("BCMS_PREVIEW_ORIGIN"),
+    run: {
+      providerRunId: required("BCMS_RUN_ID"),
+      providerRunAttempt: Number(process.env.BCMS_RUN_ATTEMPT) || 1,
+      providerRunUrl: required("BCMS_RUN_URL"),
+      workflowRef: required("BCMS_WORKFLOW_REF")
+    }
+  };
   const api = async (path, init = {}) => {
-    const response = await fetch(new URL(path, apiUrl), {
-      method: init.method ?? "GET",
-      headers: {
-        authorization: `Bearer ${apiKey}`,
-        "content-type": "application/json",
-        ...init.claim ? { "x-bcms-component-claim": init.claim } : {}
-      },
-      ...init.body === void 0 ? {} : { body: JSON.stringify(init.body) }
-    });
-    const text = await response.text();
+    let response;
+    let text;
+    try {
+      response = await fetch(new URL(path, apiUrl), {
+        method: init.method ?? "GET",
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          "content-type": "application/json",
+          ...init.claim ? { "x-bcms-component-claim": init.claim } : {}
+        },
+        ...init.body === void 0 ? {} : { body: JSON.stringify(init.body) },
+        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      });
+      text = await response.text();
+    } catch (error) {
+      const name = error.name;
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new ValidationFailure("COMPONENT_VALIDATION_API_TIMEOUT", `${init.method ?? "GET"} ${path} did not answer within ${API_TIMEOUT_MS / 1e3} seconds.`);
+      }
+      throw error;
+    }
     let parsed = null;
     try {
       parsed = JSON.parse(text);
@@ -516,38 +831,10 @@ async function validateComponent() {
     }
     return (parsed && "data" in parsed ? parsed.data : parsed) ?? {};
   };
-  const claimPath = `/api/v1/projects/${projectId}/component-implementation/implementation-requests/${requestId}`;
-  let claim = null;
-  const claimRequest = async () => {
-    claim = await api(`${claimPath}/claim`, {
-      method: "POST",
-      body: {
-        componentId,
-        commitSha,
-        adapter: { protocol: "bcms-component-runtime-v1", kind: "project-route", path: RUNTIME_PATH, familyKey, previewOrigin, nativeViewports },
-        providerRunId: required("BCMS_RUN_ID"),
-        providerRunAttempt: Number(process.env.BCMS_RUN_ATTEMPT) || 1,
-        providerRunUrl: required("BCMS_RUN_URL"),
-        workflowRef: required("BCMS_WORKFLOW_REF"),
-        // The server caps this at the request's own expiry and at ten minutes.
-        credentialExpiresAt: new Date(Date.now() + 10 * 6e4 - 5e3).toISOString()
-      }
-    });
-    return claim;
-  };
   const work = mkdtempSync(join2(tmpdir(), "bcms-validate-"));
-  let runtime = null;
-  try {
-    const manifest = await api(`/api/v1/projects/${projectId}/component-preview/manifest`);
-    const entry = manifest.components.find((c) => c.id === componentId);
-    if (!entry) {
-      throw new ValidationFailure(
-        "COMPONENT_SOURCE_NOT_RECORDED",
-        "No file is recorded as this component's source. The agent that writes a component records it with set_component_source."
-      );
-    }
+  const prepare = async (manifest) => {
     const manifestPath = join2(work, "manifest.json");
-    writeFileSync2(manifestPath, JSON.stringify({ components: manifest.components.map(({ id: id2, source }) => ({ id: id2, source })) }));
+    writeFileSync2(manifestPath, JSON.stringify({ components: manifest.components.map(({ id, source, fallback }) => ({ id, source, ...fallback ? { fallback } : {} })) }));
     const out = join2(work, "runtime");
     let built;
     try {
@@ -555,12 +842,17 @@ async function validateComponent() {
     } catch (error) {
       throw new ValidationFailure("COMPONENT_PREVIEW_BUILD_FAILED", `The preview build failed: ${error.message}`);
     }
+    const tarball = join2(work, "bundle.tgz");
+    if (spawnSync2("tar", ["-czf", tarball, "-C", out, "."], { stdio: "inherit" }).status !== 0) {
+      throw new ValidationFailure("COMPONENT_PREVIEW_BUNDLE_PACK_FAILED", "The preview runtime could not be packaged.");
+    }
+    const bundle = readFileSync2(tarball);
     const runtimeManifest = JSON.parse(readFileSync2(join2(out, "bcms-runtime.json"), "utf8"));
     const port = await freePort();
     const validatorKey = randomBytes(32).toString("base64url");
     const local = `http://127.0.0.1:${port}`;
     const { BCMS_API_KEY: _withheld, ...inherited } = process.env;
-    runtime = spawn(process.execPath, [join2(out, runtimeManifest.dir, runtimeManifest.entry)], {
+    const child = spawn(process.execPath, [join2(out, runtimeManifest.dir, runtimeManifest.entry)], {
       cwd: join2(out, runtimeManifest.dir),
       env: {
         ...inherited,
@@ -580,106 +872,76 @@ async function validateComponent() {
       stream.write(chunk);
       for (const line of chunk.toString("utf8").split("\n")) {
         const clean = line.replace(/\x1b\[[0-9;]*m/g, "").trim();
-        if (serverErrors.length < 5 && /\b(error|exception)\b/i.test(clean)) serverErrors.push(clean.slice(0, 200));
+        if (serverErrors.length < 500 && /\b(error|exception)\b/i.test(clean)) serverErrors.push(clean.slice(0, 200));
       }
     };
-    runtime.stdout?.on("data", collect(process.stdout));
-    runtime.stderr?.on("data", collect(process.stderr));
-    if (!await waitForOk(`${local}${PREVIEW_ROUTE_BASE}/health`, 6e4)) {
-      throw new ValidationFailure("COMPONENT_PREVIEW_RUNTIME_DID_NOT_START", "The preview runtime did not start within 60 seconds.");
-    }
-    const stored = await fetch(`${local}${PREVIEW_ROUTE_BASE}/props`, {
-      method: "POST",
-      headers: { "content-type": "application/json", "x-bcms-validator-key": validatorKey },
-      body: JSON.stringify({ componentId, props: entry.defaultProps })
-    });
-    if (!stored.ok) {
-      throw new ValidationFailure("COMPONENT_PREVIEW_RUNTIME_REFUSED", `The preview runtime refused the component (HTTP ${stored.status}).`);
-    }
-    const { id } = await stored.json();
-    const render = await renderInBrowser(
-      `${local}${PREVIEW_ROUTE_BASE}/render?id=${encodeURIComponent(id)}`,
-      nativeViewports,
-      manifest.brandTokenNames,
-      { section: built.kinds[componentId] === "section" }
-    );
-    const tarball = join2(work, "bundle.tgz");
-    if (spawnSync2("tar", ["-czf", tarball, "-C", out, "."], { stdio: "inherit" }).status !== 0) {
-      throw new ValidationFailure("COMPONENT_PREVIEW_BUNDLE_PACK_FAILED", "The preview runtime could not be packaged.");
+    child.stdout?.on("data", collect(process.stdout));
+    child.stderr?.on("data", collect(process.stderr));
+    let browser = null;
+    try {
+      if (!await waitForOk(`${local}${PREVIEW_ROUTE_BASE}/health`, 6e4)) {
+        throw new ValidationFailure("COMPONENT_PREVIEW_RUNTIME_DID_NOT_START", "The preview runtime did not start within 60 seconds.");
+      }
+      ensureBrowser();
+      const { chromium } = await import("playwright");
+      browser = await chromium.launch();
+    } catch (error) {
+      child.kill();
+      throw error;
     }
-    const bytes = readFileSync2(tarball);
-    runtime.kill();
-    runtime = null;
-    const target = (await claimRequest()).request;
-    const checks = {
-      brandKit: {
-        status: render.missingTokens.length === 0 ? "passed" : "failed",
-        contractHash: target.brandContractHash,
-        missingTokens: render.missingTokens
-      },
-      runtime: {
-        status: render.runtimeErrors === 0 && render.consoleErrors === 0 ? "passed" : "failed",
-        runtimeErrors: render.runtimeErrors,
-        consoleErrors: render.consoleErrors,
-        // Only on a failure, and bounded: the server's own error lines first (the real cause), then what the
-        // browser saw. The database stores them and the panel shows the first one.
-        ...render.runtimeErrors + render.consoleErrors > 0 ? { problems: [...serverErrors.map((line) => `server: ${line}`), ...render.problems].slice(0, 10).map((line) => line.slice(0, 200)) } : {}
+    const shared = browser;
+    return {
+      kinds: built.kinds,
+      bundle,
+      storeProps: async (componentId, props, signal) => {
+        const stored = await fetch(`${local}${PREVIEW_ROUTE_BASE}/props`, {
+          method: "POST",
+          headers: { "content-type": "application/json", "x-bcms-validator-key": validatorKey },
+          body: JSON.stringify({ componentId, props }),
+          signal
+        });
+        if (!stored.ok) {
+          throw new ValidationFailure("COMPONENT_PREVIEW_RUNTIME_REFUSED", `The preview runtime refused the component (HTTP ${stored.status}).`);
+        }
+        return (await stored.json()).id;
       },
-      visual: { status: "baseline-missing", reviewRequired: true, viewports: render.results }
-    };
-    const upload = await api(`/api/v1/projects/${projectId}/artifacts/upload-url`, { method: "POST" });
-    const put = await fetch(upload.uploadUrl, { method: "PUT", body: bytes, headers: { "content-type": "application/gzip" } });
-    if (!put.ok) {
-      throw new ValidationFailure("COMPONENT_PREVIEW_BUNDLE_UPLOAD_FAILED", `Storage refused the preview bundle (HTTP ${put.status}).`);
-    }
-    await api(`/api/v1/projects/${projectId}/component-preview/bundles`, {
-      method: "POST",
-      body: { commitSha: target.commitSha, uploadKey: upload.uploadKey, checksum: `sha256:${sha256(bytes)}`, sizeBytes: bytes.byteLength }
-    });
-    const evidenceDigest = `sha256:${sha256(canonical({ requestId, commitSha: target.commitSha, checks }))}`;
-    await api(`${claimPath}/complete`, {
-      method: "POST",
-      claim: claim.claimCapability,
-      body: {
-        componentId: target.componentId,
-        candidateId: target.candidateId,
-        componentVersion: target.componentVersion,
-        familyKey: target.familyKey,
-        familyContractHash: target.familyContractHash,
-        schemaHash: target.schemaHash,
-        brandContractHash: target.brandContractHash,
-        dependenciesHash: target.dependenciesHash,
-        commitSha: target.commitSha,
-        adapterHash: target.adapterHash,
-        familyManifestHash: target.familyManifestHash,
-        nativeViewports: target.nativeViewports,
-        checks,
-        evidenceDigest
+      render: (renderId, viewports, tokenNames, options, signal) => renderInBrowser(shared, `${local}${PREVIEW_ROUTE_BASE}/render?id=${encodeURIComponent(renderId)}`, viewports, tokenNames, options, signal),
+      serverErrorCount: () => serverErrors.length,
+      serverErrorsSince: (mark) => serverErrors.slice(mark),
+      close: async () => {
+        child.kill();
+        await shared.close().catch(() => {
+        });
       }
+    };
+  };
+  const budget = Number(process.env.BCMS_BATCH_BUDGET_MS);
+  try {
+    const result = await runValidationBatch(batch, ctx, {
+      api,
+      prepare,
+      putBundle: async (uploadUrl, bytes) => {
+        try {
+          const put = await fetch(uploadUrl, {
+            method: "PUT",
+            body: new Uint8Array(bytes),
+            headers: { "content-type": "application/gzip" },
+            signal: AbortSignal.timeout(BUNDLE_UPLOAD_TIMEOUT_MS)
+          });
+          return { ok: put.ok, status: put.status };
+        } catch (error) {
+          const name = error.name;
+          if (name !== "TimeoutError" && name !== "AbortError") throw error;
+          throw new ValidationFailure("COMPONENT_PREVIEW_BUNDLE_UPLOAD_FAILED", `Storage did not accept the preview bundle within ${BUNDLE_UPLOAD_TIMEOUT_MS / 6e4} minutes.`);
+        }
+      },
+      budgetMs: Number.isFinite(budget) && budget > 0 ? budget : DEFAULT_BATCH_BUDGET_MS
     });
-    const passed = checks.brandKit.status === "passed" && checks.runtime.status === "passed";
-    console.log(`bcms-preview: validation ${passed ? "PASSED" : "FAILED"} for ${componentId}`);
-    if (!passed) {
-      if (render.missingTokens.length) console.log(`  brand tokens used but not defined: ${render.missingTokens.join(", ")}`);
-      for (const problem of render.problems) console.log(`  ${problem}`);
-    }
-  } catch (error) {
-    const code = error instanceof ValidationFailure ? error.code : "COMPONENT_VALIDATION_FAILED";
-    const message = error.message.slice(0, 2e3);
-    const reported = claim ?? await claimRequest().catch((claimError) => {
-      console.error(`bcms-preview: could not claim the request to report the failure: ${claimError.message}`);
-      return null;
-    });
-    if (reported) {
-      await api(`${claimPath}/fail`, {
-        method: "POST",
-        claim: reported.claimCapability,
-        body: { componentId, errorCode: code, errorMessage: message }
-      }).catch((reportError) => console.error(`bcms-preview: could not report the failure: ${reportError.message}`));
+    if (batch.length > 1) {
+      console.log(`bcms-preview: ${result.completed.length} of ${batch.length} components completed, ${result.failed.length} could not be validated`);
     }
-    throw new CliFailure(`${code}: ${message}`);
+    if (result.exitCode) process.exitCode = 1;
   } finally {
-    runtime?.kill();
     rmSync2(work, { recursive: true, force: true });
   }
 }