@qoretechnologies/qlip 0.1.0-beta.20260128131929

package/README.md

@@ -0,0 +1,131 @@
+# Qlip
+
+Qlip is a Storybook screenshot capture tool that plugs into the Storybook Vitest addon. Add one Vitest plugin and every story automatically gets a screenshot after the test finishes. Use `screenshot()` inside a play function to capture intermediate states.
+
+## Install
+
+```bash
+npm install --save-dev @qoretechnologies/qlip
+```
+
+## Vitest setup
+
+```ts
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
+import { playwright } from '@vitest/browser-playwright';
+import { qlipVitestPlugin } from '@qoretechnologies/qlip';
+
+const dirname =
+  typeof __dirname !== 'undefined'
+    ? __dirname
+    : path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        extends: true,
+        plugins: [
+          storybookTest({
+            configDir: path.join(dirname, '.storybook'),
+          }),
+          qlipVitestPlugin(),
+        ],
+        test: {
+          name: 'storybook',
+          browser: {
+            enabled: true,
+            headless: true,
+            provider: playwright({}),
+            instances: [{ browser: 'chromium' }],
+          },
+          setupFiles: ['.storybook/vitest.setup.ts'],
+        },
+      },
+    ],
+  },
+});
+```
+
+## Manual screenshots inside play
+
+Use the existing **"Logged In"** story as a real-world example:
+
+```ts
+import { screenshot } from '@qoretechnologies/qlip';
+
+export const LoggedIn = {
+  play: async (ctx) => {
+    // interactions and assertions...
+    await screenshot(ctx, 'after-login');
+  },
+};
+```
+
+## Parameters
+
+Configure screenshots per story via `parameters.qlip`:
+
+```ts
+export const LoggedIn = {
+  parameters: {
+    qlip: {
+      skip: false,
+      viewport: { width: 1280, height: 720 },
+      disableAnimations: true,
+      pauseAnimationsAtEnd: false,
+      captureOnError: false,
+      waitForIdleMs: 300,
+      maxWaitForIdleMs: 2000,
+      ignoreElements: ['.toast', '[data-qlip-ignore]'],
+    },
+  },
+};
+```
+
+Options precedence:
+
+1. Explicit options passed to `screenshot()`
+2. `parameters.qlip`
+3. Plugin defaults
+
+## Plugin options
+
+```ts
+qlipVitestPlugin({
+  outputDir: './qlip/screenshots',
+  viewport: { width: 1280, height: 720 },
+  disableAnimations: false,
+  pauseAnimationsAtEnd: false,
+  captureOnError: false,
+  waitForIdleMs: 300,
+  maxWaitForIdleMs: 2000,
+  ignoreElements: [],
+});
+```
+
+`waitForIdleMs` waits for DOM mutations to settle before taking a screenshot. This is especially useful for animation libraries like `react-spring` that update inline styles via `requestAnimationFrame`, which bypasses CSS-based animation disabling. Increase it if you still catch mid-transition frames, or lower it for faster runs when your UI is static. `maxWaitForIdleMs` caps the wait so stories with continuously changing UI still complete.
+
+`ignoreElements` lets you provide CSS selectors to mask before capture. Qlip draws solid overlays on matching elements so layout stays intact while visual diffs ignore those regions.
+
+## Output layout
+
+```
+./qlip/screenshots/
+  <buildId>/
+    stories/
+      auto/<storyTitle>--<storyName>.png
+      manual/<storyTitle>--<storyName>--<screenshotName>.png
+      error/<storyTitle>--<storyName>--qlip-auto-error-capture.png
+    manifest.json
+```
+
+- `buildId` defaults to `YYYYMMDD-HHmmss`
+- `parameters.qlip.skip === true` disables all captures for that story
+
+## Manifest
+
+Each run writes `manifest.json` inside the build folder with tool metadata, defaults, stats, and per-screenshot entries (auto + manual).

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+export { screenshot } from './runtime/screenshot.js';
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/browser.js

@@ -0,0 +1 @@
+export { screenshot } from './runtime/screenshot.js';

package/dist/config/parameters.d.ts

