@fohte/storybook-addon 0.1.4 → 0.1.6

package/README.md

@@ -78,6 +78,8 @@ initialize({
 
 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).
 
+`viewport` applies for the whole test, not just the screenshot: mount and `play()` render at it too. `@storybook/addon-vitest` would otherwise silently mount/run every story at its own fixed 1200x900 default instead.
+
 ```ts
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'

package/lib/checks/unhandled-api-request-check.d.ts

@@ -2,6 +2,8 @@ import type { StorybookCheck } from '#checks/check.js';
 interface UnhandledApiRequestState {
     pathPrefixes: string[];
     unhandledApiRequestUrls: string[];
+    pendingFetches: Set<Promise<void>>;
+    fetchTrackerInstalled: boolean;
 }
 declare global {
     var __fohteStorybookAddonUnhandledApiRequestState__: UnhandledApiRequestState | undefined;
@@ -10,6 +12,7 @@ export declare function configureUnhandledApiRequestCheck(options: {
     pathPrefixes: string[];
 }): void;
 export declare function reportUnhandledApiRequest(url: string): boolean;
+export declare function waitForPendingApiRequests(): Promise<void>;
 export declare const unhandledApiRequestCheck: StorybookCheck;
 export {};
 //# sourceMappingURL=unhandled-api-request-check.d.ts.map

package/lib/checks/unhandled-api-request-check.js

@@ -3,28 +3,102 @@ function globalState() {
     globalThis.__fohteStorybookAddonUnhandledApiRequestState__ ??= {
         pathPrefixes: [],
         unhandledApiRequestUrls: [],
+        pendingFetches: new Set(),
+        fetchTrackerInstalled: false,
     };
     return globalThis.__fohteStorybookAddonUnhandledApiRequestState__;
 }
 export function configureUnhandledApiRequestCheck(options) {
     globalState().pathPrefixes = options.pathPrefixes;
 }
+// `url` may be relative (e.g. a same-origin fetch('/api/tasks')), so it's
+// always resolved against the current page rather than parsed on its own.
+function trackedRequestUrl(url) {
+    const parsed = new URL(url, window.location.href);
+    if (parsed.origin !== window.location.origin)
+        return undefined;
+    const isTracked = globalState().pathPrefixes.some((prefix) => parsed.pathname.startsWith(prefix));
+    return isTracked ? parsed : undefined;
+}
+function isTrackedRequestUrl(url) {
+    return trackedRequestUrl(url) !== undefined;
+}
 // Returns whether the request was recorded, so the caller can decide whether
 // to also print MSW's own error for it.
 export function reportUnhandledApiRequest(url) {
-    const parsed = new URL(url);
-    if (parsed.origin !== window.location.origin)
+    const parsed = trackedRequestUrl(url);
+    if (!parsed)
         return false;
+    globalState().unhandledApiRequestUrls.push(parsed.pathname);
+    return true;
+}
+function requestUrl(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    return input.url;
+}
+// A story's own render (e.g. a mount-time useEffect) can fire a fetch() it
+// never awaits. MSW only learns whether that request is unhandled once its
+// interception finishes, which — unlike a same-tick function call — takes at
+// least one extra tick, so a check running immediately after render can run
+// before MSW has had the chance to call reportUnhandledApiRequest() for it.
+// Tracking matching fetch() calls lets assert() wait for them to settle
+// first instead of racing that interception.
+function installFetchTracker() {
     const state = globalState();
-    if (!state.pathPrefixes.some((prefix) => parsed.pathname.startsWith(prefix))) {
-        return false;
+    if (state.fetchTrackerInstalled)
+        return;
+    state.fetchTrackerInstalled = true;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (input, init) => {
+        const response = originalFetch(input, init);
+        if (isTrackedRequestUrl(requestUrl(input))) {
+            const settled = response.then(() => undefined, () => undefined);
+            state.pendingFetches.add(settled);
+            void settled.finally(() => state.pendingFetches.delete(settled));
+        }
+        return response;
+    };
+}
+// ponytail: bounded wait, so a story that deliberately leaves a matching
+// fetch pending forever (e.g. to render a "loading" state) doesn't hang the
+// suite -- raise this if MSW's interception proves slower in practice.
+const PENDING_FETCH_TIMEOUT_MS = 2000;
+// preview.ts's afterEach awaits this before running any check's assert(),
+// so unhandledApiRequestCheck.assert() itself can stay synchronous like
+// every other check.
+export async function waitForPendingApiRequests() {
+    const { pendingFetches } = globalState();
+    const deadline = Date.now() + PENDING_FETCH_TIMEOUT_MS;
+    // A tracked fetch's own resolution can synchronously trigger another
+    // tracked fetch (e.g. fetch(user).then(() => fetch(user.posts))) — re-check
+    // pendingFetches after each round instead of racing a single snapshot of
+    // it, so a same-story follow-up fetch is also waited for, within the same
+    // overall deadline.
+    while (pendingFetches.size > 0 && Date.now() < deadline) {
+        // Each iteration re-reads pendingFetches, which the previous iteration's
+        // wait may have grown, so this can't be hoisted out of the loop.
+        await Promise.race([
+            Promise.all(pendingFetches),
+            new Promise((resolve) => setTimeout(resolve, deadline - Date.now())),
+        ]);
+    }
+    if (pendingFetches.size > 0) {
+        console.warn(`[unhandled-api-request-check] gave up waiting for ${String(pendingFetches.size)} pending fetch(es) after ${String(PENDING_FETCH_TIMEOUT_MS)}ms`);
     }
-    state.unhandledApiRequestUrls.push(parsed.pathname);
-    return true;
 }
 export const unhandledApiRequestCheck = {
     reset: () => {
-        globalState().unhandledApiRequestUrls.length = 0;
+        installFetchTracker();
+        const state = globalState();
+        state.unhandledApiRequestUrls.length = 0;
+        // Discard fetches left over from a previous story (e.g. one that never
+        // settles, to render a "loading" state) — its own afterEach already ran
+        // waitForPendingApiRequests() for it, so continuing to track it here
+        // would only force every later story to pay the full timeout too.
+        state.pendingFetches.clear();
     },
     assert: () => {
         throwIfNotEmpty(globalState().unhandledApiRequestUrls, 'Story made unhandled API request(s); add an MSW handler for');

package/lib/find-transparent-rows.d.ts

@@ -0,0 +1,2 @@
+export declare function findTransparentRows(data: Uint8ClampedArray, width: number, height: number): number[];
+//# sourceMappingURL=find-transparent-rows.d.ts.map

package/lib/find-transparent-rows.js

@@ -0,0 +1,16 @@
+export function findTransparentRows(data, width, height) {
+    const transparentRows = [];
+    for (let y = 0; y < height; y++) {
+        let hasOpaquePixel = false;
+        for (let x = 0; x < width; x++) {
+            if (data[(y * width + x) * 4 + 3] !== 0) {
+                hasOpaquePixel = true;
+                break;
+            }
+        }
+        if (!hasOpaquePixel)
+            transparentRows.push(y);
+    }
+    return transparentRows;
+}
+//# sourceMappingURL=find-transparent-rows.js.map

package/lib/preview.js

@@ -1,6 +1,6 @@
 import { externalResourceCheck } from '#checks/external-resource-check.js';
 import { overflowCheck } from '#checks/overflow-check.js';
-import { unhandledApiRequestCheck } from '#checks/unhandled-api-request-check.js';
+import { unhandledApiRequestCheck, waitForPendingApiRequests, } from '#checks/unhandled-api-request-check.js';
 export { configureUnhandledApiRequestCheck, reportUnhandledApiRequest, } from '#checks/unhandled-api-request-check.js';
 function injectStyle(css) {
     const style = document.createElement('style');
@@ -36,7 +36,12 @@ export const beforeEach = () => {
     for (const check of checks)
         check.reset();
 };
-export const afterEach = (context) => {
+export const afterEach = async (context) => {
+    // A story with no play function only has its render awaited before
+    // afterEach runs (see storybook/dist/preview/runtime.js's runStory()), so
+    // a fire-and-forget fetch() from a mount-time effect can still be in
+    // flight here — wait for it before the checks read their state.
+    await waitForPendingApiRequests();
     for (const check of checks) {
         check.assert(context.parameters, context.canvasElement);
     }

package/lib/vitest-plugin.d.ts

@@ -48,7 +48,16 @@ export declare function createStorybookProject({ name, rootDir, viewport, screen
             }[];
         };
         setupFiles: string[];
+        provide: {
+            fohteStorybookAddonViewport: {
+                width: number;
+                height: number;
+            };
+        };
         maxWorkers?: number;
+        sequence?: {
+            groupOrder: number;
+        };
         name: string;
     };
 };

package/lib/vitest-plugin.js

@@ -1,4 +1,6 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
 import storycap from '@storycap-testrun/browser/vitest-plugin';
 import { playwright } from '@vitest/browser-playwright';
@@ -47,6 +49,17 @@ 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 viewportSetupFile = fileURLToPath(import.meta.resolve('#vitest-viewport-setup.js'));
+    // `import.meta.resolve` maps `#*.js` straight to `./lib/*.js` (this
+    // package's own build output) without checking the file exists — running
+    // against a fresh clone or a stale `lib/` (before `pnpm run build`, or
+    // after editing vitest-viewport-setup.ts without rebuilding) would
+    // otherwise leave Vitest to fail on a missing/stale setupFile with no clue
+    // this is why.
+    if (!existsSync(viewportSetupFile)) {
+        // eslint-disable-next-line no-restricted-syntax -- config-load-time invariant check, mirrors storycapNetworkIdle's fail-fast pattern above
+        throw new Error(`createStorybookProject: ${viewportSetupFile} not found. Run \`pnpm run build\` first.`);
+    }
     const plugins = [
         storycapNetworkIdle,
         storybookTest({
@@ -80,17 +93,44 @@ export function createStorybookProject({ name, rootDir, viewport, screenshotsSub
         plugins,
         test: {
             name,
-            ...(maxWorkers !== undefined && { maxWorkers }),
+            ...(maxWorkers !== undefined && {
+                maxWorkers,
+                // Vitest requires distinct `sequence.groupOrder` for same-group
+                // projects with different `maxWorkers`, and a consumer's sibling
+                // project (e.g. a plain "unit" project) won't have `maxWorkers`
+                // set — so this project needs its own group whenever it sets one.
+                sequence: { groupOrder: 1 },
+            }),
             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' } }),
+                //
+                // `viewport` must match the story `viewport` above: Vitest's own
+                // iframe sizing (`__storycap_prepareViewport`) only resizes the
+                // iframe's wrapper div via CSS, it never touches the Playwright
+                // page's own viewport, which otherwise stays at Chromium's 1280x720
+                // default. `page.screenshot({ clip })` clips to the page's actual
+                // viewport regardless of the CSS layout, so a shorter page viewport
+                // silently truncates every fullPage tile's clip rect below it.
+                provider: playwright({
+                    contextOptions: { timezoneId: 'Asia/Tokyo', viewport },
+                }),
                 headless: true,
                 instances: [{ browser: 'chromium' }],
             },
-            setupFiles,
+            // @storybook/addon-vitest overrides the story viewport to its own
+            // 1200x900 default right before mount/play() unless
+            // parameters.viewport/globals.viewport are set — vitest-viewport-setup.ts
+            // sets them via setProjectAnnotations() so mount/play() see the same
+            // `viewport` as the Playwright page and the screenshot above. It must
+            // run after the consumer's own setupFiles in case any of them also
+            // call setProjectAnnotations().
+            setupFiles: [...setupFiles, viewportSetupFile],
+            provide: {
+                fohteStorybookAddonViewport: viewport,
+            },
         },
     };
 }

package/lib/vitest-viewport-setup.d.ts

@@ -0,0 +1,10 @@
+declare module 'vitest' {
+    interface ProvidedContext {
+        fohteStorybookAddonViewport: {
+            width: number;
+            height: number;
+        };
+    }
+}
+export {};
+//# sourceMappingURL=vitest-viewport-setup.d.ts.map

package/lib/vitest-viewport-setup.js

@@ -0,0 +1,50 @@
+import { setProjectAnnotations } from 'storybook/preview-api';
+import { getProjectAnnotations } from 'virtual:/@storybook/builder-vite/project-annotations.js';
+import { beforeEach, inject } from 'vitest';
+const VIEWPORT_NAME = '__fohteStorybookAddonViewport';
+const { width, height } = inject('fohteStorybookAddonViewport');
+// setProjectAnnotations() replaces the project annotations wholesale rather
+// than merging into them, so composing in the consumer's own
+// getProjectAnnotations() first is required — passing only the viewport
+// override below would drop the consumer's own preview.ts
+// renderer/decorators/loaders. Both are static per test file (the consumer's
+// preview.ts and this project's `viewport` don't change mid-run), so this is
+// computed once at setup-file top level rather than inside beforeEach below.
+const projectAnnotations = getProjectAnnotations();
+const viewportOverride = {
+    parameters: {
+        viewport: {
+            defaultViewport: VIEWPORT_NAME,
+            viewports: {
+                [VIEWPORT_NAME]: {
+                    name: 'createStorybookProject viewport',
+                    styles: {
+                        width: `${String(width)}px`,
+                        height: `${String(height)}px`,
+                    },
+                },
+            },
+        },
+    },
+    initialGlobals: { viewport: { value: VIEWPORT_NAME } },
+};
+// @storybook/addon-vitest's own testStory() calls setViewport() right before
+// mount/play(), falling back to its built-in 1200x900 default whenever
+// parameters.viewport/globals.viewport aren't set — silently overriding the
+// `viewport` createStorybookProject() was given for the screenshot capture
+// itself. setProjectAnnotations() is the public integration point Storybook
+// added for exactly this in 10.3.
+//
+// The call itself runs in beforeEach, not at setup-file top level:
+// @storybook/addon-vitest always injects its own
+// internal/setup-file-with-project-annotations alongside consumer
+// setupFiles — its "already provisioned" detection only looks inside the
+// consumer's `.storybook` dir, which this file isn't in. That file's
+// top-level setProjectAnnotations(getProjectAnnotations()) call would run
+// after this file's own top level and silently wipe this override.
+// beforeEach always runs after every setupFile finishes loading, so calling
+// setProjectAnnotations() here instead wins regardless of setupFiles order.
+beforeEach(() => {
+    setProjectAnnotations([projectAnnotations, viewportOverride]);
+});
+//# sourceMappingURL=vitest-viewport-setup.js.map

package/package.json

@@ -57,22 +57,24 @@
     "@fohte/eslint-config": "0.4.1",
     "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
     "@storybook/addon-vitest": "10.5.8",
+    "@storybook/html-vite": "10.5.8",
     "@storycap-testrun/browser": "2.1.1",
-    "@tsconfig/node-lts": "24.0.0",
+    "@tsconfig/node-lts": "24.0.1",
     "@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",
+    "concurrently": "10.0.5",
     "eslint": "10.6.0",
     "jsdom": "30.0.1",
+    "playwright": "1.62.1",
     "prettier": "3.9.6",
     "rimraf": "6.1.3",
     "storybook": "10.5.8",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
-  "version": "0.1.4",
+  "version": "0.1.6",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",
@@ -83,6 +85,7 @@
     "format": "conc -m 1 pnpm:format:eslint pnpm:format:prettier",
     "test": "conc pnpm:test:type pnpm:test:unit",
     "test:type": "tsc --noEmit",
+    "pretest:unit": "pnpm run build",
     "test:unit": "vitest run"
   }
 }