@qoretechnologies/qlip 0.1.3-pr.28.g211f2a4 → 0.1.3-pr.30.gc00bad8

package/README.md

@@ -196,6 +196,8 @@ export const LoggedIn = {
       viewport: { width: 1280, height: 720 },
       disableAnimations: true,
       pauseAnimationsAtEnd: false,
+      fullPage: false,
+      fullPageMaxHeight: 10000,
       captureOnError: false,
       waitForIdleMs: 300,
       maxWaitForIdleMs: 2000,
@@ -219,6 +221,8 @@ qlipVitestPlugin({
   viewport: { width: 1280, height: 720 },
   disableAnimations: false,
   pauseAnimationsAtEnd: false,
+  fullPage: false,
+  fullPageMaxHeight: 10000,
   captureOnError: false,
   waitForIdleMs: 300,
   maxWaitForIdleMs: 2000,
@@ -227,6 +231,8 @@ qlipVitestPlugin({
 });
 ```
 
+`fullPage` grows the viewport to the page's full content height for the capture and puts it back afterwards. A story that pins a phone viewport is otherwise photographed one screen tall; a browser "full page" screenshot would not help, because an app shell usually scrolls an inner box rather than the document. qlip measures the document and every scrolling element, grows the viewport, re-measures until nothing scrolls, and caps the height at `fullPageMaxHeight` (default 10000). A page whose content grows with the viewport (a tile sized to its column, a `vh` box) would ask for more every round; a round that asks for no more than the previous growth gave is taken as that, and the capture stays at the height the real content asked for. Under Vitest browser mode the test iframe is scaled down to fit the browser window, so the plugin also grows the window — the Playwright context viewport — through a browser command it registers (`qlipBrowserViewport`), and restores it first; the capture is 1:1, not a shrunk picture of a tall page. The same holds for any pinned `viewport` the window cannot hold: an 844px-tall phone story in a 720px window used to come back at 85%, and now grows the window too. The test-runner path grows its Playwright viewport the same way. The manifest keeps reporting the pinned `viewport` — that is the baseline key; the image is simply taller, and a capture whose content height changed shows on the server as a dimensions change rather than a pixel diff.
+
 `waitForIdleMs` waits for DOM mutations to settle before taking a screenshot. This is especially useful for animation libraries like `react-spring` that update inline styles via `requestAnimationFrame`, which bypasses CSS-based animation disabling. Increase it if you still catch mid-transition frames, or lower it for faster runs when your UI is static. `maxWaitForIdleMs` caps the wait so stories with continuously changing UI still complete.
 
 `ignoreElements` lets you provide CSS selectors to mask before capture. Qlip draws solid overlays on matching elements so layout stays intact while visual diffs ignore those regions.

package/dist/config/parameters.d.ts

@@ -8,6 +8,8 @@ export interface QlipResolvedOptions {
     disableAnimations: boolean;
     pauseAnimationsAtEnd: boolean;
     disableBackdropFilter: boolean;
+    fullPage: boolean;
+    fullPageMaxHeight: number;
     waitForIdleMs: number;
     maxWaitForIdleMs: number;
     ignoreElements: string[];

package/dist/config/parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../src/config/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5G,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,kBAAkB,GAAI,gCAIhC;IACD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,KAAG,mBAgDH,CAAC"}
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../src/config/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5G,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,kBAAkB,GAAI,gCAIhC;IACD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,KAAG,mBAqDH,CAAC"}

package/dist/config/parameters.js

@@ -11,6 +11,10 @@ export const resolveQlipOptions = ({ defaults, story, override, }) => {
         disableBackdropFilter: override?.disableBackdropFilter ??
             story?.disableBackdropFilter ??
             defaults.disableBackdropFilter,
+        fullPage: override?.fullPage ?? story?.fullPage ?? defaults.fullPage,
+        fullPageMaxHeight: override?.fullPageMaxHeight ??
+            story?.fullPageMaxHeight ??
+            defaults.fullPageMaxHeight,
         waitForIdleMs: override?.waitForIdleMs ??
             story?.waitForIdleMs ??
             defaults.waitForIdleMs,

package/dist/plugin/browserViewport.d.ts

@@ -0,0 +1,21 @@
+import type { BrowserCommand } from 'vitest/node';
+import type { FullPageSize } from '../runtime/fullPage.js';
+/** The name the runtime calls the command by (`commands.qlipBrowserViewport`). */
+export declare const QLIP_BROWSER_VIEWPORT_COMMAND = "qlipBrowserViewport";
+/**
+ * Reads — and, given a size, sets — the browser window's viewport: the
+ * Playwright context viewport that Vitest scales the test iframe to fit into.
+ * A capture whose viewport is taller or wider than the window comes back
+ * shrunk to fit unless the window grows with it (a 844px phone story in a
+ * 720px window is an 85% picture of it; a 3,600px full-page capture in a
+ * 1,440px window, a 40% one). Runs in the Vitest server process where the
+ * Playwright page lives; the runtime reaches it through
+ * `commands.qlipBrowserViewport`.
+ *
+ * Answers the size the window had before the call, or `null` when there is
+ * no such viewport to grow: another provider (webdriverio resizes the real
+ * window from `page.viewport()` and scales nothing), or a context launched
+ * with `viewport: null`.
+ */
+export declare const qlipBrowserViewport: BrowserCommand<[size?: FullPageSize | null]>;
+//# sourceMappingURL=browserViewport.d.ts.map

package/dist/plugin/browserViewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserViewport.d.ts","sourceRoot":"","sources":["../../src/plugin/browserViewport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;AAQnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC,CAa5E,CAAC"}

package/dist/plugin/browserViewport.js

@@ -0,0 +1,28 @@
+/** The name the runtime calls the command by (`commands.qlipBrowserViewport`). */
+export const QLIP_BROWSER_VIEWPORT_COMMAND = 'qlipBrowserViewport';
+/**
+ * Reads — and, given a size, sets — the browser window's viewport: the
+ * Playwright context viewport that Vitest scales the test iframe to fit into.
+ * A capture whose viewport is taller or wider than the window comes back
+ * shrunk to fit unless the window grows with it (a 844px phone story in a
+ * 720px window is an 85% picture of it; a 3,600px full-page capture in a
+ * 1,440px window, a 40% one). Runs in the Vitest server process where the
+ * Playwright page lives; the runtime reaches it through
+ * `commands.qlipBrowserViewport`.
+ *
+ * Answers the size the window had before the call, or `null` when there is
+ * no such viewport to grow: another provider (webdriverio resizes the real
+ * window from `page.viewport()` and scales nothing), or a context launched
+ * with `viewport: null`.
+ */
+export const qlipBrowserViewport = async (context, size) => {
+    const page = context.page;
+    if (context.provider.name !== 'playwright' || !page) {
+        return null;
+    }
+    const current = page.viewportSize();
+    if (size && current && (size.width !== current.width || size.height !== current.height)) {
+        await page.setViewportSize(size);
+    }
+    return current;
+};

package/dist/plugin/vitestPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vitestPlugin.d.ts","sourceRoot":"","sources":["../../src/plugin/vitestPlugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAU5C,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAMnE,eAAO,MAAM,gBAAgB,GAAI,UAAS,iBAAsB,KAAG,MAmQlE,CAAC"}
+{"version":3,"file":"vitestPlugin.d.ts","sourceRoot":"","sources":["../../src/plugin/vitestPlugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAU5C,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAanE,eAAO,MAAM,gBAAgB,GAAI,UAAS,iBAAsB,KAAG,MA8QlE,CAAC"}

package/dist/plugin/vitestPlugin.js

@@ -6,6 +6,9 @@ import pkg from '../../package.json' with { type: 'json' };
 import { DEFAULT_OUTPUT_DIR, DEFAULT_VIEWPORT, MANIFEST_FRAGMENT_DIR, TOOL_NAME, generateBuildId, } from '../fs/output.js';
 import { QlipUploadReporter } from '../upload/reporter.js';
 import { stashFinalizeConfig } from '../runtime/global-setup.js';
+import { QLIP_BROWSER_VIEWPORT_COMMAND, qlipBrowserViewport, } from './browserViewport.js';
+/** See `QlipCaptureOptions.fullPageMaxHeight`. */
+const DEFAULT_FULL_PAGE_MAX_HEIGHT = 10000;
 const normalizePath = (value) => value.replace(/\\/g, '/');
 export const qlipVitestPlugin = (options = {}) => {
     const buildId = options.buildId ?? generateBuildId();
@@ -37,6 +40,8 @@ export const qlipVitestPlugin = (options = {}) => {
                     // never a wanted baseline. See QlipCaptureOptions.
                     disableBackdropFilter: options.disableBackdropFilter ?? true,
                     captureOnError: options.captureOnError ?? false,
+                    fullPage: options.fullPage ?? false,
+                    fullPageMaxHeight: options.fullPageMaxHeight ?? DEFAULT_FULL_PAGE_MAX_HEIGHT,
                     waitForIdleMs: options.waitForIdleMs ?? 300,
                     maxWaitForIdleMs: options.maxWaitForIdleMs ?? 2000,
                     ignoreElements: options.ignoreElements ?? [],
@@ -185,6 +190,15 @@ export const qlipVitestPlugin = (options = {}) => {
                     setupFiles: [setupFile],
                     globalSetup: [globalSetupFile],
                     reporters: reportersList,
+                    // The runtime grows the browser window for a `fullPage` capture
+                    // through this command; it runs here, where the Playwright page
+                    // is. `mergeConfig` merges it beside any commands the consumer
+                    // declares.
+                    browser: {
+                        commands: {
+                            [QLIP_BROWSER_VIEWPORT_COMMAND]: qlipBrowserViewport,
+                        },
+                    },
                 },
             };
         },

package/dist/runtime/fullPage.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A `fullPage` capture grows the viewport until nothing on the page scrolls,
+ * photographs it, and puts the viewport back. A story that pins a phone
+ * viewport is otherwise one screen tall, and a browser "full page" screenshot
+ * would not help: an app shell pins the document to the viewport and scrolls
+ * an inner box, so the document is never taller than one screen.
+ *
+ * Under Vitest browser mode two viewports are involved. `page.viewport()`
+ * sizes the test iframe; the real browser window (the Playwright context
+ * viewport) stays as configured, and Vitest scales the iframe down to fit it.
+ * A 3,600px-tall iframe in a 1,440px window is photographed at 40% — the
+ * whole page, unreadable — and so is a plain 844px-tall phone story in a
+ * 720px window, at 85%. `createCaptureViewport` therefore grows the window
+ * to hold whatever viewport a capture asks for, pinned or grown, and puts
+ * both back afterwards, the window first, so the iframe lands at scale 1.
+ *
+ * This module has no imports: the runtime, the test-runner and the unit
+ * project (which has no DOM and feeds it fakes) all share it.
+ */
+export interface FullPageSize {
+    width: number;
+    height: number;
+}
+/**
+ * How tall the page really is: the document, and every box that scrolls
+ * its own content. Each scrolling box counts from its own offset, so a box
+ * that starts 105px down and scrolls 3,484px asks for 3,589px plus its own
+ * border and horizontal scrollbar.
+ *
+ * Closure-free, so the test-runner can hand it to Playwright's
+ * `page.evaluate()`, which re-evaluates the function's source inside the
+ * page; there it reads the real `document` and `window`. `env` exists for
+ * the unit test, which has neither.
+ */
+export declare const measureContentHeight: (env?: {
+    doc: Pick<Document, "documentElement" | "body" | "querySelectorAll">;
+    win: Pick<Window, "getComputedStyle" | "scrollY">;
+}) => number;
+/**
+ * Grows the viewport until nothing on the page scrolls. Growing the viewport
+ * re-lays the page out — a scrolling box that was 700px tall becomes 3,500px
+ * and may reveal another box below it that scrolls in turn — so the height is
+ * measured again after every growth, until a round asks for nothing more or
+ * `maxRounds` is spent.
+ *
+ * A page can also ask for more because it GREW WITH the viewport: a tile
+ * sized to its column, a `vh` box. Such content asks for about as much again
+ * as the last growth gave it, every round, and would be chased to the cap —
+ * a capture that is one screen of content over thousands of pixels of
+ * stretched tile. So a round that asks for no more than the previous growth
+ * is taken as content that scales, not content that was revealed, and the
+ * viewport stays where it is. (Revealed content asks for its own height,
+ * unrelated to the growth; it is only missed when it happens to be shorter
+ * than the growth that revealed it.)
+ *
+ * Returns the height the viewport ended at, or `null` when it never had to
+ * grow (the caller restores only in that case).
+ */
+export declare const growViewportToContent: ({ viewport, maxHeight, setViewport, measure, settle, maxRounds, }: {
+    viewport: FullPageSize;
+    maxHeight: number;
+    setViewport: (width: number, height: number) => Promise<void>;
+    measure: () => number | Promise<number>;
+    settle: () => Promise<void>;
+    maxRounds?: number;
+}) => Promise<number | null>;
+/**
+ * The browser-window half of the viewport, as the qlip plugin's browser
+ * command exposes it: called without a size it answers the window's current
+ * viewport, with one it resizes the window and answers the previous size.
+ * `null` means the provider has no window viewport to grow — webdriverio
+ * resizes the real window from `page.viewport()` itself and scales nothing.
+ */
+export type BrowserViewportCommand = (size?: FullPageSize | null) => Promise<FullPageSize | null>;
+/**
+ * The two viewports a capture sizes, and how each is put back. `set` grows
+ * the window to hold the iframe whenever the iframe would not fit (never
+ * shrinking it below what it was), then sizes the iframe; the window is
+ * asked for its size once. `restore` puts the window back first, so the
+ * iframe's pinned size is computed against the original window again, then
+ * the iframe — and touches neither when neither moved.
+ */
+export declare const createCaptureViewport: ({ pinned, iframe, window: windowViewport, }: {
+    pinned: FullPageSize;
+    iframe: (width: number, height: number) => Promise<void>;
+    window?: BrowserViewportCommand | undefined;
+}) => {
+    set: (width: number, height: number) => Promise<void>;
+    restore: () => Promise<void>;
+};
+//# sourceMappingURL=fullPage.d.ts.map

package/dist/runtime/fullPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullPage.d.ts","sourceRoot":"","sources":["../../src/runtime/fullPage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM;IACzC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,kBAAkB,CAAC,CAAC;IACrE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC,CAAC;CACnD,KAAG,MAiBH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAU,mEAOzC;IACD,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAmBxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,KACvB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,6CAInC;IACD,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC7C,KAAG;IACF,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CA4C9B,CAAC"}

package/dist/runtime/fullPage.js

@@ -0,0 +1,140 @@
+/**
+ * A `fullPage` capture grows the viewport until nothing on the page scrolls,
+ * photographs it, and puts the viewport back. A story that pins a phone
+ * viewport is otherwise one screen tall, and a browser "full page" screenshot
+ * would not help: an app shell pins the document to the viewport and scrolls
+ * an inner box, so the document is never taller than one screen.
+ *
+ * Under Vitest browser mode two viewports are involved. `page.viewport()`
+ * sizes the test iframe; the real browser window (the Playwright context
+ * viewport) stays as configured, and Vitest scales the iframe down to fit it.
+ * A 3,600px-tall iframe in a 1,440px window is photographed at 40% — the
+ * whole page, unreadable — and so is a plain 844px-tall phone story in a
+ * 720px window, at 85%. `createCaptureViewport` therefore grows the window
+ * to hold whatever viewport a capture asks for, pinned or grown, and puts
+ * both back afterwards, the window first, so the iframe lands at scale 1.
+ *
+ * This module has no imports: the runtime, the test-runner and the unit
+ * project (which has no DOM and feeds it fakes) all share it.
+ */
+/**
+ * How tall the page really is: the document, and every box that scrolls
+ * its own content. Each scrolling box counts from its own offset, so a box
+ * that starts 105px down and scrolls 3,484px asks for 3,589px plus its own
+ * border and horizontal scrollbar.
+ *
+ * Closure-free, so the test-runner can hand it to Playwright's
+ * `page.evaluate()`, which re-evaluates the function's source inside the
+ * page; there it reads the real `document` and `window`. `env` exists for
+ * the unit test, which has neither.
+ */
+export const measureContentHeight = (env) => {
+    const doc = env?.doc ?? document;
+    const win = env?.win ?? window;
+    let height = Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0);
+    for (const el of Array.from(doc.querySelectorAll('*'))) {
+        if (el.scrollHeight <= el.clientHeight + 1) {
+            continue;
+        }
+        const overflowY = win.getComputedStyle(el).overflowY;
+        if (overflowY !== 'auto' && overflowY !== 'scroll') {
+            continue;
+        }
+        const top = el.getBoundingClientRect().top + win.scrollY;
+        const chrome = el.offsetHeight - el.clientHeight;
+        height = Math.max(height, Math.ceil(top + el.scrollHeight + chrome));
+    }
+    return height;
+};
+/**
+ * Grows the viewport until nothing on the page scrolls. Growing the viewport
+ * re-lays the page out — a scrolling box that was 700px tall becomes 3,500px
+ * and may reveal another box below it that scrolls in turn — so the height is
+ * measured again after every growth, until a round asks for nothing more or
+ * `maxRounds` is spent.
+ *
+ * A page can also ask for more because it GREW WITH the viewport: a tile
+ * sized to its column, a `vh` box. Such content asks for about as much again
+ * as the last growth gave it, every round, and would be chased to the cap —
+ * a capture that is one screen of content over thousands of pixels of
+ * stretched tile. So a round that asks for no more than the previous growth
+ * is taken as content that scales, not content that was revealed, and the
+ * viewport stays where it is. (Revealed content asks for its own height,
+ * unrelated to the growth; it is only missed when it happens to be shorter
+ * than the growth that revealed it.)
+ *
+ * Returns the height the viewport ended at, or `null` when it never had to
+ * grow (the caller restores only in that case).
+ */
+export const growViewportToContent = async ({ viewport, maxHeight, setViewport, measure, settle, maxRounds = 4, }) => {
+    let height = viewport.height;
+    let grown = false;
+    let previous = null;
+    for (let round = 0; round < maxRounds; round += 1) {
+        const asked = Math.min(Math.ceil(await measure()), maxHeight);
+        if (asked <= height) {
+            break;
+        }
+        if (previous && asked - previous.asked <= previous.growth) {
+            break;
+        }
+        previous = { asked, growth: asked - height };
+        height = asked;
+        grown = true;
+        await setViewport(viewport.width, height);
+        await settle();
+    }
+    return grown ? height : null;
+};
+/**
+ * The two viewports a capture sizes, and how each is put back. `set` grows
+ * the window to hold the iframe whenever the iframe would not fit (never
+ * shrinking it below what it was), then sizes the iframe; the window is
+ * asked for its size once. `restore` puts the window back first, so the
+ * iframe's pinned size is computed against the original window again, then
+ * the iframe — and touches neither when neither moved.
+ */
+export const createCaptureViewport = ({ pinned, iframe, window: windowViewport, }) => {
+    // undefined: not asked yet; null: asked, and there is no window to grow
+    let base;
+    let windowAt = null;
+    let iframeAt = null;
+    const same = (a, b) => a.width === b.width && a.height === b.height;
+    const growWindow = async (width, height) => {
+        if (!windowViewport) {
+            return;
+        }
+        if (base === undefined) {
+            base = await windowViewport();
+        }
+        if (!base) {
+            return;
+        }
+        const target = {
+            width: Math.max(base.width, width),
+            height: Math.max(base.height, height),
+        };
+        if (same(target, windowAt ?? base)) {
+            return;
+        }
+        await windowViewport(target);
+        windowAt = target;
+    };
+    return {
+        set: async (width, height) => {
+            await growWindow(width, height);
+            await iframe(width, height);
+            iframeAt = { width, height };
+        },
+        restore: async () => {
+            if (base && windowAt && windowViewport) {
+                await windowViewport(base);
+                windowAt = null;
+            }
+            if (iframeAt && !same(iframeAt, pinned)) {
+                await iframe(pinned.width, pinned.height);
+                iframeAt = pinned;
+            }
+        },
+    };
+};

package/dist/runtime/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/runtime/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AA8BrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AA8L1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM;AACf;;;;;;;GAOG;AACH,gBAAgB,MAAM,KACrB;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAiCvD,CAAC;AAwDF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAIxC;IACD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,SA+DA,CAAC;AA+ZF,eAAO,MAAM,UAAU,GACrB,KAAK,gBAAgB,EACrB,gBAAgB,MAAM,GAAG,qBAAqB,EAC9C,UAAU,qBAAqB,kBA0BhC,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AA8ClE,eAAO,MAAM,qBAAqB,GAAU,KAAK,eAAe,kBAiG/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,KAAK,eAAe,kBAkEhE,CAAC"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/runtime/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AAoCrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AA8L1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM;AACf;;;;;;;GAOG;AACH,gBAAgB,MAAM,KACrB;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAiCvD,CAAC;AAwDF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAIxC;IACD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,SA+DA,CAAC;AAwbF,eAAO,MAAM,UAAU,GACrB,KAAK,gBAAgB,EACrB,gBAAgB,MAAM,GAAG,qBAAqB,EAC9C,UAAU,qBAAqB,kBA0BhC,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AA8ClE,eAAO,MAAM,qBAAqB,GAAU,KAAK,eAAe,kBAiG/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,KAAK,eAAe,kBAkEhE,CAAC"}

package/dist/runtime/screenshot.js

@@ -1,4 +1,5 @@
 import { resolveQlipOptions } from '../config/parameters.js';
+import { createCaptureViewport, growViewportToContent, measureContentHeight, } from './fullPage.js';
 import { monotonicNow, realClearInterval, realSetInterval, realSetTimeout, } from './clock.js';
 import { AUTO_ERROR_SCREENSHOT_BASE, MANIFEST_FRAGMENT_DIR, buildAutoLogPath, buildAutoScreenshotPath, buildManualLogPath, buildManualScreenshotPath, fragmentFileName, joinPath, sanitizeSegment, } from '../fs/output.js';
 import { flushConsoleLogs, initRuntimeState, markStorybookWarning, nextFragmentSeq, nextStepName, pruneStaleErrorEntries, pushEntry, updateStats, } from './context.js';
@@ -490,14 +491,31 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
     // throws.
     let error = testError ?? null;
     let cleanupMasks = null;
+    // The browser window grows to hold whatever viewport the capture asks for,
+    // pinned or full-page, or the capture comes back scaled down to fit the
+    // window (see ./fullPage.ts).
+    const captureViewport = createCaptureViewport({
+        pinned: resolved.viewport,
+        iframe: (width, height) => page.viewport(width, height),
+        window: commands.qlipBrowserViewport,
+    });
     try {
-        await page.viewport(resolved.viewport.width, resolved.viewport.height);
+        await captureViewport.set(resolved.viewport.width, resolved.viewport.height);
         applyCaptureStyleOverrides({
             disableAnimations: resolved.disableAnimations,
             pauseAnimationsAtEnd: resolved.pauseAnimationsAtEnd,
             disableBackdropFilter: resolved.disableBackdropFilter,
         });
         await waitForDomIdle(resolved.waitForIdleMs, resolved.maxWaitForIdleMs);
+        if (resolved.fullPage) {
+            await growViewportToContent({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: captureViewport.set,
+                measure: () => measureContentHeight(),
+                settle: () => waitForDomIdle(resolved.waitForIdleMs, resolved.maxWaitForIdleMs),
+            });
+        }
         cleanupMasks = applyIgnoreMasks(resolved.ignoreElements);
         await page.screenshot({ path: absolutePath, save: true });
     }
@@ -513,6 +531,15 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
         if (cleanupMasks) {
             cleanupMasks();
         }
+        // The pinned viewport is the baseline key and what the next capture
+        // inherits; a failure to put it back must not hide the capture's own
+        // outcome.
+        try {
+            await captureViewport.restore();
+        }
+        catch {
+            // The suite's own viewport reset runs before the next story.
+        }
     }
     const flushed = flushConsoleLogs(runtime);
     let logsPath;

package/dist/runtime/setup.d.ts

@@ -1,2 +1,5 @@
-export {};
+export declare const VIEWPORT_RESET_STYLE_ID = "__qlip-viewport-reset";
+export declare const VIEWPORT_RESET_CSS = "html, body, #storybook-root, body > div:not([class]):not([id]) { width: 100%; height: 100%; margin: 0; padding: 0; }";
+/** Exported for unit testing. */
+export declare const injectViewportStyles: () => void;
 //# sourceMappingURL=setup.d.ts.map

package/dist/runtime/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/runtime/setup.ts"],"names":[],"mappings":""}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/runtime/setup.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAS/D,eAAO,MAAM,kBAAkB,yHACyF,CAAC;AAEzH,iCAAiC;AACjC,eAAO,MAAM,oBAAoB,YAOhC,CAAC"}

package/dist/runtime/setup.js

@@ -3,13 +3,23 @@ import { captureAutoScreenshot, captureErrorScreenshot } from './screenshot.js';
 import { flushConsoleLogs, getRuntimeState, initRuntimeState, pushConsoleLog } from './context.js';
 import { realDateNow } from './clock.js';
 const isBrowser = () => typeof globalThis.__vitest_browser__ !== 'undefined';
-const injectViewportStyles = () => {
+export const VIEWPORT_RESET_STYLE_ID = '__qlip-viewport-reset';
+// Storybook's portable stories mount every story into an anonymous <div>
+// (no id, no class) appended to <body>; it needs the full viewport for
+// height-filling stories. A bare `body > div` also matched everything React
+// portals into <body> (reqore's fixed-position floating-actions bar, popovers)
+// and stretched it to 100% x 100%, which captured as opaque black rectangles.
+// `:first-of-type` is no alternative: Storybook's hidden `sb-wrapper` divs
+// precede the canvas.
+export const VIEWPORT_RESET_CSS = 'html, body, #storybook-root, body > div:not([class]):not([id]) { width: 100%; height: 100%; margin: 0; padding: 0; }';
+/** Exported for unit testing. */
+export const injectViewportStyles = () => {
     const doc = globalThis.document;
     if (!doc)
         return;
     const style = doc.createElement('style');
-    style.id = '__qlip-viewport-reset';
-    style.textContent = `html, body, body > div, #storybook-root { width: 100%; height: 100%; margin: 0; padding: 0; }`;
+    style.id = VIEWPORT_RESET_STYLE_ID;
+    style.textContent = VIEWPORT_RESET_CSS;
     doc.head.appendChild(style);
 };
 const serializeArg = (arg) => {

package/dist/stories/BodyPortal.d.ts

@@ -0,0 +1,12 @@
+export interface IBodyPortalProps {
+    /** Label of the portalled toolbar; the toolbar sizes itself to it. */
+    label?: string;
+}
+/**
+ * Renders a fixed-position toolbar straight into <body>, the way UI
+ * libraries portal floating actions, popovers and dropdowns. Like those, it
+ * carries no explicit width/height and sizes itself to its content, so a
+ * capture-time rule that stretches <body> children would balloon it.
+ */
+export declare const BodyPortal: ({ label }: IBodyPortalProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=BodyPortal.d.ts.map

package/dist/stories/BodyPortal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BodyPortal.d.ts","sourceRoot":"","sources":["../../src/stories/BodyPortal.tsx"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,WAAgC,gBAAgB,4CAuB1E,CAAC"}

package/dist/stories/BodyPortal.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createPortal } from 'react-dom';
+/**
+ * Renders a fixed-position toolbar straight into <body>, the way UI
+ * libraries portal floating actions, popovers and dropdowns. Like those, it
+ * carries no explicit width/height and sizes itself to its content, so a
+ * capture-time rule that stretches <body> children would balloon it.
+ */
+export const BodyPortal = ({ label = 'floating actions' }) => (_jsxs("div", { style: { height: '100%', padding: 16, boxSizing: 'border-box' }, children: [_jsx("h1", { children: "A toolbar portalled into body sits at the bottom right" }), createPortal(_jsx("div", { className: "body-portal-toolbar", "data-testid": "body-portal", style: {
+                position: 'fixed',
+                right: 16,
+                bottom: 16,
+                padding: '6px 12px',
+                background: '#1d4ed8',
+                color: '#fff',
+                borderRadius: 4,
+                whiteSpace: 'nowrap',
+            }, children: label }), document.body)] }));

package/dist/stories/BodyPortal.stories.d.ts

@@ -0,0 +1,17 @@
+import type { StoryObj } from '@storybook/react-vite';
+declare const meta: {
+    title: string;
+    component: ({ label }: import("./BodyPortal.js").IBodyPortalProps) => import("react/jsx-runtime").JSX.Element;
+    parameters: {
+        layout: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+/**
+ * The capture-time viewport reset sizes the story canvas to the viewport but
+ * must leave elements portalled into <body> alone. Before the fix the
+ * content-sized portal was stretched to 100% x 100% of the viewport.
+ */
+export declare const KeepsItsOwnSize: Story;
+//# sourceMappingURL=BodyPortal.stories.d.ts.map

package/dist/stories/BodyPortal.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BodyPortal.stories.d.ts","sourceRoot":"","sources":["../../src/stories/BodyPortal.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAK5D,QAAA,MAAM,IAAI;;;;;;CAMyB,CAAC;AAEpC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAGnC;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,KAkB7B,CAAC"}

package/dist/stories/BodyPortal.stories.js

@@ -0,0 +1,33 @@
+import { expect, within } from 'storybook/test';
+import { BodyPortal } from './BodyPortal.js';
+const meta = {
+    title: 'Example/BodyPortal',
+    component: BodyPortal,
+    parameters: {
+        layout: 'fullscreen',
+    },
+};
+export default meta;
+/**
+ * The capture-time viewport reset sizes the story canvas to the viewport but
+ * must leave elements portalled into <body> alone. Before the fix the
+ * content-sized portal was stretched to 100% x 100% of the viewport.
+ */
+export const KeepsItsOwnSize = {
+    args: { label: 'floating actions' },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText(/portalled into body/i)).toBeInTheDocument();
+        const portal = document.querySelector('[data-testid="body-portal"]');
+        if (!portal)
+            throw new Error('portal not rendered');
+        const rect = portal.getBoundingClientRect();
+        // Content-sized: a short label, one line. Stretched: the whole viewport.
+        await expect(rect.width).toBeLessThan(window.innerWidth / 2);
+        await expect(rect.height).toBeLessThan(60);
+        await expect(rect.right).toBeLessThanOrEqual(window.innerWidth);
+        await expect(rect.bottom).toBeLessThanOrEqual(window.innerHeight);
+        // The anonymous story canvas itself still fills the viewport.
+        await expect(canvasElement.getBoundingClientRect().height).toBe(window.innerHeight);
+    },
+};

package/dist/stories/TallPage.d.ts

@@ -0,0 +1,14 @@
+export interface ITallPageProps {
+    /** Sections in the scrolling column; each is 240px tall. */
+    sections?: number;
+}
+/**
+ * An app shell the way real ones are built: the document is pinned to the
+ * viewport and never scrolls, a header stays put, and a column below it
+ * scrolls its own content. A one-screen capture of this page shows the
+ * header and the first sections; everything else is inside the column's
+ * scroll, where neither the document height nor a browser "full page"
+ * screenshot can see it.
+ */
+export declare const TallPage: ({ sections }: ITallPageProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TallPage.d.ts.map

package/dist/stories/TallPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TallPage.d.ts","sourceRoot":"","sources":["../../src/stories/TallPage.tsx"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,cAAmB,cAAc,4CAiCzD,CAAC"}

package/dist/stories/TallPage.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * An app shell the way real ones are built: the document is pinned to the
+ * viewport and never scrolls, a header stays put, and a column below it
+ * scrolls its own content. A one-screen capture of this page shows the
+ * header and the first sections; everything else is inside the column's
+ * scroll, where neither the document height nor a browser "full page"
+ * screenshot can see it.
+ */
+export const TallPage = ({ sections = 12 }) => (_jsxs("div", { style: { height: '100%', display: 'flex', flexDirection: 'column', overflow: 'hidden' }, children: [_jsx("header", { style: {
+                flex: '0 0 56px',
+                display: 'flex',
+                alignItems: 'center',
+                padding: '0 16px',
+                background: '#1d4ed8',
+                color: '#fff',
+                fontWeight: 600,
+            }, children: "Inbox" }), _jsx("main", { "data-testid": "tall-page-scroll", style: { flex: 1, minHeight: 0, overflowY: 'auto' }, children: Array.from({ length: sections }, (_, index) => (_jsxs("section", { style: {
+                    height: 240,
+                    boxSizing: 'border-box',
+                    padding: 16,
+                    borderBottom: '1px solid #e5e7eb',
+                    background: index % 2 ? '#f9fafb' : '#fff',
+                }, children: [_jsxs("h2", { style: { margin: 0 }, children: ["Section ", index + 1] }), _jsxs("p", { children: ["Message ", index + 1, " of ", sections, "."] })] }, index))) })] }));

package/dist/stories/TallPage.stories.d.ts

@@ -0,0 +1,20 @@
+import type { StoryObj } from '@storybook/react-vite';
+declare const meta: {
+    title: string;
+    component: ({ sections }: import("./TallPage.js").ITallPageProps) => import("react/jsx-runtime").JSX.Element;
+    parameters: {
+        layout: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+/**
+ * `fullPage`: qlip grows the viewport (and, under Vitest browser mode, the
+ * browser window behind it) until the column no longer scrolls, so the
+ * capture is the whole column at 1:1 — the e2e test reads the PNG's height.
+ * The manifest keeps the pinned viewport as the baseline key.
+ */
+export declare const ScrollsAnInnerBox: Story;
+/** The same page without `fullPage`: one screen, the rest scrolled away. */
+export declare const OneScreen: Story;
+//# sourceMappingURL=TallPage.stories.d.ts.map

package/dist/stories/TallPage.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TallPage.stories.d.ts","sourceRoot":"","sources":["../../src/stories/TallPage.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAK5D,QAAA,MAAM,IAAI;;;;;;CAMuB,CAAC;AAElC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAgBnC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAK/B,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,SAAS,EAAE,KAKvB,CAAC"}

package/dist/stories/TallPage.stories.js

@@ -0,0 +1,41 @@
+import { expect, within } from 'storybook/test';
+import { TallPage } from './TallPage.js';
+const meta = {
+    title: 'Example/TallPage',
+    component: TallPage,
+    parameters: {
+        layout: 'fullscreen',
+    },
+};
+export default meta;
+const PHONE = { width: 390, height: 844 };
+/** The precondition that makes the two captures below differ: at the pinned
+ *  viewport the column really scrolls, and the document does not. */
+const expectsAnInnerScroller = async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Section 1')).toBeInTheDocument();
+    const column = canvasElement.querySelector('[data-testid="tall-page-scroll"]');
+    if (!column)
+        throw new Error('column not rendered');
+    await expect(column.scrollHeight).toBeGreaterThan(column.clientHeight);
+    await expect(document.documentElement.scrollHeight).toBe(window.innerHeight);
+};
+/**
+ * `fullPage`: qlip grows the viewport (and, under Vitest browser mode, the
+ * browser window behind it) until the column no longer scrolls, so the
+ * capture is the whole column at 1:1 — the e2e test reads the PNG's height.
+ * The manifest keeps the pinned viewport as the baseline key.
+ */
+export const ScrollsAnInnerBox = {
+    parameters: {
+        qlip: { viewport: PHONE, fullPage: true },
+    },
+    play: expectsAnInnerScroller,
+};
+/** The same page without `fullPage`: one screen, the rest scrolled away. */
+export const OneScreen = {
+    parameters: {
+        qlip: { viewport: PHONE },
+    },
+    play: expectsAnInnerScroller,
+};

package/dist/test-runner/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test-runner/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAaH,OAAO,KAAK,EACV,kBAAkB,EAGlB,iBAAiB,EACjB,cAAc,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,YAAY,EAIb,MAAM,qBAAqB,CAAC;AAS7B;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,UAAU,CAAC,IAAI,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtE;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,cAAc,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAC1D;AA6HD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,mBAAmB,EACzB,SAAS,gBAAgB,EACzB,UAAS,mBAAwB,KAChC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAelC,CAAC;AAuHF,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test-runner/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAcH,OAAO,KAAK,EACV,kBAAkB,EAGlB,iBAAiB,EACjB,cAAc,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,YAAY,EAIb,MAAM,qBAAqB,CAAC;AAS7B;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,UAAU,CAAC,IAAI,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtE;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,cAAc,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAC1D;AA+HD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,mBAAmB,EACzB,SAAS,gBAAgB,EACzB,UAAS,mBAAwB,KAChC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAelC,CAAC;AAmJF,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/test-runner/index.js

@@ -44,6 +44,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { resolveQlipOptions } from '../config/parameters.js';
+import { growViewportToContent, measureContentHeight } from '../runtime/fullPage.js';
 import { DEFAULT_OUTPUT_DIR, DEFAULT_VIEWPORT, MANIFEST_FRAGMENT_DIR, TOOL_NAME, buildAutoScreenshotPath, generateBuildId, } from '../fs/output.js';
 import { writeEntryFragment, getOrInitStore, nextStepName, peekStore, pushEntry, } from './manifest-store.js';
 import { applyAnimationControlInPage, applyIgnoreMasksInPage, removeIgnoreMasksInPage, waitForDomIdleInPage, } from './prep-scripts.js';
@@ -64,6 +65,8 @@ const buildResolvedDefaults = (override) => {
         pauseAnimationsAtEnd: override?.pauseAnimationsAtEnd ?? false,
         disableBackdropFilter: override?.disableBackdropFilter ?? true,
         captureOnError: override?.captureOnError ?? false,
+        fullPage: override?.fullPage ?? false,
+        fullPageMaxHeight: override?.fullPageMaxHeight ?? 10000,
         waitForIdleMs: override?.waitForIdleMs ?? 300,
         maxWaitForIdleMs: override?.maxWaitForIdleMs ?? 2000,
         ignoreElements: override?.ignoreElements ?? [],
@@ -223,6 +226,7 @@ const qlipCaptureInner = async (page, context, options) => {
     let status = 'captured';
     let error = null;
     let maskIds = [];
+    let grownTo = null;
     try {
         await page.setViewportSize({
             width: resolved.viewport.width,
@@ -236,6 +240,20 @@ const qlipCaptureInner = async (page, context, options) => {
             idleMs: resolved.waitForIdleMs,
             maxWaitMs: resolved.maxWaitForIdleMs,
         });
+        if (resolved.fullPage) {
+            // Here the viewport IS the browser window, so growing it is one call;
+            // the measure runs inside the page (see ../runtime/fullPage.ts).
+            grownTo = await growViewportToContent({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: (width, height) => page.setViewportSize({ width, height }),
+                measure: () => page.evaluate(measureContentHeight, undefined),
+                settle: () => page.evaluate(waitForDomIdleInPage, {
+                    idleMs: resolved.waitForIdleMs,
+                    maxWaitMs: resolved.maxWaitForIdleMs,
+                }),
+            });
+        }
         if (resolved.ignoreElements.length > 0) {
             maskIds = await page.evaluate(applyIgnoreMasksInPage, {
                 selectors: resolved.ignoreElements,
@@ -260,6 +278,19 @@ const qlipCaptureInner = async (page, context, options) => {
                 /* page may have navigated away; masks die with it */
             }
         }
+        if (grownTo !== null) {
+            // The pinned viewport is the baseline key; whatever the test-runner
+            // does with the page next should see the story's own size again.
+            try {
+                await page.setViewportSize({
+                    width: resolved.viewport.width,
+                    height: resolved.viewport.height,
+                });
+            }
+            catch {
+                /* the next capture sets its own viewport anyway */
+            }
+        }
     }
     const entry = buildEntry({
         kind: 'auto',

package/dist/types.d.ts

@@ -4,6 +4,13 @@ export interface QlipViewport {
 }
 export interface QlipCaptureOptions {
     skip?: boolean;
+    /**
+     * The capture's viewport, and the baseline key on the server. Under
+     * Vitest browser mode a viewport the browser window cannot hold grows the
+     * window for the capture (and puts it back), because Vitest otherwise
+     * scales the test iframe down to fit and the capture comes back smaller
+     * than the viewport it names.
+     */
     viewport?: QlipViewport;
     disableAnimations?: boolean;
     pauseAnimationsAtEnd?: boolean;
@@ -18,6 +25,34 @@ export interface QlipCaptureOptions {
      * @default true
      */
     disableBackdropFilter?: boolean;
+    /**
+     * Grow the viewport to the page's full content height for the capture,
+     * then put it back. A story that pins a phone viewport is otherwise
+     * photographed one screen tall with the rest of the page scrolled away —
+     * and a Playwright "full page" shot would not help, because an app shell
+     * usually scrolls an inner box, not the document. The height is measured
+     * from the document AND every scrolling element (an `overflow-y: auto |
+     * scroll` box whose `scrollHeight` exceeds its `clientHeight`, placed at
+     * its offset), re-measured after each growth until nothing scrolls, and
+     * capped at `fullPageMaxHeight`. Under Vitest browser mode the browser
+     * window (the Playwright context viewport) grows with the test iframe,
+     * or the capture would be scaled down to fit the window; both are put
+     * back afterwards. The manifest still reports the pinned `viewport` —
+     * that is the baseline key; the picture is simply taller. A capture whose
+     * content height changed shows on the server as a dimensions change
+     * rather than a pixel diff.
+     *
+     * @default false
+     */
+    fullPage?: boolean;
+    /**
+     * The tallest a `fullPage` capture may grow to, in CSS pixels. Chromium
+     * refuses viewports past 16384; the default leaves room for very long
+     * pages without inviting a runaway layout.
+     *
+     * @default 10000
+     */
+    fullPageMaxHeight?: number;
     waitForIdleMs?: number;
     maxWaitForIdleMs?: number;
     ignoreElements?: string[];

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist-cjs/config/parameters.js

@@ -14,6 +14,10 @@ const resolveQlipOptions = ({ defaults, story, override, }) => {
         disableBackdropFilter: override?.disableBackdropFilter ??
             story?.disableBackdropFilter ??
             defaults.disableBackdropFilter,
+        fullPage: override?.fullPage ?? story?.fullPage ?? defaults.fullPage,
+        fullPageMaxHeight: override?.fullPageMaxHeight ??
+            story?.fullPageMaxHeight ??
+            defaults.fullPageMaxHeight,
         waitForIdleMs: override?.waitForIdleMs ??
             story?.waitForIdleMs ??
             defaults.waitForIdleMs,

package/dist-cjs/runtime/fullPage.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * A `fullPage` capture grows the viewport until nothing on the page scrolls,
+ * photographs it, and puts the viewport back. A story that pins a phone
+ * viewport is otherwise one screen tall, and a browser "full page" screenshot
+ * would not help: an app shell pins the document to the viewport and scrolls
+ * an inner box, so the document is never taller than one screen.
+ *
+ * Under Vitest browser mode two viewports are involved. `page.viewport()`
+ * sizes the test iframe; the real browser window (the Playwright context
+ * viewport) stays as configured, and Vitest scales the iframe down to fit it.
+ * A 3,600px-tall iframe in a 1,440px window is photographed at 40% — the
+ * whole page, unreadable — and so is a plain 844px-tall phone story in a
+ * 720px window, at 85%. `createCaptureViewport` therefore grows the window
+ * to hold whatever viewport a capture asks for, pinned or grown, and puts
+ * both back afterwards, the window first, so the iframe lands at scale 1.
+ *
+ * This module has no imports: the runtime, the test-runner and the unit
+ * project (which has no DOM and feeds it fakes) all share it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCaptureViewport = exports.growViewportToContent = exports.measureContentHeight = void 0;
+/**
+ * How tall the page really is: the document, and every box that scrolls
+ * its own content. Each scrolling box counts from its own offset, so a box
+ * that starts 105px down and scrolls 3,484px asks for 3,589px plus its own
+ * border and horizontal scrollbar.
+ *
+ * Closure-free, so the test-runner can hand it to Playwright's
+ * `page.evaluate()`, which re-evaluates the function's source inside the
+ * page; there it reads the real `document` and `window`. `env` exists for
+ * the unit test, which has neither.
+ */
+const measureContentHeight = (env) => {
+    const doc = env?.doc ?? document;
+    const win = env?.win ?? window;
+    let height = Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0);
+    for (const el of Array.from(doc.querySelectorAll('*'))) {
+        if (el.scrollHeight <= el.clientHeight + 1) {
+            continue;
+        }
+        const overflowY = win.getComputedStyle(el).overflowY;
+        if (overflowY !== 'auto' && overflowY !== 'scroll') {
+            continue;
+        }
+        const top = el.getBoundingClientRect().top + win.scrollY;
+        const chrome = el.offsetHeight - el.clientHeight;
+        height = Math.max(height, Math.ceil(top + el.scrollHeight + chrome));
+    }
+    return height;
+};
+exports.measureContentHeight = measureContentHeight;
+/**
+ * Grows the viewport until nothing on the page scrolls. Growing the viewport
+ * re-lays the page out — a scrolling box that was 700px tall becomes 3,500px
+ * and may reveal another box below it that scrolls in turn — so the height is
+ * measured again after every growth, until a round asks for nothing more or
+ * `maxRounds` is spent.
+ *
+ * A page can also ask for more because it GREW WITH the viewport: a tile
+ * sized to its column, a `vh` box. Such content asks for about as much again
+ * as the last growth gave it, every round, and would be chased to the cap —
+ * a capture that is one screen of content over thousands of pixels of
+ * stretched tile. So a round that asks for no more than the previous growth
+ * is taken as content that scales, not content that was revealed, and the
+ * viewport stays where it is. (Revealed content asks for its own height,
+ * unrelated to the growth; it is only missed when it happens to be shorter
+ * than the growth that revealed it.)
+ *
+ * Returns the height the viewport ended at, or `null` when it never had to
+ * grow (the caller restores only in that case).
+ */
+const growViewportToContent = async ({ viewport, maxHeight, setViewport, measure, settle, maxRounds = 4, }) => {
+    let height = viewport.height;
+    let grown = false;
+    let previous = null;
+    for (let round = 0; round < maxRounds; round += 1) {
+        const asked = Math.min(Math.ceil(await measure()), maxHeight);
+        if (asked <= height) {
+            break;
+        }
+        if (previous && asked - previous.asked <= previous.growth) {
+            break;
+        }
+        previous = { asked, growth: asked - height };
+        height = asked;
+        grown = true;
+        await setViewport(viewport.width, height);
+        await settle();
+    }
+    return grown ? height : null;
+};
+exports.growViewportToContent = growViewportToContent;
+/**
+ * The two viewports a capture sizes, and how each is put back. `set` grows
+ * the window to hold the iframe whenever the iframe would not fit (never
+ * shrinking it below what it was), then sizes the iframe; the window is
+ * asked for its size once. `restore` puts the window back first, so the
+ * iframe's pinned size is computed against the original window again, then
+ * the iframe — and touches neither when neither moved.
+ */
+const createCaptureViewport = ({ pinned, iframe, window: windowViewport, }) => {
+    // undefined: not asked yet; null: asked, and there is no window to grow
+    let base;
+    let windowAt = null;
+    let iframeAt = null;
+    const same = (a, b) => a.width === b.width && a.height === b.height;
+    const growWindow = async (width, height) => {
+        if (!windowViewport) {
+            return;
+        }
+        if (base === undefined) {
+            base = await windowViewport();
+        }
+        if (!base) {
+            return;
+        }
+        const target = {
+            width: Math.max(base.width, width),
+            height: Math.max(base.height, height),
+        };
+        if (same(target, windowAt ?? base)) {
+            return;
+        }
+        await windowViewport(target);
+        windowAt = target;
+    };
+    return {
+        set: async (width, height) => {
+            await growWindow(width, height);
+            await iframe(width, height);
+            iframeAt = { width, height };
+        },
+        restore: async () => {
+            if (base && windowAt && windowViewport) {
+                await windowViewport(base);
+                windowAt = null;
+            }
+            if (iframeAt && !same(iframeAt, pinned)) {
+                await iframe(pinned.width, pinned.height);
+                iframeAt = pinned;
+            }
+        },
+    };
+};
+exports.createCaptureViewport = createCaptureViewport;

package/dist-cjs/test-runner/index.js

@@ -50,6 +50,7 @@ exports.nextStepName = exports.qlipCapture = void 0;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const parameters_js_1 = require("../config/parameters.js");
+const fullPage_js_1 = require("../runtime/fullPage.js");
 const output_js_1 = require("../fs/output.js");
 const manifest_store_js_1 = require("./manifest-store.js");
 Object.defineProperty(exports, "nextStepName", { enumerable: true, get: function () { return manifest_store_js_1.nextStepName; } });
@@ -71,6 +72,8 @@ const buildResolvedDefaults = (override) => {
         pauseAnimationsAtEnd: override?.pauseAnimationsAtEnd ?? false,
         disableBackdropFilter: override?.disableBackdropFilter ?? true,
         captureOnError: override?.captureOnError ?? false,
+        fullPage: override?.fullPage ?? false,
+        fullPageMaxHeight: override?.fullPageMaxHeight ?? 10000,
         waitForIdleMs: override?.waitForIdleMs ?? 300,
         maxWaitForIdleMs: override?.maxWaitForIdleMs ?? 2000,
         ignoreElements: override?.ignoreElements ?? [],
@@ -231,6 +234,7 @@ const qlipCaptureInner = async (page, context, options) => {
     let status = 'captured';
     let error = null;
     let maskIds = [];
+    let grownTo = null;
     try {
         await page.setViewportSize({
             width: resolved.viewport.width,
@@ -244,6 +248,20 @@ const qlipCaptureInner = async (page, context, options) => {
             idleMs: resolved.waitForIdleMs,
             maxWaitMs: resolved.maxWaitForIdleMs,
         });
+        if (resolved.fullPage) {
+            // Here the viewport IS the browser window, so growing it is one call;
+            // the measure runs inside the page (see ../runtime/fullPage.ts).
+            grownTo = await (0, fullPage_js_1.growViewportToContent)({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: (width, height) => page.setViewportSize({ width, height }),
+                measure: () => page.evaluate(fullPage_js_1.measureContentHeight, undefined),
+                settle: () => page.evaluate(prep_scripts_js_1.waitForDomIdleInPage, {
+                    idleMs: resolved.waitForIdleMs,
+                    maxWaitMs: resolved.maxWaitForIdleMs,
+                }),
+            });
+        }
         if (resolved.ignoreElements.length > 0) {
             maskIds = await page.evaluate(prep_scripts_js_1.applyIgnoreMasksInPage, {
                 selectors: resolved.ignoreElements,
@@ -268,6 +286,19 @@ const qlipCaptureInner = async (page, context, options) => {
                 /* page may have navigated away; masks die with it */
             }
         }
+        if (grownTo !== null) {
+            // The pinned viewport is the baseline key; whatever the test-runner
+            // does with the page next should see the story's own size again.
+            try {
+                await page.setViewportSize({
+                    width: resolved.viewport.width,
+                    height: resolved.viewport.height,
+                });
+            }
+            catch {
+                /* the next capture sets its own viewport anyway */
+            }
+        }
     }
     const entry = buildEntry({
         kind: 'auto',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/qlip",
-  "version": "0.1.3-pr.28.g211f2a4",
+  "version": "0.1.3-pr.30.gc00bad8",
   "description": "Storybook screenshot capture for the Vitest addon",
   "type": "module",
   "main": "./dist/index.js",
@@ -76,6 +76,7 @@
     "@storybook/addon-vitest": "^10.2.0",
     "@storybook/react-vite": "^10.2.0",
     "@types/node": "^20.10.0",
+    "@types/react-dom": "^19.2.7",
     "@typescript-eslint/eslint-plugin": "^6.10.0",
     "@typescript-eslint/parser": "^6.10.0",
     "@vitest/browser-playwright": "^4.0.17",