@juxtapose/adapter-ladle 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magic Factory LLC
+
+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,17 @@
+# @juxtapose/adapter-ladle
+
+Ladle platform adapter for juxtapose visual testing.
+
+Part of [juxtapose](https://github.com/juxtapose-dev/juxtapose), visual
+regression testing for component workbenches.
+
+**You probably don't need to install this directly.** Use
+[`@juxtapose/cli`](https://www.npmjs.com/package/@juxtapose/cli) for the
+command line, or
+[`@juxtapose/storybook`](https://www.npmjs.com/package/@juxtapose/storybook)
+to review diffs inside Storybook. This package is a building block those
+depend on.
+
+Full documentation: https://github.com/juxtapose-dev/juxtapose
+
+MIT © Magic Factory LLC

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from 'playwright';
+import type { Platform, EnumerateTarget, SettleContext, StoryManifest } from '@juxtapose/core';
+export declare class LadlePlatform implements Platform {
+    readonly name = "ladle";
+    detect(target: EnumerateTarget): Promise<boolean>;
+    enumerate(target: EnumerateTarget): Promise<StoryManifest[]>;
+    storyUrl(baseUrl: string, storyId: string): string;
+    /** URL-addressable, so showing a story is just a navigation. */
+    showStory(page: Page, storyId: string, baseUrl: string): Promise<void>;
+    previewUrl(baseUrl: string): string;
+    settle(page: Page, ctx: SettleContext): Promise<void>;
+    /**
+     * Switch stories without a navigation via Ladle's exposed dispatch.
+     *
+     * `window.ladleDispatch` is set deliberately — Ladle's own public `linkTo()`
+     * API is built on it — so this is a supported path, not a private poke.
+     *
+     * The subtlety: `data-storyloaded` is a plain attribute toggle, so a naive
+     * wait after dispatching can match the *outgoing* story's attribute before
+     * React tears it down. Clear it ourselves first, then wait for it to come
+     * back, which makes the signal unambiguous.
+     */
+    switchStory(page: Page, storyId: string, ctx: SettleContext): Promise<boolean>;
+    readonly configDirs: string[];
+    readonly storyFileGlobs: string[];
+}

package/dist/index.js

@@ -0,0 +1,127 @@
+// Ladle platform adapter.
+//
+// Written second, against the interface the Storybook adapter shaped. It needed
+// no changes to `Platform` — which is the evidence the seam is real rather than
+// a Storybook API wearing a trenchcoat.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { navigateToStory } from '@juxtapose/core';
+/** Where a story declares juxtapose config. Ladle's `meta` is an open index
+ *  signature, so a namespaced key passes through untouched. */
+const META_NAMESPACE = 'juxtapose';
+export class LadlePlatform {
+    name = 'ladle';
+    async detect(target) {
+        return (await loadMeta(target)) !== null;
+    }
+    async enumerate(target) {
+        const meta = await loadMeta(target);
+        if (!meta) {
+            throw new Error(`[ladle] no meta.json at ${target.origin ?? target.buildDir}. ` +
+                `Run \`ladle build\`, or point --origin at a running dev server.`);
+        }
+        return Object.entries(meta.stories)
+            .map(([id, story]) => ({
+            storyId: id,
+            title: story.levels.join('/'),
+            name: story.name,
+            // Empty when absent rather than fabricated — affected-story analysis
+            // treats a blank path as "can't prove unaffected" and captures it.
+            componentPath: story.filePath
+                ? path.resolve(target.projectRoot, story.filePath)
+                : '',
+            params: readParams(story.meta),
+        }))
+            .sort((a, b) => a.storyId.localeCompare(b.storyId));
+    }
+    storyUrl(baseUrl, storyId) {
+        // No iframe route; `mode=preview` is what strips the sidebar and addon
+        // chrome, leaving only the story.
+        return `${stripSlash(baseUrl)}/?story=${encodeURIComponent(storyId)}&mode=preview`;
+    }
+    /** URL-addressable, so showing a story is just a navigation. */
+    async showStory(page, storyId, baseUrl) {
+        await navigateToStory((b, s) => this.storyUrl(b, s))(page, storyId, baseUrl);
+    }
+    previewUrl(baseUrl) {
+        return `${stripSlash(baseUrl)}/?mode=preview`;
+    }
+    async settle(page, ctx) {
+        await waitForStoryLoaded(page, ctx.timeoutMs);
+    }
+    /**
+     * Switch stories without a navigation via Ladle's exposed dispatch.
+     *
+     * `window.ladleDispatch` is set deliberately — Ladle's own public `linkTo()`
+     * API is built on it — so this is a supported path, not a private poke.
+     *
+     * The subtlety: `data-storyloaded` is a plain attribute toggle, so a naive
+     * wait after dispatching can match the *outgoing* story's attribute before
+     * React tears it down. Clear it ourselves first, then wait for it to come
+     * back, which makes the signal unambiguous.
+     */
+    async switchStory(page, storyId, ctx) {
+        const dispatched = await page
+            .evaluate((id) => {
+            const w = window;
+            if (typeof w.ladleDispatch !== 'function')
+                return false;
+            document.documentElement.removeAttribute('data-storyloaded');
+            w.ladleDispatch({ type: 'update-story', value: id });
+            return true;
+        }, storyId)
+            .catch(() => false);
+        if (!dispatched)
+            return false;
+        await waitForStoryLoaded(page, ctx.timeoutMs);
+        return true;
+    }
+    configDirs = ['.ladle'];
+    storyFileGlobs = ['**/*.stories.@(ts|tsx|js|jsx|mdx)'];
+}
+/**
+ * Ladle's authoritative render signal: `data-storyloaded` on <html>.
+ *
+ * Set by a component rendered inside Suspense after the story commits, and
+ * removed by the loading spinner on mount — so its presence means the story
+ * chunk loaded and React committed, not merely that the page fired `load`.
+ * This is what Ladle's own screenshot suite waits on.
+ */
+async function waitForStoryLoaded(page, timeoutMs) {
+    await page
+        .waitForSelector('[data-storyloaded]', { timeout: timeoutMs })
+        // Timing out is not fatal: capture what rendered. A slow story should
+        // surface as a reviewable diff, not abort the run.
+        .catch(() => { });
+}
+function readParams(meta) {
+    const ns = meta?.[META_NAMESPACE];
+    return ns && typeof ns === 'object' ? ns : {};
+}
+async function loadMeta(target) {
+    if (target.origin) {
+        try {
+            const res = await fetch(new URL('meta.json', withSlash(target.origin)));
+            if (!res.ok)
+                return null;
+            const parsed = (await res.json());
+            return parsed?.stories ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!target.buildDir)
+        return null;
+    try {
+        const raw = await readFile(path.join(target.buildDir, 'meta.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed?.stories ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const withSlash = (u) => (u.endsWith('/') ? u : u + '/');
+const stripSlash = (u) => u.replace(/\/+$/, '');
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@juxtapose/adapter-ladle",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Ladle platform adapter for juxtapose visual testing.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@juxtapose/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.48.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juxtapose-dev/juxtapose.git",
+    "directory": "packages/adapter-ladle"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}