@nanisoft/prism-ui 0.7.0 → 0.8.0

package/dist/components/ui/slider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../../../src/components/ui/slider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC;IAC3F,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED;;;;;;;;GAQG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,GAAG,KAAK,EACT,EAAE,WAAW,+BAiCb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../../../src/components/ui/slider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC1E,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED;;;;;;;;GAQG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,GAAG,KAAK,EACT,EAAE,WAAW,+BAiCb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/tree.d.ts

@@ -0,0 +1,115 @@
+import { type ReactNode } from 'react';
+/**
+ * A node a reader can arrive at: a title and the address it is read at.
+ *
+ * `href` is required. A node in a tree that goes nowhere is an entry a reader can
+ * focus and not follow, and this Component renders every node with a destination
+ * as a native anchor so a reader can see where it goes before taking it.
+ */
+export type TreeNodePage = {
+    type: 'page';
+    /** The words the reader meets. */
+    title: string;
+    /** The address the node is read at. */
+    href: string;
+};
+/**
+ * A label over a list of nodes, at any depth.
+ *
+ * `href` is the group's own index and it is optional on purpose. A group with no
+ * index is a place in the tree and not a route, so this Component renders it as a
+ * label: no anchor, no `href`, nothing focusable. Inventing a route for it would
+ * publish an address that resolves to nothing.
+ *
+ * `items` is required, because a group that renders a label and holds nothing is
+ * an empty entry rather than a group. Pass a node with no children rather than a
+ * group with none.
+ */
+export type TreeNodeGroup = {
+    type: 'group';
+    /** The words on the label. A status inside them stays inside them. */
+    title: string;
+    /** The group's own index, where it has one. Omit it for a label over a list. */
+    href?: string;
+    /** The nodes under this group, in the order a reader should meet them. */
+    items: readonly TreeNode[];
+};
+/**
+ * A rule between nodes, carrying a name that is usually empty.
+ *
+ * It is a label and never a link. The alternative spelling, a page node with an
+ * empty `href`, is a control that cannot be operated, so a rule is its own type.
+ */
+export type TreeNodeDivider = {
+    type: 'divider';
+    /** The words on the rule, which may be the empty string. */
+    title: string;
+};
+/**
+ * One node in a tree, of any of the three kinds.
+ *
+ * The union is closed, and it is a union rather than one shape with optional
+ * fields because a reader meets three different things in a tree: a destination, a
+ * label over a list, and a rule. A single shape would make all three look alike,
+ * and "a place that is a heading, not a link" is the distinction the whole
+ * arrangement turns on.
+ */
+export type TreeNode = TreeNodePage | TreeNodeGroup | TreeNodeDivider;
+/** The props the Tree accepts. */
+export interface TreeProps {
+    /** The nodes, in the order a reader should meet them. */
+    nodes: readonly TreeNode[];
+    /**
+     * The address the reader is currently at, which is what marks the current node.
+     *
+     * The marking is the attribute and not a class, so it survives a theme change and
+     * does not depend on a colour a reader may not distinguish.
+     */
+    currentHref?: string;
+    /**
+     * The accessible name of the tree, read before its nodes.
+     *
+     * Required rather than defaulted, because a tree with no name is announced as
+     * "tree" and a page with two of them is a page where a reader cannot tell which
+     * is which. The name is the caller's word.
+     */
+    label: string;
+    /** Layout only. */
+    className?: string;
+    /**
+     * The words a reader is told when the tree is empty, and optionally what to do
+     * about it.
+     *
+     * A tree that renders nothing is a control with nothing in it, so the empty case
+     * is authored rather than left to a caller to notice.
+     */
+    empty?: {
+        message: string;
+        action?: ReactNode;
+    };
+}
+/**
+ * A tree of nodes, given as data.
+ *
+ * This is the third of the three primitives the expansion found missing, and the
+ * one with a different kind of work behind it: the implementation already existed
+ * as two private renderers inside the documentation Page, with its depth rule, its
+ * `aria-current` marking and its rule that a group with no index renders a label.
+ * What was missing was that it was unreachable, and that its data type was bound
+ * to documentation navigation rather than being a tree's own vocabulary. So this is
+ * a promotion rather than a second implementation, and the reasoning in the
+ * documentation Page is carried across rather than rewritten.
+ *
+ * **A flat list renders a flat tree.** An outline is a tree of depth one, so a
+ * caller passes leaves and gets leaves. A Component that required nesting to
+ * express a flat structure would make the common case the awkward one.
+ *
+ * **The Page keeps its own renderers and does not change.** Its two rules, that a
+ * section carries no status or count and that a group with no index is a label,
+ * are specific to a documentation rail and are reasoned at length in the design
+ * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
+ * Page composes this Component later is a decision this ticket does not make.
+ */
+declare function Tree({ nodes, currentHref, label, className, empty }: TreeProps): import("react").JSX.Element;
+export { Tree };
+//# sourceMappingURL=tree.d.ts.map

