@connextar/house 0.17.0 → 0.19.0

package/dist/health/health.js

@@ -0,0 +1,93 @@
+/**
+ * A liveness check that says which release is running: `GET /healthz` answers
+ * `ok 0.24.1 2c9a3cf`, so a deploy can be confirmed from outside with one curl.
+ *
+ * Lifted from PharmaLineAI's voice relay (v0.24.1), generalised for the Next.js
+ * apps on Vercel and anything on Render. The endpoint is public, so it says only
+ * a version and a short commit hash, and only when each looks like one: a value
+ * that came from the environment is never echoed as-is. It always answers 200
+ * with `ok` first, which is what a host's health check looks for.
+ *
+ * Liveness only: no database, no provider, nothing that can be slow or fail. A
+ * readiness check is a separate route of the app's own (see the README).
+ *
+ * Imports no package: the route handler is plain web `Request` and `Response`,
+ * which is what a Next route handler takes and returns.
+ */
+/** MAJOR.MINOR.PATCH with an optional pre-release (`1.2.3-rc.1`). No `v`, no build metadata. */
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** A git object name: 7 to 64 hex digits (SHA-1 or SHA-256), nothing else. */
+const HEX_HASH = /^[0-9a-f]{7,64}$/i;
+/**
+ * Where each host puts the commit it deployed, in the order they are read:
+ * Vercel (a system environment variable, exposed by default), Render, then a
+ * `GIT_COMMIT` an app or another host sets itself.
+ */
+export const COMMIT_ENV_VARS = ["VERCEL_GIT_COMMIT_SHA", "RENDER_GIT_COMMIT", "GIT_COMMIT"];
+/**
+ * The build from a version (package.json's, passed in) and the commit the host
+ * deployed, cut to 7. A version that isn't semver-shaped is dropped; the commit
+ * is the first of `COMMIT_ENV_VARS` that is a whole hex hash, so a variable set
+ * to something else is skipped rather than repeated on a public page.
+ */
+export function buildInfo(version, env = process.env) {
+    const v = typeof version === "string" ? version.trim() : "";
+    const commit = COMMIT_ENV_VARS.map((name) => (env[name] ?? "").trim()).find((value) => HEX_HASH.test(value));
+    return {
+        ...(SEMVER.test(v) ? { version: v } : {}),
+        ...(commit ? { commit: commit.slice(0, 7).toLowerCase() } : {}),
+    };
+}
+/** What the check says: `ok`, then the version and commit when known — `ok 1.2.3 abc1234`. */
+export function healthText(build = {}) {
+    return ["ok", build.version, build.commit].filter(Boolean).join(" ");
+}
+/**
+ * The format a request asks for: `?format=json` or `?format=text` first, then an
+ * `Accept` header that names `application/json`. Anything else — a browser, curl's
+ * `*\/*`, a host's checker — gets text.
+ */
+export function healthFormat(request) {
+    const asked = new URL(request.url).searchParams.get("format")?.trim().toLowerCase();
+    if (asked === "json" || asked === "text")
+        return asked;
+    const accept = (request.headers.get("accept") ?? "").toLowerCase();
+    return /(^|[\s,])application\/json(\s*;|\s*,|\s*$)/.test(accept) ? "json" : "text";
+}
+const HEADERS = {
+    // A health check must never be answered from a cache: it would say a deploy is live that isn't.
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+};
+/** The answer itself: 200, `text/plain` by default, `{ status: "ok", version, commit }` as JSON. */
+export function healthResponse(build = {}, { format = "text" } = {}) {
+    if (format === "json") {
+        const body = {
+            status: "ok",
+            ...(build.version ? { version: build.version } : {}),
+            ...(build.commit ? { commit: build.commit } : {}),
+        };
+        return new Response(JSON.stringify(body), {
+            status: 200,
+            headers: { ...HEADERS, "content-type": "application/json; charset=utf-8" },
+        });
+    }
+    return new Response(healthText(build), {
+        status: 200,
+        headers: { ...HEADERS, "content-type": "text/plain; charset=utf-8" },
+    });
+}
+/**
+ * A Next route handler for `app/healthz/route.ts`, where `pkg` is the app's own package.json
+ * imported in that file (a route file is server-only, so it never reaches the browser):
+ *
+ *     export const { GET } = createHealthRoute({ version: pkg.version });
+ *
+ * Next answers `HEAD` from `GET` on its own.
+ */
+export function createHealthRoute({ version, env }) {
+    return {
+        GET: (request) => healthResponse(buildInfo(version, env ?? process.env), { format: healthFormat(request) }),
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/health/health.js.map

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

package/dist/health/index.d.ts

@@ -0,0 +1,2 @@
+export { buildInfo, COMMIT_ENV_VARS, createHealthRoute, healthFormat, healthResponse, healthText, type BuildInfo, type HealthFormat, type HealthRouteOptions, } from "./health.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/health/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC"}

package/dist/health/index.js

@@ -0,0 +1,2 @@
+export { buildInfo, COMMIT_ENV_VARS, createHealthRoute, healthFormat, healthResponse, healthText, } from "./health.js";
+//# sourceMappingURL=index.js.map

package/dist/health/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,UAAU,GAIX,MAAM,aAAa,CAAC"}

package/dist/markdown/figure.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+import type { GuideFigureBlock, GuideFigures } from "./figures.js";
+/** Every element a guide's picture draws. Each value replaces the default for that element. */
+export interface GuideFigureClassNames {
+    figure: string;
+    /** Every screenshot `<img>`. */
+    image: string;
+    /** Added to a screenshot with no dark capture: a light picture on a dark page, toned down so it doesn't glare. */
+    imageWithoutDark: string;
+    /** Added to the light capture when there is a dark one. */
+    imageLight: string;
+    /** Added to the dark capture. */
+    imageDark: string;
+    /** The frame a diagram sits in. */
+    diagram: string;
+    caption: string;
+}
+/** The house look, on the shared theme tokens (PharmaLineAI's). */
+export declare const GUIDE_FIGURE_CLASS_NAMES: GuideFigureClassNames;
+/**
+ * A registered diagram, drawn: a component is given the alt text as `label`; an element is
+ * wrapped in `role="img"` with the alt text as its name. Null when the name isn't registered.
+ */
+export declare function drawGuideDiagram(figures: GuideFigures | undefined, name: string, label: string): ReactNode;
+export interface GuideFigureMediaProps {
+    figure: GuideFigureBlock;
+    figures?: GuideFigures;
+    classNames?: Partial<GuideFigureClassNames>;
+    /** Load the screenshot straight away rather than when it nears the screen. Default: lazy. */
+    eager?: boolean;
+}
+/**
+ * The picture itself, without its caption: a screenshot at its registered size (and its dark
+ * capture beside it when there is one, each shown by the theme's `dark:` variant), or a diagram
+ * in its frame.
+ */
+export declare function GuideFigureMedia({ figure, figures, classNames, eager }: GuideFigureMediaProps): ReactNode;
+export interface GuideFigureViewProps extends GuideFigureMediaProps {
+    /** Drawn in place of the plain picture — `GuideArticle` puts its zoom button here. */
+    media?: ReactNode;
+}
+/** A picture with its caption, as a `<figure>`. Server-safe; no zoom (`GuideArticle` adds that). */
+export declare function GuideFigureView({ figure, figures, classNames, eager, media }: GuideFigureViewProps): ReactNode;
+//# sourceMappingURL=figure.d.ts.map

package/dist/markdown/figure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figure.d.ts","sourceRoot":"","sources":["../../src/markdown/figure.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG1F,OAAO,KAAK,EAAgB,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjF,+FAA+F;AAC/F,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,EAAE,qBAStC,CAAC;AAQF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAU1G;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5C,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,qBAAqB,GAAG,SAAS,CAwBzG;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,sFAAsF;IACtF,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,oBAAoB,GAAG,SAAS,CAQ9G"}

package/dist/markdown/figure.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createElement, isValidElement } from "react";
+import { cx } from "../internal/cx.js";
+/** The house look, on the shared theme tokens (PharmaLineAI's). */
+export const GUIDE_FIGURE_CLASS_NAMES = {
+    figure: "my-8",
+    // No display utility here: a dark capture is `hidden dark:block`, and two display utilities on one element fight.
+    image: "h-auto w-full rounded-xl border border-border bg-card align-top shadow-sm",
+    imageWithoutDark: "dark:brightness-[0.92]",
+    imageLight: "dark:hidden",
+    imageDark: "hidden dark:block",
+    diagram: "rounded-xl border border-border bg-card/60 px-3 py-5 sm:px-6",
+    caption: "mt-2.5 text-center text-sm text-muted-foreground",
+};
+/** A component (function, `memo`, `forwardRef`) rather than an element or text. */
+function isComponent(entry) {
+    if (typeof entry === "function")
+        return true;
+    return typeof entry === "object" && entry !== null && !isValidElement(entry) && "$$typeof" in entry;
+}
+/**
+ * A registered diagram, drawn: a component is given the alt text as `label`; an element is
+ * wrapped in `role="img"` with the alt text as its name. Null when the name isn't registered.
+ */
+export function drawGuideDiagram(figures, name, label) {
+    const diagrams = figures?.diagrams;
+    if (!diagrams || !Object.prototype.hasOwnProperty.call(diagrams, name))
+        return null;
+    const entry = diagrams[name];
+    if (isComponent(entry))
+        return createElement(entry, { label });
+    return (_jsx("div", { role: "img", "aria-label": label, children: entry }));
+}
+/**
+ * The picture itself, without its caption: a screenshot at its registered size (and its dark
+ * capture beside it when there is one, each shown by the theme's `dark:` variant), or a diagram
+ * in its frame.
+ */
+export function GuideFigureMedia({ figure, figures, classNames, eager }) {
+    const c = { ...GUIDE_FIGURE_CLASS_NAMES, ...classNames };
+    if (figure.kind === "diagram") {
+        return _jsx("div", { className: c.diagram, children: drawGuideDiagram(figures, figure.name, figure.alt) });
+    }
+    const img = (src, className) => (
+    // A plain <img>: the package imports no app's image pipeline. The registered size reserves the space.
+    _jsx("img", { src: src, alt: figure.alt, width: figure.width, height: figure.height, loading: eager ? "eager" : "lazy", decoding: "async", className: className }));
+    if (!figure.dark)
+        return img(figure.src, cx(c.image, c.imageWithoutDark));
+    return (_jsxs(_Fragment, { children: [img(figure.src, cx(c.image, c.imageLight)), img(figure.dark, cx(c.image, c.imageDark))] }));
+}
+/** A picture with its caption, as a `<figure>`. Server-safe; no zoom (`GuideArticle` adds that). */
+export function GuideFigureView({ figure, figures, classNames, eager, media }) {
+    const c = { ...GUIDE_FIGURE_CLASS_NAMES, ...classNames };
+    return (_jsxs("figure", { className: c.figure, children: [media ?? _jsx(GuideFigureMedia, { figure: figure, figures: figures, classNames: classNames, eager: eager }), figure.caption ? _jsx("figcaption", { className: c.caption, children: figure.caption }) : null] }));
+}
+//# sourceMappingURL=figure.js.map

