@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miles Roxas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# design-hub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Design Hub product as an npm package: the hub that lists and serves a project's prototypes, the review panel and its API, the password gate, the kit, the `design-hub` command and the `miles-*` skills. A project installs it and keeps only its prototypes, kit materials and docs; `npm create @milesroxas/design-hub` makes one.
+
+```bash
+design-hub dev                    # the hub on http://localhost:<PORT>
+design-hub new <slug> --feature <feature>         # a prototype in the low-gravity space
+design-hub new <slug> --app --sprint --feature <feature>   # a feature's own prototype, in the shell
+design-hub guide <feature>        # its walkthrough, docs/sprints/<feature>/guide.md
+design-hub commands               # every command, with its flags, as JSON
+```
+
+Inside the package, from the inside out: `core/` is the pure kernel (README states, the catalog, fixture sets, checks, the Jev client, the review domain); `kit/` the materials prototypes import; `shell/` the browser hub; `server/` the Node side (the review API, signed sessions, the stores, env and paths); `vite/` the plugin that turns a project into a Vite app; `vercel/` the deployed entries; `scripts/` the CLI; `templates/` what `new` copies; `skills/` what `skills` installs. `AGENTS.md` here holds the layers and their rules.
+
+How a project becomes an app: `design-hub dev` runs Vite with the package's `shell/` as the root and the project as the content. `vite/registry.ts` writes `virtual:design-hub/registry` from the project's `prototypes/` and `docs/sprints/`; `vite/kit.ts` resolves `@kit/<name>` to the project's `kit/<name>` first and the package's second. The sections below describe the hub's own interface and the deployed site; they are the reference for changing the package, not for using it.
+
+## The index
+
+`/` lists every prototype from its README frontmatter (`shell/Index.tsx`, `shell/shell.css`). The page answers one question for a reviewer: which prototype is the feature, and what else was tried around it.
+
+### Which kind
+
+Walk this for every new prototype; the first match wins.
+
+1. The feature's main prototype, the one its walkthrough opens → `sprint`. Exactly one per feature, so a reviewer never has to guess which build is current. `design-hub new --sprint` refuses a second while the first is not archived.
+2. Another full take on that same flow, built to compare against the primary → `alternate` (`--alternate`). Refused until the primary exists, because an alternate is only legible next to what it replaces.
+3. Anything else: a side question about one part (a menu's motion, a loading state) → `exploration`, the default.
+
+### Layout
+
+Groups, in order: one per feature, then `Without a feature` (explorations with an empty `feature:`), then `Archived` (`status: archived`, any kind, plain rows).
+
+A feature group, top to bottom:
+
+1. **Heading.** The feature's name. `Walkthrough →` ends the line when `docs/sprints/<feature>/guide.md` exists.
+2. **Primary.** The one `sprint` row, its title 16px against 14px for every other row. Size alone marks it; no badge, no new shape.
+3. **Alternates.** Under an `Alternates` caption (12px, 500, quaternary text), indented 20px and joined to the primary by a 1px rail in `--border-secondary` on the primary's text edge. The rail makes them children of that one row; a heading of their own would make them peers of the feature. A stray second `sprint` renders here too.
+4. **Internal explorations.** A toggle (`Internal explorations`, the count, a chevron), collapsed by default because explorations are working material, not the feature. The open state persists per group in `localStorage` (`index-explorations-open`). Typing in the filter opens every fold, so a match is never hidden. Open, the explorations are cards on a grid (`minmax(208px, 1fr)`, 8px gap). Every exploration lives here, never in the row list.
+
+Within any list: exploring above decided, then newest first.
+
+Rhythm: inside a group, each block's text sits 20px under the text above it (primary under heading, each caption under the last summary), and a caption sits 8px over what it labels, so it reads as the start of what follows. Groups sit 40px apart, double the inner step, so a group reads as one unit.
+
+Surfaces:
+
+- **Rows** draw no dividers. The hover surface is the only drawn shape and bleeds 12px into the gutter, so every text edge on the page lines up. One page grid reaches every row through subgrid, so the context, status and date columns align across groups without fixed widths; the alternates' indent reaches the first column only.
+- **Cards** take `--radius-lg` and 12px padding, so card text keeps the page's text edge. The title line ends in an arrow (quaternary), because the whole card opens the prototype. The summary drops to caption size (12px/18px, tertiary) so three cards scan as three titles. Context, status and date sit pinned to the bottom so the meta lines up across a row of cards. The edge is an inset ring (`oklch(0 0 0 / 0.08)`) plus two soft layers in light, and a white 9% ring alone in dark, where the tokens drop every shadow. The ring is inset because the fold clips its content while it animates and would cut an outer one. Focus stacks the focus ring on the edge, since both are box-shadows and the edge alone would erase it.
+- **Status** is a 6px dot before the word: ink for exploring, success for decided, quinary for archived. The word stays, so colour is never the only signal.
+- **Foot.** The count alone, in body type over a hairline (the Ledger Foot Rule).
+- **Lede.** 18px/28px Geist at 400, secondary text. `--font-voice` resolves to Geist inside the hub's `.sys` scope (`shell/system.css`), so the index never borrows the project's faces.
+
+### Motion
+
+Nothing animates on a keyboard action.
+
+- **Arrival**, one shot: the head fades over 200ms, then each heading, caption, row and open card rises 4px and fades over 220ms, 30ms apart (stagger capped at eight), then the foot. Keyframes fill backwards only, so a settled row's opacity stays free to transition.
+- **Departure**, pointer only: a clicked row or card holds while the rest of the page fades over 150ms on the Layer Exit curve, filling the wait while the browser fetches the prototype. A modified click or Enter opens instantly; a back-forward restore clears the fade.
+- **Fold:** opens over 220ms (grid row `0fr` to `1fr`, plus the fade) and closes over 150ms, both `--ease-out`; the chevron turns 180°. A keyboard toggle is instant.
+- **Hover:** a row takes the Hover Rule fill. A card stays white and lifts instead (ring and shadow deepen; in dark, the ring brightens and the surface steps up to `--bg-primary_hover`), and its arrow moves 2px right and darkens to secondary. Both lift the summary to secondary. **Press:** `scale(0.97)`.
+- **Reduced motion** keeps the fades and drops the rise, the press, the fold's growth, the chevron's turn and the arrow's nudge.
+- Up and Down arrows walk the rows and the cards of open folds.
+
+A speculation rule in `shell/index.html` prefetches a prototype's page when its row is hovered, so the document is in cache by the click (Chromium; other browsers ignore the rule). Prerendering was rejected: it would play a prototype's entrance motion before anyone saw it.
+
+## The walkthrough
+
+`/guide/<feature>/` is `docs/sprints/<feature>/guide.md`, rendered for reviewers who have the password but not the repo; `/guide/` alone opens the only guide, or lists them. The registry plugin lists the guides, so a new feature's walkthrough appears the moment the file exists (`design-hub guide <feature>` starts one from `templates/guide.md`). The Markdown stays the one source: a Vite plugin (`vite/markdown.ts`, the `?doc` import) compiles it at build time with `marked`, so nothing is parsed in the browser. It turns the first H1 into the title, every H2 and H3 into the contents rail, each image into a figure with its pixel size (no layout shift, lazy below the first), and `> [!NOTE]` quotes into callouts. A paragraph that starts `Controls → …` renders as a click path. Links to other Markdown files lose their href, since nothing serves them. The page reads at 16px on a 680px measure; screenshots and tables take the full 960px column, because a 1440px shot at 680px is unreadable. Two raw values: a screenshot wears a 1px inset outline at 10% (black on light, white on dark) and a callout a 6% ring (8% on dark), alphas rather than tokens because they composite on any surface the page is set on. The slug `guide` is the hub's (`design-hub new guide` refuses it). The page's **Open the prototype** button goes to the feature's sprint prototype, and every prototype of the feature answers with **Open the walkthrough** as the last row of Controls, under every group, in a new tab, so a reviewer reads and clicks side by side. A sheet inside the product was rejected: it would be modal over the thing under review, and testing aids never sit in the product chrome.
+
+## Deploying, and the password
+
+`miles-deploy` owns the steps; this is what they rest on. Pushing `main` deploys the project to the linked Vercel project (`design-hub bootstrap --vercel <project>` links it and sets the env). Every path on the deployed site sits behind one password, enforced on the server by Vercel Routing Middleware (`vercel/proxy.ts`, exported as `createProxy` and default-exported by the project's one-line `proxy.ts`, which `vercel.json` names as `proxy.entrypoint`): a visitor who opens a deep link, `/sample-list/#/items` included, sees the password page first and lands on that link after. A client-side gate was rejected because the bundle and the state behind it would still download.
+
+The middleware reads two environment variables, set in the Vercel project for Production and Preview and never committed (`.env.example` names them): `GATE_PASSWORD`, the word a reviewer types, and `GATE_SECRET`, at least 32 random characters (`openssl rand -base64 32`) that sign the session cookie. With either missing the gate answers 503 on every path, so a misconfigured deploy never serves the prototypes open. The cookie is `__Host-`-prefixed, `HttpOnly`, `Secure`, `SameSite=Lax`, lasts 30 days, and its signature covers the password, so changing `GATE_PASSWORD` signs every visitor out. A wrong password waits 800ms before answering; add a Vercel Firewall rate-limit rule on `POST` for anything stronger. The password page ships a hash-based Content Security Policy with no `unsafe-inline`, plus `font-src 'self'` and `img-src 'self'`. It wears the hub's neutral look in Geist, so two files pass the gate without a session: `/_gate/geist.woff2` (the latin subset, emitted by `vite/plugin.ts` at that fixed path) and `/favicon.svg`. Nothing else does. Every response carries `X-Robots-Tag: noindex`, so no search engine lists the site. The page's title is the `siteName` the project's `proxy.ts` passes to `createProxy`.
+
+## Comments and people
+
+The password opens the site to view. To comment, a person needs their own invite link, made by an editor in the review panel's People tab or with `design-hub people invite`. Opening it shows who it is for and asks them to continue; the continue is a POST, so a mail scanner that opens every link never uses the invite. It sets a second signed cookie naming that person and their epoch, a counter a new link or a revoke bumps, which ends every session they hold on their next page load. The store keeps only a hash of each invite token, so a read of the store signs nobody in. A link lasts 14 days.
+
+The panel (`shell/review/`) mounts on every prototype page in its own React root, so a prototype that throws never takes it down. A comment carries the prototype, the URL, every dial panel's values (`snapshotDials`), and the element it was pinned to as a selector path with an offset; Show state reopens the URL and sets the dials back. Pins draw over their elements and below the Controls panel. The API is one endpoint, `/api/review` (`server/api.ts`, reached on Vercel through the project's one-line `api/review.ts`, which also bundles the project's `checks.json` so triage runs on its thresholds): queries by GET, commands by POST with a JSON body, same-origin only. The rules (who may resolve, what a valid comment is) live once, in `core/review/`, behind a small storage port: Upstash Redis over REST when deployed, a file in `.design-hub/review.json` under `design-hub dev`, where whoever runs the server is a local editor.
+
+`design-hub dev` serves the prototypes open, with the review panel on the local store. The gate is covered by `pnpm test` (`vercel/proxy.test.ts`, against an in-memory Upstash); `vercel dev` in a project runs it for real.

package/client.d.ts

@@ -0,0 +1,6 @@
+// Ambient types for a project: Vite's import.meta and asset modules, and the
+// kit's own module shapes. A project's tsconfig lists `@milesroxas/design-hub/client` in
+// `types`; it never needs vite on its own.
+/// <reference types="vite/client" />
+/// <reference path="./shell/doc.d.ts" />
+/// <reference path="./shell/registry.virtual.d.ts" />

package/configs/biome/biome.json

@@ -0,0 +1,63 @@
+{
+  "files": {
+    "includes": [
+      "**",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/.vercel",
+      "!**/.design-hub",
+      "!**/design-system",
+      "!**/docs",
+      "!**/.impeccable",
+      "!**/.claude",
+      "!**/*.md",
+      "!**/pnpm-lock.yaml"
+    ]
+  },
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 110
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "css": {
+    "formatter": {
+      "enabled": false
+    },
+    "linter": {
+      "enabled": false
+    }
+  },
+  "linter": {
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noExplicitAny": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off"
+      },
+      "a11y": {
+        "noLabelWithoutControl": {
+          "level": "error",
+          "options": {
+            "inputComponents": [
+              "Checkbox"
+            ]
+          }
+        }
+      }
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/configs/tsconfig.project.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "types": ["@milesroxas/design-hub/client"]
+  }
+}

package/core/bytes.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { base64, base64url, hex, sha256 } from './bytes.ts';
+
+test('sha256 of a known string', async () => {
+  assert.equal(hex(await sha256('abc')), 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad');
+});
+
+test('base64url swaps the two unsafe characters and drops padding', () => {
+  const bytes = new Uint8Array([251, 255, 254]);
+  assert.equal(base64(bytes), '+//+');
+  assert.equal(base64url(bytes), '-__-');
+  assert.equal(base64url(new Uint8Array([1])), 'AQ');
+});

package/core/bytes.ts

@@ -0,0 +1,14 @@
+// Bytes to text, and SHA-256, on Web Crypto only, so the same helpers serve
+// the browser, Node and Vercel's runtime.
+
+export async function sha256(text: string): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
+}
+
+export const hex = (bytes: Uint8Array) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+export const base64 = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes));
+
+/** URL-safe base64 without padding: cookies, tokens and links carry it unescaped. */
+export const base64url = (bytes: Uint8Array) =>
+  base64(bytes).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');