@@ -0,0 +1,22 @@
+import { QlipParameters, QlipResolvedDefaults, QlipScreenshotOptions } from '../types.js';
+export interface QlipResolvedOptions {
+    skip: boolean;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    disableAnimations: boolean;
+    pauseAnimationsAtEnd: boolean;
+    waitForIdleMs: number;
+    maxWaitForIdleMs: number;
+    ignoreElements: string[];
+    auto: boolean;
+    manual: boolean;
+    error: boolean;
+}
+export declare const resolveQlipOptions: ({ defaults, story, override, }: {
+    defaults: QlipResolvedDefaults;
+    story?: QlipParameters;
+    override?: QlipScreenshotOptions;
+}) => QlipResolvedOptions;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/config/parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../src/config/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,GAAI,gCAIhC;IACD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,KAAG,mBA4BH,CAAC"}

package/dist/config/parameters.js

@@ -0,0 +1,24 @@
+export const resolveQlipOptions = ({ defaults, story, override, }) => {
+    return {
+        skip: override?.skip ?? story?.skip ?? defaults.skip,
+        viewport: override?.viewport ?? story?.viewport ?? defaults.viewport,
+        disableAnimations: override?.disableAnimations ??
+            story?.disableAnimations ??
+            defaults.disableAnimations,
+        pauseAnimationsAtEnd: override?.pauseAnimationsAtEnd ??
+            story?.pauseAnimationsAtEnd ??
+            defaults.pauseAnimationsAtEnd,
+        waitForIdleMs: override?.waitForIdleMs ??
+            story?.waitForIdleMs ??
+            defaults.waitForIdleMs,
+        maxWaitForIdleMs: override?.maxWaitForIdleMs ??
+            story?.maxWaitForIdleMs ??
+            defaults.maxWaitForIdleMs,
+        ignoreElements: override?.ignoreElements ??
+            story?.ignoreElements ??
+            defaults.ignoreElements,
+        auto: override?.auto ?? story?.auto ?? defaults.auto,
+        manual: override?.manual ?? story?.manual ?? defaults.manual,
+        error: override?.error ?? story?.error ?? defaults.error,
+    };
+};

package/dist/fs/output.d.ts

@@ -0,0 +1,42 @@
+import { QlipManifest, QlipResolvedDefaults } from '../types.js';
+export declare const TOOL_NAME = "qlip";
+export declare const DEFAULT_OUTPUT_DIR = "./qlip/screenshots";
+export declare const AUTO_ERROR_SCREENSHOT_BASE = "qlip-auto-error-capture";
+export declare const DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+};
+export declare const generateBuildId: (date?: Date) => string;
+export declare const sanitizeSegment: (value: string) => string;
+export declare const joinPath: (...parts: string[]) => string;
+export declare const buildAutoScreenshotPath: ({ buildDir, storyId, storyTitle, storyName, }: {
+    buildDir: string;
+    storyId: string;
+    storyTitle?: string;
+    storyName?: string;
+}) => {
+    relativePath: string;
+    absolutePath: string;
+};
+export declare const buildManualScreenshotPath: ({ buildDir, storyId, storyTitle, storyName, screenshotName, }: {
+    buildDir: string;
+    storyId: string;
+    storyTitle?: string;
+    storyName?: string;
+    screenshotName: string;
+}) => {
+    safeName: string;
+    relativePath: string;
+    absolutePath: string;
+};
+export declare const createManifest: ({ buildId, outputDir, defaults, tool, createdAt, }: {
+    buildId: string;
+    outputDir: string;
+    defaults: QlipResolvedDefaults;
+    tool: {
+        name: string;
+        version: string;
+    };
+    createdAt?: Date;
+}) => QlipManifest;
+//# sourceMappingURL=output.d.ts.map

package/dist/fs/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/fs/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjE,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,gBAAgB;;;CAA+B,CAAC;AAE7D,eAAO,MAAM,eAAe,GAAI,OAAM,IAAiB,KAAG,MASzD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MACD,CAAC;AAEhD,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAgB7C,CAAC;AA+BF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;CAOA,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,+DAMvC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;;;;CAYA,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,oDAM5B;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,KAAG,YAeF,CAAC"}

package/dist/fs/output.js

