forgebook 0.1.8 → 0.3.0

package/dist/src/shellTheme.js

@@ -0,0 +1,274 @@
+/** The shell's light palette, every role. */
+export const LIGHT_PALETTE = {
+    window: "#f6f6f8",
+    sidebar: "#ebebef",
+    surface: "#fff",
+    fill: "#1d1d1f14",
+    "fill-quiet": "#1d1d1f0d",
+    hover: "#1d1d1f0a",
+    separator: "#1d1d1f17",
+    text: "#1d1d1f",
+    "text-secondary": "#56565d",
+    "text-tertiary": "#6a6a71",
+    accent: "#0a6cf0",
+    "accent-text": "#0059d2",
+    "on-accent": "#fff",
+    "danger-text": "#bc1f16",
+    "code-keyword": "#7036c4",
+    "code-type": "#0059d2",
+    "code-string": "#077229",
+    "code-number": "#935200",
+    "code-punctuation": "#6a6a71",
+    "code-name": "#1d1d1f",
+    edge: "#1d1d1f25",
+    "edge-hover": "#1d1d1f3d",
+    "edge-field": "#1d1d1f2e",
+    "card-edge": "#0000000f",
+    "card-edge-hover": "#0000001a",
+    "shadow-soft": "#0000000d",
+    "shadow-lift": "#00000012",
+    "shadow-deep": "#0003",
+    shade: "#1d1d1f33"
+};
+/** The shell's dark palette, every role. */
+export const DARK_PALETTE = {
+    window: "#161618",
+    sidebar: "#1e1e21",
+    surface: "#252529",
+    fill: "#ffffff1f",
+    "fill-quiet": "#ffffff12",
+    hover: "#ffffff0f",
+    separator: "#ffffff1a",
+    text: "#f2f2f4",
+    "text-secondary": "#b6b6bd",
+    "text-tertiary": "#9d9da5",
+    accent: "#1f6fe5",
+    "accent-text": "#7ab3ff",
+    "on-accent": "#fff",
+    "danger-text": "#ff8a80",
+    "code-keyword": "#c9a8ff",
+    "code-type": "#7ab3ff",
+    "code-string": "#7fdc8f",
+    "code-number": "#f2b46b",
+    "code-punctuation": "#9d9da5",
+    "code-name": "#f2f2f4",
+    edge: "#ffffff26",
+    "edge-hover": "#ffffff40",
+    "edge-field": "#ffffff2e",
+    "card-edge": "#ffffff17",
+    "card-edge-hover": "#ffffff26",
+    "shadow-soft": "#0000004d",
+    "shadow-lift": "#00000066",
+    "shadow-deep": "#00000080",
+    shade: "#00000073"
+};
+/** The roles a theme can set, the rest being the shell's own. */
+const THEME_ROLES = [
+    "window",
+    "sidebar",
+    "surface",
+    "separator",
+    "hover",
+    "text",
+    "text-secondary",
+    "text-tertiary",
+    "accent",
+    "accent-text",
+    "danger-text",
+    "code-keyword",
+    "code-type",
+    "code-string",
+    "code-number",
+    "code-punctuation",
+    "code-name"
+];
+/** The contrast text needs, WCAG 2.1 AA for body text. */
+const TEXT_CONTRAST = 4.5;
+/** The contrast a focus ring needs against what it sits on, WCAG 2.1 AA for non-text. */
+const FOCUS_CONTRAST = 3;
+/** The text roles, each read on every ground. */
+export const TEXT_ROLES = ["text", "text-secondary", "text-tertiary", "accent-text", "danger-text"];
+/** The grounds text is read on. */
+export const GROUND_ROLES = ["window", "sidebar", "surface"];
+/** The code roles, read on the code background. */
+export const CODE_ROLES = [
+    "code-keyword",
+    "code-type",
+    "code-string",
+    "code-number",
+    "code-punctuation",
+    "code-name"
+];
+/** What a plain CSS value never holds: what would end a declaration, a rule or the style block, or open a comment. */
+const UNSAFE_VALUE = /[;{}<>\\]|\/\*/;
+/** A record as custom properties, with a prefix; none for nothing. */
+const declarations = (values, prefix) => Object.entries(values)
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => `--forgebook-${prefix}${name}:${value}`)
+    .join(";");
+/** A rule, or nothing when it declares nothing. */
+const rule = (selector, body) => (body === "" ? "" : `${selector}{${body}}`);
+/** The rules of a theme's fonts and corners, which hold in both appearances. */
+const sharedCss = (theme) => rule(":root", [
+    declarations({ sans: theme.fonts?.sans, mono: theme.fonts?.mono }, "font-"),
+    declarations({
+        "control-small": theme.radius?.control,
+        control: theme.radius?.control,
+        card: theme.radius?.card
+    }, "radius-")
+]
+    .filter((part) => part !== "")
+    .join(";"));
+/** The rules of a palette: its appearance, and the system's before the page has told which. */
+const paletteCss = (colors, appearance) => {
+    const body = declarations(colors, "");
+    if (body === "")
+        return "";
+    const system = appearance === "dark" ? "(prefers-color-scheme:dark)" : "not (prefers-color-scheme:dark)";
+    return [
+        `@media ${system}{${rule(":root:not([data-forgebook-appearance])", body)}}`,
+        rule(`:root[data-forgebook-appearance="${appearance}"]`, body)
+    ].join("");
+};
+/**
+ * A theme as CSS, for the shell's page.
+ *
+ * @param theme - the theme.
+ * @returns the rules; empty when the theme sets nothing.
+ */
+export const shellThemeCss = (theme) => [sharedCss(theme), paletteCss(theme.light ?? {}, "light"), paletteCss(theme.dark ?? {}, "dark")].join("");
+/**
+ * What a frame needs of a theme: the box that says a story failed, and nothing a story could read. A frame draws in the
+ * light palette whatever the shell's appearance.
+ *
+ * @param theme - the theme.
+ * @returns the rule; empty when the theme sets nothing the box uses.
+ */
+export const frameThemeCss = (theme) => rule(".forgebook-frame-error", [
+    declarations({ sans: theme.fonts?.sans, mono: theme.fonts?.mono }, "font-"),
+    declarations({
+        "danger-text": theme.light?.["danger-text"],
+        "text-secondary": theme.light?.["text-secondary"]
+    }, "")
+]
+    .filter((part) => part !== "")
+    .join(";"));
+/**
+ * Themes over each other, role by role, the last winning: a catalogue over its presets.
+ *
+ * @param themes - the themes, in order.
+ */
+export const mergedThemes = (themes) => {
+    const merged = (field) => Object.assign({}, ...themes.map((theme) => theme[field]));
+    return { light: merged("light"), dark: merged("dark"), fonts: merged("fonts"), radius: merged("radius") };
+};
+/** Whether a value's quotes and brackets close, or the rest of the sheet would be swallowed. */
+const isBalanced = (value) => {
+    const unquoted = value.replace(/"[^"]*"|'[^']*'/g, "");
+    if (/["']/.test(unquoted))
+        return false;
+    let open = 0;
+    for (const character of unquoted) {
+        open += Number(character === "(") - Number(character === ")");
+        if (open < 0)
+            return false;
+    }
+    return open === 0;
+};
+/**
+ * What in a theme cannot be written into a page.
+ *
+ * @param theme - the theme.
+ * @returns the first value that is not a plain CSS value, named; none when all are.
+ */
+export const themeValueProblem = (theme) => {
+    const groups = { light: theme.light, dark: theme.dark, fonts: theme.fonts, radius: theme.radius };
+    for (const [group, values] of Object.entries(groups)) {
+        for (const [name, value] of Object.entries(values ?? {})) {
+            if (UNSAFE_VALUE.test(value) || !isBalanced(value)) {
+                return `shell.theme: ${group}.${name} is not a plain CSS value`;
+            }
+        }
+    }
+    return undefined;
+};
+/** A hex colour's channels, 0 to 1, with its alpha; none for anything else, which is left unjudged. */
+const channels = (color) => {
+    const digits = /^#((?:[0-9a-f]{3,4}){1,2})$/i.exec(color.trim())?.[1];
+    if (digits === undefined)
+        return undefined;
+    const full = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
+    const byte = (start) => Number.parseInt(full.slice(start, start + 2), 16) / 255;
+    return [byte(0), byte(2), byte(4), full.length === 8 ? byte(6) : 1];
+};
+/** A colour laid on an opaque one. */
+const over = (top, ground) => {
+    const [r, g, b, alpha] = top;
+    return [
+        r * alpha + ground[0] * (1 - alpha),
+        g * alpha + ground[1] * (1 - alpha),
+        b * alpha + ground[2] * (1 - alpha)
+    ];
+};
+/** The relative luminance of an opaque colour. */
+const luminance = ([r, g, b]) => {
+    const linear = (channel) => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+};
+/** Two opaque colours' contrast. */
+const contrast = (first, second) => {
+    const [a, b] = [luminance(first), luminance(second)];
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+};
+/** Colours stacked from the bottom, as the page paints them; none when one cannot be read. */
+const stacked = (palette, roles, canvas) => {
+    let ground = canvas;
+    for (const role of roles) {
+        const color = channels(palette[role] ?? "");
+        if (color === undefined)
+            return undefined;
+        ground = over(color, ground);
+    }
+    return ground;
+};
+/** A foreground that falls under a contrast on a ground, as a line; none when it holds or cannot be read. */
+const pairProblem = (appearance, palette, front, ground, minimum) => {
+    const color = channels(palette[front] ?? "");
+    const base = stacked(palette, ground, [1, 1, 1]);
+    if (color === undefined || base === undefined)
+        return undefined;
+    const ratio = contrast(over(color, base), base);
+    if (ratio >= minimum)
+        return undefined;
+    return `${appearance}: ${front} on ${ground.at(-1)} is ${ratio.toFixed(2)}:1, under ${minimum}:1`;
+};
+/** The ground a role paints on, from the page up. */
+const groundStack = (role) => (role === "window" ? ["window"] : ["window", role]);
+/** The pairs of a palette that fall under what they need. */
+const paletteProblems = (appearance, palette) => [
+    ...TEXT_ROLES.flatMap((text) => GROUND_ROLES.map((ground) => pairProblem(appearance, palette, text, groundStack(ground), TEXT_CONTRAST))),
+    ...CODE_ROLES.map((role) => pairProblem(appearance, palette, role, ["window", "surface", "fill-quiet"], TEXT_CONTRAST)),
+    ...GROUND_ROLES.map((ground) => pairProblem(appearance, palette, "accent", groundStack(ground), FOCUS_CONTRAST))
+].filter((problem) => problem !== undefined);
+/** The roles a theme sets that do not exist, or the role is written and nothing reads it. */
+const unknownRoles = (appearance, colors) => Object.keys(colors)
+    .filter((role) => !THEME_ROLES.some((known) => known === role))
+    .map((role) => `${appearance}: "${role}" is not a role of the shell's theme`);
+/**
+ * What in a theme will not work: a role that does not exist, a text under 4.5:1 on a ground, code under 4.5:1 on its
+ * background, or an accent under 3:1, since it draws the keyboard's focus. Colours that are not hex are left out: a wrong
+ * warning teaches people to ignore the right ones.
+ *
+ * @param theme - the theme.
+ * @returns one line per problem.
+ */
+export const shellThemeProblems = (theme) => [
+    ...unknownRoles("light", theme.light ?? {}),
+    ...unknownRoles("dark", theme.dark ?? {}),
+    ...(Object.keys(theme.light ?? {}).length === 0
+        ? []
+        : paletteProblems("light", { ...LIGHT_PALETTE, ...theme.light })),
+    ...(Object.keys(theme.dark ?? {}).length === 0
+        ? []
+        : paletteProblems("dark", { ...DARK_PALETTE, ...theme.dark }))
+];

package/dist/src/shellTheme.types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The shape of a catalogue's theme of the shell, as its configuration writes it.
+ *
+ * @remarks
+ * These roles are public API: renaming or removing one is a breaking change, so they are the few a library's look is
+ * made of, and adding one later breaks nobody. Edges, fills and shadows stay the shell's own: they are built from these
+ * on translucency, and freezing them would freeze how the shell draws a card.
+ *
+ * @module
+ */
+/** The colour roles a catalogue can set, each in both appearances. A CSS colour. */
+export type ShellPalette = {
+    /** The page behind everything. */
+    readonly window: string;
+    /** The sidebar. */
+    readonly sidebar: string;
+    /** Cards and panels. */
+    readonly surface: string;
+    /** Lines between sections. */
+    readonly separator: string;
+    /** A row under the pointer. */
+    readonly hover: string;
+    /** The main text. */
+    readonly text: string;
+    /** Secondary text. */
+    readonly "text-secondary": string;
+    /** The quietest text. */
+    readonly "text-tertiary": string;
+    /** The accent: selection, checked controls and the keyboard's focus ring. */
+    readonly accent: string;
+    /** The accent as text. */
+    readonly "accent-text": string;
+    /** Errors, as text. */
+    readonly "danger-text": string;
+    /** Keywords in code. */
+    readonly "code-keyword": string;
+    /** Types in code. */
+    readonly "code-type": string;
+    /** Strings in code. */
+    readonly "code-string": string;
+    /** Numbers in code. */
+    readonly "code-number": string;
+    /** Punctuation in code. */
+    readonly "code-punctuation": string;
+    /** Names in code. */
+    readonly "code-name": string;
+};
+/** The fonts of the shell: a CSS `font-family` value. */
+export type ShellFonts = {
+    /** The interface. */
+    readonly sans?: string;
+    /** Code. */
+    readonly mono?: string;
+};
+/** The corners of the shell: a CSS length. */
+export type ShellRadius = {
+    /** Buttons, fields and rows. */
+    readonly control?: string;
+    /** Cards and panels. */
+    readonly card?: string;
+};
+/** A theme of the shell; everything left out keeps the shell's own. */
+export type ShellTheme = {
+    /** Colours of the light appearance. */
+    readonly light?: Partial<ShellPalette>;
+    /** Colours of the dark appearance. */
+    readonly dark?: Partial<ShellPalette>;
+    /**
+     * Roles taken from the catalogue's design tokens (`tokens` in its configuration), by token name: each role gets the
+     * token's value in both appearances, its `light` and `dark` themes first. `light` and `dark` above win over it.
+     */
+    readonly fromTokens?: Partial<ShellPalette>;
+    /** The fonts. Forgebook ships none: a web font is loaded with `@font-face` in `css`. */
+    readonly fonts?: ShellFonts;
+    /** The corners. */
+    readonly radius?: ShellRadius;
+};
+/** The shell's look, a catalogue's or a preset's. */
+export type ShellOptions = {
+    /** The theme: written into the shell's page at build, with no script. */
+    readonly theme?: ShellTheme;
+    /**
+     * A style sheet loaded after the shell's: by path from the configuration's folder, absolute in a preset. An escape
+     * hatch: it reaches the shell's class names, which are not public API and may change in any release.
+     */
+    readonly css?: string;
+    /**
+     * Whether Forgebook's mark stands in for a catalogue without a logo, in the sidebar and as the page's icon. `false`
+     * leaves the catalogue's own logo and title, or its title alone. On by default; the catalogue's value wins over a
+     * preset's.
+     */
+    readonly branding?: boolean;
+};

package/dist/src/shellTheme.types.js

@@ -0,0 +1,10 @@
+/**
+ * The shape of a catalogue's theme of the shell, as its configuration writes it.
+ *
+ * @remarks
+ * These roles are public API: renaming or removing one is a breaking change, so they are the few a library's look is
+ * made of, and adding one later breaks nobody. Edges, fills and shadows stay the shell's own: they are built from these
+ * on translucency, and freezing them would freeze how the shell draws a card.
+ *
+ * @module
+ */

package/dist/src/sourceFiles.d.ts

@@ -1,6 +1,6 @@
 /**
  * A source's story files as one group: its `?forgebook-files` groups merged, so the tree, the frame and the panel look
- * a file up by its key wherever its pattern was declared.
+ * a file up by its key wherever its pattern was declared; its docs pages the same way.
  *
  * @remarks
  * The keys are paths relative to the module that declared the source, unique across its groups. The merge is kept per
@@ -8,11 +8,25 @@
  *
  * @module
  */
-import type { StoryFiles, StorySource } from "@forgebook/story-format/source";
+import type { DocPages, StoryFiles, StorySource } from "@forgebook/story-format/source";
 /**
  * A source's story files, every group merged.
  *
  * @param source - the source.
  */
 export declare const sourceFiles: (source: StorySource) => StoryFiles;
-//# sourceMappingURL=sourceFiles.d.ts.map
+/** A source's docs pages, every group merged: the search index stays per group (`sourceSearchLoaders`). */
+export type MergedPages = Required<Omit<DocPages, "search">>;
+/**
+ * A source's docs pages, every group merged; empty for a source without any.
+ *
+ * @param source - the source.
+ */
+export declare const sourcePages: (source: StorySource) => MergedPages;
+/**
+ * The loaders of a source's search indexes, one per group: a group's index is read as it comes, so the docs pages' text
+ * is found while a package's props are still being read.
+ *
+ * @param source - the source.
+ */
+export declare const sourceSearchLoaders: (source: StorySource) => readonly (() => Promise<unknown>)[];

package/dist/src/sourceFiles.js

@@ -19,4 +19,30 @@ export const sourceFiles = (source) => {
     MERGED.set(source, merged);
     return merged;
 };
-//# sourceMappingURL=sourceFiles.js.map
+/** The merged docs pages of each source seen, by the source object itself. */
+const MERGED_PAGES = new WeakMap();
+/**
+ * A source's docs pages, every group merged; empty for a source without any.
+ *
+ * @param source - the source.
+ */
+export const sourcePages = (source) => {
+    const known = MERGED_PAGES.get(source);
+    if (known !== undefined)
+        return known;
+    const groups = source.docs ?? [];
+    const merged = {
+        index: Object.assign({}, ...groups.map((group) => group.index)),
+        pages: Object.assign({}, ...groups.map((group) => group.pages)),
+        text: Object.assign({}, ...groups.map((group) => group.text ?? {}))
+    };
+    MERGED_PAGES.set(source, merged);
+    return merged;
+};
+/**
+ * The loaders of a source's search indexes, one per group: a group's index is read as it comes, so the docs pages' text
+ * is found while a package's props are still being read.
+ *
+ * @param source - the source.
+ */
+export const sourceSearchLoaders = (source) => [...source.files, ...(source.docs ?? [])].flatMap((group) => group.search ?? []);

package/dist/src/spills.d.ts

@@ -28,4 +28,3 @@ export type Spill = {
  * @param markAttribute - an attribute set on each element that spills, taken off the others first; none marks nothing.
  */
 export declare const findSpills: (rootSelector: string, markAttribute?: string) => Spill[];
-//# sourceMappingURL=spills.d.ts.map

package/dist/src/spills.js

@@ -62,4 +62,3 @@ export const findSpills = (rootSelector, markAttribute) => {
         return [{ element: pathOf(element), parent: pathOf(parent), by: Math.round(by) }];
     });
 };
-//# sourceMappingURL=spills.js.map

package/dist/src/storyBackground.d.ts

@@ -18,4 +18,3 @@ import { type ViewState } from "./viewState.ts";
  * @returns the CSS colour, or none when the source gives none.
  */
 export declare const storyBackground: (background: StoryBackground | undefined, view: Pick<ViewState, "switches" | "backdrop">, catalogue: Pick<CatalogueSettings, "switches" | "backdrops">, isSystemDark: boolean) => string | undefined;
-//# sourceMappingURL=storyBackground.d.ts.map

package/dist/src/storyBackground.js

@@ -24,4 +24,3 @@ export const storyBackground = (background, view, catalogue, isSystemDark) => {
         return isMoreContrast ? (background.darkMore ?? background.dark) : background.dark;
     return isMoreContrast ? (background.lightMore ?? background.light) : background.light;
 };
-//# sourceMappingURL=storyBackground.js.map

package/dist/src/storyCheck.d.ts

@@ -15,7 +15,7 @@
 import type { CatalogueLists } from "./catalogue.ts";
 import type { ViewSwitch } from "./switches.ts";
 /** What kind of check found a problem. */
-export type StoryProblemKind = "frame" | "axe" | "spill" | "overlay" | "error";
+export type StoryProblemKind = "frame" | "axe" | "spill" | "overlay" | "focus" | "error";
 /** One problem a check found. */
 export type StoryProblem = {
     /** The check that found it. */
@@ -31,10 +31,17 @@ export type StoryProblem = {
 export type StoryCheckStory = {
     /** The story's id. */
     readonly id: string;
+    /**
+     * The id an earlier rule gave it, when it differs from `id`: a baseline stored under that id is still its baseline
+     * until `forgebook shot --update` stores one under its id.
+     */
+    readonly formerId?: string;
     /** Its `parameters.height`, in CSS px, when it declares one: an overlay inside it is not a problem. */
     readonly height?: number;
     /** Whether it is about logic, not looks (`parameters.logic`): every variant then means its default view only. */
     readonly isLogic?: boolean;
+    /** Whether it draws edge to edge in a device (`parameters.device.edgeToEdge`), for a view that names one. */
+    readonly isEdgeToEdge?: boolean;
 };
 /** What a check is asked to do. */
 export type StoryCheckRequest = {
@@ -50,6 +57,24 @@ export type StoryCheckRequest = {
     readonly views: readonly string[];
     /** Check every variant the catalogue's browser tests check instead of the views given. */
     readonly isAllVariants: boolean;
+    /** The model that judges what axe cannot see; none leaves the pages on this machine. */
+    readonly semantic?: SemanticModel;
+};
+/** A model to judge stories with, as the user configured it. */
+export type SemanticModel = {
+    /** The address of an OpenAI-compatible API (`https://api.example.com/v1`). */
+    readonly url: string;
+    /** The model's name. */
+    readonly name: string;
+    /** Its key, when it needs one; only ever sent to `url`. */
+    readonly key?: string;
+};
+/** What a model judged wrong: an opinion to read, never a fact, so it does not fail a check. */
+export type StoryJudgement = {
+    /** The criterion it names (`WCAG 2.4.6`); empty when it named none. */
+    readonly criterion: string;
+    /** What it found. */
+    readonly message: string;
 };
 /** One story in one view, and its problems. */
 export type StoryCheckResult = {
@@ -61,6 +86,8 @@ export type StoryCheckResult = {
     readonly frame: string;
     /** The problems; none when it passes. */
     readonly problems: readonly StoryProblem[];
+    /** What the model judged, when one was asked; a text says why it could not. */
+    readonly judgements?: readonly StoryJudgement[] | string;
 };
 /** What a check found. */
 export type StoryCheckReport = {
@@ -68,6 +95,8 @@ export type StoryCheckReport = {
     readonly schema: 1;
     /** One result per story and view. */
     readonly results: readonly StoryCheckResult[];
+    /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no result ran axe. Absent when it does. */
+    readonly a11y?: "off";
 };
 /**
  * Whether what the testing package answered is a check's report.
@@ -90,6 +119,8 @@ export type StoryShot = {
     readonly frame: string;
     /** The picture, a PNG file's absolute path. */
     readonly file: string;
+    /** Why the story did not draw (`error`, or `silent` when it never said); none when it did. */
+    readonly status?: "error" | "silent";
 };
 /** The pictures taken. */
 export type StoryShotReport = {
@@ -98,10 +129,65 @@ export type StoryShotReport = {
     /** One picture per story and view. */
     readonly shots: readonly StoryShot[];
 };
+/** What a comparison with the baselines is asked. */
+export type StoryDiffRequest = StoryShotRequest & {
+    /** The folder the baselines are in, absolute; never the folder the pictures go in. */
+    readonly baselines: string;
+    /** The component asked for, when one was: its baselines with no story left are reported. */
+    readonly component?: string;
+    /**
+     * The id an earlier rule gave that component, when it differs from `component`: its baselines stored under that id
+     * are its own too.
+     */
+    readonly formerComponent?: string;
+};
+/** How a picture compares with its baseline. */
+export type StoryDiffStatus = "same" | "changed" | "resized" | "new" | "broken" | "removed";
+/** One story in one view against its baseline. */
+export type StoryDiff = {
+    /** The story's id. */
+    readonly storyId: string;
+    /** The view's name; empty for the default view. */
+    readonly view: string;
+    /**
+     * How it compares: `new` has no baseline yet, `resized` cannot be compared pixel by pixel, `broken` did not draw so it
+     * proves nothing, and `removed` is a baseline whose story is gone.
+     */
+    readonly status: StoryDiffStatus;
+    /** The pixels that changed. */
+    readonly changedPixels: number;
+    /** Their share of the picture, 0 to 100; 100 when it was resized. */
+    readonly percent: number;
+    /** The smallest box that holds them, in CSS px at the picture's scale. */
+    readonly region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The baseline's file. */
+    readonly baseline: string;
+    /** The new picture's file. */
+    readonly current: string;
+    /** The new picture with what changed marked. */
+    readonly diff?: string;
+};
+/** The comparison's results. */
+export type StoryDiffReport = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** One result per story and view. */
+    readonly results: readonly StoryDiff[];
+};
+/**
+ * Whether what the testing package answered is a comparison's report.
+ *
+ * @param value - the answer.
+ */
+export declare const isStoryDiffReport: (value: unknown) => value is StoryDiffReport;
 /**
  * Whether what the testing package answered is a picture run's report.
  *
  * @param value - the answer.
  */
 export declare const isStoryShotReport: (value: unknown) => value is StoryShotReport;
-//# sourceMappingURL=storyCheck.d.ts.map

package/dist/src/storyCheck.js

@@ -1,5 +1,5 @@
 /** Every kind, for reading a report back. */
-const KINDS = ["frame", "axe", "spill", "overlay", "error"];
+const KINDS = ["frame", "axe", "spill", "overlay", "focus", "error"];
 /**
  * Whether a value is a problem.
  *
@@ -38,7 +38,19 @@ export const isStoryCheckReport = (value) => typeof value === "object" &&
     value.schema === 1 &&
     "results" in value &&
     Array.isArray(value.results) &&
-    value.results.every(isResult);
+    value.results.every(isResult) &&
+    (!("a11y" in value) || value.a11y === undefined || value.a11y === "off");
+/**
+ * Whether what the testing package answered is a comparison's report.
+ *
+ * @param value - the answer.
+ */
+export const isStoryDiffReport = (value) => typeof value === "object" &&
+    value !== null &&
+    "schema" in value &&
+    value.schema === 1 &&
+    "results" in value &&
+    Array.isArray(value.results);
 /**
  * Whether what the testing package answered is a picture run's report.
  *
@@ -60,4 +72,3 @@ export const isStoryShotReport = (value) => typeof value === "object" &&
         typeof shot.frame === "string" &&
         "file" in shot &&
         typeof shot.file === "string");
-//# sourceMappingURL=storyCheck.js.map

package/dist/src/storyClock.d.ts

@@ -59,4 +59,3 @@ export type ClockReading = {
  * @returns where it stands then.
  */
 export declare const readClock: (reading: ClockReading, state: ClockState, at: number) => ClockReading;
-//# sourceMappingURL=storyClock.d.ts.map

package/dist/src/storyClock.js

@@ -48,4 +48,3 @@ export const readClock = (reading, state, at) => {
     const elapsed = Math.max(0, at - reading.at);
     return { moment: state.isRunning ? reading.moment + elapsed * state.rate : reading.moment, at };
 };
-//# sourceMappingURL=storyClock.js.map

package/dist/src/storyGlobals.d.ts

@@ -57,4 +57,3 @@ export declare const withOwnFixed: (changed: ViewState, own: ViewState, fixed: F
  */
 export declare const isFixedView: (value: unknown) => value is FixedView;
 export {};
-//# sourceMappingURL=storyGlobals.d.ts.map