package/core/catalog.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { byIndexOrder, isLive, readMeta } from './catalog.ts';
+import { frontmatter } from './frontmatter.ts';
+
+const readme = (fm: string, body = '') => `---\n${fm}\n---\n\n# X\n${body}`;
+
+test('frontmatter reads flat pairs, strips quotes, and keeps colons in values', () => {
+  const { data, body } = frontmatter(readme('title: "A: B"\nsummary: \'One line\'\nempty:'));
+  assert.deepEqual(data, { title: 'A: B', summary: 'One line', empty: '' });
+  assert.equal(body.trim(), '# X');
+  assert.deepEqual(frontmatter('# no frontmatter').data, {});
+});
+
+test('readMeta fills defaults and keeps only the known kinds', () => {
+  const m = readMeta('my-slug', readme('kind: sprint'));
+  assert.deepEqual(
+    { title: m.title, context: m.context, status: m.status, kind: m.kind, states: m.states },
+    { title: 'my-slug', context: 'space', status: 'exploring', kind: 'sprint', states: null },
+  );
+  assert.equal(readMeta('x', readme('kind: final')).kind, 'exploration');
+  assert.equal(
+    readMeta(
+      'x',
+      readme('kind: alternate', '\n## States\n\n| State | How |\n| --- | --- |\n| Open | click |\n'),
+    ).states?.length,
+    1,
+  );
+});
+
+test('open questions sort above answered ones, newest first, then by title', () => {
+  const m = (slug: string, status: string, created: string) =>
+    readMeta(slug, readme(`title: ${slug}\nstatus: ${status}\ncreated: ${created}`));
+  const sorted = [
+    m('b', 'decided', '2026-01-02'),
+    m('c', 'exploring', '2026-01-01'),
+    m('a', 'exploring', '2026-01-03'),
+  ].sort(byIndexOrder);
+  assert.deepEqual(
+    sorted.map((x) => x.slug),
+    ['a', 'c', 'b'],
+  );
+  assert.equal(isLive({ status: 'archived' }), false);
+});

