@crvy/strybk 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crvy Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# strybk
+
+Generator-first Playwright screenshot testing for Storybook.
+
+## Development
+
+Install dependencies with Bun:
+
+```sh
+bun install
+```
+
+Common local commands:
+
+```sh
+bun run lint
+bun run typecheck
+bun run test:bun
+bun run build
+bun run check
+```
+
+## CLI
+
+Generate screenshot specs from a Storybook index:
+
+```sh
+strybk generate --config ./strybk.config.ts
+```
+
+Use `--dry-run` to compute outputs without writing files:
+
+```sh
+strybk generate --config ./strybk.config.ts --dry-run
+```
+
+The config module should export a `StrybkConfig` object, typically as the default export from `defineConfig(...)`.
+
+## Changelog
+
+Preview the next changelog entry:
+
+```sh
+bun run changelog:preview
+```
+
+Regenerate the full changelog from git history:
+
+```sh
+bun run changelog:generate
+```
+
+## Local Linking
+
+Build the package:
+
+```sh
+bun run build
+```
+
+Register this package for local linking:
+
+```sh
+cd /path/to/strybk
+bun link
+```
+
+Link it into the consumer project:
+
+```sh
+cd /path/to/consumer-project
+bun link strybk
+```
+
+If you want to persist the link in the consumer's manifest, Bun supports a `link:` dependency entry:
+
+```json
+{
+  "dependencies": {
+    "strybk": "link:strybk"
+  }
+}
+```

