@juxtapose/server 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/server
+
+Local review API for juxtapose — the contract every review UI is a skin over.
+
+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,4 @@
+export type { ReviewBundle, ReviewSource, RunProgress, ImageKind } from './types.js';
+export { createRouter, API_PREFIX, type Handler } from './router.js';
+export { RunDirSource, type SourceOptions } from './source.js';
+export { serve, type ServeHandle } from './serve.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createRouter, API_PREFIX } from './router.js';
+export { RunDirSource } from './source.js';
+export { serve } from './serve.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ReviewSource } from './types.js';
+/** Mounted under this prefix so it cannot collide with workbench routes. */
+export declare const API_PREFIX = "/jux/api";
+export interface Handler {
+    (req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+}
+/**
+ * Returns a handler that resolves true when it handled the request.
+ *
+ * The boolean matters for the middleware case: when mounted inside a dev
+ * server, anything not ours has to fall through to the next handler rather
+ * than 404.
+ */
+export declare function createRouter(source: ReviewSource): Handler;

package/dist/router.js

@@ -0,0 +1,122 @@
+// HTTP surface over a ReviewSource.
+//
+// Hand-rolled rather than pulling in a framework: there are ten routes, none
+// of them need middleware, and the addon has to mount this inside Storybook's
+// own Vite dev server where an extra HTTP stack would just be in the way.
+/** Mounted under this prefix so it cannot collide with workbench routes. */
+export const API_PREFIX = '/jux/api';
+const IMAGE_KINDS = new Set(['current', 'baseline', 'diff']);
+/**
+ * Returns a handler that resolves true when it handled the request.
+ *
+ * The boolean matters for the middleware case: when mounted inside a dev
+ * server, anything not ours has to fall through to the next handler rather
+ * than 404.
+ */
+export function createRouter(source) {
+    return async function handle(req, res) {
+        const url = req.url ?? '/';
+        if (!url.startsWith(API_PREFIX))
+            return false;
+        const path = url.slice(API_PREFIX.length).split('?')[0];
+        const method = req.method ?? 'GET';
+        try {
+            await route(source, method, path, req, res);
+        }
+        catch (err) {
+            // A failure here is a bug in the tool, not in the user's stories, so
+            // surface it rather than silently returning an empty report.
+            json(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    };
+}
+async function route(source, method, path, req, res) {
+    if (method === 'GET' && path === '/bundle') {
+        return json(res, 200, await source.bundle());
+    }
+    if (method === 'GET' && path === '/progress') {
+        return json(res, 200, await source.progress());
+    }
+    if (method === 'GET' && path === '/stories') {
+        return json(res, 200, { stories: await source.stories() });
+    }
+    // /image/{kind}/{storyId} — storyId may contain slashes on some platforms,
+    // so take everything after the kind rather than splitting into fixed parts.
+    const image = /^\/image\/([^/]+)\/(.+)$/.exec(path);
+    if (method === 'GET' && image) {
+        const kind = image[1];
+        if (!IMAGE_KINDS.has(kind))
+            return json(res, 400, { error: 'unknown image kind' });
+        const bytes = await source.image(kind, decodeURIComponent(image[2]));
+        if (!bytes)
+            return json(res, 404, { error: 'no such image' });
+        res.writeHead(200, {
+            'content-type': 'image/webp',
+            'content-length': bytes.length,
+            // Images are content-addressed by the ?v= the client appends, so they
+            // can be cached hard; without this the panel refetches every poll.
+            'cache-control': 'public, max-age=31536000, immutable',
+        });
+        res.end(bytes);
+        return;
+    }
+    const handoff = /^\/handoff\/(.+)$/.exec(path);
+    if (method === 'GET' && handoff) {
+        const prompt = await source.handoff(decodeURIComponent(handoff[1]));
+        if (prompt === null)
+            return json(res, 404, { error: 'no such story in the last run' });
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end(prompt);
+        return;
+    }
+    if (method === 'POST' && path === '/approve') {
+        const body = await readJson(req);
+        if (!body?.storyId)
+            return json(res, 400, { error: 'storyId required' });
+        await source.approve(body.storyId);
+        return json(res, 200, { ok: true });
+    }
+    if (method === 'POST' && path === '/run') {
+        const body = await readJson(req);
+        // Deliberately not awaited: a run takes seconds and the client polls
+        // /progress. Holding the request open would just time out.
+        void source.run(body?.storyIds).catch(() => { });
+        return json(res, 202, { started: true });
+    }
+    if (method === 'POST' && path === '/cancel') {
+        await source.cancel();
+        return json(res, 200, { ok: true });
+    }
+    json(res, 404, { error: `no route for ${method} ${path}` });
+}
+function json(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+        'cache-control': 'no-store',
+    });
+    res.end(payload);
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        // A review API has no business accepting large bodies; refuse rather
+        // than buffering whatever arrives.
+        if (size > 1_000_000)
+            return null;
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return null;
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,0EAA0E;AAK1E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAY,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAMxE;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,KAAK,UAAU,MAAM,CAAC,GAAG,EAAE,GAAG;QACnC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAE9C,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;QAEnC,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,6DAA6D;YAC7D,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,KAAK,CAClB,MAAoB,EACpB,MAAc,EACd,IAAY,EACZ,GAAoB,EACpB,GAAmB;IAEnB,IAAI,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,KAAK,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAc,CAAC;QACnC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAEnF,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;QAE9D,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;YACjB,cAAc,EAAE,YAAY;YAC5B,gBAAgB,EAAE,KAAK,CAAC,MAAM;YAC9B,sEAAsE;YACtE,mEAAmE;YACnE,eAAe,EAAE,qCAAqC;SACvD,CAAC,CAAC;QACH,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACf,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,KAAK,IAAI,OAAO,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,KAAK,IAAI;YACjB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,+BAA+B,EAAE,CAAC,CAAC;QACpE,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAC,CAAC;QACpE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAuB,GAAG,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,EAAE,OAAO;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACzE,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAA0B,GAAG,CAAC,CAAC;QAC1D,qEAAqE;QACrE,2DAA2D;QAC3D,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,gBAAgB,MAAM,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,iCAAiC;QACjD,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC;QAC5C,eAAe,EAAE,UAAU;KAC5B,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,QAAQ,CAAI,GAAoB;IAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QAC9B,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;QACrB,qEAAqE;QACrE,mCAAmC;QACnC,IAAI,IAAI,GAAG,SAAS;YAAE,OAAO,IAAI,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/serve.d.ts

@@ -0,0 +1,7 @@
+import type { ReviewSource } from './types.js';
+export interface ServeHandle {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function serve(source: ReviewSource, port?: number): Promise<ServeHandle>;

package/dist/serve.js

@@ -0,0 +1,27 @@
+// Standalone server, for `jux serve` and for tests.
+//
+// The addon mounts `createRouter` directly into Storybook's dev server
+// instead, which is why the router is separate from this.
+import { createServer } from 'node:http';
+import { createRouter } from './router.js';
+export async function serve(source, port = 0) {
+    const handler = createRouter(source);
+    const server = createServer((req, res) => {
+        void handler(req, res).then((handled) => {
+            if (handled)
+                return;
+            res.writeHead(404, { 'content-type': 'text/plain' });
+            res.end('not found');
+        });
+    });
+    await new Promise((ok) => server.listen(port, '127.0.0.1', ok));
+    const addr = server.address();
+    return {
+        url: `http://127.0.0.1:${addr.port}`,
+        port: addr.port,
+        close: () => new Promise((ok) => {
+            server.close(() => ok());
+        }),
+    };
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,0DAA0D;AAE1D,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,MAAoB,EAAE,IAAI,GAAG,CAAC;IACxD,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAErC,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/C,KAAK,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YACtC,IAAI,OAAO;gBAAE,OAAO;YACpB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,OAAO,CAAO,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAiB,CAAC;IAE7C,OAAO;QACL,GAAG,EAAE,oBAAoB,IAAI,CAAC,IAAI,EAAE;QACpC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,EAAE,EAAE,EAAE;YACvB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3B,CAAC,CAAC;KACL,CAAC;AACJ,CAAC"}

package/dist/source.d.ts

@@ -0,0 +1,50 @@
+import { type BaselineStore, type Platform, type ProjectConfig, type StoryManifest } from '@juxtapose/core';
+import type { ImageKind, ReviewBundle, ReviewSource, RunProgress } from './types.js';
+export interface SourceOptions {
+    projectRoot: string;
+    platform: Platform;
+    store: BaselineStore;
+    config: ProjectConfig;
+    /** Where the workbench is served. For the addon this is Storybook's own
+     *  dev server, which is why it can change between requests. */
+    baseUrl: string;
+    runDir: string;
+    branch: string;
+    commitSha: string;
+}
+export declare class RunDirSource implements ReviewSource {
+    private readonly opts;
+    private report;
+    private storyCache;
+    private browser;
+    private running;
+    private done;
+    private total;
+    private currentStory;
+    private abort;
+    /**
+     * Approvals are serialized through this chain.
+     *
+     * "Approve all" fires N parallel requests and each one is a read-modify-write
+     * of the same manifest file. Without a queue the last writer wins and every
+     * other approval is silently lost — which is exactly the kind of bug that
+     * erodes trust in the tool.
+     */
+    private approvalQueue;
+    constructor(opts: SourceOptions);
+    setBaseUrl(baseUrl: string): void;
+    bundle(): Promise<ReviewBundle>;
+    progress(): Promise<RunProgress>;
+    stories(): Promise<StoryManifest[]>;
+    /** Drop the cached story index — the workbench told us it changed. */
+    flushStories(): void;
+    image(kind: ImageKind, storyId: string): Promise<Buffer | null>;
+    handoff(storyId: string): Promise<string | null>;
+    approve(storyId: string): Promise<void>;
+    run(storyIds?: string[]): Promise<void>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+    private ensureBrowser;
+    private loadReport;
+    private readImage;
+}

package/dist/source.js

@@ -0,0 +1,228 @@
+// A ReviewSource backed by run artifacts on disk plus a live capture pool.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { buildHandoffPrompt, createAncestryCheck, alwaysAncestor, deterministicLaunchOptions, encodeStoryId, runCapture, DEFAULT_VIEWPORT, } from '@juxtapose/core';
+export class RunDirSource {
+    opts;
+    report = null;
+    storyCache = null;
+    browser = null;
+    running = false;
+    done = 0;
+    total = 0;
+    currentStory = null;
+    abort = null;
+    /**
+     * Approvals are serialized through this chain.
+     *
+     * "Approve all" fires N parallel requests and each one is a read-modify-write
+     * of the same manifest file. Without a queue the last writer wins and every
+     * other approval is silently lost — which is exactly the kind of bug that
+     * erodes trust in the tool.
+     */
+    approvalQueue = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    setBaseUrl(baseUrl) {
+        this.opts.baseUrl = baseUrl;
+    }
+    async bundle() {
+        const report = await this.loadReport();
+        const manifest = await this.opts.store.readManifest();
+        // A story counts as approved if its captured bytes now match the manifest.
+        // Deriving this rather than storing it means an approval made through the
+        // CLI shows up in the panel without any shared state between them.
+        const approved = [];
+        for (const result of report?.results ?? []) {
+            if (result.status === 'pass')
+                continue;
+            const entry = manifest.baselines[result.storyId];
+            if (!entry)
+                continue;
+            const current = await this.readImage('current', result.storyId);
+            if (current && hash(current) === entry.hash)
+                approved.push(result.storyId);
+        }
+        return { report, approved, running: this.running };
+    }
+    async progress() {
+        return {
+            running: this.running,
+            done: this.done,
+            total: this.total,
+            storyId: this.currentStory,
+        };
+    }
+    async stories() {
+        if (this.storyCache)
+            return this.storyCache;
+        this.storyCache = await this.opts.platform.enumerate({
+            projectRoot: this.opts.projectRoot,
+            origin: this.opts.baseUrl,
+        });
+        return this.storyCache;
+    }
+    /** Drop the cached story index — the workbench told us it changed. */
+    flushStories() {
+        this.storyCache = null;
+    }
+    async image(kind, storyId) {
+        if (kind === 'baseline')
+            return this.opts.store.get(storyId);
+        return this.readImage(kind, storyId);
+    }
+    async handoff(storyId) {
+        const report = await this.loadReport();
+        const result = report?.results.find((r) => r.storyId === storyId);
+        if (!result)
+            return null;
+        const story = (await this.stories()).find((s) => s.storyId === storyId);
+        const images = path.join(this.opts.runDir, 'images');
+        const safe = encodeStoryId(storyId);
+        return buildHandoffPrompt({
+            storyId,
+            storyTitle: story ? `${story.title} — ${story.name}` : storyId,
+            status: result.status,
+            mismatchPercent: result.mismatchPercent,
+            mismatchPixels: result.mismatchPixels,
+            changedRegions: result.changedRegions,
+            viewport: story?.params.viewport ?? this.opts.config.viewport ?? DEFAULT_VIEWPORT,
+            componentPath: story?.componentPath ?? '',
+            images: {
+                baseline: path.join(images, `${safe}-baseline.webp`),
+                current: path.join(images, `${safe}-current.webp`),
+                diff: result.status === 'fail' ? path.join(images, `${safe}-diff.webp`) : undefined,
+            },
+            projectRoot: this.opts.projectRoot,
+        });
+    }
+    async approve(storyId) {
+        const task = this.approvalQueue.then(async () => {
+            const image = await this.readImage('current', storyId);
+            if (!image)
+                throw new Error(`no capture for ${storyId} in the last run`);
+            await this.opts.store.put(storyId, image, {
+                commit: this.opts.commitSha,
+                approvedBy: process.env.JUXTAPOSE_USER ?? process.env.USER ?? 'unknown',
+                approvedAt: new Date().toISOString(),
+            });
+        });
+        // Keep the chain alive even if this link rejects, or one failed approval
+        // would wedge every subsequent one.
+        this.approvalQueue = task.catch(() => { });
+        await task;
+    }
+    async run(storyIds) {
+        if (this.running)
+            return;
+        const all = await this.stories();
+        const selected = storyIds?.length
+            ? all.filter((s) => storyIds.includes(s.storyId))
+            : all;
+        this.running = true;
+        this.done = 0;
+        this.total = selected.length;
+        this.currentStory = null;
+        this.abort = new AbortController();
+        try {
+            const browser = await this.ensureBrowser();
+            const report = await runCapture({
+                browser,
+                platform: this.opts.platform,
+                store: this.opts.store,
+                baseUrl: this.opts.baseUrl,
+                stories: selected,
+                totalCount: all.length,
+                config: this.opts.config,
+                ancestry: existsSync(path.join(this.opts.projectRoot, '.git'))
+                    ? createAncestryCheck(this.opts.projectRoot)
+                    : alwaysAncestor,
+                runId: Date.now().toString(36),
+                branch: this.opts.branch,
+                commitSha: this.opts.commitSha,
+                signal: this.abort.signal,
+                onProgress: (done, total, storyId) => {
+                    this.done = done;
+                    this.total = total;
+                    this.currentStory = storyId;
+                },
+                onArtifact: async (a) => {
+                    const images = path.join(this.opts.runDir, 'images');
+                    await mkdir(images, { recursive: true });
+                    const safe = encodeStoryId(a.storyId);
+                    await writeFile(path.join(images, `${safe}-current.webp`), a.current);
+                    if (a.diff)
+                        await writeFile(path.join(images, `${safe}-diff.webp`), a.diff);
+                },
+            });
+            // A partial run only re-captured some stories; merging keeps the others
+            // visible instead of blanking the panel down to the subset.
+            this.report = storyIds?.length ? mergeReports(this.report, report) : report;
+            await mkdir(this.opts.runDir, { recursive: true });
+            await writeFile(path.join(this.opts.runDir, 'report.json'), JSON.stringify(this.report, null, 2) + '\n');
+        }
+        finally {
+            this.running = false;
+            this.currentStory = null;
+            this.abort = null;
+        }
+    }
+    async cancel() {
+        this.abort?.abort();
+    }
+    async close() {
+        await this.browser?.close().catch(() => { });
+        this.browser = null;
+    }
+    async ensureBrowser() {
+        // Kept alive across runs: launching Chromium is most of the latency on a
+        // single-story recapture, which is the common case in the panel.
+        if (this.browser?.isConnected())
+            return this.browser;
+        this.browser = await chromium.launch(deterministicLaunchOptions());
+        return this.browser;
+    }
+    async loadReport() {
+        if (this.report)
+            return this.report;
+        try {
+            const raw = await readFile(path.join(this.opts.runDir, 'report.json'), 'utf8');
+            this.report = JSON.parse(raw);
+        }
+        catch {
+            this.report = null;
+        }
+        return this.report;
+    }
+    async readImage(kind, storyId) {
+        const file = path.join(this.opts.runDir, 'images', `${encodeStoryId(storyId)}-${kind}.webp`);
+        try {
+            return await readFile(file);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Overlay fresh results onto the previous report, keeping untouched stories. */
+function mergeReports(previous, fresh) {
+    if (!previous)
+        return fresh;
+    const byId = new Map(previous.results.map((r) => [r.storyId, r]));
+    for (const result of fresh.results)
+        byId.set(result.storyId, result);
+    const results = [...byId.values()].sort((a, b) => a.storyId.localeCompare(b.storyId));
+    const summary = { pass: 0, fail: 0, new: 0, stale: 0, skip: 0 };
+    for (const r of results)
+        summary[r.status]++;
+    return { ...fresh, results, summary, totalCount: previous.totalCount };
+}
+/** The same hash the manifest stores, so a match means "already approved". */
+function hash(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+import type { RunReport, StoryManifest } from '@juxtapose/core';
+/** What the panel polls for. One request, everything it needs to render. */
+export interface ReviewBundle {
+    report: RunReport | null;
+    /** Story ids approved since the run, so the UI can grey them out without
+     *  waiting for a re-run. */
+    approved: string[];
+    /** True while a capture is in flight. */
+    running: boolean;
+}
+export interface RunProgress {
+    running: boolean;
+    done: number;
+    total: number;
+    storyId: string | null;
+}
+export type ImageKind = 'current' | 'baseline' | 'diff';
+/**
+ * Everything the HTTP layer needs, with no knowledge of how it is served.
+ *
+ * Splitting this out means the same implementation backs the standalone
+ * `jux serve` and the middleware mounted inside a workbench's dev server —
+ * and that a test can drive it without a socket.
+ */
+export interface ReviewSource {
+    bundle(): Promise<ReviewBundle>;
+    progress(): Promise<RunProgress>;
+    image(kind: ImageKind, storyId: string): Promise<Buffer | null>;
+    handoff(storyId: string): Promise<string | null>;
+    approve(storyId: string): Promise<void>;
+    /** Capture a subset, or everything when `storyIds` is omitted. */
+    run(storyIds?: string[]): Promise<void>;
+    cancel(): Promise<void>;
+    stories(): Promise<StoryManifest[]>;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// The review API's contract.
+//
+// This is deliberately the stable surface, not the panel. A Storybook addon,
+// a Ladle UI, an MCP server and a CLI all want the same operations; making
+// HTTP the contract means each is a skin rather than a reimplementation.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,yEAAyE"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@juxtapose/server",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Local review API for juxtapose — the contract every review UI is a skin over.",
+  "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": {
+    "playwright": "^1.48.0",
+    "@juxtapose/core": "0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juxtapose-dev/juxtapose.git",
+    "directory": "packages/server"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}