@fohte/storybook-addon 0.1.2 → 0.1.4

package/README.md

@@ -17,8 +17,13 @@ pnpm add -D @fohte/storybook-addon
 
 # Peer dependencies
 pnpm add -D storybook vitest
+
+# Peer dependencies for ./vitest-plugin only
+pnpm add -D @storybook/addon-vitest @storycap-testrun/browser @vitest/browser-playwright
 ```
 
+`@vitest/browser-playwright` pins its own `vitest` peer to its exact version (e.g. `4.1.10` requires `vitest@4.1.10` precisely), even though this package's own `peerDependencies` range for both is the looser `^4.0.0`. Keep the two installed at the same version.
+
 ## Usage
 
 Add the addon to `.storybook/main.ts`:
@@ -69,11 +74,49 @@ 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 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'
+import { fileURLToPath } from 'node:url'
+
+import { createStorybookProject } from '@fohte/storybook-addon/vitest-plugin'
+import { defineConfig } from 'vitest/config'
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  test: {
+    projects: [
+      createStorybookProject({
+        name: 'storybook',
+        rootDir,
+        viewport: { width: 1280, height: 800 },
+        screenshotsSubdir: 'desktop',
+        setupFiles: ['./.storybook/vitest.setup.ts'],
+      }),
+    ],
+  },
+})
+```
+
+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` 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.
+
+### Check failures don't block the screenshot
+
+This package's checks run inside `@storybook/addon-vitest`'s own render phase, as part of the generated test body — before your `setupFiles`' `afterEach` (the one that calls `screenshot()`) ever runs. A failing check throws there, but Vitest still runs every registered `afterEach` after a test regardless of pass or fail, so the screenshot capture always follows, against whatever the DOM looked like when the check failed. Verified against a story with a deliberate overflow: the check failed, and `screenshot()` still produced a non-blank image showing the actual overflowing content.
+
 ## Addon `afterEach` ordering
 
 Storybook runs multiple addons' `afterEach` hooks serially, in the **reverse** of the order they're listed in `main.ts`'s `addons` array — the addon listed last runs its `afterEach` first. The consuming app's own `preview.ts`/`preview.tsx` `afterEach` runs before every addon's `afterEach`. If one hook throws, the remaining ones are skipped (fail-fast).
 
-This matters once a screenshot-capturing addon is added: to keep "capture first, then let this package's checks fail the test" working, list that addon **after** `@fohte/storybook-addon` in the `addons` array.
+This doesn't apply to `./vitest-plugin`'s screenshot capture: it isn't a Storybook addon, so it never sits in the `addons` array at all — see "Check failures don't block the screenshot" above for how that ordering actually works.
 
 ## Development
 

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

@@ -0,0 +1,55 @@
+export { storycapFullPageStitch } from '#storycap-fullpage-stitch.js';
+export declare const storycapNetworkIdle: {
+    name: string;
+    transform(code: string, id: string): string | null;
+};
+export interface CreateStorybookProjectOptions {
+    /** Project name, as shown by `vitest --project <name>`. */
+    name: string;
+    /**
+     * Absolute path to the app root that the default `.storybook` config dir
+     * and the screenshot output dir are resolved against — typically
+     * `path.dirname(fileURLToPath(import.meta.url))` from the consumer's own
+     * vitest.config.ts.
+     */
+    rootDir: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Screenshots for this project are written to
+     * `<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.
+     */
+    screenshotsSubdir: string;
+    setupFiles: string[];
+    excludeTags?: string[];
+    /**
+     * `test.maxWorkers`, applied only when `process.env.CI` is set — Vitest
+     * reads `maxWorkers` per-project rather than falling back to the root
+     * config. Screenshot capture is I/O-bound (network-idle wait, font
+     * loading, CDP metric polling), so this can exceed the CI runner's vCPU
+     * count, but the right number depends on the runner in use — tune it per
+     * consumer rather than trusting this default.
+     */
+    ciMaxWorkers?: number;
+}
+export declare function createStorybookProject({ name, rootDir, viewport, screenshotsSubdir, setupFiles, excludeTags, ciMaxWorkers, }: CreateStorybookProjectOptions): {
+    plugins: any[];
+    test: {
+        browser: {
+            enabled: boolean;
+            provider: import("vitest/node").BrowserProviderOption<import("@vitest/browser-playwright").PlaywrightProviderOptions>;
+            headless: boolean;
+            instances: {
+                browser: "chromium";
+            }[];
+        };
+        setupFiles: string[];
+        maxWorkers?: number;
+        name: string;
+    };
+};
+//# sourceMappingURL=vitest-plugin.d.ts.map