package/core/catalog.ts

@@ -0,0 +1,43 @@
+// What a prototype's README says about it: the frontmatter the index lists
+// and the States table the checks read. One reader for the browser index
+// (shell/registry.ts) and the Node scripts (scripts/lib/catalog.ts), so
+// they never disagree about what a prototype is.
+import { frontmatter } from './frontmatter.ts';
+import { parseStates, type State } from './states.ts';
+
+export type Kind = 'sprint' | 'alternate' | 'exploration';
+
+export type Meta = {
+  slug: string;
+  title: string;
+  summary: string;
+  context: string;
+  status: string;
+  kind: Kind;
+  feature: string;
+  created: string;
+  /** null when the README has no States section. */
+  states: State[] | null;
+};
+
+export function readMeta(slug: string, readme: string): Meta {
+  const { data } = frontmatter(readme);
+  return {
+    slug,
+    title: data.title || slug,
+    summary: data.summary || '',
+    context: data.context || 'space',
+    status: data.status || 'exploring',
+    kind: data.kind === 'sprint' || data.kind === 'alternate' ? data.kind : 'exploration',
+    feature: data.feature || '',
+    created: data.created || '',
+    states: parseStates(readme),
+  };
+}
+
+export const isLive = (m: Pick<Meta, 'status'>) => m.status !== 'archived';
+
+// Open questions sit above answered ones; within a status, newest first.
+const rank = (status: string) => (status === 'exploring' ? 0 : 1);
+export const byIndexOrder = (a: Meta, b: Meta) =>
+  rank(a.status) - rank(b.status) || b.created.localeCompare(a.created) || a.title.localeCompare(b.title);

