@juxtapose/core 0.2.0 → 0.4.0

package/dist/analysis/affected.d.ts

@@ -17,3 +17,24 @@ export interface AffectedResult {
     reason: 'no-baseline' | 'config-changed' | 'dependency-changed' | 'graph-walk' | 'no-match-fallback' | 'git-unavailable' | 'no-changes';
 }
 export declare function resolveAffected(stories: StoryManifest[], sinceCommit: string | null, opts: AffectedOptions): Promise<AffectedResult>;
+/**
+ * Which stories a set of source files could affect, without consulting git.
+ *
+ * This is the watch-mode entry point, and it inverts the fail-safe that
+ * `resolveAffected` uses. There, an uncertain answer escalates to capturing
+ * everything, because a missed story ships a regression. Here the trigger is a
+ * developer typing: escalating would recapture the whole suite on every
+ * keystroke-pause, which is not a safety net, it is a hang. An uncertain answer
+ * narrows to the files we know changed, and the CI run remains the backstop
+ * that cannot be fooled.
+ *
+ * The bundler graph is best-effort. Storybook's dev server has no build
+ * manifest, so when `buildDir` is absent or unbuilt we fall back to matching
+ * stories by their own component path — edit `Button.tsx` and every Button
+ * story recaptures. That misses a `Card` that imports `Button`; a build lying
+ * around upgrades the answer for free.
+ */
+export declare function resolveAffectedFromPaths(stories: StoryManifest[], changedFiles: string[], opts: {
+    projectRoot: string;
+    buildDir?: string;
+}): Promise<StoryManifest[]>;

package/dist/analysis/affected.js

@@ -56,6 +56,43 @@ export async function resolveAffected(stories, sinceCommit, opts) {
         return { stories, reason: 'no-match-fallback' };
     return { stories: matched, reason: 'graph-walk' };
 }
+/**
+ * Which stories a set of source files could affect, without consulting git.
+ *
+ * This is the watch-mode entry point, and it inverts the fail-safe that
+ * `resolveAffected` uses. There, an uncertain answer escalates to capturing
+ * everything, because a missed story ships a regression. Here the trigger is a
+ * developer typing: escalating would recapture the whole suite on every
+ * keystroke-pause, which is not a safety net, it is a hang. An uncertain answer
+ * narrows to the files we know changed, and the CI run remains the backstop
+ * that cannot be fooled.
+ *
+ * The bundler graph is best-effort. Storybook's dev server has no build
+ * manifest, so when `buildDir` is absent or unbuilt we fall back to matching
+ * stories by their own component path — edit `Button.tsx` and every Button
+ * story recaptures. That misses a `Card` that imports `Button`; a build lying
+ * around upgrades the answer for free.
+ */
+export async function resolveAffectedFromPaths(stories, changedFiles, opts) {
+    if (changedFiles.length === 0)
+        return [];
+    const changed = changedFiles.map((f) => toPosixRelative(opts.projectRoot, path.resolve(opts.projectRoot, f)));
+    if (opts.buildDir) {
+        const manifest = await loadViteManifest(opts.buildDir);
+        if (manifest) {
+            const affected = walkDependents(buildReverseGraph(manifest), changed);
+            const matched = stories.filter((s) => affected.has(toPosixRelative(opts.projectRoot, s.componentPath)));
+            // An empty result means the graph does not know these files, not that
+            // nothing depends on them — fall through rather than reporting none.
+            if (matched.length > 0)
+                return matched;
+        }
+    }
+    return stories.filter((s) => {
+        const rel = toPosixRelative(opts.projectRoot, s.componentPath);
+        return changed.some((c) => rel === c || rel.endsWith('/' + c) || c.endsWith('/' + rel));
+    });
+}
 /**
  * Build `imported → importers` from Vite's manifest.
  *

package/dist/analysis/affected.js.map

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

package/dist/capture/capture.js

@@ -97,7 +97,14 @@ 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);
-    const png = await page.screenshot({ type: 'png' });
+    // A selector matching nothing is not an error — a story that conditionally
+    // renders the element shouldn't fail on the branch where it's absent.
+    const png = await page.screenshot({
+        type: 'png',
+        ...(params.mask?.length
+            ? { mask: params.mask.map((selector) => page.locator(selector)) }
+            : {}),
+    });
     // LOSSLESS, deliberately, and it is not a size-vs-quality preference.
     //
     // Lossy WebP at q90 perturbs ~7.7% of pixels frame-wide. The hash comparison

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/env.d.ts

@@ -0,0 +1,8 @@
+import type { Browser } from 'playwright';
+import type { CaptureEnv } from '../types.js';
+export type { CaptureEnv };
+export declare function captureEnv(browser: Browser): CaptureEnv;
+export declare function sameEnv(a: CaptureEnv | undefined, b: CaptureEnv | undefined): boolean;
+/** One line naming only what moved, for explaining an all-red run. Empty when
+ *  the environments match or either is unknown. */
+export declare function describeEnvChange(from: CaptureEnv | undefined, to: CaptureEnv): string;

