@taprootio/site-authoring 0.8.4 → 0.8.6

package/src/cli.js

@@ -15,7 +15,9 @@ import {
   SURFACE_DOCS_PRESENTATION,
   SURFACE_STANDARD,
   VERB_APPROVE,
+  VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
+  VERB_STAGING_REVIEW,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_HELP,
@@ -290,7 +292,11 @@ const VERBS = Object.freeze([
     tokens: ["theme", "push"],
     summary: "Validate and push the workspace's complete theme and appearance settings.",
     note: "Run pull first. Theme JSON stays decoded in the workspace; this command validates the complete light/dark"
-      + " pair and encodes it only at the API boundary. Image settings reference site-owned image IDs from media upload.",
+      + " pair and encodes it only at the API boundary. Image settings reference site-owned image IDs from media upload. "
+      + "pull writes each scheme's complete effective theme — the stored theme resolved over the same defaults every "
+      + "consumer renders — so a fresh workspace validates as pulled. semanticMappings holds only authored pins, listed "
+      + "in explicitMappingTokens; every other token compiles from roles at render time, so never copy default "
+      + "mappings into a theme: a pinned token shadows its role.",
   },
   {
     name: VERB_FOOTER_PUSH,
@@ -345,6 +351,10 @@ const VERBS = Object.freeze([
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
+    note: "deploy --staging returns a single-use review handoff in stagingPreview.url, on a managed Docs site too, "
+      + "where it stages settings only: open the URL once, then switch the site's theme toggle to review both "
+      + "schemes before deploy --production. If no handoff could be minted, stagingPreview.reason names why and "
+      + "stagingPreview.recovery the next step; 'staging review' mints another.",
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -357,7 +367,8 @@ const VERBS = Object.freeze([
     note: "Select the persisted draft by page path (as recorded by pull) or canonical lowercase UUID. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "Preview before approving: approve consumes the draft, so a page that has been approved has no draft "
-      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. "
+      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. A preview "
+      + "captured before approval stays revocable afterwards: preview revoke addresses the snapshot itself. "
       + "The handoff URL in the result is single-use and expires two minutes after it is minted: opening it "
       + "consumes it, and a reused, shared, or bookmarked preview URL answers Not found. Run preview page again "
       + "for another. "
@@ -374,6 +385,39 @@ const VERBS = Object.freeze([
     json: true,
     note: "Supply the canonical lowercase page UUID followed by the snapshot UUID returned by preview page.",
   },
+  {
+    name: VERB_DELIVERY_CHECK,
+    surface: SURFACE_DOCS_PRESENTATION,
+    // Deployments reads the deployment log and mints the staging handoff the
+    // check consumes; the public target itself needs no credential.
+    capabilities: [CAPABILITY_DEPLOYMENTS],
+    tokens: ["delivery", "check"],
+    summary: "Verify what a visitor receives after a deployment completed: routes, assets, runtime, browser.",
+    target: true,
+    deliveryOptions: true,
+    note: "A completed deployment job is not a verified delivery. This read-only check reads the target the way a "
+      + "visitor does and reports each dimension separately: the latest completed deployment for the target, HTTP "
+      + "delivery of the authored routes (from the workspace manifest, bounded), the favicon, images, module "
+      + "preloads and site bundle they reference, internal link targets, accidental local-only references, and the "
+      + "declared runtime (major pointer, fallback copy, entry module and capability modules), plus a browser "
+      + "dimension that runs only when Playwright is installed and is reported as unchecked otherwise. --staging "
+      + "resolves the acknowledged staging host and authorizes one preview session for the run (--url is refused "
+      + "there); --production needs --url https://<published-domain>/ because a site-authoring key cannot read "
+      + "hosting configuration. Only assets on the site's own origin and the runtime the page declares are "
+      + "fetched. --wait "
+      + "<seconds> (at most 120) observes everything once more after that pause for edge propagation. --no-browser skips "
+      + "the browser dimension. Nothing is purged, republished or rolled back.",
+  },
+  {
+    name: VERB_STAGING_REVIEW,
+    surface: SURFACE_DOCS_PRESENTATION,
+    capabilities: [CAPABILITY_DEPLOYMENTS],
+    tokens: ["staging", "review"],
+    summary: "Mint a fresh single-use review handoff for the site's staging host.",
+    note: "The handoff URL is reported only in the final JSON as stagingPreview.url, is single-use, and expires two "
+      + "minutes after it is minted; keep it private. Open it once, then use the site's theme toggle to review both "
+      + "schemes. This is the recovery when deploy --staging could not mint a handoff, on a managed Docs site too.",
+  },
   {
     name: VERB_STATUS,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -454,6 +498,12 @@ whoami, and env need no configuration and no site. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
+Install globally (npm install --global @taprootio/site-authoring) or run the
+current release without installing: npx --yes @taprootio/site-authoring@latest
+<verb>. An unversioned npx keeps whatever copy it cached, so always name
+@latest; check what is running with --version, and compare it with the
+release status reports as cliRelease.
+
 Troubleshooting: a command that fails with field=CliUpgradeRequired (or
 refusal=cli_outdated) means this CLI is behind the latest published release,
 which is the only release Taproot accepts. Nothing is wrong with the
@@ -499,10 +549,17 @@ function verbHelp(verb) {
     ? " <page-id> <snapshot-id>"
     : verb.positionals === "environmentSelector"
     ? " [production | local | <url>]"
+    : verb.positionals === "siteSelector"
+    ? " <site-name-or-id>"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
-  const targetOption = verb.target
+  const deliveryOptions = verb.deliveryOptions
+    ? `\n  --url <origin>   The https origin to check; required for --production, refused for --staging.
+  --wait <seconds> Re-check failures once after this pause (0-120) for edge propagation.
+  --no-browser     Skip the browser dimension even when Playwright is installed.`
+    : "";
+  const targetOption = verb.target && !verb.deliveryOptions
     ? `\n  --staging        Deploy the staged site to staging.
   --production     Promote the completed staging deployment to production.
   --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
@@ -571,12 +628,16 @@ function verbHelp(verb) {
   --help           Show this help.
   --version        Show the package version.`
     : COMMON_OPTIONS;
+  const deliveryTargetOption = verb.deliveryOptions
+    ? `\n  --staging        Check the staging target.
+  --production     Check the production target.${deliveryOptions}`
+    : "";
   return `Usage: ${prefix} ${verb.tokens.join(" ")}${positionalUsage}${targetUsage} [options]
 
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${rawHtmlOption}${jsonOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${rawHtmlOption}${jsonOption}${nameOption}${note}
 `;
 }
 
@@ -640,6 +701,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
+      || topic === "walkthrough"
+      || topic === "delivery"
     )
     && (subject !== undefined || extra.length > 0)
   ) {
@@ -707,6 +770,8 @@ function referenceResult(parsed) {
     case "media":
     case "preview":
     case "fixture":
+    case "walkthrough":
+    case "delivery":
       return {
         ...result,
         topic: "workflow",
@@ -746,6 +811,36 @@ function parseConfigOption(arguments_, index) {
  * (trimmed, 1-100 characters) belongs to the verb, which a programmatic caller
  * reaches without passing through this parser at all.
  */
+function parseUrlOption(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  let url;
+  try {
+    url = typeof candidate === "string" ? new URL(candidate) : undefined;
+  } catch {
+    url = undefined;
+  }
+  if (
+    !url || url.protocol !== "https:" || url.username || url.password || url.search || url.hash
+    || (url.pathname !== "/" && url.pathname !== "") || hasAsciiControl(candidate)
+  ) {
+    throw usageError("cli.url_option", "--url requires one https origin such as https://example.com/.", {
+      field: "url",
+    });
+  }
+  return `${url.origin}/`;
+}
+
+function parseWaitOption(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  const seconds = typeof candidate === "string" && /^\d{1,3}$/u.test(candidate) ? Number(candidate) : undefined;
+  if (seconds === undefined || seconds > 120) {
+    throw usageError("cli.wait_option", "--wait requires a whole number of seconds from 0 to 120.", {
+      field: "propagationWaitSeconds",
+    });
+  }
+  return seconds;
+}
+
 function parseNameOption(arguments_, index) {
   const candidate = arguments_[index + 1];
   if (
@@ -812,6 +907,9 @@ function parseArguments(arguments_) {
   let init = false;
   let quiet = false;
   let deployTarget;
+  let deliveryUrl;
+  let propagationWaitSeconds;
+  let browser;
   let allowFailedPreview = false;
   let allowRawHtml = false;
   let json = false;
@@ -848,6 +946,23 @@ function parseArguments(arguments_) {
       deployTarget = candidate;
       continue;
     }
+    if (verb.deliveryOptions && argument === "--url") {
+      if (deliveryUrl !== undefined) throw usageError("cli.duplicate_option", "--url may be supplied only once.");
+      deliveryUrl = parseUrlOption(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.deliveryOptions && argument === "--wait") {
+      if (propagationWaitSeconds !== undefined) throw usageError("cli.duplicate_option", "--wait may be supplied only once.");
+      propagationWaitSeconds = parseWaitOption(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.deliveryOptions && argument === "--no-browser") {
+      if (browser === false) throw usageError("cli.duplicate_option", "--no-browser may be supplied only once.");
+      browser = false;
+      continue;
+    }
     if (verb.target && argument === "--allow-failed-preview") {
       if (allowFailedPreview) {
         throw usageError("cli.duplicate_option", "--allow-failed-preview may be supplied only once.");
@@ -893,7 +1008,10 @@ function parseArguments(arguments_) {
     throw usageError("cli.unexpected_argument", "The command contains an unexpected argument.");
   }
   if (verb.target && deployTarget === undefined) {
-    throw usageError("cli.deploy_target", "deploy requires exactly one of --staging or --production.");
+    throw usageError(
+      "cli.deploy_target",
+      `${verb.tokens.join(" ")} requires exactly one of --staging or --production.`,
+    );
   }
   if (
     verb.positionals === "fixturePath"
@@ -984,6 +1102,9 @@ function parseArguments(arguments_) {
     quiet,
     deployTarget,
     allowFailedPreview,
+    ...(deliveryUrl === undefined ? {} : { deliveryUrl }),
+    ...(propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds }),
+    ...(browser === undefined ? {} : { browser }),
     init,
     allowRawHtml,
     keyName,

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.4";
+export const CLI_VERSION = "0.8.6";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -93,6 +93,8 @@ export const VERB_DEPLOY = "deploy";
 export const VERB_PREVIEW_PAGE = "preview page";
 export const VERB_PREVIEW_REVOKE = "preview revoke";
 export const VERB_STATUS = "status";
+export const VERB_DELIVERY_CHECK = "delivery check";
+export const VERB_STAGING_REVIEW = "staging review";
 export const VERB_SITES = "sites";
 export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
@@ -199,6 +201,11 @@ export const HTTP_TOO_MANY_REQUESTS = 429;
 export const GRPC_UNAUTHENTICATED = 16;
 export const HTTP_UNAUTHORIZED = 401;
 
+// gRPC `NotFound`, and its HTTP mapping. Preview revocation classifies on it:
+// the page or snapshot is not available to this caller on this site.
+export const GRPC_NOT_FOUND = 5;
+export const HTTP_NOT_FOUND = 404;
+
 export const LIMITS = Object.freeze({
   configBytes: 16 * 1024,
   configPathBytes: 4 * 1024,

package/src/delivery-browser.js

@@ -0,0 +1,276 @@
+import { sanitizeDiagnostic } from "./errors.js";
+import { withholdCredentialLocation } from "./staging-check.js";
+
+/**
+ * The optional browser dimension of delivery verification (TR00824).
+ *
+ * HTTP evidence cannot say what a visitor's browser loaded: the shared runtime
+ * comes from a mutable major pointer that a returning browser may hold in its
+ * cache. This probe drives a real browser at the target twice — a fresh
+ * context, then a second navigation in the same context so the browser's own
+ * cache participates — and reports which runtime entry each load evaluated,
+ * whether the declared capability elements were defined, and whether the
+ * second load actually served the runtime entry from cache.
+ *
+ * Playwright is deliberately not a dependency of this package: basic CLI use
+ * must not carry a browser. The probe imports it only if the operator has
+ * installed it where this package's imports resolve (a global install of both
+ * packages, run through the installed command), and reports the dimension as
+ * unchecked with that recovery otherwise.
+ *
+ * Playwright's own request routing is not used: it disables the HTTP cache,
+ * which is the very thing the returning load measures. Instead a DevTools
+ * session on the browser itself — not on the page, because a page session
+ * sees only its own target and authored script can open a popup — intercepts
+ * every document request in the browser (the navigation, each redirect hop,
+ * a script-driven navigation, a frame, a popup) at the request stage, before
+ * it is transmitted, and fails any that would leave the target origin; the
+ * subresource cache is untouched. A page session reports whether the runtime
+ * entry came from the memory or disk cache. Without the browser session the
+ * boundary cannot be enforced, so the dimension is unchecked rather than
+ * probed without it. Every URL the probe reports passes through the
+ * credential withholding the staging check uses, so a handoff-bearing
+ * redirect never reaches the result. A staging cookie is attached only to the
+ * staging origin it was minted for.
+ */
+
+// Node resolves `playwright` from the CLI's own dependency chain: a copy run
+// through `npx` lives in npm's cache and cannot see a global Playwright, so
+// the recovery installs the CLI and Playwright side by side and reruns
+// through the installed `taproot-site` command rather than `npx`.
+export const BROWSER_INSTALL_HINT = "npm install --global @taprootio/site-authoring@latest playwright && npx playwright install chromium, then rerun with the installed taproot-site command (not npx)";
+const SETTLE_MILLISECONDS = 20_000;
+const EVIDENCE_CHARACTERS = 512;
+const BLOCKED_NAVIGATION = /ERR_BLOCKED_BY_CLIENT|ERR_ABORTED/u;
+
+async function defaultImportPlaywright() {
+  return await import("playwright");
+}
+
+/** A URL or entry name as evidence: credentials withheld, controls removed, bounded. */
+function evidence(value) {
+  return [...withholdCredentialLocation(typeof value === "string" ? value : "")].slice(0, EVIDENCE_CHARACTERS).join("");
+}
+
+async function observe(page, capabilities) {
+  return await page.evaluate((declared) => {
+    const root = document.querySelector("esp-root");
+    const entries = performance.getEntriesByType("resource")
+      .map((entry) => entry.name)
+      .filter((name) => /taproot-shared-runtime[^/]*\.js(?:$|\?)/u.test(name));
+    return {
+      rootDefined: customElements.get("esp-root") !== undefined,
+      themeReady: root?.hasAttribute("data-theme-ready") ?? false,
+      loadingHeld: root?.hasAttribute("data-taproot-loading") ?? false,
+      runtimeEntries: entries.slice(0, 4),
+      capabilitiesDefined: declared.filter((tag) => customElements.get(tag) !== undefined).length,
+      title: document.title,
+    };
+  }, capabilities);
+}
+
+const NOTHING_OBSERVED = Object.freeze({ rootDefined: false, themeReady: false, loadingHeld: false, runtimeEntries: [], capabilitiesDefined: 0 });
+
+/** Every URL the navigation passed through, from the first request to the final document. */
+function redirectChain(response) {
+  const hops = [];
+  let request = response?.request?.();
+  while (request && hops.length < 16) {
+    hops.unshift(request.url());
+    request = request.redirectedFrom?.();
+  }
+  return hops;
+}
+
+function sameOrigin(url, origin) {
+  try {
+    return new URL(url).origin === origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The DevTools sessions that enforce the navigation boundary (on the browser,
+ * so every target is covered) and observe cache reuse (on the page). Undefined
+ * when the browser offers no such sessions.
+ */
+async function startDevTools(browser, context, page, { origin, expectedEntryUrl }) {
+  if (typeof browser.newBrowserCDPSession !== "function" || typeof context.newCDPSession !== "function") return undefined;
+  let boundary;
+  let session;
+  try {
+    boundary = await browser.newBrowserCDPSession();
+    session = await context.newCDPSession(page);
+  } catch {
+    return undefined;
+  }
+  const state = { blocked: [], requests: new Map(), fromCache: undefined };
+  boundary.on("Fetch.requestPaused", (event) => {
+    const url = event?.request?.url ?? "";
+    if (sameOrigin(url, origin)) {
+      boundary.send("Fetch.continueRequest", { requestId: event.requestId }).catch(() => undefined);
+    } else {
+      if (state.blocked.length < 8) state.blocked.push(url);
+      boundary.send("Fetch.failRequest", { requestId: event.requestId, errorReason: "BlockedByClient" }).catch(() => undefined);
+    }
+  });
+  session.on("Network.requestWillBeSent", (event) => {
+    if (event?.request?.url === expectedEntryUrl) state.requests.set(event.requestId, event.request.url);
+  });
+  // A memory-cache hit is announced by requestServedFromCache; only a disk
+  // (or prefetch) cache hit is visible on the response itself.
+  session.on("Network.requestServedFromCache", (event) => {
+    if (state.requests.has(event?.requestId)) state.fromCache = true;
+  });
+  session.on("Network.responseReceived", (event) => {
+    if (event?.response?.url !== expectedEntryUrl || state.fromCache === true) return;
+    state.fromCache = Boolean(event.response.fromDiskCache || event.response.fromPrefetchCache);
+  });
+  await session.send("Network.enable");
+  await boundary.send("Fetch.enable", { patterns: [{ urlPattern: "*", resourceType: "Document", requestStage: "Request" }] });
+  return {
+    state,
+    reset() {
+      state.blocked = [];
+      state.requests.clear();
+      state.fromCache = undefined;
+    },
+  };
+}
+
+async function load(page, url, capabilities, origin, devtools) {
+  devtools.reset();
+  let response;
+  let blockedNavigation = false;
+  try {
+    response = await page.goto(url, { waitUntil: "domcontentloaded" });
+  } catch (error) {
+    // The boundary failed a document request before it was sent; the
+    // navigation error is the expected outcome, not a probe failure.
+    if (devtools.state.blocked.length === 0 && !BLOCKED_NAVIGATION.test(String(error?.message ?? ""))) throw error;
+    blockedNavigation = true;
+  }
+  if (!blockedNavigation) {
+    await page.waitForFunction(
+      () => {
+        const root = document.querySelector("esp-root");
+        return root !== null && !root.hasAttribute("data-taproot-loading");
+      },
+      undefined,
+      { timeout: SETTLE_MILLISECONDS },
+    ).catch(() => undefined);
+  }
+  const hops = blockedNavigation ? [] : [...new Set([...redirectChain(response), page.url()])];
+  const strayed = [...new Set([...devtools.state.blocked, ...hops.filter((hop) => !sameOrigin(hop, origin))])];
+  const observed = blockedNavigation ? NOTHING_OBSERVED : await observe(page, capabilities);
+  return { observed, strayed, finalUrl: blockedNavigation ? "" : page.url() };
+}
+
+function judge({ observed, strayed, finalUrl }, expectedEntryUrl, capabilityCount) {
+  const loadedEntry = observed.runtimeEntries.find((name) => name === expectedEntryUrl)
+    ?? observed.runtimeEntries[0]
+    ?? "";
+  return {
+    loadedEntry: evidence(loadedEntry),
+    expectedEntry: observed.runtimeEntries.includes(expectedEntryUrl),
+    rootDefined: observed.rootDefined,
+    themeReady: observed.themeReady,
+    capabilitiesDefined: observed.capabilitiesDefined,
+    capabilitiesDeclared: capabilityCount,
+    finalUrl: evidence(finalUrl),
+    ...(strayed.length > 0 ? { offOriginNavigation: strayed.slice(0, 4).map(evidence) } : {}),
+    ok: strayed.length === 0 && observed.rootDefined && observed.themeReady
+      && observed.runtimeEntries.includes(expectedEntryUrl)
+      && observed.capabilitiesDefined === capabilityCount,
+  };
+}
+
+/**
+ * @param options.baseUrl The delivery origin.
+ * @param options.expectedEntryUrl The runtime entry the major pointer names right now.
+ * @param options.capabilities Custom-element tags the home page declares.
+ * @param options.cookie Optional staging cookie, sent only to `baseUrl`'s host.
+ * @param options.importPlaywright Test seam; defaults to a dynamic import.
+ */
+export async function probeDeliveryWithBrowser({
+  baseUrl,
+  expectedEntryUrl,
+  capabilities = [],
+  cookie,
+  importPlaywright = defaultImportPlaywright,
+}) {
+  let playwright;
+  try {
+    playwright = await importPlaywright();
+  } catch {
+    return {
+      status: "unchecked",
+      reason: "playwright_unavailable",
+      install: BROWSER_INSTALL_HINT,
+      note: "Fresh and returning browser behaviour was not verified; install the CLI and Playwright together and rerun through the installed taproot-site command to check it.",
+    };
+  }
+  const origin = new URL(baseUrl).origin;
+  let browser;
+  try {
+    browser = await playwright.chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    if (cookie) {
+      const [name, value] = cookie.split("=", 2);
+      // A __Host- cookie carries no Domain attribute by definition; the URL
+      // form binds it to the staging origin without one.
+      await context.addCookies([{ name, value, url: baseUrl, secure: true, httpOnly: true, sameSite: "Lax" }]);
+    }
+    const page = await context.newPage();
+    const devtools = await startDevTools(browser, context, page, { origin, expectedEntryUrl });
+    if (!devtools) {
+      await context.close();
+      return {
+        status: "unchecked",
+        reason: "navigation_boundary_unavailable",
+        note: "The browser offers no DevTools sessions, so document requests could not be held to the site origin; nothing was loaded.",
+      };
+    }
+    const fresh = judge(await load(page, baseUrl, capabilities, origin, devtools), expectedEntryUrl, capabilities.length);
+    if (fresh.offOriginNavigation) {
+      // A target that leaves its origin is not probed again.
+      await context.close();
+      return {
+        status: "checked",
+        fresh,
+        returning: { skipped: true, reason: "fresh_load_left_origin", ok: false },
+        staleRuntimeObserved: false,
+        returningCache: { status: "unchecked", reason: "fresh_load_left_origin" },
+        ok: false,
+      };
+    }
+    // The same context navigates again: its HTTP cache now holds whatever the
+    // first load fetched, which is exactly what a returning visitor has.
+    const returning = judge(await load(page, baseUrl, capabilities, origin, devtools), expectedEntryUrl, capabilities.length);
+    const cacheObserved = devtools.state.fromCache;
+    await context.close();
+    return {
+      status: "checked",
+      fresh,
+      returning: {
+        ...returning,
+        runtimeFromCache: cacheObserved === undefined ? "unchecked" : cacheObserved,
+      },
+      staleRuntimeObserved: fresh.ok && !returning.expectedEntry,
+      returningCache: cacheObserved === undefined
+        ? { status: "unchecked", reason: "cache_observation_unavailable" }
+        : { status: "checked", servedFromCache: cacheObserved },
+      ok: fresh.ok && returning.ok,
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      reason: "browser_probe_failed",
+      error: sanitizeDiagnostic(error instanceof Error ? error.name : "Error", "Error"),
+      note: "The browser dimension could not be completed and is not verified.",
+    };
+  } finally {
+    await browser?.close().catch(() => undefined);
+  }
+}