package/core/checks.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { DEFAULT_CHECKS, loadChecks, reaches, validateChecks } from './checks.ts';
+
+test('the default checks are valid, and loadChecks keeps a valid value', () => {
+  assert.deepEqual(validateChecks(DEFAULT_CHECKS), []);
+  assert.equal(loadChecks(DEFAULT_CHECKS).checks, DEFAULT_CHECKS);
+  assert.equal(loadChecks({ jev: {} }).checks, null);
+  assert.ok(loadChecks({ jev: {} }).problems.length > 0);
+});
+
+test('names each invalid field by path', () => {
+  const problems = validateChecks({ jev: { model: '', timeoutMs: 0 }, fidelity: { warnAt: 2 } });
+  assert.ok(problems.includes('jev.model: a model name'));
+  assert.ok(problems.some((p) => p.startsWith('fidelity.warnAt')));
+  assert.ok(problems.some((p) => p.startsWith('contacts.allow')));
+});
+
+test('a null threshold never fires', () => {
+  assert.equal(reaches(1, null), false);
+  assert.equal(reaches(0.7, 0.7), true);
+  assert.equal(reaches(0.69, 0.7), false);
+});

package/core/checks.ts

@@ -0,0 +1,72 @@
+// The model and thresholds every Jev check reads, from one file in the
+// project: .design-hub/checks.json. `design-hub calibrate --write` rewrites it
+// from labelled judgments, so thresholds come from data, never from a
+// constant in a script. The model is pinned, not an alias: an alias moves on
+// a release, and the thresholds were set against one model. A file that does
+// not validate turns every Jev check off (and `design-hub preflight` reports
+// it), because a check must never block on a config typo. A project without
+// the file runs on DEFAULT_CHECKS.
+
+/** A probability threshold, or null for "never". */
+type At = number | null;
+
+export type Checks = {
+  jev: { model: string; timeoutMs: number };
+  fidelity: { warnAt: At; blockAt: At };
+  states: { blockAt: At };
+  contacts: { privateAt: At; allow: string[] };
+  skillHint: { gateAt: At; fitsAt: At };
+  triage: { at: At };
+  visual: { warnAt: At };
+};
+
+export const DEFAULT_CHECKS: Checks = {
+  jev: { model: 'jev-1.14.0', timeoutMs: 2000 },
+  fidelity: { warnAt: 0.7, blockAt: 0.9 },
+  states: { blockAt: 0.8 },
+  contacts: { privateAt: 0.5, allow: [] },
+  skillHint: { gateAt: 0.3, fitsAt: 0.3 },
+  triage: { at: 0.5 },
+  visual: { warnAt: 0.7 },
+};
+
+const isAt = (v: unknown): v is At => v === null || (typeof v === 'number' && v >= 0 && v <= 1);
+const obj = (v: unknown): Record<string, unknown> =>
+  v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/** Every problem with a checks object, by path; empty when it is valid. */
+export function validateChecks(value: unknown): string[] {
+  const c = obj(value);
+  const problems: string[] = [];
+  const jev = obj(c.jev);
+  if (typeof jev.model !== 'string' || !jev.model) problems.push('jev.model: a model name');
+  if (typeof jev.timeoutMs !== 'number' || jev.timeoutMs <= 0)
+    problems.push('jev.timeoutMs: milliseconds > 0');
+  const thresholds: [string, string][] = [
+    ['fidelity', 'warnAt'],
+    ['fidelity', 'blockAt'],
+    ['states', 'blockAt'],
+    ['contacts', 'privateAt'],
+    ['skillHint', 'gateAt'],
+    ['skillHint', 'fitsAt'],
+    ['triage', 'at'],
+    ['visual', 'warnAt'],
+  ];
+  for (const [group, key] of thresholds)
+    if (!isAt(obj(c[group])[key])) problems.push(`${group}.${key}: a probability from 0 to 1, or null`);
+  const allow = obj(c.contacts).allow;
+  if (!Array.isArray(allow) || !allow.every((a) => typeof a === 'string'))
+    problems.push('contacts.allow: a list of strings');
+  return problems;
+}
+
+export type Loaded = { checks: Checks | null; problems: string[] };
+
+/** The checks a raw value yields: the value when it validates, else null with the problems. */
+export function loadChecks(raw: unknown): Loaded {
+  const problems = validateChecks(raw);
+  return { checks: problems.length ? null : (raw as Checks), problems };
+}
+
+/** True when p reaches the threshold; a null threshold never does. */
+export const reaches = (p: number, at: At) => at !== null && p >= at;