package/dist/capture/env.js

@@ -0,0 +1,38 @@
+// What rendered the pixels. Two baselines from different environments are not
+// comparable byte-for-byte even when nothing about the code changed, so an
+// all-red suite after a toolchain bump is indistinguishable from 700
+// regressions unless the environment is on record.
+//
+// Measured before choosing the fields: across Chromium 149 -> 151, 16 of 18
+// example stories were byte-identical, while re-encoding the same images
+// through a different libvips changed all 17 baseline hashes with zero changed
+// pixels. The encoder moves bytes far more readily than the browser does, so it
+// earns a field of its own rather than being folded into the browser version.
+import sharp from 'sharp';
+export function captureEnv(browser) {
+    return {
+        browser: browser.version(),
+        os: `${process.platform}-${process.arch}`,
+        encoder: sharp.versions.vips,
+    };
+}
+export function sameEnv(a, b) {
+    if (!a || !b)
+        return false;
+    return a.browser === b.browser && a.os === b.os && a.encoder === b.encoder;
+}
+/** One line naming only what moved, for explaining an all-red run. Empty when
+ *  the environments match or either is unknown. */
+export function describeEnvChange(from, to) {
+    if (!from)
+        return '';
+    const parts = [];
+    if (from.browser !== to.browser)
+        parts.push(`browser ${from.browser} -> ${to.browser}`);
+    if (from.os !== to.os)
+        parts.push(`os ${from.os} -> ${to.os}`);
+    if (from.encoder !== to.encoder)
+        parts.push(`encoder libvips ${from.encoder} -> ${to.encoder}`);
+    return parts.join(', ');
+}
+//# sourceMappingURL=env.js.map

package/dist/capture/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/capture/env.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,qEAAqE;AACrE,mDAAmD;AACnD,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAE9E,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE;QAC1B,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE;QACzC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAyB,EAAE,CAAyB;IAC1E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC;AAC7E,CAAC;AAED;mDACmD;AACnD,MAAM,UAAU,iBAAiB,CAAC,IAA4B,EAAE,EAAc;IAC5E,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxF,IAAI,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,IAAI,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO;QAC7B,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -1,17 +1,17 @@
 export type { StoryParams, Viewport, StoryManifest, Snapshot, ChangedRegion, DiffStatus, DiffResult, RunReport, ApprovalMeta, BaselineEntry, BaselineManifest, ProjectConfig, StorageConfig, BaselineStore, } from './types.js';
 export type { Platform, EnumerateTarget, SettleContext } from './platform.js';
 export { navigateToStory } from './url-platform.js';
-export { hashImage, resolveStatus, toDiffStatus, type BaselineStatus, type AncestryCheck, } from './baseline/status.js';
+export { waitForSelector } from './capture/settle.js';
 export { GitBaselineStore, encodeStoryId } from './baseline/git-store.js';
+export { hashImage } from './baseline/status.js';
+export type { BaselineStatus, AncestryCheck } from './baseline/status.js';
 export { createAncestryCheck, alwaysAncestor } from './git/ancestry.js';
-export { armSettle, drain, waitForSelector, waitForPaint, FREEZE_ANIMATIONS_CSS, DOM_IDLE_MS, DOM_IDLE_TIMEOUT_MS, } from './capture/settle.js';
-export { captureStory, type CaptureDeps } from './capture/capture.js';
-export { deterministicLaunchOptions, DETERMINISTIC_CHROMIUM_ARGS, type LaunchOptions, } from './capture/launch.js';
-export { capturePool, DEFAULT_CONCURRENCY, type PoolOptions, type CaptureOutcome, } from './capture/pool.js';
-export { diffImages, resolveThreshold, resolveMinDiffPercent, type DiffOutput, } from './diff/diff.js';
-export { computeChangedRegions } from './diff/regions.js';
-export { resolveAffected, type AffectedOptions, type AffectedResult, } from './analysis/affected.js';
 export { runCapture, DEFAULT_VIEWPORT, type RunOptions, type RunArtifact, } from './run/run.js';
-export { buildHandoffPrompt, describeRegion, type HandoffPayload, } from './agent/handoff.js';
-export { buildComment, COMMENT_MARKER, type CommentOptions } from './report/comment.js';
-export { resolveGitHubContext, postComment, type GitHubContext, } from './report/github.js';
+export { phases, formatPhases, type Phases } from './run/phases.js';
+export { deterministicLaunchOptions, type LaunchOptions } from './capture/launch.js';
+export { resolveAffected, resolveAffectedFromPaths, type AffectedOptions, type AffectedResult, } from './analysis/affected.js';
+export { buildHandoffPrompt, type HandoffPayload } from './agent/handoff.js';
+export { buildComment, type CommentOptions } from './report/comment.js';
+export { buildHtmlReport, type HtmlReportOptions } from './report/html.js';
+export { formatPercent } from './report/format.js';
+export { resolveArtifactUrl, resolveGitHubContext, postComment, type GitHubContext, } from './report/github.js';

