@qoretechnologies/qlip 0.1.3-pr.29.g497a7aa → 0.1.3-pr.30.gc7b05dc

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 by what they hide, and re-measures after each growth until nothing scrolls. Two kinds of box are not chased. A box that keeps its height when the viewport grows (a fixed-height code block, a capped list) stays scrolled, and the growth it asked for is given back, so the capture is not padded with blank space. Content that grows with the viewport (a tile sized to its column, a `vh` hero) would ask for more every round; it stops at the height its real content asked for. The height is capped at `fullPageMaxHeight` (default 10000); a page taller than that is captured at the cap with a `[qlip] fullPage:` warning naming the story. 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,118 @@
+/**
+ * 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 needs the viewport to be for nothing on it to scroll:
+ * the document, and every box that scrolls its own content. A scrolling box
+ * asks for the viewport plus whatever it hides — a box that fills the
+ * viewport grows with it one for one, whatever sits above or below it — and
+ * a box that already fits asks for the viewport minus its spare room.
+ * Answers 0 when nothing scrolls.
+ *
+ * A box only counts while growing the viewport can still reveal it, which
+ * only a re-measure after a growth can tell, so the rounds of one capture
+ * share a memory (`reset` starts a new one):
+ * - A box that kept its height when the viewport grew has a height of its
+ *   own (a 200px code block, a capped list). More viewport never reveals its
+ *   content, so it stops counting, and growth it asked for is given back.
+ * - A box whose content grew as much as the box did is sized to it (a tile
+ *   that follows its column). Chasing it only stretches the tile, so it keeps
+ *   asking for what it asked before it scaled. The document gets the same
+ *   test (a `vh` hero).
+ * - A box whose hidden content shrank was revealed and keeps counting, even
+ *   when a growth reveals less than it added.
+ *
+ * The document's own `scrollHeight` is the viewport again once the viewport
+ * outgrows it, so its tallest height while it still scrolled is remembered.
+ *
+ * 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: (options?: {
+    reset?: boolean;
+    env?: {
+        doc: Pick<Document, "documentElement" | "body" | "querySelectorAll">;
+        win: Pick<Window, "getComputedStyle" | "innerHeight">;
+    };
+}) => number;
+/** Where `growViewportToContent` left the viewport, and why. */
+export interface FullPageGrowth {
+    /** The height the viewport ended at: the pinned height when nothing grew. */
+    height: number;
+    /** What the content last asked for, before the `maxHeight` cap. */
+    wanted: 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. Content that does not grow with the viewport, or
+ * grows with it, is `measure`'s call (see `measureContentHeight`); when a
+ * round asks for less than the viewport already is, that growth went to such
+ * a box, and it is given back.
+ *
+ * `measure` is told when it is the capture's first round, so it can start a
+ * new memory.
+ */
+export declare const growViewportToContent: ({ viewport, maxHeight, setViewport, measure, settle, maxRounds, }: {
+    viewport: FullPageSize;
+    maxHeight: number;
+    setViewport: (width: number, height: number) => Promise<void>;
+    measure: (first: boolean) => number | Promise<number>;
+    settle: () => Promise<void>;
+    maxRounds?: number;
+}) => Promise<FullPageGrowth>;
+/**
+ * The warning for a `fullPage` capture the height cap cut short, or `null`:
+ * a page taller than `fullPageMaxHeight` is captured at the cap, and a cut-off
+ * page must not pass for the whole one.
+ */
+export declare const fullPageCapWarning: (storyId: string, growth: FullPageGrowth, maxHeight: number) => string | 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;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE;QACJ,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,kBAAkB,CAAC,CAAC;QACrE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa,CAAC,CAAC;KACvD,CAAC;CACH,KAAG,MAsEH,CAAC;AAEF,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;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,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAG,OAAO,CAAC,cAAc,CAmBzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,EACf,QAAQ,cAAc,EACtB,WAAW,MAAM,KAChB,MAAM,GAAG,IAKF,CAAC;AAEX;;;;;;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,214 @@
+/**
+ * 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 needs the viewport to be for nothing on it to scroll:
+ * the document, and every box that scrolls its own content. A scrolling box
+ * asks for the viewport plus whatever it hides — a box that fills the
+ * viewport grows with it one for one, whatever sits above or below it — and
+ * a box that already fits asks for the viewport minus its spare room.
+ * Answers 0 when nothing scrolls.
+ *
+ * A box only counts while growing the viewport can still reveal it, which
+ * only a re-measure after a growth can tell, so the rounds of one capture
+ * share a memory (`reset` starts a new one):
+ * - A box that kept its height when the viewport grew has a height of its
+ *   own (a 200px code block, a capped list). More viewport never reveals its
+ *   content, so it stops counting, and growth it asked for is given back.
+ * - A box whose content grew as much as the box did is sized to it (a tile
+ *   that follows its column). Chasing it only stretches the tile, so it keeps
+ *   asking for what it asked before it scaled. The document gets the same
+ *   test (a `vh` hero).
+ * - A box whose hidden content shrank was revealed and keeps counting, even
+ *   when a growth reveals less than it added.
+ *
+ * The document's own `scrollHeight` is the viewport again once the viewport
+ * outgrows it, so its tallest height while it still scrolled is remembered.
+ *
+ * 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 = (options) => {
+    const doc = options?.env?.doc ?? document;
+    const win = options?.env?.win ?? window;
+    const holder = win;
+    if (options?.reset || !holder.__qlipFullPage) {
+        holder.__qlipFullPage = {
+            viewport: 0,
+            docHeight: 0,
+            docOverflow: 0,
+            docScales: false,
+            boxes: new WeakMap(),
+            fixed: new WeakSet(),
+            scales: new WeakSet(),
+        };
+    }
+    const memory = holder.__qlipFullPage;
+    const viewport = win.innerHeight;
+    const grew = memory.viewport > 0 && viewport > memory.viewport + 1;
+    const docScroll = Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0);
+    const docOverflow = Math.max(0, docScroll - viewport);
+    if (grew && memory.docOverflow > 0 && docOverflow >= memory.docOverflow - 1) {
+        memory.docScales = true;
+    }
+    memory.docOverflow = docOverflow;
+    if (docOverflow > 1 && !memory.docScales) {
+        memory.docHeight = Math.max(memory.docHeight, docScroll);
+    }
+    let height = memory.docHeight;
+    for (const el of Array.from(doc.querySelectorAll('*'))) {
+        const seen = memory.boxes.get(el);
+        if (!seen) {
+            if (el.scrollHeight <= el.clientHeight + 1) {
+                continue;
+            }
+            const overflowY = win.getComputedStyle(el).overflowY;
+            if (overflowY !== 'auto' && overflowY !== 'scroll') {
+                continue;
+            }
+        }
+        const overflow = Math.max(0, el.scrollHeight - el.clientHeight);
+        if (seen && grew) {
+            if (el.clientHeight <= seen.clientHeight + 1) {
+                memory.fixed.add(el);
+            }
+            else if (seen.overflow > 0 && overflow >= seen.overflow - 1) {
+                memory.scales.add(el);
+            }
+        }
+        if (memory.fixed.has(el)) {
+            continue;
+        }
+        // A box that fits reports its own height as scrollHeight, so its content
+        // height is the one it had while it still scrolled.
+        const content = overflow > 1 ? Math.max(seen?.content ?? 0, el.scrollHeight) : (seen?.content ?? el.scrollHeight);
+        let need;
+        if (seen && memory.scales.has(el)) {
+            need = seen.need;
+        }
+        else if (overflow > 1) {
+            need = viewport + overflow;
+        }
+        else {
+            need = viewport - Math.max(0, el.clientHeight - content);
+        }
+        need = Math.ceil(need);
+        memory.boxes.set(el, { clientHeight: el.clientHeight, overflow, content, need });
+        height = Math.max(height, need);
+    }
+    memory.viewport = viewport;
+    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. Content that does not grow with the viewport, or
+ * grows with it, is `measure`'s call (see `measureContentHeight`); when a
+ * round asks for less than the viewport already is, that growth went to such
+ * a box, and it is given back.
+ *
+ * `measure` is told when it is the capture's first round, so it can start a
+ * new memory.
+ */
+export const growViewportToContent = async ({ viewport, maxHeight, setViewport, measure, settle, maxRounds = 4, }) => {
+    let height = viewport.height;
+    let wanted = 0;
+    for (let round = 0; round < maxRounds; round += 1) {
+        wanted = Math.ceil(await measure(round === 0));
+        const asked = Math.min(Math.max(wanted, viewport.height), maxHeight);
+        if (asked === height) {
+            break;
+        }
+        const givingBack = asked < height;
+        height = asked;
+        await setViewport(viewport.width, height);
+        await settle();
+        if (givingBack) {
+            // Every box still counted asked for no more than this, so it fits.
+            break;
+        }
+    }
+    return { height, wanted };
+};
+/**
+ * The warning for a `fullPage` capture the height cap cut short, or `null`:
+ * a page taller than `fullPageMaxHeight` is captured at the cap, and a cut-off
+ * page must not pass for the whole one.
+ */
+export const fullPageCapWarning = (storyId, growth, maxHeight) => growth.wanted > maxHeight
+    ? `[qlip] fullPage: ${storyId} is ${String(growth.wanted)}px tall but was captured at ` +
+        `the ${String(maxHeight)}px cap; raise fullPageMaxHeight (Chromium allows up to 16384) ` +
+        'to capture all of it.'
+    : 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;AAqCrB,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;AA4bF,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, fullPageCapWarning, 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,35 @@ 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) {
+            const growth = await growViewportToContent({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: captureViewport.set,
+                measure: (first) => measureContentHeight({ reset: first }),
+                settle: () => waitForDomIdle(resolved.waitForIdleMs, resolved.maxWaitForIdleMs),
+            });
+            const warning = fullPageCapWarning(story.id, growth, resolved.fullPageMaxHeight);
+            if (warning) {
+                console.warn(warning);
+            }
+        }
         cleanupMasks = applyIgnoreMasks(resolved.ignoreElements);
         await page.screenshot({ path: absolutePath, save: true });
     }