package/core/contacts.test.ts

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { contactsIn, contactsInJson } from './contacts.ts';
+
+test('finds emails and phone numbers', () => {
+  const found = contactsIn('Call +1 (415) 555-0134 or write ana.ruiz@example.com');
+  assert.deepEqual(
+    found.map((c) => [c.kind, c.value]),
+    [
+      ['email', 'ana.ruiz@example.com'],
+      ['phone', '+1 (415) 555-0134'],
+    ],
+  );
+});
+
+test('ignores dates, short numbers, prices and ids', () => {
+  for (const text of [
+    '2026-10-28',
+    'updated 2026-10-28T10:00:00Z',
+    '42 items',
+    '$1,299.00',
+    'v1.2.3',
+    'id 64f1a2b3c4d5e6f7a8b9c0d1',
+  ])
+    assert.deepEqual(contactsIn(text), [], text);
+});
+
+test('reports the JSON path of each match', () => {
+  const found = contactsInJson({ real: [{ name: 'A' }, { owner: { email: 'x@y.io' } }] });
+  assert.deepEqual(found, [{ kind: 'email', value: 'x@y.io', path: 'real[1].owner.email' }]);
+});

package/core/contacts.ts

@@ -0,0 +1,38 @@
+// Emails and phone numbers in fixture data. A CMS pull can put a real
+// person's details behind a share link a client forwards, so the pre-flight
+// stops on every match until it is confirmed as a business contact. This is
+// the code half of the contact check; Jev, when on, only judges whether a
+// match is a private person or a public business.
+
+export type Contact = { kind: 'email' | 'phone'; value: string; path: string };
+
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+// A run that starts and ends with a digit, may hold spaces, dots, dashes and
+// brackets, and is not glued to letters or digits on either side.
+const PHONE = /(?<![\w.+-])\+?\d[\d\s().-]{6,}\d(?![\w])/g;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}/;
+
+function phones(text: string): string[] {
+  return [...text.matchAll(PHONE)]
+    .map((m) => m[0].trim())
+    .filter((v) => {
+      const digits = v.replace(/\D/g, '').length;
+      return digits >= 9 && digits <= 15 && !ISO_DATE.test(v);
+    });
+}
+
+/** Every contact in a string, in order of appearance. */
+export function contactsIn(text: string, path = ''): Contact[] {
+  const emails = [...text.matchAll(EMAIL)].map((m) => ({ kind: 'email' as const, value: m[0], path }));
+  const withoutEmails = text.replace(EMAIL, ' ');
+  return [...emails, ...phones(withoutEmails).map((value) => ({ kind: 'phone' as const, value, path }))];
+}
+
+/** Every contact in any string of a JSON value, with the path to it (`real[2].owner`). */
+export function contactsInJson(value: unknown, path = ''): Contact[] {
+  if (typeof value === 'string') return contactsIn(value, path);
+  if (Array.isArray(value)) return value.flatMap((v, i) => contactsInJson(v, `${path}[${i}]`));
+  if (value && typeof value === 'object')
+    return Object.entries(value).flatMap(([k, v]) => contactsInJson(v, path ? `${path}.${k}` : k));
+  return [];
+}

