@democraft/playwright 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,1548 @@
+// src/types.ts
+var DEFAULT_SETTLE_STRATEGY = {
+  idleWindowMs: 350,
+  timeoutMs: 4e3,
+  signal: "both"
+};
+
+// src/environment-fingerprint.ts
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+var CAPTURE_ENVIRONMENT_HASH_PREFIX = "capture-env-v1:sha256:";
+async function resolveCaptureEnvironment(options = {}, runtime = {
+  node: process.versions.node,
+  platform: process.platform,
+  arch: process.arch,
+  engine: "chromium"
+}) {
+  const configured = options.environment ?? {};
+  const settle = resolveSettleStrategy(configured.settle);
+  const viewport = configured.viewport ?? { width: 1920, height: 1080 };
+  const environment = {
+    headless: options.headless ?? true,
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: configured.deviceScaleFactor ?? 2,
+    locale: configured.locale ?? "en-US",
+    timezone: configured.timezone ?? "UTC",
+    settle: settle ?? false,
+    timeoutMs: options.timeoutMs ?? 8e3
+  };
+  const storageStateHash = configured.storageState ? sha256(await readFile(configured.storageState)) : null;
+  const fingerprint = JSON.stringify({
+    ...environment,
+    storageStateHash,
+    runtime: {
+      node: runtime.node,
+      platform: runtime.platform,
+      arch: runtime.arch,
+      engine: runtime.engine
+    }
+  });
+  return {
+    environment,
+    captureEnvironmentHash: `${CAPTURE_ENVIRONMENT_HASH_PREFIX}${sha256(fingerprint)}`
+  };
+}
+function resolveSettleStrategy(settle) {
+  if (settle === false) return void 0;
+  if (settle === void 0) return { ...DEFAULT_SETTLE_STRATEGY };
+  return { ...DEFAULT_SETTLE_STRATEGY, ...settle };
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+// src/runner.ts
+import { access as access2, mkdir as mkdir2 } from "fs/promises";
+import { isAbsolute, relative, resolve } from "path";
+import {
+  parseDemoIR,
+  parseRecordedDemoManifest,
+  schemaVersion
+} from "@democraft/schema";
+
+// src/bindings.ts
+import { chromium } from "playwright";
+var defaultBindings = {
+  chromium
+};
+
+// src/execute.ts
+import { join } from "path";
+
+// src/screenshot-path.ts
+import { createHash as createHash2 } from "crypto";
+import path from "path";
+function canonicalScreenshotFilename(sceneId, stepId) {
+  const digest = createHash2("sha256").update(sceneId).update("\0").update(stepId).digest("hex").slice(0, 12);
+  return `${safeSegment(sceneId)}-${safeSegment(stepId)}-${digest}.png`;
+}
+function screenshotRelativePath(sceneId, stepId) {
+  return `screenshots/${canonicalScreenshotFilename(sceneId, stepId)}`;
+}
+function resolveRecordedScreenshotPath(captureDirectory, step) {
+  if (step.screenshotPath) {
+    return resolveContained(captureDirectory, step.screenshotPath);
+  }
+  const legacy = `screenshots/${step.sceneId}-${step.stepId}.png`;
+  return resolveContained(captureDirectory, legacy);
+}
+function resolveContained(root, relativePath) {
+  if (path.isAbsolute(relativePath)) return void 0;
+  const rootAbsolute = path.resolve(root);
+  const candidate = path.resolve(rootAbsolute, relativePath);
+  const relative2 = path.relative(rootAbsolute, candidate);
+  if (!relative2 || relative2.startsWith("..") || path.isAbsolute(relative2)) {
+    return void 0;
+  }
+  return candidate;
+}
+function safeSegment(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "step";
+}
+
+// src/execute.ts
+import {
+  diagnosticDocsUrl as diagnosticDocsUrl2
+} from "@democraft/schema";
+
+// src/locator.ts
+async function resolveTarget(ir, page, targetId, timeoutMs = 5e3) {
+  const startedAtMs = Date.now();
+  const target = ir.targets[targetId];
+  const attemptedLocators = [];
+  if (!target) {
+    return {
+      snapshot: {
+        targetId,
+        attemptedLocators,
+        visible: false,
+        resolutionDurationMs: Date.now() - startedAtMs
+      }
+    };
+  }
+  for (const locatorDefinition of target.locators) {
+    const locator = createLocator(page, locatorDefinition);
+    try {
+      let visible = await locator.isVisible({ timeout: timeoutMs });
+      if (!visible && locator.waitFor) {
+        try {
+          await locator.waitFor({ state: "visible", timeout: timeoutMs });
+          visible = true;
+        } catch {
+          visible = false;
+        }
+      }
+      const boundingBox = await locator.boundingBox({ timeout: timeoutMs }) ?? void 0;
+      attemptedLocators.push({ locator: locatorDefinition, success: visible });
+      if (visible) {
+        return {
+          locator,
+          snapshot: {
+            targetId,
+            attemptedLocators,
+            successfulLocator: locatorDefinition,
+            boundingBox,
+            visible,
+            resolutionDurationMs: Date.now() - startedAtMs
+          }
+        };
+      }
+    } catch (error) {
+      attemptedLocators.push({
+        locator: locatorDefinition,
+        success: false,
+        error: error instanceof Error ? error.message : "Locator failed."
+      });
+    }
+  }
+  return {
+    snapshot: {
+      targetId,
+      attemptedLocators,
+      visible: false,
+      resolutionDurationMs: Date.now() - startedAtMs
+    }
+  };
+}
+function createLocator(page, locator) {
+  switch (locator.kind) {
+    case "role":
+      return page.getByRole(locator.role, { name: locator.name });
+    case "label":
+      return page.getByLabel(locator.text);
+    case "testId":
+      return page.getByTestId(locator.id);
+    case "text":
+      return page.getByText(locator.text);
+  }
+}
+function resolveUrl(ir, path3) {
+  if (/^https?:\/\//.test(path3)) return path3;
+  return new URL(path3, ir.source.baseUrl).toString();
+}
+
+// src/diagnostics.ts
+import {
+  diagnosticDocsUrl
+} from "@democraft/schema";
+function targetDiagnostic(demoId, sceneId, stepId, targetId, message, details) {
+  return {
+    code: "DC201",
+    severity: "error",
+    message,
+    path: `scenes.${sceneId}.steps.${stepId}.target`,
+    suggestion: message.includes("could not be resolved") ? `Review the locators declared for target "${targetId}".` : `Inspect target "${targetId}" and the failed assertion.`,
+    docsUrl: diagnosticDocsUrl("DC201"),
+    demoId,
+    sceneId,
+    stepId,
+    targetId,
+    details
+  };
+}
+function unresolvedTargetDiagnostic(demoId, sceneId, stepId, targetId, attemptedLocators) {
+  return targetDiagnostic(
+    demoId,
+    sceneId,
+    stepId,
+    targetId,
+    `Target "${targetId}" could not be resolved.`,
+    { attemptedLocators }
+  );
+}
+
+// src/settle.ts
+async function waitForSettled(page, strategy) {
+  const deadline = Date.now() + strategy.timeoutMs;
+  const needDom = strategy.signal === "dom" || strategy.signal === "both";
+  const needVisual = strategy.signal === "visual" || strategy.signal === "both";
+  const needNetwork = strategy.signal === "network" || strategy.signal === "both";
+  const monitors = await installMonitors(page, {
+    dom: needDom,
+    network: needNetwork
+  });
+  const quietSinceBySignal = {};
+  const initSignal = (name) => {
+    quietSinceBySignal[name] = Date.now();
+  };
+  if (needDom && monitors.dom) initSignal("dom");
+  if (needVisual) initSignal("visual");
+  if (needNetwork && monitors.network) initSignal("network");
+  let lastVisualSignature;
+  while (Date.now() < deadline) {
+    const now = Date.now();
+    if (monitors.dom) {
+      const mutations = await withFallback(readDomMutations(page), 0);
+      if (mutations > 0) quietSinceBySignal["dom"] = Date.now();
+    }
+    if (needVisual) {
+      const signature = await withFallback(visualSignature(page), void 0);
+      if (signature !== void 0 && signature !== lastVisualSignature) {
+        lastVisualSignature = signature;
+        quietSinceBySignal["visual"] = Date.now();
+      }
+    }
+    if (monitors.network) {
+      const active = await withFallback(readNetworkActivity(page), 0);
+      if (active > 0) quietSinceBySignal["network"] = Date.now();
+    }
+    const signals = [];
+    if (needDom && monitors.dom) {
+      signals.push(now - quietSinceBySignal["dom"] >= strategy.idleWindowMs);
+    }
+    if (needVisual) {
+      signals.push(now - quietSinceBySignal["visual"] >= strategy.idleWindowMs);
+    }
+    if (needNetwork && monitors.network) {
+      signals.push(
+        now - quietSinceBySignal["network"] >= strategy.idleWindowMs
+      );
+    }
+    if (signals.length > 0 && signals.every(Boolean)) return;
+    await sleep(Math.max(50, strategy.idleWindowMs / 2));
+  }
+}
+async function withFallback(promise, fallback, perCallMs = 2e3) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((resolve2) => {
+        timer = setTimeout(() => resolve2(fallback), perCallMs);
+      })
+    ]);
+  } catch {
+    return fallback;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function installMonitors(page, need) {
+  if (!page.evaluate) return { dom: false, network: false };
+  try {
+    await withFallback(
+      page.evaluate(() => {
+        const w = window;
+        w.__democraftMutations = 0;
+        w.__democraftObserver?.disconnect();
+        const observer = new MutationObserver(() => {
+          w.__democraftMutations = (w.__democraftMutations ?? 0) + 1;
+        });
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          characterData: true
+        });
+        w.__democraftObserver = observer;
+        if (!w.__democraftInstrumented) {
+          w.__democraftFetchActive = 0;
+          const originalFetch = window.fetch;
+          window.fetch = function democraftFetch(...args) {
+            w.__democraftFetchActive = (w.__democraftFetchActive ?? 0) + 1;
+            return originalFetch.apply(this, args).finally(() => {
+              w.__democraftFetchActive = Math.max(
+                0,
+                (w.__democraftFetchActive ?? 0) - 1
+              );
+            });
+          };
+          const originalOpen = XMLHttpRequest.prototype.open;
+          const originalSend = XMLHttpRequest.prototype.send;
+          XMLHttpRequest.prototype.open = function democraftXhrOpen(...args) {
+            this.addEventListener("loadend", () => {
+              w.__democraftFetchActive = Math.max(
+                0,
+                (w.__democraftFetchActive ?? 0) - 1
+              );
+            });
+            return originalOpen.apply(this, args);
+          };
+          XMLHttpRequest.prototype.send = function democraftXhrSend(...args) {
+            w.__democraftFetchActive = (w.__democraftFetchActive ?? 0) + 1;
+            return originalSend.apply(this, args);
+          };
+          w.__democraftInstrumented = true;
+        } else {
+          w.__democraftFetchActive = 0;
+        }
+      }),
+      void 0
+    );
+    return { dom: need.dom, network: need.network };
+  } catch {
+    return { dom: false, network: false };
+  }
+}
+async function readDomMutations(page) {
+  return page.evaluate(() => {
+    const w = window;
+    const count = w.__democraftMutations ?? 0;
+    w.__democraftMutations = 0;
+    return count;
+  });
+}
+async function readNetworkActivity(page) {
+  return page.evaluate(() => {
+    const w = window;
+    return w.__democraftFetchActive ?? 0;
+  });
+}
+async function visualSignature(page) {
+  if (!page.screenshot) return void 0;
+  try {
+    const png = await page.screenshot({ type: "png" });
+    return hashBuffer(png);
+  } catch {
+    return void 0;
+  }
+}
+function hashBuffer(buf) {
+  let hash = 2166136261;
+  for (let i = 0; i < buf.length; i += 1) {
+    hash ^= buf[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+function sleep(ms) {
+  return new Promise((resolve2) => {
+    setTimeout(resolve2, ms);
+  });
+}
+
+// src/execute.ts
+async function executeStep(args) {
+  const startedAtMs = Date.now();
+  let targetSnapshot;
+  try {
+    switch (args.step.kind) {
+      case "browser.goto":
+        await args.page.goto(resolveUrl(args.ir, args.step.path));
+        break;
+      case "browser.click": {
+        const resolved = await resolveTarget(
+          args.ir,
+          args.page,
+          args.step.target,
+          args.timeoutMs
+        );
+        targetSnapshot = resolved.snapshot;
+        if (resolved.locator) {
+          const urlBefore = args.page.url();
+          await resolved.locator.click();
+          await waitForClientNavigation(args.page, urlBefore, args.timeoutMs);
+        } else {
+          args.diagnostics.push(
+            unresolvedTargetDiagnostic(
+              args.ir.id,
+              args.sceneId,
+              args.step.id,
+              args.step.target,
+              resolved.snapshot.attemptedLocators
+            )
+          );
+        }
+        break;
+      }
+      case "browser.fill": {
+        const resolved = await resolveTarget(
+          args.ir,
+          args.page,
+          args.step.target,
+          args.timeoutMs
+        );
+        targetSnapshot = resolved.snapshot;
+        if (resolved.locator) {
+          await resolved.locator.fill(args.step.value);
+        } else {
+          args.diagnostics.push(
+            unresolvedTargetDiagnostic(
+              args.ir.id,
+              args.sceneId,
+              args.step.id,
+              args.step.target,
+              resolved.snapshot.attemptedLocators
+            )
+          );
+        }
+        break;
+      }
+      case "browser.select": {
+        const resolved = await resolveTarget(
+          args.ir,
+          args.page,
+          args.step.target,
+          args.timeoutMs
+        );
+        targetSnapshot = resolved.snapshot;
+        if (resolved.locator) {
+          await resolved.locator.selectOption(args.step.value);
+        } else {
+          args.diagnostics.push(
+            unresolvedTargetDiagnostic(
+              args.ir.id,
+              args.sceneId,
+              args.step.id,
+              args.step.target,
+              resolved.snapshot.attemptedLocators
+            )
+          );
+        }
+        break;
+      }
+      case "assert.visible": {
+        const resolved = await resolveTarget(
+          args.ir,
+          args.page,
+          args.step.target,
+          args.timeoutMs
+        );
+        targetSnapshot = resolved.snapshot;
+        if (!targetSnapshot.visible) {
+          args.diagnostics.push(
+            targetDiagnostic(
+              args.ir.id,
+              args.sceneId,
+              args.step.id,
+              args.step.target,
+              "Target is not visible."
+            )
+          );
+        }
+        break;
+      }
+      case "assert.text": {
+        const resolved = await resolveTarget(
+          args.ir,
+          args.page,
+          args.step.target,
+          args.timeoutMs
+        );
+        targetSnapshot = resolved.snapshot;
+        const text = await resolved.locator?.textContent();
+        if (!text?.includes(args.step.text)) {
+          args.diagnostics.push(
+            targetDiagnostic(
+              args.ir.id,
+              args.sceneId,
+              args.step.id,
+              args.step.target,
+              `Target text does not include "${args.step.text}".`
+            )
+          );
+        }
+        break;
+      }
+      case "assert.url":
+        if (!args.page.url().includes(args.step.path)) {
+          args.diagnostics.push({
+            code: "DC201",
+            severity: "error",
+            message: `Current URL "${args.page.url()}" does not include "${args.step.path}".`,
+            path: `scenes.${args.sceneId}.steps.${args.step.id}.path`,
+            suggestion: `Navigate to a URL containing "${args.step.path}" or update the assertion.`,
+            docsUrl: diagnosticDocsUrl2("DC201"),
+            demoId: args.ir.id,
+            sceneId: args.sceneId,
+            stepId: args.step.id
+          });
+        }
+        break;
+      case "camera.establish":
+      case "camera.focus":
+      case "overlay.callout":
+        if ("target" in args.step && args.step.target) {
+          targetSnapshot = (await resolveTarget(
+            args.ir,
+            args.page,
+            args.step.target,
+            args.timeoutMs
+          )).snapshot;
+        }
+        break;
+      case "overlay.caption":
+      case "overlay.visual":
+      case "timeline.hold":
+      case "timeline.transition":
+      case "cue":
+        break;
+    }
+  } catch (error) {
+    args.diagnostics.push({
+      code: "DC201",
+      severity: "error",
+      message: error instanceof Error ? error.message : "Step execution failed.",
+      path: `scenes.${args.sceneId}.steps.${args.step.id}`,
+      suggestion: "Inspect the failed browser step and its target contract.",
+      docsUrl: diagnosticDocsUrl2("DC201"),
+      demoId: args.ir.id,
+      sceneId: args.sceneId,
+      stepId: args.step.id
+    });
+  }
+  if (args.settleStrategy && stepIsActionDriven(args.step)) {
+    await waitForSettled(args.page, args.settleStrategy);
+  }
+  if (!args.settleStrategy || !stepIsActionDriven(args.step)) {
+    await args.page.waitForTimeout?.(captureStepHoldMs(args.step));
+  }
+  let screenshotPath;
+  const screenshotFilename = canonicalScreenshotFilename(
+    args.sceneId,
+    args.step.id
+  );
+  try {
+    await args.page.screenshot?.({
+      path: join(args.screenshotsPath, screenshotFilename),
+      // Capture the viewport, not the full document. A full-page screenshot
+      // grows with page content (a tall dashboard yields a 1440×3244 PNG while
+      // a short page yields 1440×900), so consecutive steps would be captured
+      // at different aspect ratios and the renderer's fixed-size stage would
+      // re-scale every cut — visible as flicker/flash between steps. The
+      // viewport is constant (matches `environment.viewport`), so every
+      // screenshot lands at identical dimensions and maps 1:1 onto the stage.
+      // Element bounding boxes from Playwright are viewport-relative, so camera
+      // focus targets line up with what the screenshot actually shows.
+      fullPage: false
+    });
+    if (args.page.screenshot) {
+      screenshotPath = screenshotRelativePath(args.sceneId, args.step.id);
+    }
+  } catch (error) {
+    args.diagnostics.push({
+      code: "DC201",
+      severity: "warning",
+      message: error instanceof Error ? `Screenshot failed: ${error.message}` : "Screenshot failed.",
+      path: `scenes.${args.sceneId}.steps.${args.step.id}`,
+      suggestion: "Check screenshot permissions and the browser page state.",
+      docsUrl: diagnosticDocsUrl2("DC201"),
+      demoId: args.ir.id,
+      sceneId: args.sceneId,
+      stepId: args.step.id
+    });
+  }
+  return {
+    stepId: args.step.id,
+    sceneId: args.sceneId,
+    kind: args.step.kind,
+    startedAtMs,
+    endedAtMs: Date.now(),
+    targetSnapshot,
+    url: args.page.url(),
+    screenshotPath
+  };
+}
+function stepIsActionDriven(step) {
+  switch (step.kind) {
+    case "browser.goto":
+    case "browser.click":
+    case "browser.fill":
+    case "browser.select":
+    case "assert.visible":
+    case "assert.text":
+    case "assert.url":
+    case "camera.establish":
+    case "camera.focus":
+    case "overlay.callout":
+      return true;
+    case "timeline.hold":
+    case "timeline.transition":
+    case "overlay.caption":
+    case "overlay.visual":
+    case "cue":
+      return false;
+  }
+}
+function captureStepHoldMs(step) {
+  switch (step.kind) {
+    case "timeline.hold":
+      return step.durationMs;
+    case "timeline.transition":
+      return step.durationMs ?? 500;
+    case "overlay.caption":
+      return Math.max(1200, step.text.length * 45);
+    case "overlay.callout":
+      return Math.max(
+        1800,
+        `${step.title} ${step.description ?? ""}`.trim().length * 45
+      );
+    case "overlay.visual":
+      return step.durationMs ?? 1800;
+    case "camera.establish":
+      return 700;
+    case "camera.focus":
+      return 1100;
+    case "browser.click":
+      return 650;
+    case "browser.fill":
+    case "browser.select":
+      return 700;
+    case "browser.goto":
+      return 700;
+    case "assert.visible":
+    case "assert.text":
+    case "assert.url":
+      return 300;
+    case "cue":
+      return 1;
+  }
+}
+var CLIENT_NAV_TIMEOUT_MS = 6e3;
+var CLIENT_NAV_POLL_MS = 150;
+async function waitForClientNavigation(page, urlBefore, timeoutMs = CLIENT_NAV_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (page.url() !== urlBefore) {
+      await withTimeout(
+        page.waitForLoadState?.("domcontentloaded"),
+        CLIENT_NAV_TIMEOUT_MS
+      );
+      return;
+    }
+    await sleep2(CLIENT_NAV_POLL_MS);
+  }
+}
+function sleep2(ms) {
+  return new Promise((resolve2) => {
+    setTimeout(resolve2, ms);
+  });
+}
+async function withTimeout(promise, ms) {
+  if (!promise) return;
+  let timer;
+  try {
+    await Promise.race([
+      promise,
+      new Promise((resolve2) => {
+        timer = setTimeout(resolve2, ms);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// src/capture-artifacts.ts
+import { createHash as createHash3, randomBytes } from "crypto";
+import {
+  access,
+  lstat,
+  mkdir,
+  readdir,
+  readFile as readFile2,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import { homedir } from "os";
+import path2 from "path";
+import {
+  parseCaptureArtifactMetadata,
+  parseCaptureArtifactMetadataJson,
+  parseLatestCapturePointer,
+  parseLatestCapturePointerJson,
+  parseRecordedDemoManifestJson
+} from "@democraft/schema";
+var MAX_CREATE_ATTEMPTS = 16;
+var LATEST_LOCK_ATTEMPTS = 200;
+var LOCK_LEASE_MS = 3e4;
+var LOCK_RETRY_MS = 10;
+async function createCaptureArtifact(options, dependencies = {}) {
+  const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
+  const randomId = dependencies.randomId ?? (() => randomBytes(6).toString("hex"));
+  const slug = captureSlug(options.demoId);
+  const namespace = captureNamespace(options.demoId);
+  const createdAt = now().toISOString();
+  const timestamp = createdAt.replace(/[:.]/g, "-");
+  buildInitialMetadata(options, `${slug}-${timestamp}-validation`, createdAt);
+  let directory;
+  let captureRunId = "";
+  let demoDirectory;
+  let metadata;
+  let releaseLock;
+  if (options.outputDirectory) {
+    directory = options.outputDirectory;
+    captureRunId = `${slug}-${timestamp}-${randomId()}`;
+    metadata = buildInitialMetadata(options, captureRunId, createdAt);
+    await mkdir(directory, { recursive: true });
+    releaseLock = await acquireCaptureLeaseLock(
+      path2.join(directory, ".capture.lock"),
+      options.lockOptions
+    );
+    try {
+      await rm(path2.join(directory, "manifest.json"), { force: true });
+    } catch (error) {
+      await releaseLock();
+      throw error;
+    }
+  } else {
+    demoDirectory = path2.join(options.rootDirectory, namespace);
+    await mkdir(demoDirectory, { recursive: true });
+    for (let attempt = 0; attempt < MAX_CREATE_ATTEMPTS; attempt += 1) {
+      const suffix = `${timestamp}-${randomId()}`;
+      const candidate = path2.join(demoDirectory, suffix);
+      const candidateRunId = `${slug}-${suffix}`;
+      const candidateMetadata = buildInitialMetadata(
+        options,
+        candidateRunId,
+        createdAt
+      );
+      try {
+        await mkdir(candidate, { recursive: false });
+        directory = candidate;
+        captureRunId = candidateRunId;
+        metadata = candidateMetadata;
+        break;
+      } catch (error) {
+        if (!isNodeError(error, "EEXIST")) throw error;
+      }
+    }
+  }
+  if (!directory) {
+    throw new Error(
+      `Could not allocate a unique capture directory after ${MAX_CREATE_ATTEMPTS} attempts.`
+    );
+  }
+  if (!metadata) throw new Error("Capture metadata was not initialized.");
+  const artifact = {
+    captureRunId,
+    demoId: options.demoId,
+    directory,
+    metadataPath: path2.join(directory, "metadata.json"),
+    manifestPath: path2.join(directory, "manifest.json"),
+    screenshotsPath: path2.join(directory, "screenshots"),
+    tracePath: path2.join(directory, "trace.zip"),
+    metadata,
+    managed: options.outputDirectory === void 0,
+    demoDirectory,
+    releaseLock
+  };
+  try {
+    await writeCaptureMetadata(artifact, metadata);
+  } catch (error) {
+    await releaseLock?.();
+    if (artifact.managed) {
+      await rm(artifact.directory, { recursive: true, force: true });
+    }
+    throw error;
+  }
+  return artifact;
+}
+async function startCaptureArtifact(artifact, now = /* @__PURE__ */ new Date()) {
+  assertMutable(artifact);
+  const timestamp = now.toISOString();
+  await writeCaptureMetadata(artifact, {
+    ...artifact.metadata,
+    status: "running",
+    startedAt: timestamp,
+    updatedAt: timestamp
+  });
+}
+async function completeCaptureArtifact(artifact, options = {}) {
+  assertMutable(artifact);
+  await access(artifact.manifestPath);
+  const timestamp = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const relativeRecording = options.recordingPath ? relativeArtifactPath(artifact.directory, options.recordingPath) : void 0;
+  await writeCaptureMetadata(artifact, {
+    ...artifact.metadata,
+    status: "completed",
+    updatedAt: timestamp,
+    finishedAt: timestamp,
+    paths: {
+      ...artifact.metadata.paths,
+      trace: options.traceAvailable ? "trace.zip" : void 0,
+      recording: relativeRecording
+    }
+  });
+  if (artifact.managed && artifact.demoDirectory) {
+    await updateLatestCapturePointer(artifact, timestamp).catch(
+      () => void 0
+    );
+  }
+}
+async function failCaptureArtifact(artifact, error, now = /* @__PURE__ */ new Date()) {
+  assertMutable(artifact);
+  const timestamp = now.toISOString();
+  await writeCaptureMetadata(artifact, {
+    ...artifact.metadata,
+    status: "failed",
+    startedAt: artifact.metadata.startedAt ?? timestamp,
+    updatedAt: timestamp,
+    finishedAt: timestamp,
+    error: { message: redactCaptureErrorMessage(error, artifact.directory) }
+  });
+}
+async function cancelCaptureArtifact(artifact, now = /* @__PURE__ */ new Date()) {
+  assertMutable(artifact);
+  const timestamp = now.toISOString();
+  await writeCaptureMetadata(artifact, {
+    ...artifact.metadata,
+    status: "cancelled",
+    startedAt: artifact.metadata.startedAt ?? timestamp,
+    updatedAt: timestamp,
+    finishedAt: timestamp
+  });
+}
+async function writeCaptureManifestAtomic(artifact, json) {
+  await writeFileAtomic(artifact.manifestPath, json);
+}
+async function resolveLatestCompletedCapture(rootDirectory, demoId) {
+  let canonicalRoot;
+  try {
+    canonicalRoot = await realpath(rootDirectory);
+  } catch {
+    return void 0;
+  }
+  const directories = [
+    path2.join(rootDirectory, captureNamespace(demoId)),
+    path2.join(rootDirectory, captureSlug(demoId))
+  ];
+  const scanned = (await Promise.all(
+    directories.map(
+      (dir) => scanCompletedCaptures(canonicalRoot, dir, demoId)
+    )
+  )).flat().sort(compareCompletedCaptures)[0];
+  if (scanned) {
+    await repairPointer(scanned).catch(() => void 0);
+    return {
+      captureDir: scanned.directory,
+      manifestPath: path2.join(scanned.directory, "manifest.json"),
+      captureRunId: scanned.metadata.captureRunId,
+      legacy: false
+    };
+  }
+  if (path2.basename(demoId) !== demoId || demoId === "." || demoId === "..") {
+    return void 0;
+  }
+  const legacyDir = path2.join(rootDirectory, demoId);
+  const safeLegacyDir = await canonicalContained(canonicalRoot, legacyDir);
+  if (safeLegacyDir && await isReusableCaptureDirectory(safeLegacyDir, demoId)) {
+    return {
+      captureDir: legacyDir,
+      manifestPath: path2.join(legacyDir, "manifest.json"),
+      legacy: true
+    };
+  }
+  return void 0;
+}
+async function isReusableCaptureDirectory(directory, demoId) {
+  try {
+    const canonicalDirectory = await realpath(directory);
+    const manifestPath = await canonicalContained(
+      canonicalDirectory,
+      path2.join(directory, "manifest.json")
+    );
+    if (!manifestPath) return false;
+    const manifest = parseRecordedDemoManifestJson(
+      await readFile2(manifestPath, "utf8")
+    );
+    if (manifest.demoId !== demoId) return false;
+    try {
+      const metadataCandidate = path2.join(directory, "metadata.json");
+      const metadataPath = await canonicalContained(
+        canonicalDirectory,
+        metadataCandidate
+      );
+      if (!metadataPath) {
+        try {
+          await lstat(metadataCandidate);
+          return false;
+        } catch (error) {
+          return isNodeError(error, "ENOENT");
+        }
+      }
+      const metadata = parseCaptureArtifactMetadataJson(
+        await readFile2(metadataPath, "utf8")
+      );
+      return metadata.status === "completed" && metadata.demoId === demoId && metadata.captureRunId === manifest.captureRunId && metadata.captureEnvironmentHash === manifest.captureEnvironmentHash;
+    } catch (error) {
+      return isNodeError(error, "ENOENT");
+    }
+  } catch {
+    return false;
+  }
+}
+function captureSlug(demoId) {
+  const slug = demoId.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  return slug || "demo";
+}
+function captureNamespace(demoId) {
+  const digest = createHash3("sha256").update(demoId).digest("hex").slice(0, 12);
+  return `${captureSlug(demoId)}-${digest}`;
+}
+function isCaptureAbort(error, signal) {
+  return Boolean(signal?.aborted) || error instanceof CaptureAbortError;
+}
+var CaptureAbortError = class extends Error {
+  constructor() {
+    super("Capture was cancelled.");
+    this.name = "AbortError";
+  }
+};
+async function writeCaptureMetadata(artifact, metadata) {
+  const validated = parseCaptureArtifactMetadata(metadata);
+  await writeFileAtomic(
+    artifact.metadataPath,
+    `${JSON.stringify(validated, null, 2)}
+`
+  );
+  artifact.metadata = validated;
+}
+async function updateLatestCapturePointer(artifact, completedAt, force = false) {
+  const demoDirectory = artifact.demoDirectory;
+  const lockPath = path2.join(demoDirectory, ".latest.lock");
+  const releaseLock = await acquireCaptureLeaseLock(lockPath);
+  try {
+    const pointerPath = path2.join(demoDirectory, "latest.json");
+    let current;
+    try {
+      current = parseLatestCapturePointerJson(
+        await readFile2(pointerPath, "utf8")
+      );
+    } catch {
+      current = void 0;
+    }
+    const next = parseLatestCapturePointer({
+      schemaVersion: 1,
+      demoId: artifact.demoId,
+      captureRunId: artifact.captureRunId,
+      captureDirectory: path2.basename(artifact.directory),
+      completedAt
+    });
+    if (force || !current || comparePointers(next, current) > 0) {
+      await writeFileAtomic(pointerPath, `${JSON.stringify(next, null, 2)}
+`);
+    }
+  } finally {
+    await releaseLock();
+  }
+}
+function compareCompletedCaptures(left, right) {
+  const byFinishedAt = (right.finishedAt ?? "").localeCompare(
+    left.finishedAt ?? ""
+  );
+  return byFinishedAt || right.metadata.captureRunId.localeCompare(left.metadata.captureRunId);
+}
+async function scanCompletedCaptures(rootDirectory, demoDirectory, demoId) {
+  const publicDemoDirectory = demoDirectory;
+  const safeDemoDirectory = await canonicalContained(
+    rootDirectory,
+    demoDirectory
+  );
+  if (!safeDemoDirectory) return [];
+  demoDirectory = safeDemoDirectory;
+  let entries;
+  try {
+    entries = await readdir(demoDirectory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = await Promise.all(
+    entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+      const directory = path2.join(demoDirectory, entry.name);
+      const publicDirectory = path2.join(publicDemoDirectory, entry.name);
+      try {
+        const metadataPath = await canonicalContained(
+          directory,
+          path2.join(directory, "metadata.json")
+        );
+        if (!metadataPath) return void 0;
+        const metadata = parseCaptureArtifactMetadataJson(
+          await readFile2(metadataPath, "utf8")
+        );
+        if (metadata.status !== "completed" || metadata.demoId !== demoId || !await isReusableCaptureDirectory(directory, demoId)) {
+          return void 0;
+        }
+        return {
+          directory: publicDirectory,
+          demoDirectory: publicDemoDirectory,
+          metadata,
+          finishedAt: metadata.finishedAt
+        };
+      } catch {
+        return void 0;
+      }
+    })
+  );
+  return candidates.filter((item) => Boolean(item));
+}
+async function canonicalContained(root, candidate) {
+  try {
+    const canonical = await realpath(candidate);
+    const relative2 = path2.relative(root, canonical);
+    return relative2 !== ".." && !relative2.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative2) ? canonical : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function repairPointer(capture) {
+  const artifact = {
+    captureRunId: capture.metadata.captureRunId,
+    demoId: capture.metadata.demoId,
+    directory: capture.directory,
+    demoDirectory: capture.demoDirectory
+  };
+  await updateLatestCapturePointer(
+    artifact,
+    capture.finishedAt ?? capture.metadata.updatedAt,
+    true
+  );
+}
+function comparePointers(left, right) {
+  const byTime = left.completedAt.localeCompare(right.completedAt);
+  return byTime || left.captureRunId.localeCompare(right.captureRunId);
+}
+function buildInitialMetadata(options, captureRunId, createdAt) {
+  return parseCaptureArtifactMetadata({
+    schemaVersion: 1,
+    captureRunId,
+    demoId: options.demoId,
+    definitionHash: options.definitionHash,
+    captureHash: options.captureHash,
+    captureEnvironmentHash: options.captureEnvironmentHash,
+    status: "created",
+    createdAt,
+    updatedAt: createdAt,
+    paths: { manifest: "manifest.json", screenshots: "screenshots" },
+    environment: options.environment
+  });
+}
+async function acquireCaptureLeaseLock(lockPath, options = {}) {
+  const token = randomBytes(16).toString("hex");
+  const leaseMs = options.leaseMs ?? LOCK_LEASE_MS;
+  const retryMs = options.retryMs ?? LOCK_RETRY_MS;
+  const maxAttempts = options.maxAttempts ?? LATEST_LOCK_ATTEMPTS;
+  const malformedStaleMs = options.malformedStaleMs ?? leaseMs;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const acquired = await withOperationGuard(
+      lockPath,
+      malformedStaleMs,
+      async () => {
+        await cleanupLegacyRecoveryMarker(lockPath, malformedStaleMs);
+        const exists = await fileExists(lockPath);
+        const current = exists ? await readLock(lockPath) : void 0;
+        if (!exists) {
+          const now2 = Date.now();
+          await writeFile(
+            lockPath,
+            lockContents(token, process.pid, now2, leaseMs),
+            { flag: "wx" }
+          );
+          return true;
+        }
+        const malformedOld = current ? false : await existsOldMalformed(lockPath, malformedStaleMs);
+        if (!malformedOld && (!current || isProcessAlive(current.pid))) {
+          return false;
+        }
+        await options.insideRecoveryGuard?.();
+        const confirmed = await readLock(lockPath);
+        const confirmedMalformedOld = confirmed ? false : await existsOldMalformed(lockPath, malformedStaleMs);
+        if (!confirmedMalformedOld && (!confirmed || isProcessAlive(confirmed.pid))) {
+          return false;
+        }
+        await rm(lockPath, { force: true });
+        const now = Date.now();
+        await writeFile(
+          lockPath,
+          lockContents(token, process.pid, now, leaseMs),
+          { flag: "wx" }
+        );
+        return true;
+      }
+    );
+    if (acquired) {
+      let released = false;
+      const refresh = async () => {
+        if (released) return false;
+        return awaitOperationGuard(
+          lockPath,
+          malformedStaleMs,
+          retryMs,
+          maxAttempts,
+          async () => {
+            const current = await readLock(lockPath);
+            return current?.token === token && current.pid === process.pid;
+          }
+        );
+      };
+      let releasePromise;
+      const release = Object.assign(
+        async () => {
+          if (!releasePromise) {
+            released = true;
+            releasePromise = awaitOperationGuard(
+              lockPath,
+              malformedStaleMs,
+              retryMs,
+              maxAttempts,
+              async () => {
+                await options.insideReleaseGuard?.();
+                const current = await readLock(lockPath);
+                if (current?.token === token) {
+                  await rm(lockPath, { force: true });
+                }
+                return true;
+              }
+            ).then(() => void 0);
+          }
+          await releasePromise;
+        },
+        { refresh }
+      );
+      return release;
+    }
+    if (attempt + 1 < maxAttempts) await delay(retryMs);
+  }
+  throw new Error(
+    `Timed out acquiring capture lock ${path2.basename(lockPath)}.`
+  );
+}
+async function awaitOperationGuard(lockPath, malformedStaleMs, retryMs, maxAttempts, operation) {
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const result = await withOperationGuard(
+      lockPath,
+      malformedStaleMs,
+      operation
+    );
+    if (result !== void 0) return result;
+    if (attempt + 1 < maxAttempts) await delay(retryMs);
+  }
+  throw new Error(
+    `Timed out entering capture lock operation guard ${path2.basename(lockPath)}.`
+  );
+}
+function lockContents(token, pid, createdAt, leaseMs) {
+  return `${JSON.stringify({ token, pid, createdAt, expiresAt: Date.now() + leaseMs })}
+`;
+}
+async function readLock(lockPath) {
+  try {
+    const value = JSON.parse(await readFile2(lockPath, "utf8"));
+    if (typeof value.token !== "string" || !Number.isInteger(value.pid) || !Number.isFinite(value.createdAt) || !Number.isFinite(value.expiresAt)) {
+      return void 0;
+    }
+    return value;
+  } catch {
+    return void 0;
+  }
+}
+async function withOperationGuard(lockPath, malformedStaleMs, operation) {
+  const guardPath = `${lockPath}.operation`;
+  const recoveryPath = `${guardPath}.recovery`;
+  const token = randomBytes(16).toString("hex");
+  await cleanupOrphanGuardRecovery(recoveryPath, malformedStaleMs);
+  if (await fileExists(recoveryPath)) return void 0;
+  try {
+    const now = Date.now();
+    await writeFile(
+      guardPath,
+      lockContents(token, process.pid, now, Math.max(malformedStaleMs, 100)),
+      { flag: "wx" }
+    );
+  } catch (error) {
+    if (!isNodeError(error, "EEXIST")) throw error;
+    const guard = await readLock(guardPath);
+    const malformedOld = guard ? false : await existsOldMalformed(guardPath, malformedStaleMs);
+    if (!malformedOld && (!guard || isProcessAlive(guard.pid)))
+      return void 0;
+    if (!await claimGuardRecovery(recoveryPath, malformedStaleMs)) {
+      return void 0;
+    }
+    let recovered = false;
+    try {
+      const confirmed = await readLock(guardPath);
+      const confirmedMalformedOld = confirmed ? false : await existsOldMalformed(guardPath, malformedStaleMs);
+      if (confirmedMalformedOld || confirmed && !isProcessAlive(confirmed.pid)) {
+        await rm(guardPath, { force: true });
+        const now = Date.now();
+        await writeFile(
+          guardPath,
+          lockContents(
+            token,
+            process.pid,
+            now,
+            Math.max(malformedStaleMs, 100)
+          ),
+          { flag: "wx" }
+        );
+        recovered = true;
+      }
+    } finally {
+      await rm(recoveryPath, { force: true });
+    }
+    if (!recovered) return void 0;
+  }
+  try {
+    return await operation();
+  } finally {
+    const guard = await readLock(guardPath);
+    if (guard?.token === token) await rm(guardPath, { force: true });
+  }
+}
+async function claimGuardRecovery(recoveryPath, malformedStaleMs) {
+  await cleanupOrphanGuardRecovery(recoveryPath, malformedStaleMs);
+  const now = Date.now();
+  try {
+    await writeFile(
+      recoveryPath,
+      lockContents(
+        randomBytes(16).toString("hex"),
+        process.pid,
+        now,
+        Math.max(malformedStaleMs, 100)
+      ),
+      { flag: "wx" }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function cleanupOrphanGuardRecovery(recoveryPath, malformedStaleMs) {
+  const marker = await readLock(recoveryPath);
+  const malformedOld = marker ? false : await existsOldMalformed(recoveryPath, malformedStaleMs);
+  if (malformedOld || marker && !isProcessAlive(marker.pid)) {
+    await rm(recoveryPath, { force: true });
+  }
+}
+async function cleanupLegacyRecoveryMarker(lockPath, malformedStaleMs) {
+  await cleanupOrphanGuardRecovery(`${lockPath}.recovery`, malformedStaleMs);
+}
+async function fileExists(file) {
+  return access(file).then(() => true).catch(() => false);
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isNodeError(error, "EPERM");
+  }
+}
+async function existsOldMalformed(file, ageMs) {
+  return stat(file).then((value) => Date.now() - value.mtimeMs > ageMs).catch(() => false);
+}
+async function writeFileAtomic(file, contents) {
+  const temporary = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(temporary, contents, { flag: "wx" });
+    await rename(temporary, file);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+function relativeArtifactPath(directory, target) {
+  const relative2 = path2.relative(directory, path2.resolve(target));
+  if (relative2 && !relative2.startsWith("..") && !path2.isAbsolute(relative2)) {
+    return relative2;
+  }
+  return path2.basename(target);
+}
+function redactCaptureErrorMessage(error, directory) {
+  const raw = error instanceof Error ? error.message : String(error);
+  const paths = [
+    [directory ? path2.resolve(directory) : "", "[capture]"],
+    [process.cwd(), "[workspace]"],
+    [homedir(), "[home]"]
+  ];
+  const pathRedacted = paths.reduce(
+    (message, [sensitive, replacement]) => sensitive ? message.split(sensitive).join(replacement) : message,
+    raw
+  );
+  return pathRedacted.replace(
+    /\b(Proxy-Authorization|Authorization|Set-Cookie|Cookie)\s*:\s*[^\r\n]*/gi,
+    "$1: [redacted]"
+  ).replace(/:\/\/[^\s/@:]+(?::[^\s/@]*)?@/g, "://[redacted]@").replace(
+    /([?&](?:access_?token|token|code|api_?key|key|secret|password|passwd|auth|authorization|signature|sig)=)[^&#\s]*/gi,
+    "$1[redacted]"
+  ).replace(
+    /\b((?:access_?token|token|api_?key|secret|password|passwd|authorization|signature)\s*[=:]\s*)[^\s,;&#/?]+/gi,
+    "$1[redacted]"
+  );
+}
+function assertMutable(artifact) {
+  if (["completed", "failed", "cancelled"].includes(artifact.metadata.status)) {
+    throw new Error(
+      `Capture ${artifact.captureRunId} is already ${artifact.metadata.status}.`
+    );
+  }
+}
+function isNodeError(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+function delay(durationMs) {
+  return new Promise((resolve2) => setTimeout(resolve2, durationMs));
+}
+
+// src/runner.ts
+async function runDemo(ir, options = {}) {
+  return runDemoWithBindings(ir, defaultBindings, options);
+}
+async function runDemoWithBindings(ir, bindings, options = {}) {
+  ir = parseDemoIR(ir);
+  const configuredEnvironment = options.environment ?? {};
+  const resolvedEnvironment = await resolveCaptureEnvironment(options);
+  const environment = resolvedEnvironment.environment;
+  const viewport = environment.viewport;
+  const deviceScaleFactor = environment.deviceScaleFactor;
+  const timeoutMs = environment.timeoutMs;
+  assertPositiveFinite("viewport.width", viewport.width);
+  assertPositiveFinite("viewport.height", viewport.height);
+  assertPositiveFinite("deviceScaleFactor", deviceScaleFactor);
+  assertPositiveFinite("timeoutMs", timeoutMs);
+  throwIfAborted(options.signal);
+  const settleStrategy = resolveSettleStrategy(environment.settle);
+  const artifact = await createCaptureArtifact({
+    rootDirectory: options.captureRootDir ?? resolve(".democraft", "runs"),
+    outputDirectory: options.outputDir,
+    demoId: ir.id,
+    definitionHash: ir.definitionHash,
+    captureHash: ir.captureHash,
+    captureEnvironmentHash: resolvedEnvironment.captureEnvironmentHash,
+    environment
+  });
+  const diagnostics = [];
+  const steps = [];
+  let browser;
+  let context;
+  let page;
+  let traceStarted = false;
+  let recordingPath;
+  let traceAvailable = false;
+  try {
+    await startCaptureArtifact(artifact);
+    await options.onArtifactCreated?.({
+      captureRunId: artifact.captureRunId,
+      outputDir: artifact.directory,
+      manifestPath: artifact.manifestPath,
+      metadataPath: artifact.metadataPath
+    });
+    throwIfAborted(options.signal);
+    await mkdir2(artifact.screenshotsPath, { recursive: true });
+    throwIfAborted(options.signal);
+    browser = await bindings.chromium.launch({
+      headless: environment.headless
+    });
+    throwIfAborted(options.signal);
+    context = await browser.newContext({
+      viewport,
+      deviceScaleFactor,
+      locale: environment.locale,
+      timezoneId: environment.timezone,
+      storageState: configuredEnvironment.storageState,
+      recordVideo: { dir: artifact.directory, size: viewport }
+    });
+    let executionFailed = false;
+    let executionError;
+    let cleanupFailed = false;
+    let cleanupError;
+    try {
+      throwIfAborted(options.signal);
+      await context.tracing?.start({
+        screenshots: true,
+        snapshots: true,
+        sources: true
+      });
+      traceStarted = Boolean(context.tracing);
+      throwIfAborted(options.signal);
+      page = await context.newPage();
+      for (const scene of ir.scenes) {
+        for (const step of scene.steps) {
+          throwIfAborted(options.signal);
+          const recorded = await executeStep({
+            ir,
+            page,
+            sceneId: scene.id,
+            step,
+            // Default 8s: SPAs (Next App Router) can take several seconds to
+            // swap a route on a cold code-split chunk, and this timeout gates
+            // both target resolution and click-navigation. Override for faster
+            // apps or mock runtimes.
+            timeoutMs,
+            screenshotsPath: artifact.screenshotsPath,
+            diagnostics,
+            settleStrategy
+          });
+          steps.push(recorded);
+          throwIfAborted(options.signal);
+        }
+      }
+    } catch (error) {
+      executionFailed = true;
+      executionError = error;
+    } finally {
+      if (traceStarted) {
+        try {
+          await context.tracing?.stop({ path: artifact.tracePath });
+        } catch (error) {
+          cleanupFailed = true;
+          cleanupError = error;
+        }
+        if (!cleanupFailed) {
+          traceAvailable = await access2(artifact.tracePath).then(() => true).catch(() => false);
+        }
+      }
+      try {
+        await context.close();
+      } catch (error) {
+        if (!cleanupFailed) cleanupError = error;
+        cleanupFailed = true;
+      }
+      try {
+        recordingPath = await page?.video?.()?.path().catch(() => void 0);
+      } catch {
+      }
+    }
+    if (executionFailed) throw executionError;
+    if (cleanupFailed) throw cleanupError;
+    await browser.close();
+    browser = void 0;
+    throwIfAborted(options.signal);
+    const manifest = parseRecordedDemoManifest({
+      schemaVersion,
+      demoId: ir.id,
+      captureRunId: artifact.captureRunId,
+      definitionHash: ir.definitionHash,
+      captureHash: ir.captureHash,
+      captureEnvironmentHash: resolvedEnvironment.captureEnvironmentHash,
+      capture: {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor
+      },
+      recording: recordingPath ? {
+        path: publicArtifactPath(recordingPath),
+        width: viewport.width,
+        height: viewport.height
+      } : void 0,
+      tracePath: traceAvailable ? publicArtifactPath(artifact.tracePath) : void 0,
+      screenshotsPath: publicArtifactPath(artifact.screenshotsPath),
+      steps,
+      diagnostics
+    });
+    await writeCaptureManifestAtomic(
+      artifact,
+      `${JSON.stringify(manifest, null, 2)}
+`
+    );
+    await completeCaptureArtifact(artifact, { recordingPath, traceAvailable });
+    return manifest;
+  } catch (error) {
+    try {
+      if (isCaptureAbort(error, options.signal)) {
+        await cancelCaptureArtifact(artifact);
+      } else {
+        await failCaptureArtifact(artifact, error);
+      }
+    } catch {
+    }
+    throw error;
+  } finally {
+    await browser?.close().catch(() => void 0);
+    await artifact.releaseLock?.();
+  }
+}
+function assertPositiveFinite(name, value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${name} must be a finite number greater than 0.`);
+  }
+}
+function throwIfAborted(signal) {
+  if (!signal?.aborted) return;
+  throw new CaptureAbortError();
+}
+function publicArtifactPath(target) {
+  const absolute = resolve(target);
+  const fromCwd = relative(process.cwd(), absolute);
+  return fromCwd && !fromCwd.startsWith("..") && !isAbsolute(fromCwd) ? fromCwd : absolute;
+}
+export {
+  CAPTURE_ENVIRONMENT_HASH_PREFIX,
+  CaptureAbortError,
+  DEFAULT_SETTLE_STRATEGY,
+  acquireCaptureLeaseLock,
+  cancelCaptureArtifact,
+  canonicalScreenshotFilename,
+  captureNamespace,
+  captureSlug,
+  completeCaptureArtifact,
+  createCaptureArtifact,
+  failCaptureArtifact,
+  isReusableCaptureDirectory,
+  redactCaptureErrorMessage,
+  resolveCaptureEnvironment,
+  resolveLatestCompletedCapture,
+  resolveRecordedScreenshotPath,
+  resolveTarget,
+  runDemo,
+  runDemoWithBindings,
+  screenshotRelativePath,
+  startCaptureArtifact,
+  writeCaptureManifestAtomic
+};