@@ -0,0 +1,83 @@
+export const TOOL_NAME = 'qlip';
+export const DEFAULT_OUTPUT_DIR = './qlip/screenshots';
+export const AUTO_ERROR_SCREENSHOT_BASE = 'qlip-auto-error-capture';
+export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+export const generateBuildId = (date = new Date()) => {
+    const pad = (num) => String(num).padStart(2, '0');
+    const year = date.getFullYear();
+    const month = pad(date.getMonth() + 1);
+    const day = pad(date.getDate());
+    const hours = pad(date.getHours());
+    const minutes = pad(date.getMinutes());
+    const seconds = pad(date.getSeconds());
+    return `${year}${month}${day}-${hours}${minutes}${seconds}`;
+};
+export const sanitizeSegment = (value) => value.trim().replace(/[^a-zA-Z0-9_.-]/g, '_');
+export const joinPath = (...parts) => {
+    const normalized = parts
+        .filter((part) => part.length > 0)
+        .map((part) => part.replace(/\\/g, '/'));
+    if (normalized.length === 0) {
+        return '';
+    }
+    let result = normalized[0];
+    for (let index = 1; index < normalized.length; index += 1) {
+        const part = normalized[index].replace(/^\/+/, '');
+        result = result.replace(/\/+$/, '');
+        result = `${result}/${part}`;
+    }
+    return result;
+};
+const splitStoryId = (storyId) => {
+    const [titlePart, namePart] = storyId.split('--');
+    return {
+        titlePart: titlePart || storyId,
+        namePart: namePart || undefined,
+    };
+};
+const buildStoryBaseName = ({ storyTitle, storyName, storyId, }) => {
+    const { titlePart, namePart } = splitStoryId(storyId);
+    const resolvedTitle = storyTitle ?? titlePart;
+    const resolvedName = storyName && storyName !== 'storyFn' ? storyName : namePart ?? storyId;
+    const safeTitle = sanitizeSegment(resolvedTitle);
+    const safeName = sanitizeSegment(resolvedName);
+    return `${safeTitle}--${safeName}`;
+};
+const buildKindDir = (kind) => joinPath('stories', kind);
+export const buildAutoScreenshotPath = ({ buildDir, storyId, storyTitle, storyName, }) => {
+    const baseName = buildStoryBaseName({ storyTitle, storyName, storyId });
+    const relativePath = `${buildKindDir('auto')}/${baseName}.png`;
+    return {
+        relativePath,
+        absolutePath: joinPath(buildDir, relativePath),
+    };
+};
+export const buildManualScreenshotPath = ({ buildDir, storyId, storyTitle, storyName, screenshotName, }) => {
+    const baseName = buildStoryBaseName({ storyTitle, storyName, storyId });
+    const safeName = sanitizeSegment(screenshotName);
+    const kind = safeName.startsWith(AUTO_ERROR_SCREENSHOT_BASE)
+        ? 'error'
+        : 'manual';
+    const relativePath = `${buildKindDir(kind)}/${baseName}--${safeName}.png`;
+    return {
+        safeName,
+        relativePath,
+        absolutePath: joinPath(buildDir, relativePath),
+    };
+};
+export const createManifest = ({ buildId, outputDir, defaults, tool, createdAt = new Date(), }) => ({
+    tool,
+    buildId,
+    createdAt: createdAt.toISOString(),
+    outputDir,
+    defaults,
+    stats: {
+        storiesTotal: 0,
+        capturedAuto: 0,
+        capturedManual: 0,
+        skipped: 0,
+        failed: 0,
+        durationMs: 0,
+    },
+    entries: [],
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { qlipVitestPlugin } from './plugin/vitestPlugin.js';
+export { screenshot } from './runtime/screenshot.js';
+export type { QlipManifest, QlipManifestEntry, QlipParameters, QlipPluginOptions, QlipResolvedDefaults, QlipScreenshotOptions, QlipViewport, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { qlipVitestPlugin } from './plugin/vitestPlugin.js';
+export { screenshot } from './runtime/screenshot.js';

package/dist/plugin/vitestPlugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vitest/config';
+import { QlipPluginOptions } from '../types.js';
+export declare const qlipVitestPlugin: (options?: QlipPluginOptions) => Plugin;
+//# sourceMappingURL=vitestPlugin.d.ts.map

package/dist/plugin/vitestPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitestPlugin.d.ts","sourceRoot":"","sources":["../../src/plugin/vitestPlugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAQ5C,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAInE,eAAO,MAAM,gBAAgB,GAC3B,UAAS,iBAAsB,KAC9B,MAsEF,CAAC"}

package/dist/plugin/vitestPlugin.js

@@ -0,0 +1,71 @@
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pkg from '../../package.json' with { type: 'json' };
+import { DEFAULT_OUTPUT_DIR, DEFAULT_VIEWPORT, TOOL_NAME, generateBuildId, } from '../fs/output.js';
+const normalizePath = (value) => value.replace(/\\/g, '/');
+export const qlipVitestPlugin = (options = {}) => {
+    const buildId = options.buildId ?? generateBuildId();
+    let runtimeConfig = null;
+    return {
+        name: 'qlip-vitest-plugin',
+        enforce: 'pre',
+        config: (config) => {
+            const root = config.root ?? process.cwd();
+            const outputDir = options.outputDir ?? DEFAULT_OUTPUT_DIR;
+            const resolvedOutputDir = normalizePath(path.resolve(root, outputDir));
+            const buildDir = normalizePath(path.join(resolvedOutputDir, buildId));
+            const version = pkg.version ?? '0.0.0';
+            runtimeConfig = {
+                buildId,
+                outputDir: resolvedOutputDir,
+                buildDir,
+                defaults: {
+                    outputDir,
+                    viewport: options.viewport ?? DEFAULT_VIEWPORT,
+                    skip: false,
+                    disableAnimations: options.disableAnimations ?? false,
+                    pauseAnimationsAtEnd: options.pauseAnimationsAtEnd ?? false,
+                    captureOnError: options.captureOnError ?? false,
+                    waitForIdleMs: options.waitForIdleMs ?? 300,
+                    maxWaitForIdleMs: options.maxWaitForIdleMs ?? 2000,
+                    ignoreElements: options.ignoreElements ?? [],
+                    auto: options.auto ?? true,
+                    manual: options.manual ?? true,
+                    error: options.error ?? true,
+                },
+                tool: { name: TOOL_NAME, version },
+            };
+            const setupTs = fileURLToPath(new URL('../runtime/setup.ts', import.meta.url));
+            const setupJs = fileURLToPath(new URL('../runtime/setup.js', import.meta.url));
+            const setupFile = existsSync(setupTs) ? setupTs : setupJs;
+            const existingSetupFiles = config.test?.setupFiles;
+            const setupFiles = new Set();
+            if (typeof existingSetupFiles === 'string') {
+                setupFiles.add(existingSetupFiles);
+            }
+            else if (Array.isArray(existingSetupFiles)) {
+                existingSetupFiles.forEach((file) => setupFiles.add(file));
+            }
+            setupFiles.add(setupFile);
+            return {
+                define: {
+                    __QLIP_CONFIG__: JSON.stringify(runtimeConfig),
+                },
+                test: {
+                    setupFiles: Array.from(setupFiles),
+                },
+            };
+        },
+        async configResolved() {
+            if (!runtimeConfig) {
+                return;
+            }
+            await fs.mkdir(runtimeConfig.buildDir, { recursive: true });
+            await fs.mkdir(path.join(runtimeConfig.buildDir, 'stories'), {
+                recursive: true,
+            });
+        },
+    };
+};

package/dist/runtime/context.d.ts

@@ -0,0 +1,15 @@
+import { QlipManifest, QlipManifestEntry, QlipRuntimeConfig } from '../types.js';
+export interface QlipRuntimeState {
+    config: QlipRuntimeConfig;
+    manifest: QlipManifest;
+    counters: Map<string, number>;
+    startedAt: number;
+    warnedMissingStorybook: boolean;
+}
+export declare const getRuntimeState: () => QlipRuntimeState | null;
+export declare const initRuntimeState: () => QlipRuntimeState | null;
+export declare const nextStepName: (state: QlipRuntimeState, storyId: string) => string;
+export declare const pushEntry: (state: QlipRuntimeState, entry: QlipManifestEntry) => void;
+export declare const updateStats: (state: QlipRuntimeState, updates: Partial<QlipManifest["stats"]>) => void;
+export declare const markStorybookWarning: (state: QlipRuntimeState) => void;
+//# sourceMappingURL=context.d.ts.map

package/dist/runtime/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAyBD,eAAO,MAAM,eAAe,QAAO,gBAAgB,GAAG,IAKrD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,gBAAgB,GAAG,IA+BtD,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,OAAO,gBAAgB,EACvB,SAAS,MAAM,KACd,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,OAAO,gBAAgB,EACvB,OAAO,iBAAiB,SAGzB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,gBAAgB,EAAE,SAAS,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,SAM3F,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,SAE3D,CAAC"}

package/dist/runtime/context.js

@@ -0,0 +1,70 @@
+import { createManifest } from '../fs/output.js';
+const GLOBAL_KEY = '__QLIP_RUNTIME__';
+const readConfig = () => {
+    const globalValue = globalThis
+        .__QLIP_CONFIG__;
+    if (globalValue) {
+        return globalValue;
+    }
+    if (typeof __QLIP_CONFIG__ === 'undefined') {
+        return undefined;
+    }
+    if (typeof __QLIP_CONFIG__ === 'string') {
+        try {
+            return JSON.parse(__QLIP_CONFIG__);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return __QLIP_CONFIG__;
+};
+export const getRuntimeState = () => {
+    const globalState = globalThis;
+    return globalState[GLOBAL_KEY] ?? null;
+};
+export const initRuntimeState = () => {
+    const existing = getRuntimeState();
+    if (existing) {
+        return existing;
+    }
+    const runtimeConfig = readConfig();
+    if (!runtimeConfig) {
+        return null;
+    }
+    const manifest = createManifest({
+        buildId: runtimeConfig.buildId,
+        outputDir: runtimeConfig.buildDir,
+        defaults: runtimeConfig.defaults,
+        tool: runtimeConfig.tool,
+    });
+    const runtime = {
+        config: runtimeConfig,
+        manifest,
+        counters: new Map(),
+        startedAt: Date.now(),
+        warnedMissingStorybook: false,
+    };
+    const globalState = globalThis;
+    globalState[GLOBAL_KEY] = runtime;
+    return runtime;
+};
+export const nextStepName = (state, storyId) => {
+    const current = state.counters.get(storyId) ?? 0;
+    const next = current + 1;
+    state.counters.set(storyId, next);
+    return `step-${next}`;
+};
+export const pushEntry = (state, entry) => {
+    state.manifest.entries.push(entry);
+};
+export const updateStats = (state, updates) => {
+    state.manifest.stats = {
+        ...state.manifest.stats,
+        ...updates,
+    };
+    state.manifest.stats.durationMs = Date.now() - state.startedAt;
+};
+export const markStorybookWarning = (state) => {
+    state.warnedMissingStorybook = true;
+};

package/dist/runtime/screenshot.d.ts

@@ -0,0 +1,10 @@
+import { QlipScreenshotOptions, QlipStoryContext } from '../types.js';
+import type { TestContext } from 'vitest';
+export declare const screenshot: (ctx: QlipStoryContext, nameOrOptions?: string | QlipScreenshotOptions, options?: QlipScreenshotOptions) => Promise<void>;
+type QlipTestContext = TestContext & {
+    story?: QlipStoryContext;
+};
+export declare const captureAutoScreenshot: (ctx: QlipTestContext) => Promise<void>;
+export declare const captureErrorScreenshot: (ctx: QlipTestContext) => Promise<void>;
+export {};
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/runtime/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/runtime/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AAgBrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAyc1C,eAAO,MAAM,UAAU,GACrB,KAAK,gBAAgB,EACrB,gBAAgB,MAAM,GAAG,qBAAqB,EAC9C,UAAU,qBAAqB,kBA0BhC,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAElE,eAAO,MAAM,qBAAqB,GAAU,KAAK,eAAe,kBAoC/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,KAAK,eAAe,kBA2ChE,CAAC"}