package/dist/src/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export interface GenerateCliArgs {
+    command: "generate";
+    configPath: string;
+    dryRun: boolean;
+}
+export declare function parseCliArgs(argv: string[]): GenerateCliArgs;
+export declare function runCli(argv: string[]): Promise<Array<{
+    outputPath: string;
+    content: string;
+}>>;
+export declare function main(argv?: string[]): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { generateScreenshots } from "./generate/index.js";
+const isRecord = (value) => typeof value === "object" && value !== null;
+const asUnknown = (value) => value;
+const toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const readExistingFile = (filePath) => {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+};
+const resolveConfigExport = (moduleNamespace) => {
+    if (!isRecord(moduleNamespace)) {
+        return moduleNamespace;
+    }
+    if ("default" in moduleNamespace) {
+        return moduleNamespace.default;
+    }
+    if ("config" in moduleNamespace) {
+        return moduleNamespace.config;
+    }
+    return moduleNamespace;
+};
+const isStrybkConfig = (value) => isRecord(value) &&
+    typeof value.storybookUrl === "string" &&
+    Array.isArray(value.storyGlobs) &&
+    typeof value.resolveSpecPath === "function" &&
+    typeof value.resolveHarnessImports === "function";
+const getIndexEntriesRecord = (payload) => {
+    if (!isRecord(payload)) {
+        throw new Error("Storybook index response must be an object");
+    }
+    const indexPayload = payload;
+    const entries = indexPayload.entries ?? indexPayload.stories;
+    if (!isRecord(entries)) {
+        throw new Error("Storybook index response must include an entries object");
+    }
+    return entries;
+};
+const toStoryIndexEntry = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if ("type" in value && value.type !== undefined && value.type !== "story") {
+        return null;
+    }
+    if (typeof value.id !== "string" ||
+        typeof value.title !== "string" ||
+        typeof value.name !== "string") {
+        return null;
+    }
+    return {
+        id: value.id,
+        title: value.title,
+        name: value.name,
+        importPath: typeof value.importPath === "string" ? value.importPath : undefined,
+        exportName: typeof value.exportName === "string" ? value.exportName : undefined,
+    };
+};
+const resolveStorybookIndexUrl = (storybookUrl) => new URL("./index.json", storybookUrl.endsWith("/") ? storybookUrl : `${storybookUrl}/`);
+const loadConfig = async (configPath) => {
+    const resolvedConfigPath = resolve(configPath);
+    const moduleNamespace = await import(pathToFileURL(resolvedConfigPath).href);
+    const config = resolveConfigExport(moduleNamespace);
+    if (!isStrybkConfig(config)) {
+        throw new Error(`Config module '${resolvedConfigPath}' must export a StrybkConfig object`);
+    }
+    return config;
+};
+const fetchStoryIndex = async (config) => {
+    const indexUrl = resolveStorybookIndexUrl(config.storybookUrl);
+    const response = await fetch(indexUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${indexUrl.toString()}: ${response.status} ${response.statusText}`.trim());
+    }
+    const payload = asUnknown(await response.json());
+    const entries = getIndexEntriesRecord(payload);
+    return Object.values(entries)
+        .map(toStoryIndexEntry)
+        .filter((entry) => entry !== null);
+};
+const writeGeneratedFiles = (outputs) => {
+    for (const output of outputs) {
+        mkdirSync(dirname(output.outputPath), { recursive: true });
+        writeFileSync(output.outputPath, output.content);
+    }
+};
+export function parseCliArgs(argv) {
+    const [command, ...options] = argv;
+    if (command !== "generate") {
+        throw new Error("Expected 'generate' command");
+    }
+    let configPath;
+    let dryRun = false;
+    for (let index = 0; index < options.length; index += 1) {
+        const option = options[index];
+        if (option === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (option === "--config") {
+            const nextOption = options[index + 1];
+            if (!nextOption || nextOption.startsWith("--")) {
+                throw new Error("Missing value for --config option");
+            }
+            configPath = nextOption;
+            index += 1;
+            continue;
+        }
+        if (option.startsWith("--config=")) {
+            configPath = option.slice("--config=".length);
+            if (configPath.length === 0) {
+                throw new Error("Missing value for --config option");
+            }
+            continue;
+        }
+        throw new Error(`Unknown option: ${option}`);
+    }
+    if (configPath === undefined) {
+        throw new Error("Missing required --config option");
+    }
+    return {
+        command: "generate",
+        configPath,
+        dryRun,
+    };
+}
+export async function runCli(argv) {
+    const cliArgs = parseCliArgs(argv);
+    const config = await loadConfig(cliArgs.configPath);
+    const indexEntries = await fetchStoryIndex(config);
+    const outputs = await generateScreenshots({
+        config,
+        indexEntries,
+        readExistingFile,
+    });
+    if (!cliArgs.dryRun) {
+        writeGeneratedFiles(outputs);
+    }
+    return outputs;
+}
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        const outputs = await runCli(argv);
+        const dryRun = argv.includes("--dry-run");
+        const suffix = dryRun ? " (dry run)" : "";
+        console.log(`Generated ${outputs.length} file(s)${suffix}.`);
+    }
+    catch (error) {
+        console.error(toErrorMessage(error));
+        process.exitCode = 1;
+    }
+}
+const maybeEntrypoint = process.argv[1];
+if (maybeEntrypoint !== undefined) {
+    try {
+        const currentFilePath = realpathSync(fileURLToPath(import.meta.url));
+        const invokedFilePath = realpathSync(resolve(maybeEntrypoint));
+        if (currentFilePath === invokedFilePath) {
+            void main();
+        }
+    }
+    catch {
+        // Ignore resolution failures during module import.
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,20 @@
+export interface StorybookGlobals {
+    [key: string]: string | number | boolean | null | undefined;
+}
+export interface StrybkConfig {
+    storybookUrl: string;
+    storyGlobs: string[];
+    resolveSpecPath: (args: {
+        storyFilePath: string;
+    }) => string;
+    resolveHarnessImports: (args: {
+        outputPath: string;
+    }) => {
+        fixturesImport: string;
+        switchStoryImport: string;
+    };
+    generatedRegionName?: string;
+    deleteOrphans?: boolean;
+    metadataExtractors?: "creevey"[];
+}
+export declare function defineConfig(config: StrybkConfig): StrybkConfig;

package/dist/src/config.js

@@ -0,0 +1,8 @@
+export function defineConfig(config) {
+    return {
+        generatedRegionName: "auto-screenshots",
+        deleteOrphans: true,
+        metadataExtractors: [],
+        ...config,
+    };
+}

package/dist/src/generate/discover.d.ts

@@ -0,0 +1,5 @@
+export interface StoryFile {
+    filePath: string;
+    title: string;
+}
+export declare function discoverStoryFiles(patterns: string[]): Promise<StoryFile[]>;

package/dist/src/generate/discover.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { glob } from "glob";
+export async function discoverStoryFiles(patterns) {
+    const files = await glob(patterns, { absolute: true });
+    return files.flatMap((filePath) => {
+        const content = readFileSync(filePath, "utf8");
+        const titleMatch = content.match(/title:\s*['"]([^'"]+)['"]/u);
+        if (!titleMatch) {
+            return [];
+        }
+        return [{ filePath, title: titleMatch[1] }];
+    });
+}

package/dist/src/generate/index.d.ts

@@ -0,0 +1,16 @@
+import type { StrybkConfig } from "../config.js";
+export interface StoryIndexEntry {
+    id: string;
+    title: string;
+    name: string;
+    importPath?: string;
+    exportName?: string;
+}
+export declare function generateScreenshots(args: {
+    config: StrybkConfig;
+    indexEntries: StoryIndexEntry[];
+    readExistingFile?: (filePath: string) => string | null;
+}): Promise<Array<{
+    outputPath: string;
+    content: string;
+}>>;

package/dist/src/generate/index.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { discoverStoryFiles } from "./discover.js";
+import { extractCreeveyMetadata, FILE_POLICY_KEY } from "./metadata.js";
+import { renderScreenshotSpec } from "./render.js";
+const escapeForRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const toStoryIdSegment = (value) => value
+    .replace(/([a-z0-9])([A-Z])/gu, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .toLowerCase();
+const isStorySkipped = (story, storyMetadata) => {
+    if (story.exportName !== undefined) {
+        return storyMetadata[story.exportName]?.skip === true;
+    }
+    const storyIdSegment = story.id.split("--").slice(1).join("--");
+    return Object.entries(storyMetadata).some(([exportName, policy]) => policy.skip === true && toStoryIdSegment(exportName) === storyIdSegment);
+};
+export async function generateScreenshots(args) {
+    const storyFiles = await discoverStoryFiles(args.config.storyGlobs);
+    const generatedRegionName = args.config.generatedRegionName ?? "auto-screenshots";
+    const manualRegionPattern = new RegExp(`// @generated-end ${escapeForRegExp(generatedRegionName)}\\s*([\\s\\S]*)$`, "u");
+    const shouldExtractCreeveyMetadata = args.config.metadataExtractors?.includes("creevey") ?? false;
+    return storyFiles.flatMap((storyFile) => {
+        const stories = args.indexEntries.filter((entry) => entry.title === storyFile.title);
+        const storyMetadata = shouldExtractCreeveyMetadata
+            ? extractCreeveyMetadata(readFileSync(storyFile.filePath, "utf8"))
+            : {};
+        const isFileSkipped = storyMetadata[FILE_POLICY_KEY]?.skip === true;
+        const filteredStories = isFileSkipped
+            ? []
+            : stories.filter((story) => !isStorySkipped(story, storyMetadata));
+        const outputPath = args.config.resolveSpecPath({ storyFilePath: storyFile.filePath });
+        const existing = args.readExistingFile?.(outputPath) ?? null;
+        const manualRegion = existing?.match(manualRegionPattern)?.[1]?.trim() ?? "";
+        if (filteredStories.length === 0 && manualRegion.length === 0) {
+            return [];
+        }
+        const harnessImports = args.config.resolveHarnessImports({ outputPath });
+        return [
+            {
+                outputPath,
+                content: renderScreenshotSpec({
+                    config: args.config,
+                    fixturesImport: harnessImports.fixturesImport,
+                    switchStoryImport: harnessImports.switchStoryImport,
+                    title: storyFile.title,
+                    stories: filteredStories,
+                    manualRegion,
+                }),
+            },
+        ];
+    });
+}

package/dist/src/generate/metadata.d.ts

@@ -0,0 +1,5 @@
+export interface StoryPolicy {
+    skip?: boolean;
+}
+export declare const FILE_POLICY_KEY = "__file__";
+export declare function extractCreeveyMetadata(source: string): Record<string, StoryPolicy>;

package/dist/src/generate/metadata.js

@@ -0,0 +1,124 @@
+export const FILE_POLICY_KEY = "__file__";
+const skipWhitespace = (source, startIndex) => {
+    let index = startIndex;
+    while (/\s/u.test(source[index] ?? "")) {
+        index += 1;
+    }
+    return index;
+};
+const extractObjectLiteral = (source, startIndex) => {
+    const objectStartIndex = skipWhitespace(source, startIndex);
+    if (source[objectStartIndex] !== "{") {
+        return null;
+    }
+    let depth = 0;
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let inTemplateString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let index = objectStartIndex; index < source.length; index += 1) {
+        const char = source[index] ?? "";
+        const nextChar = source[index + 1] ?? "";
+        const previousChar = source[index - 1] ?? "";
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (previousChar === "*" && char === "/") {
+                inBlockComment = false;
+            }
+            continue;
+        }
+        if (inSingleQuote) {
+            if (char === "'" && previousChar !== "\\") {
+                inSingleQuote = false;
+            }
+            continue;
+        }
+        if (inDoubleQuote) {
+            if (char === '"' && previousChar !== "\\") {
+                inDoubleQuote = false;
+            }
+            continue;
+        }
+        if (inTemplateString) {
+            if (char === "`" && previousChar !== "\\") {
+                inTemplateString = false;
+            }
+            continue;
+        }
+        if (char === "/" && nextChar === "/") {
+            inLineComment = true;
+            index += 1;
+            continue;
+        }
+        if (char === "/" && nextChar === "*") {
+            inBlockComment = true;
+            index += 1;
+            continue;
+        }
+        if (char === "'") {
+            inSingleQuote = true;
+            continue;
+        }
+        if (char === '"') {
+            inDoubleQuote = true;
+            continue;
+        }
+        if (char === "`") {
+            inTemplateString = true;
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return source.slice(objectStartIndex, index + 1);
+            }
+        }
+    }
+    return null;
+};
+const extractSkipPolicy = (source, scope) => {
+    if (source === null) {
+        return undefined;
+    }
+    const pattern = scope === "parameters"
+        ? /\bcreevey\s*:\s*\{[\s\S]*?\bskip\s*:\s*(true|false)\b/u
+        : /\bparameters\s*:\s*\{[\s\S]*?\bcreevey\s*:\s*\{[\s\S]*?\bskip\s*:\s*(true|false)\b/u;
+    const skipMatch = source.match(pattern);
+    return skipMatch ? { skip: skipMatch[1] === "true" } : undefined;
+};
+const collectPolicies = (source, pattern, scope) => Array.from(source.matchAll(pattern)).flatMap((match) => {
+    const index = match.index ?? 0;
+    const policy = extractSkipPolicy(extractObjectLiteral(source, index + match[0].length), scope);
+    return policy ? [[index, match[1], policy]] : [];
+});
+export function extractCreeveyMetadata(source) {
+    const storyPolicies = [
+        ...collectPolicies(source, /(\w+)\.parameters\s*=/gu, "parameters"),
+        ...collectPolicies(source, /export\s+const\s+(\w+)(?:\s*:\s*[^=]+)?\s*=/gu, "object"),
+    ];
+    const constPolicies = new Map(collectPolicies(source, /const\s+(\w+)(?:\s*:\s*[^=]+)?\s*=/gu, "object").map(([, name, policy]) => [name, policy]));
+    const filePolicies = [
+        ...Array.from(source.matchAll(/export\s+default\b/gu)).flatMap((match) => {
+            const index = match.index ?? 0;
+            const policy = extractSkipPolicy(extractObjectLiteral(source, index + match[0].length), "object");
+            return policy ? [[index, FILE_POLICY_KEY, policy]] : [];
+        }),
+        ...Array.from(source.matchAll(/export\s+default\s+(\w+)\s*;/gu)).flatMap((match) => {
+            const policy = constPolicies.get(match[1]);
+            return policy ? [[match.index ?? 0, FILE_POLICY_KEY, policy]] : [];
+        }),
+    ];
+    return Object.fromEntries([...storyPolicies, ...filePolicies]
+        .sort((left, right) => left[0] - right[0])
+        .map(([, name, policy]) => [name, policy]));
+}

package/dist/src/generate/render.d.ts

@@ -0,0 +1,13 @@
+import type { StrybkConfig } from "../config.js";
+export interface RenderableStory {
+    id: string;
+    name: string;
+}
+export declare function renderScreenshotSpec(args: {
+    config: StrybkConfig;
+    fixturesImport: string;
+    switchStoryImport: string;
+    title: string;
+    stories: RenderableStory[];
+    manualRegion: string;
+}): string;

package/dist/src/generate/render.js

@@ -0,0 +1,8 @@
+const escapeSingleQuotes = (value) => value.replace(/'/gu, "\\'");
+export function renderScreenshotSpec(args) {
+    const generatedRegionName = args.config.generatedRegionName ?? "auto-screenshots";
+    const tests = args.stories
+        .map((story) => `  test('${escapeSingleQuotes(story.name)}', async ({ sharedPage }) => {\n    await switchStory(sharedPage, '${story.id}');\n    await expect(sharedPage).toHaveScreenshot();\n  });`)
+        .join("\n\n");
+    return `import { test, expect } from '${args.fixturesImport}';\nimport { switchStory } from '${args.switchStoryImport}';\n\n// @generated-begin ${generatedRegionName}\ntest.describe('${escapeSingleQuotes(args.title)}', () => {\n${tests}\n});\n// @generated-end ${generatedRegionName}\n\n${args.manualRegion}`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { defineConfig } from "./config.js";
+export type { StrybkConfig, StorybookGlobals } from "./config.js";
+export { generateScreenshots } from "./generate/index.js";
+export { createStrybkFixtures, switchStory } from "./playwright/index.js";

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { defineConfig } from "./config.js";
+export { generateScreenshots } from "./generate/index.js";
+export { createStrybkFixtures, switchStory } from "./playwright/index.js";

package/dist/src/playwright/fixtures.d.ts

@@ -0,0 +1,11 @@
+import type { Page, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from "@playwright/test";
+type StrybkFixtures = {
+    sharedPage: Page;
+};
+type PublicStrybkTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions & StrybkFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+type StrybkFixtureHandles = {
+    expect: typeof import("@playwright/test").expect;
+    test: PublicStrybkTest;
+};
+export declare const createStrybkFixtures: () => StrybkFixtureHandles;
+export {};

package/dist/src/playwright/fixtures.js

@@ -0,0 +1,84 @@
+import { createChannelDriver } from "../storybook/channelDriver.js";
+import { loadPlaywrightTestRuntime } from "./runtime.js";
+const animationDisablerStyles = [
+    "*, *::before, *::after {",
+    "  animation: none !important;",
+    "  caret-color: transparent !important;",
+    "  cursor: none !important;",
+    "  transition: none !important;",
+    "}",
+    "html {",
+    "  scroll-behavior: auto !important;",
+    "}",
+].join("\n");
+const storybookReadyTimeoutMs = 10_000;
+const channelDriver = createChannelDriver();
+const isStorybookGlobalValue = (value) => value === null ||
+    value === undefined ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string";
+const getStorybookGlobals = (testInfo) => {
+    const metadata = testInfo.project.metadata;
+    const storybookGlobals = metadata?.storybookGlobals;
+    if (typeof storybookGlobals !== "object" ||
+        storybookGlobals === null ||
+        Array.isArray(storybookGlobals)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(storybookGlobals).filter(([, value]) => isStorybookGlobalValue(value)));
+};
+const resolveIframeUrl = (baseURL) => baseURL !== undefined && baseURL.length > 0
+    ? new URL("/iframe.html", baseURL).toString()
+    : "/iframe.html";
+const disableAnimations = async (page) => {
+    await page.addStyleTag({ content: animationDisablerStyles });
+};
+const resetSharedPage = async (page) => {
+    await page.mouse.move(0, 0);
+    await page.evaluate(() => {
+        window.scrollTo(0, 0);
+        document.documentElement.scrollTop = 0;
+        document.body.scrollTop = 0;
+    });
+};
+const restoreSharedPageBaseline = async (page, baseURL) => {
+    await page.goto(resolveIframeUrl(baseURL));
+    await page.waitForSelector("#storybook-root", {
+        state: "attached",
+        timeout: storybookReadyTimeoutMs,
+    });
+    await disableAnimations(page);
+    await resetSharedPage(page);
+};
+export const createStrybkFixtures = () => {
+    const { expect, test: base } = loadPlaywrightTestRuntime();
+    const test = base.extend({
+        _workerPage: [
+            async ({ browser }, use, workerInfo) => {
+                const context = await browser.newContext({
+                    baseURL: workerInfo.project.use.baseURL,
+                    viewport: workerInfo.project.use.viewport,
+                });
+                const page = await context.newPage();
+                await restoreSharedPageBaseline(page, workerInfo.project.use.baseURL);
+                await use(page);
+                await context.close();
+            },
+            { scope: "worker" },
+        ],
+        sharedPage: async ({ _workerPage }, use, testInfo) => {
+            const storybookGlobals = getStorybookGlobals(testInfo);
+            if (storybookGlobals !== undefined) {
+                await channelDriver.updateGlobals(_workerPage, storybookGlobals);
+            }
+            await resetSharedPage(_workerPage);
+            await use(_workerPage);
+            await restoreSharedPageBaseline(_workerPage, testInfo.project.use.baseURL);
+        },
+    });
+    return {
+        expect,
+        test: test,
+    };
+};

package/dist/src/playwright/index.d.ts

@@ -0,0 +1,2 @@
+export { createStrybkFixtures } from "./fixtures.js";
+export { switchStory } from "./switchStory.js";

package/dist/src/playwright/index.js

@@ -0,0 +1,2 @@
+export { createStrybkFixtures } from "./fixtures.js";
+export { switchStory } from "./switchStory.js";

package/dist/src/playwright/runtime.d.ts

@@ -0,0 +1 @@
+export declare const loadPlaywrightTestRuntime: () => typeof import("@playwright/test");

package/dist/src/playwright/runtime.js

@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+const isPlaywrightTestRuntime = (value) => {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+        return false;
+    }
+    return "expect" in value && "test" in value;
+};
+export const loadPlaywrightTestRuntime = () => {
+    const requireFromCwd = createRequire(resolve(process.cwd(), "package.json"));
+    const runtime = requireFromCwd("@playwright/test");
+    if (!isPlaywrightTestRuntime(runtime)) {
+        throw new Error("Failed to load @playwright/test runtime");
+    }
+    return runtime;
+};

package/dist/src/playwright/switchStory.d.ts

@@ -0,0 +1,2 @@
+import type { Page } from "@playwright/test";
+export declare function switchStory(page: Page, storyId: string): Promise<void>;

package/dist/src/playwright/switchStory.js

@@ -0,0 +1,5 @@
+import { createChannelDriver } from "../storybook/channelDriver.js";
+const defaultDriver = createChannelDriver();
+export async function switchStory(page, storyId) {
+    await defaultDriver.selectStory(page, storyId);
+}

package/dist/src/storybook/channelDriver.d.ts

@@ -0,0 +1,2 @@
+import type { StorybookDriver } from "./driver.js";
+export declare function createChannelDriver(): StorybookDriver;

package/dist/src/storybook/channelDriver.js

@@ -0,0 +1,73 @@
+export function createChannelDriver() {
+    return {
+        async selectStory(page, storyId) {
+            await page.evaluate(async (currentStoryId) => {
+                const storySwitchTimeoutMs = 10_000;
+                const channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+                if (!channel) {
+                    throw new Error("Storybook addons channel is unavailable");
+                }
+                await new Promise((resolve, reject) => {
+                    let settled = false;
+                    const cleanup = () => {
+                        channel.off("storyRendered", handleSuccess);
+                        channel.off("storyUnchanged", handleSuccess);
+                        channel.off("storyErrored", handleError);
+                    };
+                    const settle = (callback) => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        clearTimeout(timeout);
+                        cleanup();
+                        callback();
+                    };
+                    const handleSuccess = () => {
+                        cleanup();
+                        void (document.fonts?.ready ?? Promise.resolve())
+                            .then(() => {
+                            settle(() => {
+                                resolve();
+                            });
+                        })
+                            .catch((error) => {
+                            settle(() => {
+                                reject(error instanceof Error ? error : new Error(String(error)));
+                            });
+                        });
+                    };
+                    const handleError = (payload) => {
+                        const message = typeof payload === "object" &&
+                            payload !== null &&
+                            "description" in payload &&
+                            typeof payload.description === "string"
+                            ? payload.description
+                            : `Storybook failed to render story ${currentStoryId}`;
+                        settle(() => {
+                            reject(new Error(message));
+                        });
+                    };
+                    const timeout = setTimeout(() => {
+                        settle(() => {
+                            reject(new Error(`Failed to select story '${currentStoryId}': Story switch timeout`));
+                        });
+                    }, storySwitchTimeoutMs);
+                    channel.on("storyRendered", handleSuccess);
+                    channel.on("storyUnchanged", handleSuccess);
+                    channel.on("storyErrored", handleError);
+                    channel.emit("setCurrentStory", { storyId: currentStoryId });
+                });
+            }, storyId);
+        },
+        async updateGlobals(page, globals) {
+            await page.evaluate((nextGlobals) => {
+                const channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+                if (!channel) {
+                    throw new Error("Storybook addons channel is unavailable");
+                }
+                channel.emit("updateGlobals", { globals: nextGlobals });
+            }, globals);
+        },
+    };
+}

package/dist/src/storybook/driver.d.ts

@@ -0,0 +1,5 @@
+import type { Page } from "@playwright/test";
+export interface StorybookDriver {
+    selectStory(page: Page, storyId: string): Promise<void>;
+    updateGlobals(page: Page, globals: Record<string, unknown>): Promise<void>;
+}

package/dist/src/storybook/driver.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@crvy/strybk",
+  "version": "0.0.1",
+  "description": "Generator-first Playwright screenshot testing for Storybook.",
+  "keywords": [
+    "crvy",
+    "playwright",
+    "screenshot",
+    "storybook",
+    "testing",
+    "visual-regression"
+  ],
+  "homepage": "https://github.com/creevey/strybk",
+  "bugs": {
+    "url": "https://github.com/creevey/strybk/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/creevey/strybk.git"
+  },
+  "bin": {
+    "strybk": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./config": {
+      "types": "./dist/src/config.d.ts",
+      "default": "./dist/src/config.js"
+    },
+    "./playwright": {
+      "types": "./dist/src/playwright/index.d.ts",
+      "default": "./dist/src/playwright/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "oxlint --config .oxlintrc.json .",
+    "lint:fix": "oxlint --config .oxlintrc.json --fix .",
+    "format": "oxfmt --write . --ignore-path=.oxfmtignore",
+    "format:check": "oxfmt --check . --ignore-path=.oxfmtignore",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "knip": "knip-bun --strict",
+    "duplicates": "jscpd --config .jscpd.json",
+    "test": "bun run test:bun",
+    "test:bun": "for file in tests/*.test.ts; do bun test \"$file\" || exit $?; done",
+    "check": "bash ./scripts/check.sh",
+    "check:staged": "bash ./scripts/check.sh --staged",
+    "changelog:preview": "sh ./scripts/changelog-release.sh --preview",
+    "changelog:generate": "sh ./scripts/changelog-release.sh --generate",
+    "changelog:release": "sh ./scripts/changelog-release.sh",
+    "prepublishOnly": "bun run build && bunx publint",
+    "prepare": "[ -d .git ] && cp scripts/pre-commit.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit || true"
+  },
+  "dependencies": {
+    "glob": "^11.0.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "@types/bun": "^1.3.7",
+    "@types/node": "25.9.0",
+    "git-cliff": "2.13.1",
+    "jscpd": "^4.0.8",
+    "knip": "^6.3.0",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
+    "oxlint-tsgolint": "^0.22.1",
+    "publint": "^0.3.18",
+    "typescript": "5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.59.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=24"
+  },
+  "packageManager": "bun@1.3.13"
+}