@@ -513,6 +535,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/stories/TallPage.d.ts

@@ -0,0 +1,20 @@
+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;
+/**
+ * An ordinary page, nothing pinned, whose only scroller is a fixed-height
+ * box (a code block, a capped list). Growing the viewport never grows that
+ * box, so a `fullPage` capture has nothing to reveal and stays one screen.
+ */
+export declare const FixedBoxPage: () => 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;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,+CAWxB,CAAC"}

package/dist/stories/TallPage.js

@@ -0,0 +1,30 @@
+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))) })] }));
+/**
+ * An ordinary page, nothing pinned, whose only scroller is a fixed-height
+ * box (a code block, a capped list). Growing the viewport never grows that
+ * box, so a `fullPage` capture has nothing to reveal and stays one screen.
+ */
+export const FixedBoxPage = () => (_jsxs("div", { style: { padding: 16, fontFamily: 'sans-serif' }, children: [_jsx("h1", { style: { margin: 0 }, children: "Release notes" }), _jsx("pre", { "data-testid": "fixed-box", style: { height: 200, margin: '16px 0', overflowY: 'auto', border: '1px solid #d1d5db' }, children: Array.from({ length: 100 }, (_, index) => `line ${String(index + 1)}`).join('\n') }), _jsx("p", { style: { margin: 0 }, children: "The page ends here." })] }));

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

