@juxtapose/core 0.8.0 → 0.10.0

package/dist/capture/capture.js

@@ -2,13 +2,20 @@
 // each step exists. Because pass/fail is a byte-exact hash, every source of
 // nondeterminism left in this path becomes a false failure somewhere.
 import sharp from 'sharp';
+import { emulatedMedia } from '../browser/page.js';
 import { assertCssSelector } from '../browser/selectors.js';
-import { armSettle, drain, FREEZE_ANIMATIONS_CSS, waitForPaint, waitForSelector, } from './settle.js';
+import { FREEZE_ANIMATIONS_CSS, waitForPaint, waitForSelector } from './settle.js';
+import { installIdleDetector, movedSincePaint, resetIdle, waitForIdle, } from './idle.js';
+import { checkSettle, layerScalars, resolveSettle, } from './settle-options.js';
 import { captureStructure } from './structure.js';
+import { deepEqual, mergeLiveParams, platformStoryId } from './variants.js';
 const DEFAULT_CAPTURE_TIMEOUT_MS = 2000;
 /** Per-page memo: skip work that only needs doing once per page. */
 const styleInjected = new WeakSet();
 const pageViewport = new WeakMap();
+const pageColorScheme = new WeakMap();
+/** The capture last shown on a page: its key and its platform story id. */
+const pageCapture = new WeakMap();
 const warmPages = new WeakMap();
 export async function captureStory(page, story, deps, viewport) {
     const started = Date.now();
@@ -17,35 +24,72 @@ export async function captureStory(page, story, deps, viewport) {
     const params = { ...story.params };
     const effectiveViewport = params.viewport ?? viewport;
     const timeoutMs = params.captureTimeout ?? DEFAULT_CAPTURE_TIMEOUT_MS;
-    const ctx = { story, params, timeoutMs };
+    // Every platform call gets the platform's own id; the variant capture key
+    // means nothing to Storybook or Ladle.
+    const id = platformStoryId(story);
+    const ctx = {
+        story: id === story.storyId ? story : { ...story, storyId: id },
+        params,
+        timeoutMs,
+    };
     // Selector syntax is validated before the page is touched: a Playwright-only
     // selector (`text=`, `>>`) would otherwise match nothing and the story would
     // be captured unmasked, or wait its whole timeout, and the baseline would
     // record the wrong thing. Live params are re-checked below.
     assertSelectors(params);
+    // Before the first navigation on this page: the init script applies to
+    // documents created after it is installed.
+    const idle = await installIdleDetector(page);
     await ensureViewport(page, effectiveViewport);
-    // Arm before triggering the render, or the observer misses the mutations it
-    // exists to watch.
-    //
+    // Only a variant sets a scheme: a default capture resets to light, which is
+    // what stops a pooled page carrying a dark variant's scheme into the next
+    // story.
+    const scheme = story.variant !== undefined ? (params.colorScheme ?? 'light') : 'light';
     // A story that wants animations running can't reuse a page whose stylesheet
-    // already froze them, so force the cold path for those.
+    // already froze them, so force the cold path for those. Likewise a scheme
+    // change: an app that reads matchMedia once at boot keeps the old scheme
+    // across a warm switch (measured: card then card__dark captured both light,
+    // the reverse both dark). Decided before the scheme is applied, against
+    // what the page booted under.
+    //
+    // And another capture of the same story (default -> mobile): the platform
+    // sees its story already rendered and "switches" without re-rendering, so
+    // the variant would be captured from the previous capture's layout.
+    const previous = pageCapture.get(page);
+    const sameStoryOtherCapture = previous !== undefined && previous.base === id && previous.key !== story.storyId;
+    const schemeChanged = pageColorScheme.has(page) && pageColorScheme.get(page) !== scheme;
     const warm = deps.warmSwitch === true &&
         warmPages.get(page) === deps.baseUrl &&
+        !schemeChanged &&
+        !sameStoryOtherCapture &&
         !(params.animations === 'play' && styleInjected.has(page));
-    if (warm)
-        await armSettle(page);
+    // Before showStory, on every capture, so the story renders in its scheme
+    // from the first frame. Memoized, so it costs nothing when unchanged.
+    await ensureColorScheme(page, scheme);
+    // A variant shares its story's URL, and a URL differing only in its
+    // fragment is a same-document navigation: the cold path below would not
+    // reload, and an app that read the scheme at boot would keep the old one,
+    // or keep the previous capture's render. Blank the page so the story boots
+    // fresh.
+    if ((schemeChanged || sameStoryOtherCapture) && warmPages.has(page)) {
+        await page.goto('about:blank');
+        warmPages.delete(page);
+    }
+    pageCapture.set(page, { key: story.storyId, base: id });
+    // Before the render is triggered, so a request or ready() call from this
+    // story's render is never mistaken for the previous one's.
+    await resetIdle(page, idle, warm);
     const switched = warm && deps.platform.switchStory
-        ? await deps.platform.switchStory(page, story.storyId, ctx)
+        ? await deps.platform.switchStory(page, id, ctx)
         : false;
     if (!switched) {
         // Delegated rather than built here: not every platform addresses a story
         // by URL. Playwright galleries render via window.mount() on a fixed page.
-        await deps.platform.showStory(page, story.storyId, deps.baseUrl);
+        await deps.platform.showStory(page, id, deps.baseUrl);
         // A navigation discards injected style tags, so the freeze must be
         // re-applied for the next story that wants it.
         styleInjected.delete(page);
         warmPages.set(page, deps.baseUrl);
-        await armSettle(page);
     }
     // Freeze BEFORE the story renders, not after.
     //
@@ -70,16 +114,25 @@ export async function captureStory(page, story, deps, viewport) {
     // waitForSelector and skip on that platform.
     //
     // Live params override manifest params — the live preview is the story's own
-    // declaration, and the index is a lossy projection of it.
-    const live = await deps.platform.readLiveParams?.(page, story.storyId);
+    // declaration, and the index is a lossy projection of it — but merge under
+    // a variant's own fields, so the mobile variant stays mobile.
+    const live = await deps.platform.readLiveParams?.(page, id);
     if (live) {
-        Object.assign(params, live);
+        Object.assign(params, mergeLiveParams(story, live));
         assertSelectors(params);
+        // A story can opt out of a project variant in params only the live
+        // preview carries (Storybook). Honour it as a skip.
+        if (story.variant !== undefined && live.variants?.[story.variant] === false) {
+            return null;
+        }
+        if (story.variant !== undefined && liveOverrideDiffers(story, live)) {
+            deps.onWarning?.(`jux: ${story.storyId}: the story's live parameters declare variant '${story.variant}' differently from the settings it was captured with. Parameters read after render can't change which variants exist or what they set; declare variants in the story's parameters, where discovery reads them before capture.`);
+        }
         // Viewport is the one param that cannot be applied retroactively — the
         // story has already laid out. Re-set it and let the platform settle
         // again, so a story declaring its own viewport is captured at that size
         // rather than the project default.
-        const liveViewport = live.viewport;
+        const liveViewport = params.viewport;
         if (liveViewport && !sameViewport(liveViewport, effectiveViewport)) {
             await ensureViewport(page, liveViewport);
             await deps.platform.settle(page, { ...ctx, params });
@@ -91,10 +144,18 @@ export async function captureStory(page, story, deps, viewport) {
     // screenshot and would report a meaningless hash.
     if (params.skip === true)
         return null;
+    // Project and call layers around the story's own: waitForSelector and
+    // delay are call > story > project; settle merges field by field. Live
+    // params can carry a `settle` discovery never saw, so it is checked here;
+    // a bad one fails this story with the reason.
+    Object.assign(params, layerScalars(deps.settleLayers?.project, params, deps.settleLayers?.call));
+    assertSelectors(params);
+    checkSettle(params.settle, `story '${story.storyId}'`);
+    const settle = resolveSettle(deps.settleLayers?.project?.settle, params.settle, deps.settleLayers?.call?.settle);
     if (params.waitForSelector) {
         await waitForSelector(page, params.waitForSelector, timeoutMs);
     }
-    await drain(page);
+    const first = await waitForIdle(page, idle, settle);
     // Fixed delay is the escape hatch of last resort — it costs the same on
     // every run whether or not it was needed. Prefer waitForSelector.
     if (params.delay && params.delay > 0) {
@@ -105,6 +166,17 @@ export async function captureStory(page, story, deps, viewport) {
     // this the capture intermittently catches an intermediate frame — which a
     // byte-exact hash reports as a failure.
     await waitForPaint(page);
+    // Work that landed during the paint barrier (an observer callback, a
+    // request the last frame started) gets one more wait, within what is left
+    // of the cap. Once: a page that keeps moving is captured, not chased.
+    let flagged = first.status === 'idle' ? undefined : first;
+    if (first.status === 'idle' &&
+        (await movedSincePaint(page, idle, first.snap, settle))) {
+        const second = await waitForIdle(page, idle, settle, Math.max(100, settle.timeoutMs - first.waitedMs));
+        await waitForPaint(page);
+        if (second.status !== 'idle')
+            flagged = second;
+    }
     // Structure from the same frame the screenshot is about to take: after the
     // paint barrier, before the shutter, with nothing in between that could
     // mutate the page.
@@ -132,6 +204,8 @@ export async function captureStory(page, story, deps, viewport) {
         .toBuffer();
     return {
         storyId: story.storyId,
+        ...(story.baseStoryId !== undefined ? { baseStoryId: story.baseStoryId } : {}),
+        ...(story.variant !== undefined ? { variant: story.variant } : {}),
         image,
         // The live params may have widened or narrowed this after first render,
         // so report what we actually captured at — the agent handoff computes
@@ -140,8 +214,29 @@ export async function captureStory(page, story, deps, viewport) {
         capturedAt: new Date().toISOString(),
         durationMs: Date.now() - started,
         ...(structure ? { structure } : {}),
+        ...(flagged?.status === 'timeout'
+            ? {
+                settle: {
+                    status: 'timeout',
+                    timeoutMs: settle.timeoutMs,
+                    pending: flagged.pending ?? [],
+                },
+            }
+            : flagged?.status === 'fallback'
+                ? { settle: { status: 'fallback', pending: flagged.pending ?? [] } }
+                : {}),
     };
 }
+/** Whether the live preview declares this variant with settings other than
+ *  the ones it was expanded with: Storybook keeps story-level variants out of
+ *  index.json, so they only surface here, after the capture set is fixed. */
+function liveOverrideDiffers(story, live) {
+    const spec = story.variant !== undefined ? live.variants?.[story.variant] : undefined;
+    if (spec === undefined || spec === false || typeof spec !== 'object')
+        return false;
+    const expanded = story.variantParams ?? {};
+    return Object.entries(spec).some(([k, v]) => k !== 'extends' && !deepEqual(v, expanded[k]));
+}
 const sameViewport = (a, b) => a.width === b.width && a.height === b.height;
 /** Setting the viewport is a CDP round-trip; skip it when nothing changed. */
 async function ensureViewport(page, viewport) {
@@ -151,6 +246,16 @@ async function ensureViewport(page, viewport) {
     await page.setViewportSize(viewport);
     pageViewport.set(page, key);
 }
+/** Media emulation is a CDP round-trip too; skip it when nothing changed. */
+async function ensureColorScheme(page, scheme) {
+    if (pageColorScheme.get(page) === scheme)
+        return;
+    if (page.setColorScheme)
+        await page.setColorScheme(scheme);
+    else
+        await page.send('Emulation.setEmulatedMedia', emulatedMedia(scheme));
+    pageColorScheme.set(page, scheme);
+}
 /**
  * Inject the freeze stylesheet, once per page.
  *

package/dist/capture/capture.js.map

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

package/dist/capture/config-errors.d.ts

@@ -0,0 +1,10 @@
+/** A bad variant declaration. The CLI reports it and exits 2. */
+export declare class VariantConfigError extends Error {
+    constructor(message: string);
+}
+/** A bad settle option. Extends VariantConfigError so every caller that
+ *  already reports a declaration error (run, init, the review server) reports
+ *  this one the same way: exit 2 with the message. */
+export declare class SettleConfigError extends VariantConfigError {
+    constructor(message: string);
+}

package/dist/capture/config-errors.js

@@ -0,0 +1,20 @@
+// Declaration errors. Their own module because variants.ts and
+// settle-options.ts each need the other's checks, and a class extended at
+// module evaluation must not sit on an import cycle.
+/** A bad variant declaration. The CLI reports it and exits 2. */
+export class VariantConfigError extends Error {
+    constructor(message) {
+        super(`jux: ${message}`);
+        this.name = 'VariantConfigError';
+    }
+}
+/** A bad settle option. Extends VariantConfigError so every caller that
+ *  already reports a declaration error (run, init, the review server) reports
+ *  this one the same way: exit 2 with the message. */
+export class SettleConfigError extends VariantConfigError {
+    constructor(message) {
+        super(message);
+        this.name = 'SettleConfigError';
+    }
+}
+//# sourceMappingURL=config-errors.js.map

package/dist/capture/config-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-errors.js","sourceRoot":"","sources":["../../src/capture/config-errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,0EAA0E;AAC1E,qDAAqD;AAErD,iEAAiE;AACjE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;sDAEsD;AACtD,MAAM,OAAO,iBAAkB,SAAQ,kBAAkB;IACvD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/capture/discover.d.ts

@@ -0,0 +1,28 @@
+import type { Browser } from '../browser/browser.js';
+import type { EnumerateTarget, Platform } from '../platform.js';
+import type { StoryManifest, VariantSpec, Viewport } from '../types.js';
+export interface PrepareOptions {
+    platform: Platform;
+    browser: Browser;
+    baseUrl: string;
+    viewport: Viewport;
+    /** `ProjectConfig.variants`. */
+    projectVariants?: Record<string, VariantSpec | false>;
+    onWarning?: (message: string) => void;
+    timeoutMs?: number;
+    /** Keep discovered params on disk, keyed by the platform's
+     *  `discoveryKey`, so an unchanged build skips the preview load. */
+    cache?: {
+        dir: string;
+        target: EnumerateTarget;
+    };
+}
+/**
+ * Merge the platform's discovered params over the enumerated ones. Never
+ * throws for discovery itself: a preview that can't be read costs the
+ * story-level settings the index lacks, which is today's behavior, and must
+ * not cost the run. Throws VariantConfigError from expansion.
+ */
+export declare function discoverParams(stories: readonly StoryManifest[], opts: Omit<PrepareOptions, 'projectVariants'>): Promise<StoryManifest[]>;
+/** Discover, then expand: one StoryManifest per capture. */
+export declare function prepareCaptures(stories: readonly StoryManifest[], opts: PrepareOptions): Promise<StoryManifest[]>;

package/dist/capture/discover.js

@@ -0,0 +1,109 @@
+// Enumeration-time parameter discovery, then variant expansion: the step
+// between "what stories exist" and "what captures to take".
+//
+// Lives in core so every caller that captures (jux run, jux init, the review
+// server) builds the same capture set from the same inputs.
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { expandVariants } from './variants.js';
+/** A preview that hasn't produced its parameters in this long is broken, not
+ *  slow: the example's 17 stories take ~60 ms. */
+const DISCOVER_TIMEOUT_MS = 30_000;
+/** Bumped when the cached shape or what discovery reads changes. */
+const CACHE_SCHEMA = 1;
+const CACHE_FILE = 'discovered-params.json';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Merge the platform's discovered params over the enumerated ones. Never
+ * throws for discovery itself: a preview that can't be read costs the
+ * story-level settings the index lacks, which is today's behavior, and must
+ * not cost the run. Throws VariantConfigError from expansion.
+ */
+export async function discoverParams(stories, opts) {
+    const discover = opts.platform.discoverParams?.bind(opts.platform);
+    if (!discover || stories.length === 0)
+        return [...stories];
+    const key = await cacheKey(opts);
+    const cached = key ? await readCache(opts.cache.dir, key) : undefined;
+    const found = cached ?? (await discoverLive(discover, opts));
+    if (!found)
+        return [...stories];
+    if (key && !cached)
+        await writeCache(opts.cache.dir, key, found);
+    return stories.map((s) => {
+        const params = found.get(s.storyId);
+        return isRecord(params) ? { ...s, params: { ...s.params, ...params } } : s;
+    });
+}
+/** One preview load; undefined (after a warning) when it can't be read. */
+async function discoverLive(discover, opts) {
+    let found;
+    const context = await opts.browser.newContext({ viewport: opts.viewport });
+    let timer;
+    try {
+        const page = await context.newPage();
+        const timeoutMs = opts.timeoutMs ?? DISCOVER_TIMEOUT_MS;
+        found = await Promise.race([
+            discover(page, opts.baseUrl),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs} ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    catch (err) {
+        opts.onWarning?.(`jux: could not read story parameters from the ${opts.platform.name} preview (${err instanceof Error ? err.message : String(err)}); story-level settings and variants come from the index only`);
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        await context.close().catch(() => { });
+    }
+    return found;
+}
+/** The platform's fingerprint of what it would discover from, salted with
+ *  the platform and cache schema; undefined disables the cache. */
+async function cacheKey(opts) {
+    if (!opts.cache || !opts.platform.discoveryKey)
+        return undefined;
+    try {
+        const key = await opts.platform.discoveryKey(opts.cache.target);
+        if (key === undefined)
+            return undefined;
+        return createHash('sha256')
+            .update(`${CACHE_SCHEMA}\0${opts.platform.name}\0${key}`)
+            .digest('hex');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A missing, unreadable or mismatched cache is a miss, never an error. */
+async function readCache(dir, key) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(dir, CACHE_FILE), 'utf8'));
+        if (!isRecord(parsed) || parsed['key'] !== key || !isRecord(parsed['params']))
+            return undefined;
+        return new Map(Object.entries(parsed['params']));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Written atomically; a failed write costs the next run a discovery. */
+async function writeCache(dir, key, found) {
+    try {
+        await mkdir(dir, { recursive: true });
+        const tmp = path.join(dir, `${CACHE_FILE}.${process.pid}.tmp`);
+        await writeFile(tmp, JSON.stringify({ key, params: Object.fromEntries(found) }) + '\n');
+        await rename(tmp, path.join(dir, CACHE_FILE));
+    }
+    catch {
+        // best effort
+    }
+}
+/** Discover, then expand: one StoryManifest per capture. */
+export async function prepareCaptures(stories, opts) {
+    return expandVariants(await discoverParams(stories, opts), opts.projectVariants);
+}
+//# sourceMappingURL=discover.js.map

package/dist/capture/discover.js.map

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

package/dist/capture/idle.d.ts

@@ -0,0 +1,88 @@
+import type { Page } from '../browser/page.js';
+import { type ResolvedSettle } from './settle-options.js';
+/** What the page reported at its last check. */
+export interface IdleSnapshot {
+    timers: number;
+    rafs: number;
+    /** Posted messages sent and not yet delivered. */
+    msgs: number;
+    delivered: number;
+    /** Workers created within the horizon that have not answered yet. */
+    workers: number;
+    workerSrcs: string[];
+    mut: number;
+    fonts: string;
+    images: number;
+    /** The first few incomplete images, for the pending description. */
+    imageSrcs: string[];
+    ready: boolean;
+    /** The last check saw the DOM change. */
+    changing?: boolean;
+}
+export interface IdleResult {
+    /** `fallback`: the detector could not run (not installed, or the page
+     *  navigated mid-wait), so a fonts/images/quiet-DOM wait stood in. */
+    status: 'idle' | 'timeout' | 'fallback';
+    waitedMs: number;
+    snap?: IdleSnapshot;
+    /** Set on `timeout` (what was still pending) and `fallback` (why).
+     *  Never empty. */
+    pending?: string[];
+}
+interface Request {
+    url: string;
+    type?: string;
+    /** Set on main-frame requests: the document loader that started it. */
+    mainLoader?: string;
+}
+/** In-flight and completed requests on one page, from CDP Network events. */
+export declare class NetworkTracker {
+    private readonly inflight;
+    private done;
+    private readonly listeners;
+    /** In flight when the current story started on a warm switch: the last
+     *  story's, never this one's. */
+    private excluded;
+    /** The committed main document's loader. */
+    private mainLoader;
+    constructor(page: Page & Required<Pick<Page, 'on'>>, mainFrameId: string | undefined);
+    /** A warm switch renders a new story in the same document: the last
+     *  story's completions must not satisfy `require`, and its requests still
+     *  in flight (a long poll) must not pin this one at the cap. */
+    reset(): void;
+    /** In-flight requests the wait counts: required, or not ignored. */
+    counted(s: ResolvedSettle): Request[];
+    /** `require` patterns no completed request has matched yet. */
+    missing(s: ResolvedSettle): string[];
+    busy(s: ResolvedSettle): boolean;
+    /** Resolves when the wait no longer counts anything, or after `ms`. */
+    settled(s: ResolvedSettle, ms: number): Promise<void>;
+}
+/** One page's settle machinery: the init script is installed, and the
+ *  tracker is null when the page cannot deliver events. */
+export interface IdleDetector {
+    net: NetworkTracker | null;
+}
+/**
+ * Install the init script and the request tracker, once per page, before
+ * its first navigation: the script applies to every later document on the
+ * page. Network.enable is already part of page init.
+ */
+export declare function installIdleDetector(page: Page): Promise<IdleDetector>;
+/** Before a story renders: forget the last story's completions, and on a
+ *  warm switch (same document) its ready() call. */
+export declare function resetIdle(page: Page, idle: IdleDetector, warm: boolean): Promise<void>;
+/**
+ * Wait until the page reports no pending work and no counted request is in
+ * flight, or `capMs` passes. Never throws.
+ */
+export declare function waitForIdle(page: Page, idle: IdleDetector, s: ResolvedSettle, capMs?: number): Promise<IdleResult>;
+/** After the paint barrier: did the DOM, fonts, images or network move? */
+export declare function movedSincePaint(page: Page, idle: IdleDetector, before: IdleSnapshot | undefined, s: ResolvedSettle): Promise<boolean>;
+/**
+ * What was still pending at the cap, one line per kind, so an agent reading
+ * the result can respond: ignore a request, require one, raise the cap, or
+ * mask what keeps changing. Never empty.
+ */
+export declare function describePending(snap: IdleSnapshot | undefined, net: NetworkTracker | null, s: ResolvedSettle): string[];
+export {};