package/dist/markdown/figure.js.map

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

package/dist/markdown/figures.d.ts

@@ -0,0 +1,94 @@
+import type { ComponentType, ReactNode } from "react";
+/**
+ * Pictures in the guides: screenshots and diagrams, written in a guide's Markdown as
+ * an image on a line of its own, with a blank line either side:
+ *
+ *     ![What the picture shows, for someone who can't see it](/guide-images/calls-log.webp "Caption")
+ *     ![What the diagram shows](diagram:identity-check)
+ *
+ * Only pictures in the app's registry are drawn — a guide can't pull an image in from
+ * anywhere else, and a typo never shows a broken image — each with its width and height
+ * so the page doesn't jump as it loads. `guideFigureProblems` is the check an app's test
+ * asserts empty: an unregistered picture, missing alt text, or a picture inside a list or
+ * paragraph.
+ *
+ * Lifted from PharmaLineAI v0.23.1 (`lib/guide-figures.ts`). Pure: no file access, no
+ * React at run time.
+ */
+/** A screenshot in the app's `public/guide-images/`, with its size so the page doesn't jump. */
+export interface GuideScreenshot {
+    width: number;
+    height: number;
+    /** A dark-mode capture of the same screen, at the same size, shown instead under `dark:`. */
+    dark?: string;
+}
+/**
+ * A diagram: an element to draw as it is, or a component given the picture's alt text as
+ * `label` (to put on its own `<svg role="img" aria-label>`).
+ */
+export type GuideDiagram = ReactNode | ComponentType<{
+    label: string;
+}>;
+/** Every picture a guide may show. */
+export interface GuideFigures {
+    /** By public path: `"/guide-images/calls-log.webp": { width: 1600, height: 986 }`. */
+    screenshots: Readonly<Record<string, GuideScreenshot>>;
+    /** By name, as a guide writes it after `diagram:`. */
+    diagrams?: Readonly<Record<string, GuideDiagram>>;
+}
+/** A picture line as written, before it is looked up. */
+export interface GuideFigureLine {
+    alt: string;
+    src: string;
+    caption?: string;
+}
+export type GuideFigureBlock = {
+    kind: "screenshot";
+    src: string;
+    alt: string;
+    caption?: string;
+    width: number;
+    height: number;
+    dark?: string;
+} | {
+    kind: "diagram";
+    name: string;
+    alt: string;
+    caption?: string;
+};
+export type GuideBlock = {
+    kind: "markdown";
+    content: string;
+} | GuideFigureBlock;
+export declare const DIAGRAM_PREFIX = "diagram:";
+/** A picture line, or null when the line isn't one. */
+export declare function parseFigureLine(line: string): GuideFigureLine | null;
+/** The picture a line names, or null when it names nothing in the registry or has no alt text. */
+export declare function resolveGuideFigure(line: GuideFigureLine, figures: GuideFigures | undefined): GuideFigureBlock | null;
+/**
+ * A guide body as runs of Markdown and the pictures between them. A picture line that
+ * names nothing in the registry is dropped; inside a code fence a picture line is just
+ * code. `GuideMarkdown` draws figures in the same places itself, keeping every heading's
+ * id — this is the same split as data, for an app's own layout or its tests.
+ */
+export declare function splitGuideFigures(body: string, figures: GuideFigures | undefined): GuideBlock[];
+export interface GuideFigureCheckOptions {
+    /** The shortest alt text accepted. Default 1 — any; PharmaLine asks for more than 20. */
+    minAltLength?: number;
+}
+/**
+ * Every way a guide's pictures would fail to show as written, as sentences with line
+ * numbers. An app's test asserts it is empty for each guide:
+ *
+ *     expect(guideFigureProblems(body, GUIDE_FIGURES)).toEqual([]);
+ *
+ * - a picture that isn't registered (a screenshot path or a `diagram:` name);
+ * - a picture with no alt text, or shorter than `minAltLength`;
+ * - a picture without a blank line either side — inside a list it would end the list and
+ *   restart its numbering after it; inside a paragraph it would split it;
+ * - an image written inside a line of text, which is never drawn.
+ *
+ * Lines inside code fences, and images inside inline code, are left alone.
+ */
+export declare function guideFigureProblems(body: string, figures: GuideFigures | undefined, { minAltLength }?: GuideFigureCheckOptions): string[];
+//# sourceMappingURL=figures.d.ts.map