package/dist/index.js

@@ -1,16 +1,33 @@
+// The public surface of @juxtapose/core.
+//
+// Everything here is a semver commitment once this publishes, so it is chosen
+// rather than accumulated. The settle pipeline, the diff internals and the
+// worker pool are deliberately NOT exported: CLAUDE.md describes them as
+// load-bearing and easy to break, and exporting them invites downstream code
+// to pin exactly the parts that most need freedom to change.
+//
+// If you are writing a third-party adapter or baseline store, the types and
+// helpers below are what you need. If something is missing for that, the seam
+// needs widening — say so rather than reaching into the package.
 export { navigateToStory } from './url-platform.js';
-export { hashImage, resolveStatus, toDiffStatus, } from './baseline/status.js';
+export { waitForSelector } from './capture/settle.js';
+// Implementing a baseline store. `encodeStoryId` matters for anyone building
+// keys from a story id — they are platform-supplied and not path-safe.
 export { GitBaselineStore, encodeStoryId } from './baseline/git-store.js';
+// hashImage is exported because anything comparing against a manifest entry
+// must use the same function the manifest was written with, not its own copy.
+export { hashImage } from './baseline/status.js';
 export { createAncestryCheck, alwaysAncestor } from './git/ancestry.js';
-export { armSettle, drain, waitForSelector, waitForPaint, FREEZE_ANIMATIONS_CSS, DOM_IDLE_MS, DOM_IDLE_TIMEOUT_MS, } from './capture/settle.js';
-export { captureStory } from './capture/capture.js';
-export { deterministicLaunchOptions, DETERMINISTIC_CHROMIUM_ARGS, } from './capture/launch.js';
-export { capturePool, DEFAULT_CONCURRENCY, } from './capture/pool.js';
-export { diffImages, resolveThreshold, resolveMinDiffPercent, } from './diff/diff.js';
-export { computeChangedRegions } from './diff/regions.js';
-export { resolveAffected, } from './analysis/affected.js';
+// Driving a run.
 export { runCapture, DEFAULT_VIEWPORT, } from './run/run.js';
-export { buildHandoffPrompt, describeRegion, } from './agent/handoff.js';
-export { buildComment, COMMENT_MARKER } from './report/comment.js';
-export { resolveGitHubContext, postComment, } from './report/github.js';
+// Per-phase timings, so a slow run can say which phase was slow.
+export { phases, formatPhases } from './run/phases.js';
+export { deterministicLaunchOptions } from './capture/launch.js';
+export { resolveAffected, resolveAffectedFromPaths, } from './analysis/affected.js';
+// Reporting on one.
+export { buildHandoffPrompt } from './agent/handoff.js';
+export { buildComment } from './report/comment.js';
+export { buildHtmlReport } from './report/html.js';
+export { formatPercent } from './report/format.js';
+export { resolveArtifactUrl, resolveGitHubContext, postComment, } from './report/github.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,SAAS,EACT,aAAa,EACb,YAAY,GAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EACL,SAAS,EACT,KAAK,EACL,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAoB,MAAM,sBAAsB,CAAC;AACtE,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,GAE5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,mBAAmB,GAGpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EACL,eAAe,GAGhB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,UAAU,EACV,gBAAgB,GAGjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,cAAc,GAEf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,cAAc,EAAuB,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,WAAW,GAEZ,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,yEAAyE;AACzE,6EAA6E;AAC7E,6DAA6D;AAC7D,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,iEAAiE;AAqBjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,6EAA6E;AAC7E,uEAAuE;AACvE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC1E,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExE,iBAAiB;AACjB,OAAO,EACL,UAAU,EACV,gBAAgB,GAGjB,MAAM,cAAc,CAAC;AAEtB,iEAAiE;AACjE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAsB,MAAM,qBAAqB,CAAC;AACrF,OAAO,EACL,eAAe,EACf,wBAAwB,GAGzB,MAAM,wBAAwB,CAAC;AAEhC,oBAAoB;AACpB,OAAO,EAAE,kBAAkB,EAAuB,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAuB,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,eAAe,EAA0B,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,GAEZ,MAAM,oBAAoB,CAAC"}

package/dist/report/comment.d.ts

@@ -10,7 +10,8 @@ export declare const COMMENT_MARKER = "<!-- juxtapose-bot -->";
 export interface CommentOptions {
     report: RunReport;
     /** Where to point someone who wants the images. Omitted when there is no
-     *  artifact to link to. */
+     *  artifact to link to — a link to an empty artifacts list is worse than no
+     *  link, so callers pass this only when they actually wrote a report. */
     artifactUrl?: string;
 }
 export declare function buildComment({ report, artifactUrl }: CommentOptions): string;