@fohte/storybook-addon 0.1.3 → 0.1.4

package/README.md

@@ -76,7 +76,7 @@ initialize({
 
 ## Vitest plugin (`./vitest-plugin`)
 
-Builds a Vitest browser-mode project that runs Storybook stories through [`@storybook/addon-vitest`](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) and captures a screenshot of each with [`@storycap-testrun/browser`](https://github.com/reg-viz/storycap-testrun), patched to shorten storycap's hardcoded 500ms network-idle wait to 100ms.
+Builds a Vitest browser-mode project that runs Storybook stories through [`@storybook/addon-vitest`](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) and captures a screenshot of each with [`@storycap-testrun/browser`](https://github.com/reg-viz/storycap-testrun), patched to shorten storycap's hardcoded 500ms network-idle wait to 100ms and to fix a tiling bug in its fullPage capture (`clip` staying anchored to the top of the viewport instead of following the browser's clamped scroll position, which duplicated content and cut off the bottom of any story taller than the viewport).
 
 ```ts
 import path from 'node:path'
@@ -104,7 +104,7 @@ export default defineConfig({
 
 Screenshots for a project land in `<rootDir>/__screenshots__/<screenshotsSubdir>` — downstream tooling that consumes these images depends on this exact path, so treat it as a stable contract rather than an implementation detail.
 
-`storycapNetworkIdle` is also exported on its own, for building a project without `createStorybookProject`.
+`storycapNetworkIdle` and `storycapFullPageStitch` are also exported on their own, for building a project without `createStorybookProject`. `storycapFullPageStitch` must be placed after storycap's own plugin in the `plugins` array — it works by overriding the `__storycap_takeScreenshot` command storycap registers, and Vite resolves conflicting plugin `config()` keys in plugin order, later wins.
 
 Your `setupFiles` entry needs an `afterEach` that calls storycap's own `screenshot()` — see [`@storycap-testrun/browser`'s "Setup Screenshot Capture"](https://github.com/reg-viz/storycap-testrun/tree/main/packages/browser#2-setup-screenshot-capture) for the exact shape. Don't call `setProjectAnnotations()` there, and don't even mention that identifier in a comment: `@storybook/addon-vitest` decides whether to inject this package's checks by a plain substring search over the setup file's source text, so its mere presence silently disables every check in the project, with no error.
 

package/lib/storycap-fullpage-stitch.d.ts

@@ -0,0 +1,33 @@
+import type { BrowserCommand, BrowserCommandContext } from 'vitest/node';
+type Viewport = {
+    width: number;
+    height: number;
+};
+type Page = BrowserCommandContext['page'];
+type ScreenshotOptions = NonNullable<Parameters<Page['screenshot']>[0]>;
+interface TakeScreenshotOptions {
+    fullPage?: boolean;
+    omitBackground?: ScreenshotOptions['omitBackground'];
+    scale?: ScreenshotOptions['scale'];
+    type?: ScreenshotOptions['type'];
+}
+export declare function computeChunkClip(requestedScrollY: number, actualScrollY: number, viewportHeight: number, scrollHeight: number): {
+    clipYOffset: number;
+    chunkHeight: number;
+};
+export declare function storycapFullPageStitch(options?: {
+    viewport?: Viewport;
+}): {
+    name: string;
+    config(): {
+        test: {
+            browser: {
+                commands: {
+                    __storycap_takeScreenshot: BrowserCommand<[string, TakeScreenshotOptions], string>;
+                };
+            };
+        };
+    };
+};
+export {};
+//# sourceMappingURL=storycap-fullpage-stitch.d.ts.map

package/lib/storycap-fullpage-stitch.js

@@ -0,0 +1,170 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const IFRAME_SELECTOR = 'iframe[data-vitest]';
+// @storycap-testrun/browser's own fullPage tiling (packages/browser/src/vitest-plugin/index.ts,
+// `captureFullPage`) always clips each tile starting at the iframe's bounding-box
+// top, on the assumption that `scrollTo(0, requestedScrollY)` always lands
+// exactly at `requestedScrollY`. The browser clamps the scroll position once
+// it exceeds `scrollHeight - viewportHeight`, so whenever the page height
+// isn't an exact multiple of the viewport height, the last tile re-captures
+// already-seen content instead of the page's true bottom, which is never
+// captured. Comparing the requested position against what the browser
+// actually applied gives the pixel offset the clip rect needs to shift down
+// by to land on unseen content.
+export function computeChunkClip(requestedScrollY, actualScrollY, viewportHeight, scrollHeight) {
+    const clipYOffset = requestedScrollY - actualScrollY;
+    const chunkHeight = Math.min(viewportHeight - clipYOffset, scrollHeight - requestedScrollY);
+    return { clipYOffset, chunkHeight };
+}
+async function scrollIframeTo(ctx, top) {
+    // `{ behavior: 'instant' }` overrides any `scroll-behavior: smooth` set by
+    // the story's own CSS. Without it, a smooth-scrolling story would still be
+    // mid-animation when the position is read back below, making the reported
+    // scroll position (and therefore the capture) non-deterministic.
+    return ctx.iframe.locator('body').evaluate((body, scrollTop) => {
+        const view = body.ownerDocument.defaultView;
+        view?.scrollTo({ top: scrollTop, left: 0, behavior: 'instant' });
+        return view?.scrollY ?? 0;
+    }, top);
+}
+async function getIframeBoundingBox(ctx) {
+    const box = await ctx.page.locator(IFRAME_SELECTOR).boundingBox();
+    if (box)
+        return box;
+    // eslint-disable-next-line no-restricted-syntax -- interop boundary: BrowserCommand contract signals failure by rejecting
+    throw new Error('Could not determine iframe position for screenshot');
+}
+function screenshotOptionsFrom(options) {
+    return {
+        animations: 'disabled',
+        caret: 'hide',
+        // Playwright's own default ('device') scales the returned buffer by
+        // deviceScaleFactor, but captureFullPage's canvas below is sized in CSS
+        // pixels — pin 'css' so a chunk's pixel dimensions always match the
+        // canvas region it gets drawn into.
+        scale: options.scale ?? 'css',
+        ...(options.omitBackground != null && {
+            omitBackground: options.omitBackground,
+        }),
+        ...(options.type != null && { type: options.type }),
+    };
+}
+async function captureTiles(ctx, viewport, scrollHeight, options) {
+    // The iframe element's position on the outer page doesn't move when its
+    // own inner content scrolls, so this only needs to be read once per
+    // capture instead of once per tile.
+    const iframeBox = await getIframeBoundingBox(ctx);
+    const images = [];
+    const heights = [];
+    for (let requestedScrollY = 0; requestedScrollY < scrollHeight; requestedScrollY += viewport.height) {
+        const actualScrollY = await scrollIframeTo(ctx, requestedScrollY);
+        const { clipYOffset, chunkHeight } = computeChunkClip(requestedScrollY, actualScrollY, viewport.height, scrollHeight);
+        const chunkBuffer = await ctx.page.screenshot({
+            clip: {
+                x: iframeBox.x,
+                y: iframeBox.y + clipYOffset,
+                width: iframeBox.width,
+                height: chunkHeight,
+            },
+            ...screenshotOptionsFrom(options),
+        });
+        images.push(Buffer.from(chunkBuffer).toString('base64'));
+        heights.push(chunkHeight);
+    }
+    const mimeType = options.type === 'jpeg' ? 'image/jpeg' : 'image/png';
+    const stitchedBase64 = await ctx.page.evaluate(async ({ images: chunkImages, width, heights: chunkHeights, mimeType: mime, }) => {
+        const totalHeight = chunkHeights.reduce((sum, h) => sum + h, 0);
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = totalHeight;
+        const canvasContext = canvas.getContext('2d');
+        let y = 0;
+        for (let i = 0; i < chunkImages.length; i++) {
+            const img = new Image();
+            img.src = `data:${mime};base64,${chunkImages[i] ?? ''}`;
+            await new Promise((resolve, reject) => {
+                img.onload = () => {
+                    resolve();
+                };
+                img.onerror = () => {
+                    reject(new Error(`failed to decode screenshot chunk ${i.toString()}`));
+                };
+            });
+            canvasContext?.drawImage(img, 0, y);
+            y += chunkHeights[i] ?? 0;
+        }
+        return canvas.toDataURL(mime).split(',')[1] ?? '';
+    }, { images, width: viewport.width, heights, mimeType });
+    return Buffer.from(stitchedBase64, 'base64');
+}
+// Vitest's browser mode reuses one iframe per test file, so a scroll
+// position left behind by a failed capture would bleed into whichever
+// story runs next in the same file — reset it whether captureTiles()
+// succeeds or rejects.
+function captureFullPage(ctx, viewport, scrollHeight, options) {
+    return captureTiles(ctx, viewport, scrollHeight, options).finally(() => scrollIframeTo(ctx, 0));
+}
+function takeScreenshot(configuredViewport) {
+    return async (ctx, filepath, options) => {
+        const viewport = configuredViewport ??
+            ctx.page.viewportSize() ?? { width: 1280, height: 720 };
+        let buffer;
+        if (options.fullPage === false) {
+            await ctx.page.evaluate(() => {
+                window.scrollTo(0, 0);
+            });
+            const iframeBox = await getIframeBoundingBox(ctx);
+            buffer = Buffer.from(await ctx.page.screenshot({
+                clip: iframeBox,
+                ...screenshotOptionsFrom(options),
+            }));
+        }
+        else {
+            const scrollHeight = await ctx.iframe
+                .locator('body')
+                .evaluate((body) => Math.max(body.scrollHeight, body.ownerDocument.documentElement.scrollHeight));
+            buffer =
+                scrollHeight > viewport.height
+                    ? await captureFullPage(ctx, viewport, scrollHeight, options)
+                    : await ctx.iframe
+                        .locator('body')
+                        .screenshot(screenshotOptionsFrom(options));
+        }
+        await fs.mkdir(path.dirname(filepath), { recursive: true });
+        await fs.writeFile(filepath, buffer);
+        return Buffer.from(buffer).toString('base64');
+    };
+}
+// Replaces @storycap-testrun/browser's `__storycap_takeScreenshot` command
+// (registered by the `storycap` plugin passed to `createStorybookProject`,
+// via the same `config()` → `test.browser.commands` shape used below) with
+// a from-scratch reimplementation that fixes the fullPage tiling bug
+// described above. Vite merges plugin `config()`
+// hooks in plugin order, with later plugins overriding matching keys — so
+// this must be placed after the `storycap` plugin in `createStorybookProject`'s
+// `plugins` array for the override to take effect. `resolveScreenshotFilepath`,
+// `__storycap_prepareViewport` and `__storycap_restoreViewport` are untouched,
+// since this only supplies the `__storycap_takeScreenshot` key.
+//
+// No upstream issue tracks this bug. Drop this plugin (and its wiring in
+// vitest-plugin.ts) once @storycap-testrun/browser's own `captureFullPage`
+// (packages/browser/src/vitest-plugin/index.ts) accounts for `scrollTo`
+// clamping the requested position instead of assuming it always lands
+// exactly where requested.
+export function storycapFullPageStitch(options = {}) {
+    return {
+        name: 'storycap-fullpage-stitch-fix',
+        config() {
+            return {
+                test: {
+                    browser: {
+                        commands: {
+                            __storycap_takeScreenshot: takeScreenshot(options.viewport),
+                        },
+                    },
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=storycap-fullpage-stitch.js.map

package/lib/vitest-plugin.d.ts

@@ -1,3 +1,4 @@
+export { storycapFullPageStitch } from '#storycap-fullpage-stitch.js';
 export declare const storycapNetworkIdle: {
     name: string;
     transform(code: string, id: string): string | null;

package/lib/vitest-plugin.js

@@ -2,6 +2,8 @@ import path from 'node:path';
 import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
 import storycap from '@storycap-testrun/browser/vitest-plugin';
 import { playwright } from '@vitest/browser-playwright';
+import { storycapFullPageStitch } from '#storycap-fullpage-stitch.js';
+export { storycapFullPageStitch } from '#storycap-fullpage-stitch.js';
 // @storycap-testrun/browser ships a bundled .d.ts with its own copy of vite's
 // `Plugin` type, so it's structurally identical but nominally unrelated to
 // ours — cast to sidestep the resulting "unrelated types" error. Typing this
@@ -45,6 +47,29 @@ export function createStorybookProject({ name, rootDir, viewport, screenshotsSub
     const configDir = path.join(rootDir, '.storybook');
     const screenshotsDir = path.join(rootDir, '__screenshots__', screenshotsSubdir);
     const maxWorkers = process.env['CI'] != null ? ciMaxWorkers : undefined;
+    const plugins = [
+        storycapNetworkIdle,
+        storybookTest({
+            configDir,
+            tags: { exclude: excludeTags },
+        }),
+        asPlugin(storycap({
+            viewport,
+            output: { dir: screenshotsDir },
+        })),
+        storycapFullPageStitch({ viewport }),
+    ];
+    // storycapFullPageStitch's own comment explains why plugin order is what
+    // makes it an override of storycap's `__storycap_takeScreenshot` — check
+    // that order here (by plugin name, since storycap's own plugin type is
+    // cast to `any` above) instead of leaving a reorder to silently resurrect
+    // the fullPage tiling bug it fixes.
+    const storycapIndex = plugins.findIndex((p) => p.name === 'vitest:screenshot');
+    const fullPageStitchIndex = plugins.findIndex((p) => p.name === 'storycap-fullpage-stitch-fix');
+    if (fullPageStitchIndex < storycapIndex) {
+        // eslint-disable-next-line no-restricted-syntax -- config-load-time invariant check, mirrors storycapNetworkIdle's fail-fast pattern above
+        throw new Error('storycapFullPageStitch must be registered after storycap in the plugins array for its __storycap_takeScreenshot override to take effect');
+    }
     // storybookTest() below returns a Promise that starts loading a real
     // Storybook config from `configDir` as soon as it's constructed — nothing
     // but Vite's own plugin container ever awaits that Promise, so calling
@@ -52,17 +77,7 @@ export function createStorybookProject({ name, rootDir, viewport, screenshotsSub
     // surfaces it as an unhandled rejection instead of a useful assertion.
     // This branch is covered by running against a real Storybook config instead.
     return {
-        plugins: [
-            storycapNetworkIdle,
-            storybookTest({
-                configDir,
-                tags: { exclude: excludeTags },
-            }),
-            asPlugin(storycap({
-                viewport,
-                output: { dir: screenshotsDir },
-            })),
-        ],
+        plugins,
         test: {
             name,
             ...(maxWorkers !== undefined && { maxWorkers }),

package/package.json

@@ -52,11 +52,11 @@
     "neverthrow": "8.2.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "21.2.1",
+    "@commitlint/cli": "21.2.2",
     "@eslint/eslintrc": "3.3.6",
     "@fohte/eslint-config": "0.4.1",
     "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
-    "@storybook/addon-vitest": "10.5.7",
+    "@storybook/addon-vitest": "10.5.8",
     "@storycap-testrun/browser": "2.1.1",
     "@tsconfig/node-lts": "24.0.0",
     "@tsconfig/strictest": "2.0.8",
@@ -68,11 +68,11 @@
     "jsdom": "30.0.1",
     "prettier": "3.9.6",
     "rimraf": "6.1.3",
-    "storybook": "10.5.7",
+    "storybook": "10.5.8",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
-  "version": "0.1.3",
+  "version": "0.1.4",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",