package/dist/components/ui/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tree.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;AAErE,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;CAChD;AAqKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,SAAS,+BAkEvE;AAED,OAAO,EAAE,IAAI,EAAE,CAAA"}

package/dist/components/ui/tree.js

@@ -0,0 +1,137 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { cn } from '../../lib/utils';
+/** Whether a group's subtree contains the current address, at any depth. */
+function containsHref(nodes, currentHref) {
+    if (currentHref === undefined)
+        return false;
+    for (const node of nodes) {
+        if (node.type === 'page' && node.href === currentHref)
+            return true;
+        if (node.type === 'group') {
+            if (node.href === currentHref)
+                return true;
+            if (containsHref(node.items, currentHref))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether an address is the current one or lies under it, for a heading's emphasis. */
+function under(href, currentHref) {
+    if (currentHref === undefined)
+        return false;
+    return currentHref === href || currentHref.startsWith(`${href}/`);
+}
+function TreeLevel({ nodes, currentHref, depth, }) {
+    return (_jsx("ul", { "data-slot": "tree-list", "data-depth": depth, 
+        // `group` on the list, not `treeitem`: the items are the things a reader
+        // navigates between, and a `ul` of them is a group. `role="none"` on each
+        // item below removes the listitem role so that only the anchors and labels
+        // are the navigable things, which is what lets a caller's own keyboard model
+        // move between them without a roving tabindex fighting the document's.
+        role: "group", className: cn('border-border flex flex-col gap-1 border-l', 
+        // One level of indent per nested group and none at the top, so the depth
+        // reads from the rule rather than from the words.
+        depth > 0 && 'ps-3'), children: nodes.map((node, index) => (_jsx(TreeItem, { node: node, currentHref: currentHref, depth: depth }, `${node.type}:${index}`))) }));
+}
+function TreeItem({ node, currentHref, depth, }) {
+    if (node.type === 'divider') {
+        // A rule between nodes. It is a label, so it is not focusable and a reader
+        // does not meet it as a destination, and the empty title renders no words
+        // above the hairline rather than a word a reader has to interpret.
+        return (_jsx("li", { "data-slot": "tree-divider", role: "none", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: node.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: node.title })) : null }));
+    }
+    if (node.type === 'group') {
+        return (_jsx("li", { "data-slot": "tree-group", role: "none", children: _jsxs("div", { className: "flex flex-col gap-1", children: [node.href === undefined ? (
+                    /*
+                     * A group with no index is a tree item that is not a destination, so it
+                     * carries `role="treeitem"` and its level and nothing else. It is not a
+                     * bare span: `aria-level` on an element with no role is prohibited
+                     * rather than ignored, which the accessibility gate caught the first
+                     * time this was rendered, and a reader needs the level to place a label
+                     * that has no anchor to place it by.
+                     */
+                    _jsx("span", { "data-slot": "tree-label", role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(node.items, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })) : (_jsx("a", { "data-slot": "tree-heading", href: node.href, role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(node.href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })), node.items.length > 0 ? (_jsx(TreeLevel, { nodes: node.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+    }
+    return (_jsx("li", { "data-slot": "tree-item", role: "none", children: _jsx("a", { "data-slot": "tree-link", href: node.href, 
+            // A destination in a tree is a `treeitem`, not a link with a level hung
+            // off it: the level belongs to the item, and a reader placing it in the
+            // tree is reading the item rather than the anchor inside it.
+            role: "treeitem", "aria-level": depth + 1, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === node.href
+                ? 'text-foreground border-primary font-medium'
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: node.title }) }));
+}
+/**
+ * A tree of nodes, given as data.
+ *
+ * This is the third of the three primitives the expansion found missing, and the
+ * one with a different kind of work behind it: the implementation already existed
+ * as two private renderers inside the documentation Page, with its depth rule, its
+ * `aria-current` marking and its rule that a group with no index renders a label.
+ * What was missing was that it was unreachable, and that its data type was bound
+ * to documentation navigation rather than being a tree's own vocabulary. So this is
+ * a promotion rather than a second implementation, and the reasoning in the
+ * documentation Page is carried across rather than rewritten.
+ *
+ * **A flat list renders a flat tree.** An outline is a tree of depth one, so a
+ * caller passes leaves and gets leaves. A Component that required nesting to
+ * express a flat structure would make the common case the awkward one.
+ *
+ * **The Page keeps its own renderers and does not change.** Its two rules, that a
+ * section carries no status or count and that a group with no index is a label,
+ * are specific to a documentation rail and are reasoned at length in the design
+ * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
+ * Page composes this Component later is a decision this ticket does not make.
+ */
+function Tree({ nodes, currentHref, label, className, empty }) {
+    const root = useRef(null);
+    /**
+     * The keyboard model, and the reason it lives here rather than in a caller's.
+     *
+     * A tree is one Tab stop, and the arrow keys move inside it. That is the ARIA
+     * pattern, and a consumer who composes the markup themselves gets the Tab order
+     * of the document instead, which is every node in the tree and none of the
+     * arrows. A roving tabindex is the mechanism: one node is tabbable at a time and
+     * the arrows move which one.
+     *
+     * The flat order is collected from the DOM rather than computed from the node
+     * data, because the DOM is what a reader actually moves through and computing a
+     * second order from the data is a second list to fall behind the first. Only
+     * focusable nodes take part, so a label that is not a destination is skipped
+     * rather than focused and doing nothing.
+     */
+    const onKeyDown = (event) => {
+        const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
+        if (!keys.includes(event.key))
+            return;
+        const root_ = root.current;
+        if (root_ === null)
+            return;
+        const items = [
+            ...root_.querySelectorAll('[data-slot="tree-link"], [data-slot="tree-heading"]'),
+        ];
+        if (items.length === 0)
+            return;
+        const at = items.indexOf(document.activeElement);
+        if (at === -1)
+            return;
+        event.preventDefault();
+        const next = event.key === 'ArrowDown'
+            ? Math.min(at + 1, items.length - 1)
+            : event.key === 'ArrowUp'
+                ? Math.max(at - 1, 0)
+                : event.key === 'Home'
+                    ? 0
+                    : items.length - 1;
+        items[next]?.focus();
+    };
+    if (nodes.length === 0) {
+        // A tree that renders nothing is a control with nothing in it, so the empty
+        // case is authored rather than left for a caller to notice.
+        return (_jsxs("div", { "data-slot": "tree-empty", className: cn('text-muted-foreground text-sm', className), children: [empty?.message ?? null, empty?.action] }));
+    }
+    return (_jsx("div", { "data-slot": "tree", ref: root, role: "tree", "aria-label": label, onKeyDown: onKeyDown, className: cn('flex flex-col', className), children: _jsx(TreeLevel, { nodes: nodes, currentHref: currentHref, depth: 0 }) }));
+}
+export { Tree };

package/dist/styles.css

@@ -635,6 +635,9 @@
     --tw-translate-y: var(--spacing-0\.5);
     translate: var(--tw-translate-x) var(--tw-translate-y);
   }
+  .transform {
+    transform: var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,);
+  }
   .cursor-default {
     cursor: default;
   }
@@ -1002,6 +1005,9 @@
   .p-6 {
     padding: var(--spacing-6);
   }
+  .px-0\.5 {
+    padding-inline: var(--spacing-0\.5);
+  }
   .px-1 {
     padding-inline: var(--spacing-1);
   }
@@ -2624,6 +2630,26 @@
   inherits: false;
   initial-value: 0;
 }
+@property --tw-rotate-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-z {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-y {
+  syntax: "*";
+  inherits: false;
+}
 @property --tw-border-style {
   syntax: "*";
   inherits: false;
@@ -2891,6 +2917,11 @@
       --tw-translate-x: 0;
       --tw-translate-y: 0;
       --tw-translate-z: 0;
+      --tw-rotate-x: initial;
+      --tw-rotate-y: initial;
+      --tw-rotate-z: initial;
+      --tw-skew-x: initial;
+      --tw-skew-y: initial;
       --tw-border-style: solid;
       --tw-gradient-position: initial;
       --tw-gradient-from: #0000;

package/gates/README.md

@@ -0,0 +1,98 @@
+# `@nanisoft/prism-ui/gates`
+
+The cross-repository laws, as programs, in the package a consumer already pins
+exactly.
+
+For four years the five NaniSoft repositories coordinated through a prose
+contract mirrored in four files. It drifted into three implementations of one rule
+and one of the three rules was false, and it could not be enforced because prose
+cannot fail. This subpath is the replacement: every law is the failure message of
+a gate, and the gate is here, so a change to a law lands once and reaches every
+consumer in one release.
+
+## What a consumer holds, and what the package holds
+
+A consumer's repository holds **data**:
+
+| the consumer declares | because |
+| --- | --- |
+| its stylesheets | which sheets are its own is a fact about its own pages |
+| its pack map | the regions it allows, and why each one exists |
+| its region resolver | naming a region means knowing its own DOM |
+| its coverage floors | how many rules or routes count as having read something |
+| its destinations known to be broken | one site's content defect, with a reason |
+| its custom properties the build supplies | one site's build, one site's font |
+
+The package holds **every law**: what the judgements are, what each failure says,
+and why each one exists. A consumer that restates any of it has two rules that will
+disagree, and the disagreement is invisible until a reader sees the difference.
+
+## Running it
+
+```bash
+pnpm exec prism-gates                 # every gate prism-gates.json names
+pnpm exec prism-gates --gate=links    # one gate
+pnpm exec prism-gates --json          # machine-readable, for a test
+```
+
+In a consumer's `package.json`:
+
+```json
+{
+  "scripts": {
+    "check:gates": "prism-gates"
+  }
+}
+```
+
+And in `prism-gates.json`, at the repository root:
+
+```json
+{
+  "gateKit": 1,
+  "gates": ["pin", "retired-line", "stylesheet-ownership", "links", "hidden-state"],
+  "stylesheet-ownership": { "sheets": ["app/globals.css"], "minDeclarations": 20 },
+  "links": { "outDir": "out", "minRoutes": 30, "minAnchors": 200 },
+  "hidden-state": { "sheets": ["app/globals.css"], "minRules": 25 }
+}
+```
+
+`gateKit` is the generation of the contract the consumer is holding itself to. A
+consumer that does not state one gets the package's current generation, and a law
+rewritten in a later release is then a version the consumer has not moved to rather
+than a silent change of wording underneath it.
+
+## The laws
+
+| id | the law |
+| --- | --- |
+| `pin` | the design system is an exact version, and the token package is the component package's dependency rather than the consumer's |
+| `retired-line` | no trace of the retired component library survives |
+| `stylesheet-ownership` | a site stylesheet does not own a surface the design system owns |
+| `token-read` | a custom property that nothing declares is not a wrong colour, it is no declaration at all |
+| `links` | every internal destination resolves and every fragment names an element that exists |
+| `pack-boundary` | a pack boundary lands on a mark, and a declared region set is the whole of what may carry a second pack |
+| `hidden-state` | a CSS-authored hidden state is escapable, and its exit is not a clock |
+
+The full text of each, and the failure each one prevents, is in `laws.mjs` and is
+printed by the gate that holds it. It is not restated here on purpose: this file is
+the one place a reader looks when a build is red, and a second copy of a law in a
+second file is a second rule.
+
+## What a gate here cannot do
+
+Stated here rather than left for a reader to discover:
+
+- **It reads text, not a cascade.** The ownership gate sees a selector and a
+  declaration. It does not resolve which rule wins.
+- **It reads the emitted export, not a browser.** The links and pack-boundary gates
+  read `out/`. Run the build first; a gate that read nothing fails rather than
+  reporting a clean page.
+- **It does not see a runtime.** A `data-pack` attribute set after paint, or a
+  token read in client code, is outside every gate in this kit.
+- **A stylesheet half is not a rendered half.** A consumer that ships a hidden
+  state also needs a test that renders with scripting switched off.
+
+These limits are printed on every run as well, because a gate that appeared to
+resolve cascades and did not would be worse than no gate: it would retire the
+question.

package/gates/cli.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * The consumer's gate chain. One program, one configuration file, one exit code.
+ *
+ * A consumer's repository holds data: its roots, its sheet, its pack map, its
+ * coverage floors, its destinations it knows are broken. It does not hold the
+ * wording of a rule, because a wording held in four places is four rules that will
+ * disagree, and the version they disagree at is the version nobody chose.
+ *
+ *     pnpm prism-gates                       # every gate the configuration names
+ *     pnpm prism-gates --gate=links          # one gate
+ *     pnpm prism-gates --gate=links --json   # machine-readable, for a test
+ *
+ * `--json` exists because the assertion that matters about a gate is not that it
+ * passed: it is that it went red on a defect it can see. A test cannot watch a
+ * human-readable exit code and be sure it saw the failure it planted, so the
+ * machine form carries the findings and the coverage the run achieved.
+ *
+ * **The exit code is the contract.** 0 means every named gate ran and found
+ * nothing. 1 means a gate found something. 2 means a gate could not read what it
+ * was pointed at, which is a different answer from "clean" and is never reported
+ * as 0. A gate that read nothing and exited 0 is the failure this program exists
+ * to make impossible, and it is why the coverage floors live in the gates rather
+ * than in the consumer's expectations.
+ */
+import process from 'node:process'
+import path from 'node:path'
+
+import { GATE_IDS, GATE_KIT_VERSION, gate, laws } from './index.mjs'
+import { CoverageError, readJson } from './run.mjs'
+
+const CONFIG_NAME = 'prism-gates.json'
+
+const flag = (name) => process.argv.find((argument) => argument.startsWith(`--${name}=`))?.slice(name.length + 3)
+const has = (name) => process.argv.includes(`--${name}`)
+
+async function main() {
+  const root = path.resolve(process.cwd())
+  const configPath = flag('config') ?? CONFIG_NAME
+  const json = has('json')
+  const only = flag('gate')
+
+  let config
+  try {
+    config = readJson(root, configPath)
+  } catch (cause) {
+    return fail(`error prism-gates: ${cause.message}`)
+  }
+  if (!config) {
+    return fail(
+      `error prism-gates: ${path.join(root, configPath)} does not resolve.\n` +
+        '  A gate chain with no configuration is a chain that runs nothing, and nothing looks like a pass.\n' +
+        '  The configuration holds this repository\'s own data only: its roots, its sheet, its pack map, its\n' +
+        '  coverage floors. The laws are not in it, because they are in the package.',
+    )
+  }
+
+  const named = only ? [only] : (config.gates ?? [])
+  if (named.length === 0) {
+    return fail(
+      `error prism-gates: ${configPath} names no gates, so this run enforced nothing.\n` +
+        `  A chain that runs nothing exits the same as a chain that found nothing, which is the answer this\n` +
+        `  program exists to stop giving. The kit ships: ${GATE_IDS.join(', ')}.`,
+    )
+  }
+
+  const results = []
+  let findings = 0
+  let unreadable = 0
+
+  for (const id of named) {
+    const settings = config[id] ?? {}
+    try {
+      const { run } = await gate(id)
+      const result = await run({ root, config: settings })
+      findings += result.findings.length
+      results.push({ gate: id, law: result.law.id, ok: result.findings.length === 0, findings: result.findings, notes: result.notes, also: (result.also ?? []).map((l) => l.id) })
+    } catch (cause) {
+      unreadable += 1
+      const message =
+        cause instanceof CoverageError
+          ? `error prism-gates: ${id}: ${cause.message}`
+          : `error prism-gates: ${id} could not run: ${cause.stack ?? cause.message}`
+      if (json) {
+        results.push({ gate: id, ok: false, unreadable: true, findings: [], notes: [message] })
+      } else {
+        console.error(message)
+      }
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { gateKit: GATE_KIT_VERSION, laws: laws().map((l) => l.id), results },
+        null,
+        2,
+      ),
+    )
+    return findings > 0 || unreadable > 0 ? 1 : 0
+  }
+
+  for (const result of results) {
+    if (result.unreadable) continue
+    for (const line of result.notes) console.log(line)
+    for (const line of result.findings) console.error(line)
+    if (result.findings.length > 0) {
+      const law = laws().find((l) => l.id === result.law)
+      console.error(`\n${law.title}`)
+      console.error(law.message)
+      console.error(`  It is here because: ${law.why}`)
+    }
+  }
+
+  console.log(
+    `\nprism-gates: gate kit ${GATE_KIT_VERSION}, ${named.length} gate(s) run, ${findings} finding(s), ` +
+      `${unreadable} unreadable`,
+  )
+  console.log(`prism-gates: the laws this run enforced: ${laws().map((l) => l.id).join(', ')}`)
+  console.log(
+    'prism-gates: the wording of every law above is in the package you pinned, not in this repository. A change\n' +
+      '  to it reaches this repository in one release and cannot be declined here.',
+  )
+
+  return findings > 0 || unreadable > 0 ? 1 : 0
+}
+
+function fail(message) {
+  console.error(message)
+  return 2
+}
+
+process.exitCode = await main()