package/dist/markdown/figures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figures.d.ts","sourceRoot":"","sources":["../../src/markdown/figures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AAEH,gGAAgG;AAChG,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAExE,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACvD,sDAAsD;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CACnD;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAAC;AAMlF,eAAO,MAAM,cAAc,aAAa,CAAC;AAMzC,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAKpE;AAED,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAkBpH;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,UAAU,EAAE,CAsB/F;AAED,MAAM,WAAW,uBAAuB;IACtC,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,EAAE,YAAgB,EAAE,GAAE,uBAA4B,GACjD,MAAM,EAAE,CAyCV"}

package/dist/markdown/figures.js

@@ -0,0 +1,126 @@
+/** An image alone on its line: `![alt](src)` or `![alt](src "caption")`. */
+const IMAGE_LINE = /^!\[([^\]]*)\]\(\s*(\S+?)(?:\s+"([^"]*)")?\s*\)$/;
+/** An image anywhere in a line, for the check that one isn't written inside a paragraph. */
+const INLINE_IMAGE = /!\[[^\]]*\]\([^)]*\)/;
+export const DIAGRAM_PREFIX = "diagram:";
+const isFence = (line) => line.trim().startsWith("```");
+const own = (record, key) => record && Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+/** A picture line, or null when the line isn't one. */
+export function parseFigureLine(line) {
+    const match = line.trim().match(IMAGE_LINE);
+    if (!match)
+        return null;
+    const caption = match[3]?.trim();
+    return { alt: (match[1] ?? "").trim(), src: match[2] ?? "", ...(caption ? { caption } : {}) };
+}
+/** The picture a line names, or null when it names nothing in the registry or has no alt text. */
+export function resolveGuideFigure(line, figures) {
+    if (!line.alt || !figures)
+        return null;
+    const caption = line.caption ? { caption: line.caption } : {};
+    if (line.src.startsWith(DIAGRAM_PREFIX)) {
+        const name = line.src.slice(DIAGRAM_PREFIX.length);
+        return own(figures.diagrams, name) === undefined ? null : { kind: "diagram", name, alt: line.alt, ...caption };
+    }
+    const shot = own(figures.screenshots, line.src);
+    if (!shot)
+        return null;
+    return {
+        kind: "screenshot",
+        src: line.src,
+        alt: line.alt,
+        ...caption,
+        width: shot.width,
+        height: shot.height,
+        ...(shot.dark ? { dark: shot.dark } : {}),
+    };
+}
+/**
+ * A guide body as runs of Markdown and the pictures between them. A picture line that
+ * names nothing in the registry is dropped; inside a code fence a picture line is just
+ * code. `GuideMarkdown` draws figures in the same places itself, keeping every heading's
+ * id — this is the same split as data, for an app's own layout or its tests.
+ */
+export function splitGuideFigures(body, figures) {
+    const blocks = [];
+    let run = [];
+    let inFence = false;
+    const flush = () => {
+        const content = run.join("\n");
+        if (content.trim())
+            blocks.push({ kind: "markdown", content });
+        run = [];
+    };
+    for (const line of body.replace(/\r\n/g, "\n").split("\n")) {
+        if (isFence(line))
+            inFence = !inFence;
+        const parsed = inFence ? null : parseFigureLine(line);
+        if (!parsed) {
+            run.push(line);
+            continue;
+        }
+        flush();
+        const figure = resolveGuideFigure(parsed, figures);
+        if (figure)
+            blocks.push(figure);
+    }
+    flush();
+    return blocks;
+}
+/**
+ * Every way a guide's pictures would fail to show as written, as sentences with line
+ * numbers. An app's test asserts it is empty for each guide:
+ *
+ *     expect(guideFigureProblems(body, GUIDE_FIGURES)).toEqual([]);
+ *
+ * - a picture that isn't registered (a screenshot path or a `diagram:` name);
+ * - a picture with no alt text, or shorter than `minAltLength`;
+ * - a picture without a blank line either side — inside a list it would end the list and
+ *   restart its numbering after it; inside a paragraph it would split it;
+ * - an image written inside a line of text, which is never drawn.
+ *
+ * Lines inside code fences, and images inside inline code, are left alone.
+ */
+export function guideFigureProblems(body, figures, { minAltLength = 1 } = {}) {
+    const lines = body.replace(/\r\n/g, "\n").split("\n");
+    const problems = [];
+    let inFence = false;
+    lines.forEach((line, i) => {
+        if (isFence(line)) {
+            inFence = !inFence;
+            return;
+        }
+        if (inFence)
+            return;
+        const at = `Line ${i + 1}`;
+        const parsed = parseFigureLine(line);
+        if (!parsed) {
+            if (INLINE_IMAGE.test(line.replace(/`[^`]*`/g, ""))) {
+                problems.push(`${at}: a picture inside a line of text is never drawn; put it on a line of its own.`);
+            }
+            return;
+        }
+        const what = `\`${parsed.src}\``;
+        if (parsed.src.startsWith(DIAGRAM_PREFIX)) {
+            if (own(figures?.diagrams, parsed.src.slice(DIAGRAM_PREFIX.length)) === undefined) {
+                problems.push(`${at}: ${what} isn't a registered diagram.`);
+            }
+        }
+        else if (!own(figures?.screenshots, parsed.src)) {
+            problems.push(`${at}: ${what} isn't a registered screenshot.`);
+        }
+        if (!parsed.alt)
+            problems.push(`${at}: ${what} has no alt text.`);
+        else if (parsed.alt.length < minAltLength) {
+            problems.push(`${at}: ${what} has alt text shorter than ${minAltLength} characters.`);
+        }
+        if ((lines[i - 1] ?? "").trim() !== "" || (lines[i + 1] ?? "").trim() !== "") {
+            problems.push(`${at}: ${what} needs a blank line before and after it (a picture can't sit inside a list).`);
+        }
+        else if (/^\s/.test(line)) {
+            problems.push(`${at}: ${what} is indented as if inside a list; a picture ends the list, so start it at the margin.`);
+        }
+    });
+    return problems;
+}
+//# sourceMappingURL=figures.js.map

package/dist/markdown/figures.js.map

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

package/dist/markdown/guide.d.ts

@@ -1,4 +1,6 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
+import { type GuideFigureClassNames } from "./figure.js";
+import { type GuideFigureBlock, type GuideFigures } from "./figures.js";
 import { type MarkdownTableClassNames } from "./table-view.js";
 /**
  * The help-centre guide renderer: Markdown files under `docs/guides/` drawn as a
@@ -14,7 +16,8 @@ import { type MarkdownTableClassNames } from "./table-view.js";
  *
  * The syntax is the constrained subset guides use: `##`–`####` headings,
  * paragraphs, blockquotes, ordered and unordered lists, tables, fenced code,
- * horizontal rules, and inline bold, italic, code and links. Raw HTML is never
+ * horizontal rules, inline bold, italic, code and links, and pictures from the
+ * app's registry on a line of their own (`figures.ts`). Raw HTML is never
  * interpreted, so a guide cannot put markup on a public page.
  *
  * Server-safe: no hooks, no client boundary.
@@ -70,7 +73,13 @@ export interface GuideLinkOptions {
  * protocol-relative `//host` — becomes `#`.
  */
 export declare function resolveGuideHref(href: string, { guidesPath, indexSlug }?: GuideLinkOptions): string;
-/** Every element a guide draws. Each value replaces the default for that element. */
+/**
+ * Every element a guide draws. Each value replaces the default for that element.
+ *
+ * `table` and `figure` are each a set of parts, merged over the house's, and optional: an app that
+ * writes out a whole `GuideClassNames` (KRP's palette classes) needn't name a part it doesn't
+ * restyle, and a set of parts added in a later release can't break its typecheck.
+ */
 export interface GuideClassNames {
     h2: string;
     h3: string;
@@ -85,14 +94,24 @@ export interface GuideClassNames {
     code: string;
     pre: string;
     hr: string;
-    table: Partial<MarkdownTableClassNames>;
+    table?: Partial<MarkdownTableClassNames>;
+    /** Left out, the house's picture classes (`GUIDE_FIGURE_CLASS_NAMES`). */
+    figure?: Partial<GuideFigureClassNames>;
 }
-/** The house look, on the shared theme tokens. */
-export declare const GUIDE_CLASS_NAMES: GuideClassNames;
+/** The house look, on the shared theme tokens. Every part named, so `GUIDE_CLASS_NAMES.figure` is always there. */
+export declare const GUIDE_CLASS_NAMES: Required<GuideClassNames>;
 export interface GuideMarkdownProps extends GuideLinkOptions {
     content: string;
     classNames?: Partial<GuideClassNames>;
+    /**
+     * The pictures a guide may show. A picture line (`![alt](/guide-images/x.webp "Caption")`
+     * or `![alt](diagram:name)`, alone on its line) is drawn only when it is registered here
+     * and has alt text; otherwise it is left out, never drawn as a broken image.
+     */
+    figures?: GuideFigures;
+    /** Draws each registered picture. Default: `GuideFigureView`, a plain `<figure>`; `GuideArticle` adds zoom. */
+    renderFigure?: (figure: GuideFigureBlock) => ReactNode;
 }
 /** Render a guide body. */
-export declare function GuideMarkdown({ content, guidesPath, indexSlug, classNames }: GuideMarkdownProps): ReactNode;
+export declare function GuideMarkdown({ content, guidesPath, indexSlug, classNames, figures, renderFigure, }: GuideMarkdownProps): ReactNode;
 //# sourceMappingURL=guide.d.ts.map

package/dist/markdown/guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/markdown/guide.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AASD,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CA0BnE;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAQ3D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAkB5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAmC3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAsB,EAAE,SAAS,EAAE,GAAE,gBAAqB,GAAG,MAAM,CAUnH;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACzC;AAED,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,eAiB/B,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACvC;AAED,2BAA2B;AAC3B,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAoL3G"}
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/markdown/guide.tsx"],"names":[],"mappings":"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"}

package/dist/markdown/guide.js

@@ -1,5 +1,8 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment } from "react";
 import { Link } from "../internal/next-link.js";
+import { GuideFigureView } from "./figure.js";
+import { parseFigureLine, resolveGuideFigure } from "./figures.js";
 import { readTable, isTableStart } from "./table.js";
 import { MarkdownTableView } from "./table-view.js";
 const lines = (markdown) => markdown.replace(/\r\n/g, "\n").split("\n");
@@ -147,7 +150,7 @@ export function resolveGuideHref(href, { guidesPath = "/guides", indexSlug } = {
         return href;
     return "#";
 }
-/** The house look, on the shared theme tokens. */
+/** The house look, on the shared theme tokens. Every part named, so `GUIDE_CLASS_NAMES.figure` is always there. */
 export const GUIDE_CLASS_NAMES = {
     h2: "mt-12 scroll-mt-24 text-2xl font-bold tracking-tight text-foreground",
     h3: "mt-8 scroll-mt-24 text-lg font-semibold text-foreground",
@@ -165,12 +168,20 @@ export const GUIDE_CLASS_NAMES = {
     pre: "my-6 overflow-x-auto rounded-xl border border-border bg-muted/60 p-4 font-mono text-[0.85em] leading-relaxed text-foreground",
     hr: "my-8 border-border",
     table: {},
+    figure: {},
 };
 /** Render a guide body. */
-export function GuideMarkdown({ content, guidesPath, indexSlug, classNames }) {
-    const c = { ...GUIDE_CLASS_NAMES, ...classNames };
-    // `table` is itself a set of parts, so an override of one part keeps the rest.
-    c.table = { ...GUIDE_CLASS_NAMES.table, ...classNames?.table };
+export function GuideMarkdown({ content, guidesPath, indexSlug, classNames, figures, renderFigure, }) {
+    // `table` and `figure` are each a set of parts, so an override of one part keeps the rest, and leaving one out
+    // (or passing it as undefined) keeps the house's.
+    const c = {
+        ...GUIDE_CLASS_NAMES,
+        ...classNames,
+        table: { ...GUIDE_CLASS_NAMES.table, ...classNames?.table },
+        figure: { ...GUIDE_CLASS_NAMES.figure, ...classNames?.figure },
+    };
+    const drawFigure = renderFigure ??
+        ((figure) => _jsx(GuideFigureView, { figure: figure, figures: figures, classNames: c.figure }));
     const linkOptions = {
         ...(guidesPath === undefined ? {} : { guidesPath }),
         ...(indexSlug === undefined ? {} : { indexSlug }),
@@ -190,7 +201,8 @@ export function GuideMarkdown({ content, guidesPath, indexSlug, classNames }) {
             trimmed.startsWith(">") ||
             isRule(line) ||
             isFence(line) ||
-            isTableStart(all, at));
+            isTableStart(all, at) ||
+            parseFigureLine(line) !== null);
     };
     /** A list: each item, with any wrapped lines that follow it folded in. */
     const readList = (isItem, marker) => {
@@ -255,6 +267,15 @@ export function GuideMarkdown({ content, guidesPath, indexSlug, classNames }) {
             blocks.push(_jsx("blockquote", { className: c.blockquote, children: inline(quote.join(" "), `q${key}`) }, key++));
             continue;
         }
+        // A picture on a line of its own. Unregistered or undescribed, it is left out rather than drawn broken.
+        const picture = parseFigureLine(line);
+        if (picture) {
+            const figure = resolveGuideFigure(picture, figures);
+            if (figure)
+                blocks.push(_jsx(Fragment, { children: drawFigure(figure) }, key++));
+            i++;
+            continue;
+        }
         const table = readTable(all, i);
         if (table) {
             const tableKey = key++;