@trylayout/qa 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,9 @@
 # Layout QA
 
+[![npm](https://img.shields.io/npm/v/@trylayout/qa?label=npm)](https://www.npmjs.com/package/@trylayout/qa)
+[![CI](https://github.com/Layout-App/layout-qa/actions/workflows/ci.yml/badge.svg)](https://github.com/Layout-App/layout-qa/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
+
 Layout QA is a local browser QA protocol and runner for AI-built frontends. It runs deterministic flows against a local or preview URL, captures screenshots at meaningful checkpoints, checks browser health, and writes a static HTML report.
 
 The core loop is intentionally local:
@@ -7,10 +11,15 @@ The core loop is intentionally local:
 ```bash
 npx @trylayout/qa init
 npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --open
+npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --viewport 390x844 --open
 ```
 
 No account, upload, hosted service, or external docs are required.
 
+## Example Report
+
+![Layout QA HTML report for a synthetic CRM demo](docs/assets/layout-qa-report.png)
+
 Package names:
 
 - Canonical npm package: `@trylayout/qa`
@@ -28,8 +37,8 @@ npx layout-qa run --target-url http://localhost:5173 --scenario happy_path --ope
 
 Frontend agents can move faster when they have a visual feedback loop they can run themselves. Layout gives the agent a small protocol:
 
-- Wire deterministic API/auth mocks behind a local env flag such as `VITE_LAYOUT_QA_MOCKS=1`.
-- Switch mock states with `localStorage["layout.qa.scenario"]`.
+- Wire deterministic API/auth responses behind a local env flag such as `VITE_LAYOUT_QA_MOCKS=1`.
+- Switch response states with `localStorage["layout.qa.scenario"]`.
 - Declare high-value browser flows in `.layout/qa-flows.json`.
 - Run the CLI locally and inspect the generated screenshots/report.
 
@@ -70,7 +79,7 @@ Create a starter flow manifest:
 npx @trylayout/qa init
 ```
 
-Start your app with whatever mock flag your project uses:
+Start your app with whatever local QA flag your project uses:
 
 ```bash
 VITE_LAYOUT_QA_MOCKS=1 npm run dev
@@ -88,7 +97,7 @@ npx @trylayout/qa run \
 Each run writes:
 
 ```text
-.layout/runs/<timestamp-scenario>/
+.layout/runs/<timestamp-scenario-viewport>/
   index.html
   result.json
   screenshots/
@@ -110,9 +119,10 @@ Options:
 
 ```text
 --target-url <url>     URL of the running frontend to test.
---scenario <name>      Mock scenario to activate. Defaults to happy_path.
+--scenario <name>      Scenario to activate. Defaults to happy_path.
 --flows <path>         Flow manifest path. Defaults to .layout/qa-flows.json.
 --out <path>           Artifact directory. Defaults to .layout/runs.
+--viewport <value>     Viewport preset or size. Use desktop, tablet, mobile, or WIDTHxHEIGHT. Defaults to desktop.
 --timeout <ms>         Browser run timeout. Defaults to 60000.
 --headed               Show the browser instead of running headless.
 --open                 Open the generated local HTML report after the run.
@@ -172,6 +182,8 @@ Step fields:
 - `label`: optional human-readable report label.
 - `screenshot`: set `true` to capture a screenshot after the step.
 - `timeoutMs`: optional per-step timeout.
+- `tolerance`: optional pixel tolerance for layout assertions.
+- `minWidth`, `maxWidth`, `minHeight`, `maxHeight`: optional `assert_box` constraints.
 
 Supported step types:
 
@@ -181,6 +193,9 @@ Supported step types:
 - `assert_visible_text`: require visible `text`.
 - `wait_for_text`: alias for a visible text wait.
 - `assert_url`: require current URL to equal `url` or contain `contains`.
+- `assert_no_horizontal_overflow`: require the page not to overflow the viewport horizontally.
+- `assert_in_viewport`: require a `selector` or visible `text` to have a nonzero box intersecting the viewport.
+- `assert_box`: require a `selector` or visible `text` to satisfy width/height constraints.
 - `screenshot`: capture a screenshot checkpoint.
 
 Examples:
@@ -197,7 +212,44 @@ Examples:
 { "id": "settings_url", "type": "assert_url", "contains": "/settings" }
 ```
 
-## Mock Scenarios
+```json
+{ "id": "no_overflow", "type": "assert_no_horizontal_overflow" }
+```
+
+```json
+{ "id": "main_visible", "type": "assert_in_viewport", "selector": "main" }
+```
+
+```json
+{
+  "id": "primary_cta_size",
+  "type": "assert_box",
+  "selector": "[data-qa='primary-cta']",
+  "minWidth": 120,
+  "maxHeight": 56
+}
+```
+
+## Viewports
+
+The runner defaults to the desktop viewport, `1280x900`. Use `--viewport` to run the same flow at a preset or exact size:
+
+```bash
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport desktop
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport tablet
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport mobile
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport 390x844
+```
+
+Presets:
+
+- `desktop`: `1280x900`
+- `tablet`: `768x1024`
+- `mobile`: `390x844`
+
+The selected viewport is written to `result.json`, shown in the HTML report, and included in the run directory name.
+
+## Scenarios
 
 Before the app loads, the runner sets:
 
@@ -206,7 +258,7 @@ localStorage.setItem("layout.qa.scenario", "<scenario>");
 sessionStorage.setItem("layout.qa.runner", "1");
 ```
 
-Your app can use `layout.qa.scenario` to switch deterministic mock states:
+Your app can use `layout.qa.scenario` to switch deterministic API/auth response states:
 
 - `happy_path`: normal populated data.
 - `empty`: successful responses with empty states.
@@ -227,14 +279,14 @@ Create a local-only browser QA loop that an agent can run while changing fronten
 Rules:
 - Do not add a standalone mock server.
 - Do not require a hosted Layout service.
-- Keep all mock data local to this app.
-- Gate mocks behind a local-only env flag such as VITE_LAYOUT_QA_MOCKS=1, NEXT_PUBLIC_LAYOUT_QA_MOCKS=1, or the framework-appropriate equivalent.
-- Use localStorage["layout.qa.scenario"] to select at least happy_path, empty, and error mock states.
+- Keep all deterministic response fixtures local to this app.
+- Gate deterministic API/auth responses behind a local-only env flag such as VITE_LAYOUT_QA_MOCKS=1, NEXT_PUBLIC_LAYOUT_QA_MOCKS=1, or the framework-appropriate equivalent.
+- Use localStorage["layout.qa.scenario"] to select at least happy_path, empty, and error response states.
 - Hide any local QA switcher or debug controls when sessionStorage["layout.qa.runner"] === "1".
 
 Implementation:
 - Add deterministic API fixtures for the highest-value frontend route.
-- If the app has a central auth/session abstraction, add a deterministic mock user only when the Layout QA env flag is enabled.
+- If the app has a central auth/session abstraction, add a deterministic QA user only when the Layout QA env flag is enabled.
 - If auth is scattered or provider-SDK-only, leave a clear note in the PR/code comments and start with public or logged-out flows.
 - Add .layout/qa-flows.json with one smoke flow for the most important page.
 - Prefer visible text and stable selectors.
@@ -281,8 +333,14 @@ This package is intentionally small:
 - It does run Playwright against an already-running frontend.
 - It does write local screenshots and an HTML report.
 - It does support deterministic scenario switching.
+- It does support explicit viewport sizing.
+- It does support lightweight layout assertions.
 - It does not build or host your app.
 - It does not upload results.
 - It does not perform AI review by itself.
 
 Those hosted/reporting layers can be added later without changing the local protocol.
+
+## Feedback
+
+Issues and examples are welcome in [GitHub Issues](https://github.com/Layout-App/layout-qa/issues). You can also reach me on X at [@tscepo](https://x.com/tscepo).

package/build/cli/layoutQa.js

@@ -9,6 +9,7 @@ const path_1 = __importDefault(require("path"));
 const flows_1 = require("../flows");
 const runner_1 = require("../runner");
 const report_1 = require("../report");
+const viewports_1 = require("../viewports");
 function printHelp() {
     process.stdout.write(`Layout QA CLI
 
@@ -25,9 +26,10 @@ Commands:
 
 Options:
   --target-url <url>     URL of the running frontend to test.
-  --scenario <name>      Mock scenario to activate. Defaults to happy_path.
+  --scenario <name>      Scenario to activate. Defaults to happy_path.
   --flows <path>         Flow manifest path. Defaults to .layout/qa-flows.json.
   --out <path>           Artifact directory. Defaults to .layout/runs.
+  --viewport <value>     Viewport preset or size. Use desktop, tablet, mobile, or WIDTHxHEIGHT. Defaults to desktop.
   --timeout <ms>         Browser run timeout. Defaults to LAYOUT_QA_TEST_TIMEOUT_MS or 60000.
   --headed               Show the browser instead of running headless.
   --open                 Open the generated local HTML report after the run.
@@ -59,6 +61,7 @@ function parseArgs(args) {
         scenario: readFlag(args, '--scenario') || 'happy_path',
         flowsPath: readFlag(args, '--flows'),
         outDir: readFlag(args, '--out'),
+        viewport: (0, viewports_1.parseViewport)(readFlag(args, '--viewport')),
         timeoutMs: parsedTimeoutMs,
         headed: hasFlag(args, '--headed'),
         json: hasFlag(args, '--json'),
@@ -92,6 +95,9 @@ function printHumanSummary(input) {
     process.stdout.write(`\nLayout QA ${passed ? 'passed' : 'failed'}\n` +
         `Scenario: ${input.scenario}\n` +
         `Target: ${input.targetUrl}\n` +
+        `Viewport: ${input.result.viewport
+            ? (0, viewports_1.formatViewport)(input.result.viewport)
+            : 'unavailable'}\n` +
         `Final URL: ${input.result.finalUrl || 'unavailable'}\n` +
         `Flow: ${input.result.flow?.name || 'None'} (${input.result.flow?.source || 'none'})\n` +
         `Manifest: ${input.manifestFound ? input.manifestPath : 'not found; default smoke'}\n\n`);
@@ -142,11 +148,12 @@ async function runCommand(options) {
             flow,
             timeoutMs: options.timeoutMs || (0, flows_1.getTestTimeoutMs)(),
             headless: !options.headed,
+            viewport: options.viewport,
         });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        result = (0, runner_1.buildRunnerErrorResult)(message);
+        result = (0, runner_1.buildRunnerErrorResult)(message, options.viewport);
     }
     const artifacts = await (0, report_1.writeArtifacts)({
         outDir: options.outDir,
@@ -162,6 +169,7 @@ async function runCommand(options) {
             status: passed ? 'passed' : 'failed',
             scenario: options.scenario,
             targetUrl: options.targetUrl,
+            viewport: options.viewport,
             manifestPath,
             manifestFound,
             artifacts,

package/build/flows.js

@@ -59,6 +59,11 @@ function normalizeFlowStep(value, index) {
         exact: booleanValue(value.exact),
         screenshot: booleanValue(value.screenshot, type === 'screenshot'),
         timeoutMs: numberValue(value.timeoutMs),
+        tolerance: numberValue(value.tolerance),
+        minWidth: numberValue(value.minWidth),
+        maxWidth: numberValue(value.maxWidth),
+        minHeight: numberValue(value.minHeight),
+        maxHeight: numberValue(value.maxHeight),
     };
 }
 function normalizeFlow(value, index) {

package/build/index.d.ts

@@ -2,3 +2,4 @@ export * from './flows';
 export * from './report';
 export * from './runner';
 export * from './types';
+export * from './viewports';

package/build/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./flows"), exports);
 __exportStar(require("./report"), exports);
 __exportStar(require("./runner"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./viewports"), exports);

package/build/report.js

@@ -12,6 +12,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const flows_1 = require("./flows");
 const runner_1 = require("./runner");
+const viewports_1 = require("./viewports");
 function safeName(value) {
     return value.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
 }
@@ -56,7 +57,7 @@ function renderStatusBadge(status) {
 function renderCheckList(result) {
     return result.checks
         .map(check => `<li class="row">
-        <span class="status ${check.passed ? 'passed' : 'failed'}">${check.passed ? 'PASS' : 'FAIL'}</span>
+        <span class="status ${check.passed ? 'passed' : 'failed'}">${check.passed ? 'Pass' : 'Fail'}</span>
         <div>
           <p class="row-title">${escapeHtml(check.label)}</p>
           ${check.detail
@@ -111,6 +112,7 @@ function renderReport(input) {
         : '';
     const resultHref = relativeHref(input.runDir, input.resultPath);
     const flow = input.result.flow;
+    const viewport = input.result.viewport;
     const failedCheckCount = input.result.checks.filter(check => !check.passed).length;
     return `<!doctype html>
 <html lang="en">
@@ -121,81 +123,149 @@ function renderReport(input) {
   <style>
     :root {
       color-scheme: light;
-      --bg: #f7f7f2;
-      --panel: #fffdf8;
-      --line: #e4e1d8;
-      --text: #1b1a17;
-      --muted: #65635d;
-      --green: #2f7a45;
-      --green-bg: #e6f4ea;
-      --red: #9b2c2c;
-      --red-bg: #fff0f0;
-      --amber: #7a5c14;
-      --amber-bg: #fff5d6;
+      --bg: #ffffff;
+      --surface: #f5f5f7;
+      --surface-strong: #fbfbfd;
+      --line: #d2d2d7;
+      --line-soft: #e8e8ed;
+      --text: #1d1d1f;
+      --muted: #6e6e73;
+      --blue: #06c;
+      --green: #248a3d;
+      --red: #d70015;
+      --amber: #b25000;
     }
     * { box-sizing: border-box; }
     body {
       margin: 0;
       background: var(--bg);
       color: var(--text);
-      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-      line-height: 1.5;
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", sans-serif;
+      line-height: 1.47059;
+      -webkit-font-smoothing: antialiased;
+      text-rendering: optimizeLegibility;
+    }
+    main { max-width: 1180px; margin: 0 auto; padding: 56px 28px 72px; }
+    header.page {
+      display: flex;
+      justify-content: space-between;
+      gap: 32px;
+      align-items: flex-start;
+      border-bottom: 1px solid var(--line-soft);
+      padding-bottom: 36px;
     }
-    main { max-width: 1120px; margin: 0 auto; padding: 32px 24px 56px; }
-    header.page { display: flex; justify-content: space-between; gap: 24px; align-items: flex-start; border-bottom: 1px solid var(--line); padding-bottom: 24px; }
     h1, h2, h3, p { margin: 0; }
-    h1 { font-size: clamp(2rem, 5vw, 4rem); line-height: 1; font-weight: 600; letter-spacing: 0; }
-    h2 { font-size: 1rem; font-weight: 650; margin-bottom: 12px; }
-    h3 { font-size: 1rem; font-weight: 650; }
-    section { margin-top: 28px; }
-    a { color: inherit; }
-    .eyebrow { color: var(--muted); font-size: .78rem; font-weight: 650; text-transform: uppercase; letter-spacing: .04em; }
-    .summary { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; margin-top: 24px; }
+    h1 {
+      font-size: clamp(2.75rem, 7vw, 5.5rem);
+      line-height: .95;
+      font-weight: 500;
+      letter-spacing: 0;
+    }
+    h2 { font-size: 1.375rem; line-height: 1.2; font-weight: 500; margin-bottom: 18px; }
+    h3 { font-size: 1.0625rem; line-height: 1.25; font-weight: 500; }
+    section { margin-top: 42px; }
+    a { color: var(--blue); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .eyebrow {
+      color: var(--muted);
+      font-size: .8125rem;
+      font-weight: 500;
+      text-transform: uppercase;
+      letter-spacing: .04em;
+      margin-bottom: 10px;
+    }
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(5, minmax(0, 1fr));
+      gap: 1px;
+      margin-top: 32px;
+      border: 1px solid var(--line-soft);
+      border-radius: 14px;
+      overflow: hidden;
+      background: var(--line-soft);
+    }
     .metric, .panel, .step, .issue {
-      border: 1px solid var(--line);
-      background: var(--panel);
-      border-radius: 8px;
+      background: var(--surface-strong);
+    }
+    .metric { padding: 18px 20px; min-width: 0; }
+    .metric dt { color: var(--muted); font-size: .8125rem; }
+    .metric dd { margin: 5px 0 0; font-weight: 500; overflow-wrap: anywhere; }
+    .panel {
+      padding: 22px;
+      border: 1px solid var(--line-soft);
+      border-radius: 14px;
+    }
+    .stack { display: grid; gap: 0; list-style: none; margin: 0; padding: 0; }
+    .row {
+      display: grid;
+      grid-template-columns: 64px minmax(0, 1fr);
+      gap: 16px;
+      padding: 14px 0;
+      border-top: 1px solid var(--line-soft);
     }
-    .metric { padding: 14px; min-width: 0; }
-    .metric dt { color: var(--muted); font-size: .82rem; }
-    .metric dd { margin: 4px 0 0; font-weight: 650; overflow-wrap: anywhere; }
-    .panel { padding: 16px; }
-    .stack { display: grid; gap: 10px; list-style: none; margin: 0; padding: 0; }
-    .row { display: grid; grid-template-columns: 56px minmax(0, 1fr); gap: 12px; padding: 10px 0; border-top: 1px solid var(--line); }
     .row:first-child { border-top: 0; padding-top: 0; }
     .row:last-child { padding-bottom: 0; }
-    .row-title { font-weight: 650; overflow-wrap: anywhere; }
-    .muted { color: var(--muted); font-size: .92rem; overflow-wrap: anywhere; }
-    .detail { margin-top: 8px; color: #3f3d38; overflow-wrap: anywhere; }
+    .row-title { font-weight: 500; overflow-wrap: anywhere; }
+    .muted { color: var(--muted); font-size: .9375rem; overflow-wrap: anywhere; }
+    .detail { margin-top: 10px; color: #424245; overflow-wrap: anywhere; }
     .break { word-break: break-all; }
-    .status { font-size: .78rem; font-weight: 750; padding-top: 2px; }
+    .status { font-size: .8125rem; font-weight: 500; padding-top: 2px; }
     .status.passed { color: var(--green); }
     .status.failed { color: var(--red); }
     .badge {
       display: inline-flex;
       align-items: center;
-      border-radius: 6px;
-      border: 1px solid var(--line);
-      padding: 4px 8px;
-      font-size: .82rem;
-      font-weight: 650;
+      border-radius: 999px;
+      border: 1px solid var(--line-soft);
+      padding: 5px 10px;
+      font-size: .875rem;
+      font-weight: 500;
       text-transform: capitalize;
       white-space: nowrap;
+      background: var(--surface);
+    }
+    .badge.passed { color: var(--green); }
+    .badge.failed { color: var(--red); }
+    .badge.skipped { color: var(--amber); }
+    .badge.hero { font-size: 1rem; padding: 8px 14px; }
+    .step {
+      padding: 22px;
+      margin-top: 16px;
+      border: 1px solid var(--line-soft);
+      border-radius: 14px;
     }
-    .badge.passed { color: var(--green); background: var(--green-bg); border-color: #c8e6d0; }
-    .badge.failed { color: var(--red); background: var(--red-bg); border-color: #f0c9c9; }
-    .badge.skipped { color: var(--amber); background: var(--amber-bg); border-color: #f0dc9f; }
-    .badge.hero { font-size: .95rem; padding: 8px 12px; }
-    .step { padding: 16px; margin-top: 12px; }
     .step-header { display: flex; justify-content: space-between; gap: 16px; align-items: flex-start; }
-    .screenshot-link { display: block; margin-top: 14px; border: 1px solid var(--line); border-radius: 8px; overflow: hidden; background: white; }
+    .screenshot-link {
+      display: block;
+      margin-top: 18px;
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      overflow: hidden;
+      background: white;
+      box-shadow: 0 12px 36px rgba(0, 0, 0, .06);
+    }
+    .screenshot-link:hover { text-decoration: none; }
     img { display: block; width: 100%; height: auto; }
-    .issue { padding: 12px; border-color: #f0c9c9; background: #fff8f8; }
-    .next { border-color: #d9d6cb; }
+    .issue {
+      padding: 16px;
+      border: 1px solid #ffd7d9;
+      border-radius: 12px;
+      background: #fff7f7;
+    }
+    .next { background: var(--surface); }
     .empty { color: var(--muted); }
-    .footer { margin-top: 28px; color: var(--muted); font-size: .9rem; }
+    .footer {
+      margin-top: 42px;
+      padding-top: 20px;
+      border-top: 1px solid var(--line-soft);
+      color: var(--muted);
+      font-size: .9375rem;
+      overflow-wrap: anywhere;
+    }
+    ul:not(.stack) { margin: 14px 0 0; padding-left: 1.2rem; color: #424245; }
+    li + li { margin-top: 6px; }
     @media (max-width: 760px) {
-      main { padding: 24px 16px 40px; }
+      main { padding: 34px 18px 48px; }
       header.page { display: grid; }
       .summary { grid-template-columns: 1fr; }
     }
@@ -215,6 +285,7 @@ function renderReport(input) {
       <div class="metric"><dt>Scenario</dt><dd>${escapeHtml(input.scenario)}</dd></div>
       <div class="metric"><dt>Flow</dt><dd>${escapeHtml(flow?.name || 'None')}</dd></div>
       <div class="metric"><dt>Target URL</dt><dd>${escapeHtml(input.targetUrl)}</dd></div>
+      <div class="metric"><dt>Viewport</dt><dd>${escapeHtml(viewport ? (0, viewports_1.formatViewport)(viewport) : 'unavailable')}</dd></div>
       <div class="metric"><dt>Final URL</dt><dd>${escapeHtml(input.result.finalUrl || 'unavailable')}</dd></div>
     </dl>
 
@@ -265,7 +336,8 @@ async function writeArtifacts(input) {
         ? path_1.default.resolve(process.cwd(), input.outDir)
         : await (0, flows_1.resolveDefaultPath)('.layout/runs');
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const runDir = path_1.default.join(outRoot, `${stamp}-${safeName(input.scenario)}`);
+    const viewportId = input.result.viewport?.id || 'viewport_unknown';
+    const runDir = path_1.default.join(outRoot, `${stamp}-${safeName(input.scenario)}-${safeName(viewportId)}`);
     const screenshotsDir = path_1.default.join(runDir, 'screenshots');
     await promises_1.default.mkdir(screenshotsDir, { recursive: true });
     const screenshots = [];

package/build/runner.d.ts

@@ -1,10 +1,11 @@
-import { LoadedQaFlow, QaTestRunCheck, QaTestRunFlowResult, QaTestRunIssue, QaTestRunNextAction, QaTestRunResult } from './types';
+import { LoadedQaFlow, QaTestRunCheck, QaTestRunFlowResult, QaTestRunIssue, QaTestRunNextAction, QaTestRunResult, QaViewport } from './types';
 export declare function runLayoutQaBrowser(input: {
     targetUrl: string;
     scenario: string;
     flow: LoadedQaFlow;
     timeoutMs?: number;
     headless?: boolean;
+    viewport?: QaViewport;
 }): Promise<{
     finalUrl: string;
     title: string;
@@ -13,10 +14,11 @@ export declare function runLayoutQaBrowser(input: {
     screenshotDataUrl: string | undefined;
     screenshotBytes: number;
     bodyTextSample: string;
+    viewport: QaViewport;
     checks: QaTestRunCheck[];
     issues: QaTestRunIssue[];
     flow: QaTestRunFlowResult;
     nextAction: QaTestRunNextAction;
 }>;
-export declare function buildRunnerErrorResult(message: string): QaTestRunResult;
+export declare function buildRunnerErrorResult(message: string, viewport?: QaViewport): QaTestRunResult;
 export declare function isQaRunPassed(result: QaTestRunResult): boolean;

package/build/runner.js

@@ -38,6 +38,7 @@ exports.buildRunnerErrorResult = buildRunnerErrorResult;
 exports.isQaRunPassed = isQaRunPassed;
 const url_1 = require("url");
 const flows_1 = require("./flows");
+const viewports_1 = require("./viewports");
 function truncate(value, maxLength = 1000) {
     return value.length <= maxLength ? value : `${value.slice(0, maxLength)}...`;
 }
@@ -80,7 +81,7 @@ function buildChecks(input) {
         },
         {
             id: 'scenario_ready',
-            label: 'Mock scenario is available',
+            label: 'Scenario flag is available',
             passed: scenarioReady,
             detail: input.controlsPresent
                 ? `Layout QA controls detected; requested ${input.scenario}.`
@@ -125,11 +126,11 @@ function buildNextAction(input) {
         return {
             category: 'target_unreachable',
             title: 'Target URL did not load cleanly',
-            detail: 'Layout could not reach the target page well enough to evaluate mock states.',
+            detail: 'Layout could not reach the target page well enough to evaluate deterministic response states.',
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
                 'Start the app or deploy preview URL before running Layout QA.',
-                'Use the URL where the frontend is served with the Layout mock env flag enabled.',
+                'Use the URL where the frontend is served with the Layout QA env flag enabled.',
                 'Retry the same scenario after the target URL is reachable from the runner.',
             ],
         };
@@ -137,13 +138,13 @@ function buildNextAction(input) {
     if (failedCheckIds.has('scenario_ready')) {
         return {
             category: 'fixtures',
-            title: 'Mock scenario was not active',
-            detail: 'The page loaded, but Layout could not confirm that the requested mock scenario was available.',
+            title: 'Scenario flag was not active',
+            detail: 'The page loaded, but Layout could not confirm that the requested scenario was available.',
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
-                'Confirm the target is running with the Layout mock env flag set to 1.',
+                'Confirm the target is running with the Layout QA env flag set to 1.',
                 'Check that the app reads localStorage["layout.qa.scenario"] before API calls run.',
-                `Review ${flows_1.FLOW_MANIFEST_PATH}, the Layout QA docs, and the fixture file for missing handlers.`,
+                `Review ${flows_1.FLOW_MANIFEST_PATH}, the Layout QA docs, and the API/auth response fixtures for missing handlers.`,
             ],
         };
     }
@@ -153,11 +154,11 @@ function buildNextAction(input) {
             category: 'flow',
             title: 'Flow step needs review',
             detail: failedStep?.detail ||
-                'The target loaded with mocks, but a declared QA flow step failed.',
+                'The target loaded with deterministic responses, but a declared QA flow step failed.',
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
                 `Inspect ${flows_1.FLOW_MANIFEST_PATH} and confirm the failing step still matches the app UI.`,
-                'Update selectors, visible text assertions, or scenario fixtures so the flow follows real user behavior.',
+                'Update selectors, visible text assertions, or scenario responses so the flow follows real user behavior.',
                 `Use ${flows_1.QA_DOCS_URL} for the supported flow step schema.`,
             ],
         };
@@ -168,24 +169,24 @@ function buildNextAction(input) {
         return {
             category: 'browser_errors',
             title: 'Browser errors need review',
-            detail: 'The target loaded with mocks, but browser errors or failed requests were observed.',
+            detail: 'The target loaded with deterministic responses, but browser errors or failed requests were observed.',
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
                 'Inspect the issues captured on this QA run.',
-                'Add or correct fixtures for unhandled frontend API requests.',
-                'Fix app code that throws under the selected mock scenario, then rerun.',
+                'Add or correct fixtures for unhandled frontend API/auth requests.',
+                'Fix app code that throws under the selected scenario, then rerun.',
             ],
         };
     }
     if (appearsToBePublicOrAuthSurface(input.bodyTextSample)) {
         return {
             category: 'auth_boundary',
-            title: 'Public surface reached; wire mock auth next',
-            detail: 'The run passed the basic mock-browser checks, but the page appears to be a logged-out or public surface. Authenticated flows need a mockable auth boundary before Layout can test them end to end.',
+            title: 'Public surface reached; wire deterministic auth next',
+            detail: 'The run passed the basic browser checks, but the page appears to be a logged-out or public surface. Authenticated flows need a deterministic auth boundary before Layout can test them end to end.',
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
-                `Use ${flows_1.FLOW_MANIFEST_PATH} and the Layout QA docs to add or confirm a central mock auth boundary.`,
-                'Expose a deterministic mock user/session only when the Layout mock env flag is enabled.',
+                `Use ${flows_1.FLOW_MANIFEST_PATH} and the Layout QA docs to add or confirm a central auth boundary for QA runs.`,
+                'Expose a deterministic user/session only when the Layout QA env flag is enabled.',
                 'Point the next QA run at an authenticated route and rerun happy_path, empty, and error scenarios.',
             ],
         };
@@ -193,11 +194,11 @@ function buildNextAction(input) {
     return {
         category: 'ready',
         title: 'Ready for deeper flow coverage',
-        detail: 'The target loaded with the requested mock scenario and no basic browser issues were detected.',
+        detail: 'The target loaded with the requested scenario and no basic browser issues were detected.',
         docsPath: flows_1.FLOW_MANIFEST_PATH,
         nextSteps: [
             `Add route-specific Playwright-style flow steps to ${flows_1.FLOW_MANIFEST_PATH} for the highest-value user path.`,
-            'Expand fixtures for any API calls encountered by that flow.',
+            'Expand deterministic API/auth responses for any requests encountered by that flow.',
             'Run the same flow across happy_path, empty, and error scenarios.',
         ],
     };
@@ -230,6 +231,131 @@ function requireStepValue(value, field) {
     }
     return value;
 }
+function stepLocator(page, step, exact, requiredField) {
+    if (step.selector) {
+        return page.locator(step.selector).first();
+    }
+    const text = requireStepValue(step.text, requiredField);
+    return page.getByText(text, { exact }).first();
+}
+function formatBox(box) {
+    return `${Math.round(box.width)}x${Math.round(box.height)} at ${Math.round(box.x)},${Math.round(box.y)}`;
+}
+async function assertNoHorizontalOverflow(page, tolerance = 1) {
+    const result = (await page.evaluate(checkTolerance => {
+        function elementLabel(element) {
+            const tagName = element.tagName.toLowerCase();
+            const testId = element.getAttribute('data-testid') ||
+                element.getAttribute('data-qa') ||
+                '';
+            if (testId)
+                return `${tagName}[data-qa/testid="${testId}"]`;
+            if (element.id)
+                return `${tagName}#${element.id}`;
+            const className = Array.from(element.classList).slice(0, 3).join('.');
+            return className ? `${tagName}.${className}` : tagName;
+        }
+        const root = document.documentElement;
+        const body = document.body;
+        const viewportWidth = window.innerWidth;
+        const scrollWidth = Math.max(root?.scrollWidth || 0, body?.scrollWidth || 0);
+        const overflowPx = Math.max(0, scrollWidth - viewportWidth);
+        const offenders = Array.from(document.body?.querySelectorAll('*') || [])
+            .map(element => {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return null;
+            const rightOverflow = Math.max(0, rect.right - viewportWidth);
+            const leftOverflow = Math.max(0, -rect.left);
+            const elementOverflowPx = Math.max(rightOverflow, leftOverflow);
+            if (elementOverflowPx <= checkTolerance)
+                return null;
+            return {
+                label: elementLabel(element),
+                x: Math.round(rect.x),
+                width: Math.round(rect.width),
+                right: Math.round(rect.right),
+                overflowPx: Math.round(elementOverflowPx),
+            };
+        })
+            .filter((entry) => Boolean(entry))
+            .sort((a, b) => b.overflowPx - a.overflowPx)
+            .slice(0, 5);
+        return {
+            viewportWidth,
+            scrollWidth,
+            overflowPx,
+            offenders,
+        };
+    }, tolerance));
+    if (result.overflowPx > tolerance) {
+        const offenderDetail = result.offenders.length
+            ? ` Offenders: ${result.offenders
+                .map(offender => `${offender.label} overflowed ${offender.overflowPx}px (x=${offender.x}, width=${offender.width}, right=${offender.right})`)
+                .join('; ')}.`
+            : '';
+        throw new Error(`Horizontal overflow detected: document width ${result.scrollWidth}px exceeds viewport ${result.viewportWidth}px by ${result.overflowPx}px.${offenderDetail}`);
+    }
+    return `No horizontal overflow: document width ${result.scrollWidth}px, viewport ${result.viewportWidth}px.`;
+}
+async function assertElementInViewport(input) {
+    const locator = stepLocator(input.page, input.step, input.exact, 'selector or text');
+    await locator.waitFor({ state: 'visible', timeout: input.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error('Expected element to have a visible nonzero layout box.');
+    }
+    const viewport = input.page.viewportSize();
+    if (!viewport) {
+        throw new Error('Could not read the current browser viewport size.');
+    }
+    const tolerance = input.step.tolerance ?? 1;
+    const right = box.x + box.width;
+    const bottom = box.y + box.height;
+    const visibleWidth = Math.min(right, viewport.width) - Math.max(box.x, 0);
+    const visibleHeight = Math.min(bottom, viewport.height) - Math.max(box.y, 0);
+    if (visibleWidth <= tolerance || visibleHeight <= tolerance) {
+        throw new Error(`Expected element to intersect viewport ${viewport.width}x${viewport.height}, got box ${formatBox(box)}.`);
+    }
+    return `Element intersects viewport ${viewport.width}x${viewport.height}: ${formatBox(box)}.`;
+}
+function definedBoxConstraints(step) {
+    return [
+        ['minWidth', step.minWidth],
+        ['maxWidth', step.maxWidth],
+        ['minHeight', step.minHeight],
+        ['maxHeight', step.maxHeight],
+    ];
+}
+async function assertElementBox(input) {
+    const constraints = definedBoxConstraints(input.step).filter(([, value]) => value !== undefined);
+    if (constraints.length === 0) {
+        throw new Error('assert_box requires at least one of minWidth, maxWidth, minHeight, or maxHeight.');
+    }
+    const locator = stepLocator(input.page, input.step, input.exact, 'selector or text');
+    await locator.waitFor({ state: 'visible', timeout: input.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error('Expected element to have a visible nonzero layout box.');
+    }
+    const failures = [];
+    if (input.step.minWidth !== undefined && box.width < input.step.minWidth) {
+        failures.push(`width ${Math.round(box.width)}px is below minWidth ${input.step.minWidth}px`);
+    }
+    if (input.step.maxWidth !== undefined && box.width > input.step.maxWidth) {
+        failures.push(`width ${Math.round(box.width)}px is above maxWidth ${input.step.maxWidth}px`);
+    }
+    if (input.step.minHeight !== undefined && box.height < input.step.minHeight) {
+        failures.push(`height ${Math.round(box.height)}px is below minHeight ${input.step.minHeight}px`);
+    }
+    if (input.step.maxHeight !== undefined && box.height > input.step.maxHeight) {
+        failures.push(`height ${Math.round(box.height)}px is above maxHeight ${input.step.maxHeight}px`);
+    }
+    if (failures.length > 0) {
+        throw new Error(`Element box ${formatBox(box)} failed constraints: ${failures.join('; ')}.`);
+    }
+    return `Element box matched constraints: ${formatBox(box)}.`;
+}
 async function caseSensitiveGoto(page, targetUrl, timeoutMs) {
     return page.goto(targetUrl, {
         waitUntil: 'domcontentloaded',
@@ -287,6 +413,25 @@ async function executeFlowStep(input) {
         }
         return `URL matched: ${currentUrl}`;
     }
+    if (input.step.type === 'assert_no_horizontal_overflow') {
+        return assertNoHorizontalOverflow(input.page, input.step.tolerance ?? 1);
+    }
+    if (input.step.type === 'assert_in_viewport') {
+        return assertElementInViewport({
+            page: input.page,
+            step: input.step,
+            exact,
+            timeoutMs: stepTimeout,
+        });
+    }
+    if (input.step.type === 'assert_box') {
+        return assertElementBox({
+            page: input.page,
+            step: input.step,
+            exact,
+            timeoutMs: stepTimeout,
+        });
+    }
     if (input.step.type === 'screenshot') {
         return 'Captured screenshot checkpoint.';
     }
@@ -345,13 +490,14 @@ async function runFlow(input) {
 }
 async function runLayoutQaBrowser(input) {
     const timeoutMs = input.timeoutMs || flows_1.DEFAULT_TEST_TIMEOUT_MS;
+    const viewport = input.viewport || viewports_1.DEFAULT_VIEWPORT;
     const issues = [];
     const { chromium } = await Promise.resolve().then(() => __importStar(require('playwright')));
     const browser = await chromium.launch({ headless: input.headless !== false });
     try {
         const context = await browser.newContext({
             ignoreHTTPSErrors: true,
-            viewport: { width: 1280, height: 900 },
+            viewport: { width: viewport.width, height: viewport.height },
         });
         await context.addInitScript({
             content: `
@@ -444,6 +590,7 @@ async function runLayoutQaBrowser(input) {
             screenshotDataUrl,
             screenshotBytes: screenshot.byteLength,
             bodyTextSample: pageState.bodyTextSample,
+            viewport,
             checks,
             issues: issues.slice(0, 20),
             flow: flowResult,
@@ -464,8 +611,9 @@ async function runLayoutQaBrowser(input) {
         });
     }
 }
-function buildRunnerErrorResult(message) {
+function buildRunnerErrorResult(message, viewport = viewports_1.DEFAULT_VIEWPORT) {
     return {
+        viewport,
         checks: [
             {
                 id: 'runner_error',
@@ -487,8 +635,9 @@ function buildRunnerErrorResult(message) {
             docsPath: flows_1.FLOW_MANIFEST_PATH,
             nextSteps: [
                 'Confirm the target URL is reachable by the runner.',
-                'Confirm the app is served with the Layout mock env flag enabled.',
+                'Confirm the app is served with the Layout QA env flag enabled.',
                 'Retry after the target loads consistently in a browser.',
+                `Viewport used for this run: ${(0, viewports_1.formatViewport)(viewport)}.`,
             ],
         },
     };

package/build/types.d.ts

@@ -27,6 +27,11 @@ export type QaTestRunFlowStepResult = {
     screenshotDataUrl?: string;
     screenshotBytes?: number;
 };
+export type QaViewport = {
+    id: string;
+    width: number;
+    height: number;
+};
 export type QaTestRunFlowResult = {
     id: string;
     name: string;
@@ -41,6 +46,7 @@ export type QaTestRunResult = {
     screenshotDataUrl?: string;
     screenshotBytes?: number;
     bodyTextSample?: string;
+    viewport?: QaViewport;
     checks: QaTestRunCheck[];
     issues: QaTestRunIssue[];
     flow?: QaTestRunFlowResult;
@@ -58,6 +64,11 @@ export type QaFlowStep = {
     exact?: boolean;
     screenshot?: boolean;
     timeoutMs?: number;
+    tolerance?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
 };
 export type QaFlowDefinition = {
     id: string;

package/build/viewports.d.ts

@@ -0,0 +1,5 @@
+import { QaViewport } from './types';
+export declare const DEFAULT_VIEWPORT: QaViewport;
+export declare const VIEWPORT_PRESETS: Record<string, QaViewport>;
+export declare function parseViewport(value?: string): QaViewport;
+export declare function formatViewport(viewport: QaViewport): string;

package/build/viewports.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIEWPORT_PRESETS = exports.DEFAULT_VIEWPORT = void 0;
+exports.parseViewport = parseViewport;
+exports.formatViewport = formatViewport;
+exports.DEFAULT_VIEWPORT = {
+    id: 'desktop',
+    width: 1280,
+    height: 900,
+};
+exports.VIEWPORT_PRESETS = {
+    desktop: exports.DEFAULT_VIEWPORT,
+    tablet: {
+        id: 'tablet',
+        width: 768,
+        height: 1024,
+    },
+    mobile: {
+        id: 'mobile',
+        width: 390,
+        height: 844,
+    },
+};
+function cloneViewport(viewport) {
+    return { ...viewport };
+}
+function parseViewport(value) {
+    const raw = (value || '').trim().toLowerCase();
+    if (!raw)
+        return cloneViewport(exports.DEFAULT_VIEWPORT);
+    const preset = exports.VIEWPORT_PRESETS[raw];
+    if (preset)
+        return cloneViewport(preset);
+    const match = raw.match(/^(\d{2,5})x(\d{2,5})$/);
+    if (!match) {
+        throw new Error(`Unsupported viewport "${value}". Use desktop, tablet, mobile, or WIDTHxHEIGHT.`);
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isInteger(width) ||
+        !Number.isInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        throw new Error(`Viewport "${value}" must use positive integer dimensions.`);
+    }
+    return {
+        id: `${width}x${height}`,
+        width,
+        height,
+    };
+}
+function formatViewport(viewport) {
+    return `${viewport.id} (${viewport.width}x${viewport.height})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylayout/qa",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local browser QA runner and HTML reports for AI-built frontends.",
   "license": "MIT",
   "author": "Layout",
@@ -26,6 +26,7 @@
   },
   "files": [
     "build",
+    "docs/assets/layout-qa-report.png",
     "README.md",
     "LICENSE"
   ],
@@ -38,6 +39,7 @@
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit",
+    "publish:alias": "cd packages/layout-qa && npm publish --access public",
     "prepack": "npm run build"
   },
   "dependencies": {