doc-detective 4.30.0 → 4.31.0

package/dist/index.cjs

@@ -634107,6 +634107,49 @@ function logLevelEnabled(config, level) {
     return true;
   return false;
 }
+function viewportMismatchWarning(requested, actual, tolerance = 0) {
+  const parts = [];
+  for (const dim of ["width", "height"]) {
+    const req = Number(requested?.[dim]);
+    if (!(req > 0))
+      continue;
+    const act = Number(actual?.[dim]);
+    if (!Number.isFinite(act)) {
+      parts.push(`${dim} requested ${req}px, rendered unknown`);
+    } else if (Math.abs(act - req) > tolerance) {
+      parts.push(`${dim} requested ${req}px, rendered ${act}px`);
+    }
+  }
+  if (parts.length === 0)
+    return null;
+  return `Requested viewport not fully realized \u2014 the browser or OS enforces a minimum window size: ${parts.join("; ")}. Screenshots and measurements reflect the rendered size, not the requested size.`;
+}
+function resolveViewportTarget(requested, current) {
+  const w = Number(requested?.width);
+  const h = Number(requested?.height);
+  return {
+    width: w > 0 ? w : Number(current?.width),
+    height: h > 0 ? h : Number(current?.height)
+  };
+}
+async function readViewport(driver) {
+  const v = await driver.execute("return { width: window.innerWidth, height: window.innerHeight }", []);
+  return { width: Number(v?.width), height: Number(v?.height) };
+}
+async function realizeViewport(driver, requested, config = {}, label) {
+  const current = await readViewport(driver);
+  const target = resolveViewportTarget(requested, current);
+  const windowSize = await driver.getWindowSize();
+  const deltaWidth = Number.isFinite(current.width) && Number.isFinite(target.width) ? target.width - current.width : 0;
+  const deltaHeight = Number.isFinite(current.height) && Number.isFinite(target.height) ? target.height - current.height : 0;
+  await driver.setWindowSize(Math.round(windowSize.width + deltaWidth), Math.round(windowSize.height + deltaHeight));
+  const actual = await readViewport(driver);
+  const warning = viewportMismatchWarning(requested, actual, VIEWPORT_TOLERANCE_PX);
+  if (warning) {
+    await log(config, "warning", label ? `${label}: ${warning}` : warning);
+  }
+  return actual;
+}
 async function log(config, level, message) {
   if (message === void 0) {
     message = config;
@@ -634441,7 +634484,7 @@ function llevenshteinDistance(s, t) {
   }
   return arr[t.length][s.length];
 }
-var import_node_fs7, import_node_os2, import_node_path5, import_node_crypto2, import_promises, import_node_net, import_axios, import_node_child_process4, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, FETCH_BINARY_DEFAULTS, ENV_VAR_REGEX, posixBashProbe;
+var import_node_fs7, import_node_os2, import_node_path5, import_node_crypto2, import_promises, import_node_net, import_axios, import_node_child_process4, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, FETCH_BINARY_DEFAULTS, VIEWPORT_TOLERANCE_PX, ENV_VAR_REGEX, posixBashProbe;
 var init_utils = __esm({
   "dist/core/utils.js"() {
     "use strict";
@@ -634483,6 +634526,7 @@ var init_utils = __esm({
       maxBodyLength: 50 * 1024 * 1024,
       maxRedirects: 5
     };
+    VIEWPORT_TOLERANCE_PX = 16;
     ENV_VAR_REGEX = /\$[a-zA-Z0-9_]+(?![a-zA-Z0-9_$])/g;
   }
 });
@@ -646563,6 +646607,14 @@ async function saveScreenshot({ config, step, driver, appSession }) {
       return result;
     }
   }
+  try {
+    const savedMeta = await sharp(finalBuffer).metadata();
+    if (savedMeta.width && savedMeta.height) {
+      result.outputs.width = savedMeta.width;
+      result.outputs.height = savedMeta.height;
+    }
+  } catch {
+  }
   const writeFinalPng = (destination) => {
     try {
       import_node_fs20.default.writeFileSync(destination, finalBuffer);
@@ -648764,20 +648816,31 @@ async function startSurfaceStep({ config, step, platform, driver, processRegistr
     }
     const vw = Number(d.viewport?.width);
     const vh = Number(d.viewport?.height);
+    let viewportOutput;
     if (vw > 0 || vh > 0) {
+      const requested = {
+        ...vw > 0 ? { width: vw } : {},
+        ...vh > 0 ? { height: vh } : {}
+      };
+      let rendered;
       try {
-        await applyViewport(opened.driver, d.viewport);
+        rendered = await realizeViewport(opened.driver, requested, config, `startSurface "${opened.name}"`);
       } catch (error) {
         return {
           status: "FAIL",
           description: `Opened browser surface "${opened.name}" but couldn't apply the viewport: ${error?.message ?? error}`
         };
       }
+      viewportOutput = { requested, actual: rendered };
     }
     return {
       status: "PASS",
       description: `Opened browser surface "${opened.name}" (${engine}).`,
-      outputs: { name: opened.name, engine }
+      outputs: {
+        name: opened.name,
+        engine,
+        ...viewportOutput ? { viewport: viewportOutput } : {}
+      }
     };
   };
   const runProcessDescriptor = async (d) => {
@@ -648892,13 +648955,6 @@ async function startSurfaceStep({ config, step, platform, driver, processRegistr
     outputs: { surfaces: results }
   };
 }
-async function applyViewport(driver, viewport) {
-  const viewportSize = await driver.execute("return { width: window.innerWidth, height: window.innerHeight }", []);
-  const windowSize = await driver.getWindowSize();
-  const deltaWidth = (viewport.width || viewportSize.width) - viewportSize.width;
-  const deltaHeight = (viewport.height || viewportSize.height) - viewportSize.height;
-  await driver.setWindowSize(windowSize.width + deltaWidth, windowSize.height + deltaHeight);
-}
 
 // dist/core/tests/mobileBrowser.js
 var import_node_path24 = __toESM(require("node:path"), 1);
@@ -650108,6 +650164,10 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
           // 10 minutes
           "appium:executable": chromium.driver,
           browserName: "chrome",
+          // Classic WebDriver, no BiDi socket. Enabling `webSocketUrl` for
+          // viewport emulation (driver.setViewport) crashed headed recording
+          // contexts with a stack overflow and can't be gated off recording
+          // (viewport+recording is a supported combo) — see ADR 01072 (rejected).
           "wdio:enforceWebDriverClassic": true,
           // Disable BiDi, use classic mode
           "goog:chromeOptions": {
@@ -650465,14 +650525,18 @@ function driverSkipDiagnostic({ requestedName, platform, platformMatches, attemp
   msg += ` A present-but-broken driver (for example a partially downloaded ${driverHint}) can cause this; reinstall the driver or its browser.`;
   return msg;
 }
-async function setViewportSize(context, driver) {
-  if (context.browser?.viewport?.width || context.browser?.viewport?.height) {
-    const viewportSize = await driver.execute("return { width: window.innerWidth, height: window.innerHeight }", []);
-    const windowSize = await driver.getWindowSize();
-    const deltaWidth = (context.browser?.viewport?.width || viewportSize.width) - viewportSize.width;
-    const deltaHeight = (context.browser?.viewport?.height || viewportSize.height) - viewportSize.height;
-    await driver.setWindowSize(windowSize.width + deltaWidth, windowSize.height + deltaHeight);
+async function setViewportSize(context, driver, config = {}) {
+  const vw = Number(context.browser?.viewport?.width);
+  const vh = Number(context.browser?.viewport?.height);
+  if (vw > 0 || vh > 0) {
+    const requested = {
+      ...vw > 0 ? { width: vw } : {},
+      ...vh > 0 ? { height: vh } : {}
+    };
+    const label = `viewport for ${context.browser?.name ?? "browser"} on ${context.platform ?? "host"}`;
+    return realizeViewport(driver, requested, config, label);
   }
+  return void 0;
 }
 async function allowUnsafeSteps({ config }) {
   if (config.allowUnsafeSteps === true)
@@ -652191,8 +652255,10 @@ ${JSON.stringify(context, null, 2)}`);
           driver
         });
       }
-      if (context.browser?.viewport?.width || context.browser?.viewport?.height) {
-        await setViewportSize(context, driver);
+      const viewportW = Number(context.browser?.viewport?.width);
+      const viewportH = Number(context.browser?.viewport?.height);
+      if (viewportW > 0 || viewportH > 0) {
+        await setViewportSize(context, driver, config);
       } else if (context.browser?.window?.width || context.browser?.window?.height) {
         const windowSize = await driver.getWindowSize();
         await driver.setWindowSize(context.browser?.window?.width || windowSize.width, context.browser?.window?.height || windowSize.height);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-detective",
-  "version": "4.30.0",
+  "version": "4.31.0",
   "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
   "bin": {
     "doc-detective": "bin/doc-detective.js",