@@ -0,0 +1,27 @@
+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;
+/**
+ * `fullPage` on an ordinary page whose only scroller is a fixed-height box:
+ * more viewport never reveals it, so qlip gives the growth back and the
+ * capture stays one screen — not a screen of page over a tall blank strip.
+ * The e2e test reads the PNG's height.
+ */
+export declare const FixedHeightBox: 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;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,KAU5B,CAAC"}

package/dist/stories/TallPage.stories.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { expect, within } from 'storybook/test';
+import { FixedBoxPage, 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,
+};
+/**
+ * `fullPage` on an ordinary page whose only scroller is a fixed-height box:
+ * more viewport never reveals it, so qlip gives the growth back and the
+ * capture stays one screen — not a screen of page over a tall blank strip.
+ * The e2e test reads the PNG's height.
+ */
+export const FixedHeightBox = {
+    render: () => _jsx(FixedBoxPage, {}),
+    parameters: {
+        qlip: { viewport: PHONE, fullPage: true },
+    },
+    play: async ({ canvasElement }) => {
+        const box = canvasElement.querySelector('[data-testid="fixed-box"]');
+        if (!box)
+            throw new Error('box not rendered');
+        await expect(box.scrollHeight).toBeGreaterThan(box.clientHeight);
+    },
+};

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;AAkBH,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;AA0JF,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 { fullPageCapWarning, 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,27 @@ 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).
+            const growth = await growViewportToContent({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: (width, height) => page.setViewportSize({ width, height }),
+                measure: (first) => page.evaluate(measureContentHeight, { reset: first }),
+                settle: () => page.evaluate(waitForDomIdleInPage, {
+                    idleMs: resolved.waitForIdleMs,
+                    maxWaitMs: resolved.maxWaitForIdleMs,
+                }),
+            });
+            if (growth.height !== resolved.viewport.height) {
+                grownTo = growth.height;
+            }
+            const warning = fullPageCapWarning(context.id, growth, resolved.fullPageMaxHeight);
+            if (warning) {
+                console.warn(warning);
+            }
+        }
         if (resolved.ignoreElements.length > 0) {
             maskIds = await page.evaluate(applyIgnoreMasksInPage, {
                 selectors: resolved.ignoreElements,
@@ -260,6 +285,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,38 @@ 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`), and
+     * re-measured after each growth until nothing scrolls. A box that keeps
+     * its height when the viewport grows (a fixed-height code block) stays
+     * scrolled and gives its growth back, and content that grows with the
+     * viewport is not chased. 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. A page taller than this is
+     * captured at the cap, with a `[qlip] fullPage:` warning naming the story.
+     *
+     * @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,221 @@
+"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.fullPageCapWarning = exports.growViewportToContent = exports.measureContentHeight = void 0;
+/**
+ * How tall the page needs the viewport to be for nothing on it to scroll:
+ * the document, and every box that scrolls its own content. A scrolling box
+ * asks for the viewport plus whatever it hides — a box that fills the
+ * viewport grows with it one for one, whatever sits above or below it — and
+ * a box that already fits asks for the viewport minus its spare room.
+ * Answers 0 when nothing scrolls.
+ *
+ * A box only counts while growing the viewport can still reveal it, which
+ * only a re-measure after a growth can tell, so the rounds of one capture
+ * share a memory (`reset` starts a new one):
+ * - A box that kept its height when the viewport grew has a height of its
+ *   own (a 200px code block, a capped list). More viewport never reveals its
+ *   content, so it stops counting, and growth it asked for is given back.
+ * - A box whose content grew as much as the box did is sized to it (a tile
+ *   that follows its column). Chasing it only stretches the tile, so it keeps
+ *   asking for what it asked before it scaled. The document gets the same
+ *   test (a `vh` hero).
+ * - A box whose hidden content shrank was revealed and keeps counting, even
+ *   when a growth reveals less than it added.
+ *
+ * The document's own `scrollHeight` is the viewport again once the viewport
+ * outgrows it, so its tallest height while it still scrolled is remembered.
+ *
+ * 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 = (options) => {
+    const doc = options?.env?.doc ?? document;
+    const win = options?.env?.win ?? window;
+    const holder = win;
+    if (options?.reset || !holder.__qlipFullPage) {
+        holder.__qlipFullPage = {
+            viewport: 0,
+            docHeight: 0,
+            docOverflow: 0,
+            docScales: false,
+            boxes: new WeakMap(),
+            fixed: new WeakSet(),
+            scales: new WeakSet(),
+        };
+    }
+    const memory = holder.__qlipFullPage;
+    const viewport = win.innerHeight;
+    const grew = memory.viewport > 0 && viewport > memory.viewport + 1;
+    const docScroll = Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0);
+    const docOverflow = Math.max(0, docScroll - viewport);
+    if (grew && memory.docOverflow > 0 && docOverflow >= memory.docOverflow - 1) {
+        memory.docScales = true;
+    }
+    memory.docOverflow = docOverflow;
+    if (docOverflow > 1 && !memory.docScales) {
+        memory.docHeight = Math.max(memory.docHeight, docScroll);
+    }
+    let height = memory.docHeight;
+    for (const el of Array.from(doc.querySelectorAll('*'))) {
+        const seen = memory.boxes.get(el);
+        if (!seen) {
+            if (el.scrollHeight <= el.clientHeight + 1) {
+                continue;
+            }
+            const overflowY = win.getComputedStyle(el).overflowY;
+            if (overflowY !== 'auto' && overflowY !== 'scroll') {
+                continue;
+            }
+        }
+        const overflow = Math.max(0, el.scrollHeight - el.clientHeight);
+        if (seen && grew) {
+            if (el.clientHeight <= seen.clientHeight + 1) {
+                memory.fixed.add(el);
+            }
+            else if (seen.overflow > 0 && overflow >= seen.overflow - 1) {
+                memory.scales.add(el);
+            }
+        }
+        if (memory.fixed.has(el)) {
+            continue;
+        }
+        // A box that fits reports its own height as scrollHeight, so its content
+        // height is the one it had while it still scrolled.
+        const content = overflow > 1 ? Math.max(seen?.content ?? 0, el.scrollHeight) : (seen?.content ?? el.scrollHeight);
+        let need;
+        if (seen && memory.scales.has(el)) {
+            need = seen.need;
+        }
+        else if (overflow > 1) {
+            need = viewport + overflow;
+        }
+        else {
+            need = viewport - Math.max(0, el.clientHeight - content);
+        }
+        need = Math.ceil(need);
+        memory.boxes.set(el, { clientHeight: el.clientHeight, overflow, content, need });
+        height = Math.max(height, need);
+    }
+    memory.viewport = viewport;
+    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. Content that does not grow with the viewport, or
+ * grows with it, is `measure`'s call (see `measureContentHeight`); when a
+ * round asks for less than the viewport already is, that growth went to such
+ * a box, and it is given back.
+ *
+ * `measure` is told when it is the capture's first round, so it can start a
+ * new memory.
+ */
+const growViewportToContent = async ({ viewport, maxHeight, setViewport, measure, settle, maxRounds = 4, }) => {
+    let height = viewport.height;
+    let wanted = 0;
+    for (let round = 0; round < maxRounds; round += 1) {
+        wanted = Math.ceil(await measure(round === 0));
+        const asked = Math.min(Math.max(wanted, viewport.height), maxHeight);
+        if (asked === height) {
+            break;
+        }
+        const givingBack = asked < height;
+        height = asked;
+        await setViewport(viewport.width, height);
+        await settle();
+        if (givingBack) {
+            // Every box still counted asked for no more than this, so it fits.
+            break;
+        }
+    }
+    return { height, wanted };
+};
+exports.growViewportToContent = growViewportToContent;
+/**
+ * The warning for a `fullPage` capture the height cap cut short, or `null`:
+ * a page taller than `fullPageMaxHeight` is captured at the cap, and a cut-off
+ * page must not pass for the whole one.
+ */
+const fullPageCapWarning = (storyId, growth, maxHeight) => growth.wanted > maxHeight
+    ? `[qlip] fullPage: ${storyId} is ${String(growth.wanted)}px tall but was captured at ` +
+        `the ${String(maxHeight)}px cap; raise fullPageMaxHeight (Chromium allows up to 16384) ` +
+        'to capture all of it.'
+    : null;
+exports.fullPageCapWarning = fullPageCapWarning;
+/**
+ * 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,27 @@ 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).
+            const growth = await (0, fullPage_js_1.growViewportToContent)({
+                viewport: resolved.viewport,
+                maxHeight: resolved.fullPageMaxHeight,
+                setViewport: (width, height) => page.setViewportSize({ width, height }),
+                measure: (first) => page.evaluate(fullPage_js_1.measureContentHeight, { reset: first }),
+                settle: () => page.evaluate(prep_scripts_js_1.waitForDomIdleInPage, {
+                    idleMs: resolved.waitForIdleMs,
+                    maxWaitMs: resolved.maxWaitForIdleMs,
+                }),
+            });
+            if (growth.height !== resolved.viewport.height) {
+                grownTo = growth.height;
+            }
+            const warning = (0, fullPage_js_1.fullPageCapWarning)(context.id, growth, resolved.fullPageMaxHeight);
+            if (warning) {
+                console.warn(warning);
+            }
+        }
         if (resolved.ignoreElements.length > 0) {
             maskIds = await page.evaluate(prep_scripts_js_1.applyIgnoreMasksInPage, {
                 selectors: resolved.ignoreElements,
@@ -268,6 +293,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.29.g497a7aa",
+  "version": "0.1.3-pr.30.gc7b05dc",
   "description": "Storybook screenshot capture for the Vitest addon",
   "type": "module",
   "main": "./dist/index.js",