@fohte/storybook-addon 0.1.7 → 0.1.9

package/README.md

@@ -4,7 +4,7 @@
 
 Runs three checks right after each story renders, and fails the story's test when one trips:
 
-- **overflow-check** — flags elements whose content is clipped by their container (scrollWidth > clientWidth), which usually means a silent layout bug.
+- **overflow-check** — flags elements whose content is clipped by their container (scrollWidth > clientWidth), or the story's own root overflowing the viewport itself, which usually means a silent layout bug.
 - **external-resource-check** — flags stories that load a non-same-origin resource (font, image, stylesheet), which makes VRT captures non-deterministic.
 - **unhandled-api-request-check** — flags stories that hit an API endpoint with no MSW handler, which would otherwise render with MSW's error response instead of failing.
 
@@ -42,6 +42,10 @@ This wires up `overflow-check` and `external-resource-check` — no further setu
 
 ### overflow-check
 
+Besides scanning canvasElement's descendants, this check also compares `document.documentElement.scrollWidth` against `window.innerWidth`, catching canvasElement itself (or anything above it) overflowing the viewport — which the descendant scan can never see under `layout: 'centered'`, since a flex item's automatic minimum size keeps a fixed-width story from self-overflowing there. This is on by default alongside the descendant scan; `parameters.overflowCheck.disable` turns off both.
+
+`ignoreSelectors`/`globalIgnoreSelectors` below only filter the descendant scan, not the viewport check — the viewport check has no selector-level exemption and can only be turned off entirely via `disable`.
+
 To exempt a selector across every story (e.g. a component whose oversized hit target never visibly clips anything), set `parameters.overflowCheck.globalIgnoreSelectors` once in `.storybook/preview.ts`. It's additive with a story's own `parameters.overflowCheck.ignoreSelectors` — both apply, since they're separate keys and Storybook deep-merges parameter objects by key (only arrays at the same key replace wholesale, so a story-level `ignoreSelectors` can't drop the global list):
 
 ```ts
@@ -108,6 +112,17 @@ Screenshots for a project land in `<rootDir>/__screenshots__/<screenshotsSubdir>
 
 `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.
 
+`createStorybookProject` blocks non-`localhost` network requests in the browser by passing `BLOCK_EXTERNAL_REQUESTS_ARGS` to `playwright()`'s `launchOptions.args`, so a story can't depend on an external CDN request completing before the test's `afterEach` runs. It's a Chromium-only launch flag (matching `createStorybookProject`'s own `instances: [{ browser: 'chromium' }]`) — a `firefox`/`webkit` instance would silently get no blocking at all. If you build your `playwright()` call by hand instead of using `createStorybookProject`, spread this in yourself:
+
+```ts
+import { BLOCK_EXTERNAL_REQUESTS_ARGS } from '@fohte/storybook-addon/vitest-plugin'
+import { playwright } from '@vitest/browser-playwright'
+
+playwright({
+  launchOptions: { args: [...BLOCK_EXTERNAL_REQUESTS_ARGS] },
+})
+```
+
 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

package/lib/checks/check.js

@@ -1,9 +1,9 @@
-import { assert } from 'vitest';
 export function throwIfNotEmpty(urls, message) {
     if (urls.length === 0)
         return;
     const list = urls.join('\n');
     urls.length = 0;
-    assert.fail(`${message}:\n${list}`);
+    // eslint-disable-next-line no-restricted-syntax -- interop boundary: Storybook's afterEach (preview.ts) only reports a check as a story failure when assert() throws
+    throw new Error(`${message}:\n${list}`);
 }
 //# sourceMappingURL=check.js.map

package/lib/checks/external-resource-check.js

@@ -13,9 +13,16 @@ function isExternalResourceUrl(url) {
     return ((protocol === 'http:' || protocol === 'https:') &&
         origin !== window.location.origin);
 }
+function isPerformanceResourceTiming(entry) {
+    return entry.entryType === 'resource';
+}
 new PerformanceObserver((list) => {
     for (const entry of list.getEntries()) {
-        if (entry.startTime >= resetAt && isExternalResourceUrl(entry.name)) {
+        if (!isPerformanceResourceTiming(entry))
+            continue;
+        // Entries are queued at completion, so responseEnd (not startTime) is
+        // what must be compared against resetAt.
+        if (entry.responseEnd >= resetAt && isExternalResourceUrl(entry.name)) {
             externalResourceUrls.push(entry.name);
         }
     }

package/lib/checks/overflow-check.js

@@ -83,6 +83,18 @@ function findOverflows(root, ignoreSelectors) {
     }
     return groupByAncestor(entries);
 }
+// `findOverflows` never sees canvasElement itself overflowing. Under
+// `layout: 'centered'`, canvasElement is a flex item that never shrinks
+// below its own content width, so the clip only shows up on
+// `document.documentElement`, above canvasElement.
+function findViewportOverflow() {
+    const overflowPx = document.documentElement.scrollWidth - window.innerWidth;
+    if (overflowPx <= 0)
+        return [];
+    return [
+        `document.documentElement.scrollWidth=${String(document.documentElement.scrollWidth)} is ${String(overflowPx)}px wider than window.innerWidth=${String(window.innerWidth)}. This usually means the story's own wrapper uses a fixed width (e.g. Tailwind's \`w-*\`) instead of a max-width (\`max-w-*\`).`,
+    ];
+}
 function overflowCheckParameters(storyParameters) {
     if (typeof storyParameters !== 'object' || storyParameters === null) {
         return undefined;
@@ -152,6 +164,7 @@ export const overflowCheck = {
             ...globalIgnoreSelectorsOf(params),
             ...ignoreSelectorsOf(params),
         ]), 'Story has element(s) overflowing their container (clipped and invisible)');