package/core/doc.ts

@@ -0,0 +1,4 @@
+// What a compiled walkthrough looks like: the shape the Vite plugin writes at
+// build time (vite/markdown.ts) and the page reads (shell/Guide.tsx).
+export type TocEntry = { id: string; text: string; depth: number };
+export type Doc = { meta: Record<string, string>; title: string; toc: TocEntry[]; html: string };

package/core/feature.ts

@@ -0,0 +1,6 @@
+// The feature slug names docs/sprints/<feature>/ and a prototype's `feature:`. One rule for its shape and its display name.
+export const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export const featureTitle = (slug: string) => slug.replace(/-/g, ' ').replace(/^\w/, (c) => c.toUpperCase());
+
+export const guideHref = (feature: string) => `/guide/${feature}/`;

package/core/fixtures.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { fixtureSets } from './fixtures.ts';
+
+type Item = { id: string; name: string; status: string; updated: string };
+const real: Item[] = [
+  { id: '1', name: 'Short', status: 'active', updated: '2026-10-28' },
+  { id: '2', name: 'A much longer name', status: 'done', updated: '2026-10-21' },
+];
+const sets = fixtureSets({ real, missing: [] }, { max: 5, text: ['name'] });
+
+test('longest stretches only the named text fields, on the first row', () => {
+  assert.deepEqual(sets.longest[0], {
+    id: '1',
+    name: 'A much longer name A much longer name',
+    status: 'active',
+    updated: '2026-10-28',
+  });
+  assert.deepEqual(sets.longest[1], real[1]);
+});
+
+test('max repeats to the count with unique ids; empty is empty', () => {
+  assert.deepEqual(
+    sets.max.map((i) => i.id),
+    ['1', '2', '1-1', '2-1', '1-2'],
+  );
+  assert.deepEqual(sets.empty, []);
+});
+
+test('a set written by hand wins', () => {
+  const hand = fixtureSets({ real, missing: [], longest: [real[1]] }, { max: 1, text: ['name'] });
+  assert.deepEqual(hand.longest, [real[1]]);
+});