package/lib/vitest-plugin.js

@@ -0,0 +1,97 @@
+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
+// as `Plugin` (instead of `any`) reintroduces a cascading "exactOptionalPropertyTypes"
+// mismatch between vite's own `Plugin` and rollup's, so this stays `any`.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see comment above
+function asPlugin(plugin) {
+    return plugin;
+}
+// @storycap-testrun/browser waits for 500ms of network silence before every
+// capture and exposes no option to shorten it, so every story pays that flat
+// half second per viewport. Only the floor moves: the window still restarts on
+// each resource load, and `document.fonts.ready` plus the metrics-stability
+// poll that follow it are untouched.
+const NETWORK_IDLE_MS = 100;
+// The module arrives here either as the shipped `dist/index.mjs` or as an
+// esbuild pre-bundle, which reformats the minified source but keeps the literal.
+const NETWORK_IDLE_DEFAULT = /=\s*500\s*\)\s*=>\s*new Promise\(/;
+// A Vite plugin that patches @storycap-testrun/browser's own minified
+// source. If a version bump moves the 500ms literal (or removes it), this
+// throws at config-load time instead of silently leaving the 500ms wait in
+// place — the alternative (staying quiet) would just make every capture
+// slower with no visible symptom.
+export const storycapNetworkIdle = {
+    name: 'storycap-network-idle',
+    transform(code, id) {
+        if (!id.includes('@storycap-testrun') ||
+            !code.includes('PerformanceObserver')) {
+            return null;
+        }
+        const patched = code.replace(NETWORK_IDLE_DEFAULT, (match) => match.replace('500', String(NETWORK_IDLE_MS)));
+        if (patched === code) {
+            // This throw fails config loading itself, before any test runs.
+            // eslint-disable-next-line no-restricted-syntax -- Vite plugin transform hook contract: throwing is how a plugin aborts config loading
+            throw new Error(`storycap-network-idle: no 500ms network-idle default found in ${id}. Drop this plugin if @storycap-testrun made the wait configurable, otherwise re-derive the pattern.`);
+        }
+        return patched;
+    },
+};
+export function createStorybookProject({ name, rootDir, viewport, screenshotsSubdir, setupFiles, excludeTags = [], ciMaxWorkers = 8, }) {
+    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
+    // this factory directly against a synthetic `rootDir` in a unit test
+    // 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,
+        test: {
+            name,
+            ...(maxWorkers !== undefined && { maxWorkers }),
+            browser: {
+                enabled: true,
+                // Pin the browser's timezone so time-dependent stories (calendar
+                // "now" indicators, relative timestamps) render identically
+                // regardless of the host machine's local timezone.
+                provider: playwright({ contextOptions: { timezoneId: 'Asia/Tokyo' } }),
+                headless: true,
+                instances: [{ browser: 'chromium' }],
+            },
+            setupFiles,
+        },
+    };
+}
+//# sourceMappingURL=vitest-plugin.js.map

package/package.json

@@ -12,6 +12,10 @@
     "./preview": {
       "types": "./lib/preview.d.ts",
       "default": "./lib/preview.js"
+    },
+    "./vitest-plugin": {
+      "types": "./lib/vitest-plugin.d.ts",
+      "default": "./lib/vitest-plugin.js"
     }
   },
   "imports": {
@@ -27,31 +31,48 @@
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
+    "@storybook/addon-vitest": "^10.0.0",
+    "@storycap-testrun/browser": "^2.0.0",
+    "@vitest/browser-playwright": "^4.0.0",
     "storybook": "^10.0.0",
     "vitest": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@storybook/addon-vitest": {
+      "optional": true
+    },
+    "@storycap-testrun/browser": {
+      "optional": true
+    },
+    "@vitest/browser-playwright": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "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.0",
+    "@fohte/eslint-config": "0.4.1",
     "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
+    "@storybook/addon-vitest": "10.5.8",
+    "@storycap-testrun/browser": "2.1.1",
     "@tsconfig/node-lts": "24.0.0",
     "@tsconfig/strictest": "2.0.8",
     "@types/jsdom": "30.0.0",
     "@types/node": "24.13.3",
+    "@vitest/browser-playwright": "4.1.10",
     "concurrently": "10.0.4",
     "eslint": "10.6.0",
     "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.2",
+  "version": "0.1.4",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",