+        throwIfNotEmpty(findViewportOverflow(), 'Story overflows the viewport itself (not just an inner element)');
     },
 };
 //# sourceMappingURL=overflow-check.js.map

package/lib/vitest-plugin.d.ts

@@ -3,6 +3,7 @@ export declare const storycapNetworkIdle: {
     name: string;
     transform(code: string, id: string): string | null;
 };
+export declare const BLOCK_EXTERNAL_REQUESTS_ARGS: string[];
 export interface CreateStorybookProjectOptions {
     /** Project name, as shown by `vitest --project <name>`. */
     name: string;

package/lib/vitest-plugin.js

@@ -45,6 +45,12 @@ export const storycapNetworkIdle = {
         return patched;
     },
 };
+// Blocks all requests except to localhost (Vitest's dev server), so a story
+// can't depend on an external CDN request finishing before `afterEach`.
+// Doesn't affect Playwright's own CDP connection, which uses a local pipe, not DNS.
+export const BLOCK_EXTERNAL_REQUESTS_ARGS = [
+    '--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE localhost',
+];
 export function createStorybookProject({ name, rootDir, viewport, screenshotsSubdir, setupFiles, excludeTags = [], ciMaxWorkers = 8, }) {
     const configDir = path.join(rootDir, '.storybook');
     const screenshotsDir = path.join(rootDir, '__screenshots__', screenshotsSubdir);
@@ -116,6 +122,7 @@ export function createStorybookProject({ name, rootDir, viewport, screenshotsSub
                 // silently truncates every fullPage tile's clip rect below it.
                 provider: playwright({
                     contextOptions: { timezoneId: 'Asia/Tokyo', viewport },
+                    launchOptions: { args: [...BLOCK_EXTERNAL_REQUESTS_ARGS] },
                 }),
                 headless: true,
                 instances: [{ browser: 'chromium' }],

package/package.json

@@ -56,25 +56,25 @@
     "@eslint/eslintrc": "3.3.6",
     "@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",
+    "@storybook/addon-vitest": "10.5.10",
+    "@storybook/html-vite": "10.5.10",
     "@storycap-testrun/browser": "2.1.1",
     "@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",
+    "@vitest/browser-playwright": "4.1.11",
     "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",
+    "storybook": "10.5.10",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
-  "version": "0.1.7",
+  "version": "0.1.9",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",