package/core/fixtures.ts

@@ -0,0 +1,69 @@
+// Hostile fixture sets, derived from the real ones so Claude never writes
+// them by hand. A feature's fixtures.json holds `real` (pulled from the CMS
+// or copied from the comp) and `missing` (the item with no image, no link,
+// hand-written because no rule can derive it). This file fills in the rest:
+//
+//   longest  the first item carries, in each free-text field the component
+//            names (`text`), the longest real value for that field doubled,
+//            because the CMS will hold a longer title than anything in it
+//            today; the other items stay real, so the monster row is judged
+//            beside normal ones. Only named fields stretch: a doubled date,
+//            status or URL is not a longer value, it is a broken one
+//   empty    nothing
+//   max      the real items repeated up to the design's maximum count, ids
+//            made unique so React keys hold
+//
+// A set written in the JSON by hand wins over the derived one, so a feature
+// can replace any of them when its component needs something the rule
+// cannot know.
+
+export const SET_NAMES = ['real', 'longest', 'empty', 'max', 'missing'] as const;
+export type SetName = (typeof SET_NAMES)[number];
+
+export type FixtureSets<T> = Record<SetName, T[]>;
+type Source<T> = { real: T[]; missing: T[] } & Partial<Record<SetName, T[]>>;
+/** The keys of T whose values are strings: the only fields `longest` can stretch. */
+type TextKey<T> = { [K in keyof T & string]: T[K] extends string | null | undefined ? K : never }[keyof T &
+  string];
+type Options<T> = {
+  /** The design's maximum count, for `max`. */
+  max: number;
+  /** The free-text fields a reviewer reads (a name, a title), for `longest`. */
+  text: readonly TextKey<T>[];
+};
+
+export function fixtureSets<T extends Record<string, unknown>>(
+  source: Source<T>,
+  { max, text }: Options<T>,
+): FixtureSets<T> {
+  return {
+    real: source.real,
+    longest: source.longest ?? longest(source.real, text),
+    empty: source.empty ?? [],
+    max: source.max ?? repeat(source.real, max),
+    missing: source.missing,
+  };
+}
+
+function longest<T extends Record<string, unknown>>(real: T[], text: readonly string[]): T[] {
+  const [first, ...rest] = real;
+  if (!first) return [];
+  const hostile = { ...first } as Record<string, unknown>;
+  for (const key of text) {
+    const widest = real
+      .map((item) => item[key])
+      .filter((v): v is string => typeof v === 'string')
+      .reduce((a, b) => (b.length > a.length ? b : a), '');
+    if (widest) hostile[key] = `${widest} ${widest}`;
+  }
+  return [hostile as T, ...rest];
+}
+
+function repeat<T extends Record<string, unknown>>(real: T[], count: number): T[] {
+  if (!real.length) return [];
+  return Array.from({ length: count }, (_, i) => {
+    const item = real[i % real.length];
+    const round = Math.floor(i / real.length);
+    return round === 0 || !('id' in item) ? item : { ...item, id: `${String(item.id)}-${round}` };
+  });
+}

package/core/frontmatter.ts

@@ -0,0 +1,15 @@
+// The YAML block at the top of a Markdown file, read as flat `key: value`
+// pairs. Shared by the index (in the browser) and the ?doc plugin (in Node).
+export function frontmatter(md: string) {
+  const match = md.match(/^---\n([\s\S]*?)\n---\n?/);
+  const data: Record<string, string> = {};
+  for (const line of (match?.[1] ?? '').split('\n')) {
+    const at = line.indexOf(':');
+    if (at > 0)
+      data[line.slice(0, at).trim()] = line
+        .slice(at + 1)
+        .trim()
+        .replace(/^["']|["']$/g, '');
+  }
+  return { data, body: match ? md.slice(match[0].length) : md };
+}

package/core/html.ts

@@ -0,0 +1,3 @@
+/** Text made safe to place in HTML content or a double-quoted attribute. */
+export const escapeHtml = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');