@qoretechnologies/qlip 0.1.3-beta.20260908110821 → 0.1.3-beta.20260929120101

package/README.md

@@ -194,8 +194,11 @@ export const LoggedIn = {
     qlip: {
       skip: false,
       viewport: { width: 1280, height: 720 },
+      fullSizeCaptures: false,
       disableAnimations: true,
       pauseAnimationsAtEnd: false,
+      fullPage: false,
+      fullPageMaxHeight: 10000,
       captureOnError: false,
       waitForIdleMs: 300,
       maxWaitForIdleMs: 2000,
@@ -217,8 +220,11 @@ Options precedence:
 qlipVitestPlugin({
   outputDir: './qlip/screenshots',
   viewport: { width: 1280, height: 720 },
+  fullSizeCaptures: false,
   disableAnimations: false,
   pauseAnimationsAtEnd: false,
+  fullPage: false,
+  fullPageMaxHeight: 10000,
   captureOnError: false,
   waitForIdleMs: 300,
   maxWaitForIdleMs: 2000,
@@ -227,6 +233,12 @@ 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 a `fullPage` capture also grows the window — the Playwright context viewport — through a browser command the plugin registers (`qlipBrowserViewport`), and restores it first; the capture is 1:1, not a shrunk picture of a tall page. `fullSizeCaptures` does the same for every capture (below). 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.
+
+`fullSizeCaptures` captures every story at the full size of its `viewport`. Under Vitest browser mode the browser window stays at the Playwright context viewport — 1280×720 headless, unless you configure it — whatever the story's `viewport` says, and Vitest scales the test iframe down to fit the window. The layout is the story's, but the pixels are shrunk: a 1920×1080 story comes back 1280×720, a 390×844 phone story 333×720, with its text and any fine difference shrunk with it. With `fullSizeCaptures: true` the window grows to hold the viewport for each capture and is put back afterwards, so the PNG is exactly the viewport. The runner path always captures at full size, and `fullPage` always grows the window.
+
+It is off by default, so upgrading qlip changes no baselines, and it will become the default in a future minor release. Turning it on changes the size of every capture whose viewport is larger than the window (stories that fit it are unaffected), and the server reports each of those as changed against its baseline, a dimensions change. Turn it on in one change on your default branch and accept those captures once.
+
 `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

@@ -5,9 +5,12 @@ export interface QlipResolvedOptions {
         width: number;
         height: number;
     };
+    fullSizeCaptures: boolean;
     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,gBAAgB,EAAE,OAAO,CAAC;IAC1B,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,mBAyDH,CAAC"}

package/dist/config/parameters.js

@@ -2,6 +2,9 @@ export const resolveQlipOptions = ({ defaults, story, override, }) => {
     return {
         skip: override?.skip ?? story?.skip ?? defaults.skip,
         viewport: override?.viewport ?? story?.viewport ?? defaults.viewport,
+        fullSizeCaptures: override?.fullSizeCaptures ??
+            story?.fullSizeCaptures ??
+            defaults.fullSizeCaptures,
         disableAnimations: override?.disableAnimations ??
             story?.disableAnimations ??
             defaults.disableAnimations,
@@ -11,6 +14,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,MAkRlE,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();
@@ -30,6 +33,9 @@ export const qlipVitestPlugin = (options = {}) => {
                 defaults: {
                     outputDir,
                     viewport: options.viewport ?? DEFAULT_VIEWPORT,
+                    // Off by default — turning it on resizes every capture that was
+                    // being scaled to fit the window. See QlipCaptureOptions.
+                    fullSizeCaptures: options.fullSizeCaptures ?? false,
                     skip: false,
                     disableAnimations: options.disableAnimations ?? false,
                     pauseAnimationsAtEnd: options.pauseAnimationsAtEnd ?? false,
@@ -37,6 +43,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 +193,16 @@ export const qlipVitestPlugin = (options = {}) => {
                     setupFiles: [setupFile],
                     globalSetup: [globalSetupFile],
                     reporters: reportersList,
+                    // The runtime grows the browser window for a `fullPage` capture,
+                    // and for every capture with `fullSizeCaptures`, 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,120 @@
+/**
+ * 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,
+ * when it is given one, 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. The runtime gives it the window for a `fullPage` capture
+ * and, with `fullSizeCaptures` on, for every capture.
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;GAoBG;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,216 @@
+/**
+ * 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,
+ * when it is given one, 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. The runtime gives it the window for a `fullPage` capture
+ * and, with `fullSizeCaptures` on, for every capture.
+ *
+ * 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;AAicF,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,39 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
     // throws.
     let error = testError ?? null;
     let cleanupMasks = null;
+    // Unless the browser window grows with it, a viewport larger than the
+    // window is captured scaled down to fit it (see ./fullPage.ts). Growing it
+    // resizes captures that already have baselines, so it is opt-in
+    // (`fullSizeCaptures`); a `fullPage` capture always grows it, since scaled
+    // it is unreadable.
+    const captureViewport = createCaptureViewport({
+        pinned: resolved.viewport,
+        iframe: (width, height) => page.viewport(width, height),
+        window: resolved.fullSizeCaptures || resolved.fullPage
+            ? commands.qlipBrowserViewport
+            : undefined,
+    });
     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 +539,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/Page.stories.d.ts

@@ -9,6 +9,13 @@ declare const meta: {
 export default meta;
 type Story = StoryObj<typeof meta>;
 export declare const LoggedOut: Story;
+/**
+ * A desktop viewport wider and taller than the 1280×720 headless browser
+ * window. `fullSizeCaptures` grows the window to hold it, so the capture is
+ * 1920×1080; without it Vitest would scale the story down to 1280×720. The
+ * e2e test reads the PNG.
+ */
+export declare const DesktopFullSize: Story;
 export declare const LoggedIn: Story;
 export declare const ElementWithFullHeight: Story;
 export declare const WithConsoleError: Story;

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

@@ -1 +1 @@
-{"version":3,"file":"Page.stories.d.ts","sourceRoot":"","sources":["../../src/stories/Page.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAO5D,QAAA,MAAM,IAAI;;;;;;CAOmB,CAAC;AAE9B,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAGnC,eAAO,MAAM,SAAS,EAAE,KAAU,CAAC;AAGnC,eAAO,MAAM,QAAQ,EAAE,KAatB,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,KAQnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAS9B,CAAC"}
+{"version":3,"file":"Page.stories.d.ts","sourceRoot":"","sources":["../../src/stories/Page.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAO5D,QAAA,MAAM,IAAI;;;;;;CAOmB,CAAC;AAE9B,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAGnC,eAAO,MAAM,SAAS,EAAE,KAAU,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,KAI7B,CAAC;AAGF,eAAO,MAAM,QAAQ,EAAE,KAatB,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,KAQnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAS9B,CAAC"}

package/dist/stories/Page.stories.js

@@ -12,6 +12,17 @@ const meta = {
 };
 export default meta;
 export const LoggedOut = {};
+/**
+ * A desktop viewport wider and taller than the 1280×720 headless browser
+ * window. `fullSizeCaptures` grows the window to hold it, so the capture is
+ * 1920×1080; without it Vitest would scale the story down to 1280×720. The
+ * e2e test reads the PNG.
+ */
+export const DesktopFullSize = {
+    parameters: {
+        qlip: { viewport: { width: 1920, height: 1080 }, fullSizeCaptures: true },
+    },
+};
 // More on component testing: https://storybook.js.org/docs/writing-tests/interaction-testing
 export const LoggedIn = {
     play: async (ctx) => {