@junoput01/junoui 0.6.0 → 0.8.0

package/src/css/components/tree.css

@@ -0,0 +1,259 @@
+/* ════════════════════════════════════════════════════════════════════
+ *  Component — Tree / outliner (nested rows, disclosure, selection)
+ *  Layer stacks, file browsers, settings trees, org charts, comment
+ *  threads, nested navigation. Where .juno-list is flat and
+ *  .juno-accordion is single-level, this nests to arbitrary depth and
+ *  carries a selection.
+ *
+ *  ZERO JS FOR THE VISUALS. Indentation comes from the nested `role=group`
+ *  lists the ARIA pattern already requires, so depth costs no custom
+ *  property and no inline style; collapse is `[aria-expanded='false']`
+ *  hiding the child group. The app owns the attribute, exactly like
+ *  __item's aria-pressed elsewhere in junoui.
+ *
+ *  KEYBOARD IS NOT OPTIONAL and is not CSS. A tree without arrow-key
+ *  traversal and a roving tabindex is a list of buttons wearing tree
+ *  roles. junoui ships the contract in docs/components/tree.md and a
+ *  stateless enhancer at `junoui/tree` — use one or the other, but a tree
+ *  that has neither is not accessible and no stylesheet can fix it.
+ *
+ *  Usage (the markup the roles require — see the doc for the full ARIA
+ *  contract, which is the half apps get wrong):
+ *    <ul class="juno-tree" role="tree" aria-label="Scene">
+ *      <li class="juno-tree__item" role="treeitem" aria-level="1"
+ *          aria-expanded="true" aria-selected="false">
+ *        <div class="juno-tree__row">
+ *          <button class="juno-tree__caret" tabindex="-1" aria-hidden="true"></button>
+ *          <svg class="juno-icon juno-tree__icon" aria-hidden="true">…</svg>
+ *          <span class="juno-tree__label">Terrain</span>
+ *          <span class="juno-tree__count">12</span>
+ *          <span class="juno-tree__trail">…</span>
+ *          <button class="juno-tree__handle" aria-label="Reorder Terrain"></button>
+ *        </div>
+ *        <ul class="juno-tree__group" role="group">…</ul>
+ *      </li>
+ *    </ul>
+ * ════════════════════════════════════════════════════════════════════ */
+
+.juno-tree {
+  --juno-role: var(--juno-active);
+
+  /* One indent step. Applied per nested group, so depth is structural and
+     arbitrary rather than a level number someone has to keep in sync. */
+  --juno-tree-indent: var(--juno-space-16);
+
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-family: var(--juno-font-family-sans);
+  font-size: var(--juno-font-size-13);
+  color: var(--juno-data);
+}
+
+.juno-tree__group {
+  margin: 0;
+  padding: 0;
+  padding-inline-start: var(--juno-tree-indent);
+  list-style: none;
+}
+
+/* Collapsed: the child group goes. `display: none` and not a height
+   animation — a tree collapses an unknown number of rows at an unknown
+   depth, so there is no end value to transition to, and interpolate-size
+   is not available everywhere junoui targets. */
+.juno-tree__item[aria-expanded='false'] > .juno-tree__group {
+  display: none;
+}
+
+.juno-tree__row {
+  display: flex;
+  align-items: center;
+  gap: var(--juno-space-8);
+  inline-size: 100%;
+  min-block-size: var(--juno-size-tap-min);
+  padding-inline: var(--juno-space-8);
+  padding-block: var(--juno-space-4);
+  border: none;
+  border-radius: var(--juno-radius-3);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: start;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.juno-tree__row:hover {
+  background: var(--juno-s2);
+}
+
+/* SELECTION is a different fact from hover and from aria-current, and the
+   ticket is right that conflating them is the common bug: hover is where the
+   pointer is, aria-current is which page you are on, aria-selected is what
+   the next action will apply to. A layer stack has all three at once. */
+.juno-tree__item[aria-selected='true'] > .juno-tree__row {
+  background: var(--juno-s3);
+  color: var(--juno-role);
+}
+
+.juno-tree__item[aria-current] > .juno-tree__row {
+  box-shadow: inset var(--juno-border-width-2) 0 0 var(--juno-role);
+}
+
+.juno-tree__row:focus-visible {
+  outline: var(--juno-border-width-2) solid var(--juno-active);
+  outline-offset: calc(-1 * var(--juno-border-width-2));
+}
+
+/* ── disclosure caret ──────────────────────────────────────────────────
+   aria-hidden and tabindex=-1 on purpose: the row itself is the treeitem
+   and Left/Right already collapse and expand, so a separately focusable
+   caret puts a second stop in the tab order for an action the row has. It
+   stays a real button for the pointer. */
+.juno-tree__caret {
+  flex-shrink: 0;
+  inline-size: var(--juno-space-16);
+  block-size: var(--juno-space-16);
+  display: grid;
+  place-items: center;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--juno-label);
+  cursor: pointer;
+  transition: transform var(--juno-motion-duration-quick) var(--juno-motion-ease-standard);
+}
+
+.juno-tree__caret::before {
+  content: '';
+  inline-size: 0;
+  block-size: 0;
+  border-block: calc(var(--juno-space-4) + 1px) solid transparent;
+  border-inline-start: calc(var(--juno-space-4) + 2px) solid currentcolor;
+}
+
+.juno-tree__item[aria-expanded='true'] > .juno-tree__row > .juno-tree__caret {
+  transform: rotate(90deg);
+}
+
+/* A leaf keeps the caret's box so labels line up down the column, but paints
+   nothing — an empty gap would let sibling labels wander. */
+.juno-tree__item:not([aria-expanded]) > .juno-tree__row > .juno-tree__caret {
+  visibility: hidden;
+  cursor: default;
+}
+
+.juno-tree__icon {
+  flex-shrink: 0;
+  color: var(--juno-label);
+}
+
+.juno-tree__label {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Count badge on a group row. Pushed to the trailing edge with the rest of
+   the trailing furniture. */
+.juno-tree__count {
+  margin-inline-start: auto;
+  flex-shrink: 0;
+  font-size: var(--juno-font-size-11);
+  font-variant-numeric: tabular-nums;
+  color: var(--juno-muted);
+}
+
+/* The same trailing-control slot .juno-list__row has: a switch, a menu
+   trigger, a value. Follows the count when both are present. */
+.juno-tree__trail {
+  margin-inline-start: auto;
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--juno-space-8);
+}
+
+.juno-tree__count + .juno-tree__trail {
+  margin-inline-start: 0;
+}
+
+/* ── reorder handle ────────────────────────────────────────────────────
+   The AFFORDANCE and its hit area; the reorder logic is the app's, which is
+   junoui's usual line. It is a real button and always visible on touch: a
+   long-press-drag is the obvious gesture and the wrong one, because a tree
+   sitting on or beside a pan/zoom surface has to let the pan win. An
+   explicit handle is the only unambiguous target — see the doc.
+   `touch-action: none` on the handle ALONE, so dragging it never scrolls
+   while the rest of the row still pans normally. */
+.juno-tree__handle {
+  flex-shrink: 0;
+  inline-size: var(--juno-space-16);
+  block-size: var(--juno-space-16);
+  display: grid;
+  place-items: center;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--juno-muted);
+  cursor: grab;
+  touch-action: none;
+}
+
+.juno-tree__handle:active {
+  cursor: grabbing;
+}
+
+.juno-tree__handle::before {
+  content: '';
+  inline-size: var(--juno-space-10);
+  block-size: var(--juno-border-width-1);
+  box-shadow:
+    0 calc(-1 * var(--juno-space-4)) 0 currentcolor,
+    0 var(--juno-space-4) 0 currentcolor;
+  background: currentcolor;
+}
+
+/* The row being dragged, while the app moves it. */
+.juno-tree__item[data-juno-dragging] > .juno-tree__row {
+  opacity: var(--juno-opacity-muted);
+}
+
+/* Drop target edge. A line rather than a filled row: the drop lands BETWEEN
+   rows, and a filled highlight says "into this one", which is a different
+   operation in a tree and the one users complain about. */
+.juno-tree__item[data-juno-drop='before'] > .juno-tree__row {
+  box-shadow: inset 0 var(--juno-border-width-2) 0 var(--juno-active);
+}
+
+.juno-tree__item[data-juno-drop='after'] > .juno-tree__row {
+  box-shadow: inset 0 calc(-1 * var(--juno-border-width-2)) 0 var(--juno-active);
+}
+
+.juno-tree__item[data-juno-drop='into'] > .juno-tree__row {
+  outline: var(--juno-border-width-2) solid var(--juno-active);
+  outline-offset: calc(-1 * var(--juno-border-width-2));
+}
+
+/* ── touch ─────────────────────────────────────────────────────────────
+   The caret and the handle paint small so a dense tree stays dense, but a
+   16px target is not tappable. Grow the HIT AREA only, with a transparent
+   overlay, exactly as .nx-check does downstream: a 44px painted caret would
+   swallow the row it sits in. The row's own floor comes from
+   --juno-size-tap-min, which base.css promotes on a coarse pointer. */
+@media (pointer: coarse) {
+  .juno-tree__caret,
+  .juno-tree__handle {
+    position: relative;
+  }
+
+  .juno-tree__caret::after,
+  .juno-tree__handle::after {
+    content: '';
+    position: absolute;
+
+    /* (44 - 16) / 2 = 14 */
+    inset: calc(-1 * (var(--juno-size-tap-comfortable) - var(--juno-space-16)) / 2);
+  }
+}

package/src/css/touch-surfaces.mjs

@@ -0,0 +1,95 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui — the tappable surfaces, declared once
+// ════════════════════════════════════════════════════════════════════════
+//  THE source of truth for "this is one of junoui's own tappable components".
+//  scripts/bundle-css.mjs generates the touch-default rules from it, so the
+//  class names exist in exactly one place and a member cannot be misspelled
+//  into silence.
+//
+//  WHY THIS FILE EXISTS. base.css used to carry two hand-maintained `:where()`
+//  lists, and both had drifted:
+//
+//    - from the CLASSES: `.juno-seg__option` (the shipped class is
+//      `.juno-seg__opt`) and `.juno-list__item` (it is `.juno-list__row`) sat
+//      in them. `:where()` matched nothing, the rule still parsed, every other
+//      member kept working — so every segmented control and every grouped list
+//      row in every consumer kept the ~300ms double-tap delay. Invisible to
+//      lint, to the build and to a screenshot (20260826-024).
+//    - from EACH OTHER: the tap-highlight list was a strict subset of the
+//      touch-action one, missing __overflow, __opt, chip and toggle-btn, with
+//      nothing recording whether that was a decision.
+//
+//  ONE SET, NOT TWO — the open question from docs/conformance-kit.md, decided
+//  on the rules' own rationales rather than by merging them for tidiness. The
+//  tap-highlight rule exists so a UA square "never flashes past a rounded
+//  control on tap"; every name the shorter list omitted is a rounded tappable
+//  (`.juno-chip` and `.juno-pillbar__overflow` are 999px pills,
+//  `.juno-seg__opt` and `.juno-toggle-btn` carry radius-3). The omission has no
+//  stated reason and the rationale covers them, so it was an omission and not a
+//  decision. Both properties answer the same question — "is this one of ours,
+//  and is it tapped?" — and now read the same answer.
+//
+//  Adding a component here is the whole opt-in: state the class once, get both
+//  defaults. test/classes.test.mjs asserts every member is a class some
+//  component file actually defines, so a typo fails the build rather than
+//  going quiet.
+// ════════════════════════════════════════════════════════════════════════
+
+export const TOUCH_SURFACES = [
+  'juno-btn',
+  'juno-chip',
+  'juno-dock__item',
+  'juno-list__row',
+  'juno-menu__item',
+  'juno-pillbar__item',
+  'juno-pillbar__overflow',
+  'juno-seg__opt',
+  'juno-tabs__tab',
+  'juno-toggle-btn',
+  'juno-tree__row',
+  'juno-gizmo__mark',
+  'juno-gizmo__center',
+  'juno-swatch--button',
+  'juno-palette__option',
+];
+
+/** The `:where()` selector list, formatted for the bundle. */
+export function whereList(indent = '') {
+  return `:where(\n${TOUCH_SURFACES.map((c) => `${indent}  .${c}`).join(',\n')}\n${indent})`;
+}
+
+/** The generated touch-default layer.
+ *
+ *  Two rules, one member list. `touch-action` is NOT inside the coarse block:
+ *  a hybrid device (touch laptop, iPad with a trackpad) reports a fine primary
+ *  pointer while still taking touch input, and the property is inert on a
+ *  mouse anyway. The tap highlight only exists on touch, so it is.
+ *
+ *  `:where()` contributes zero specificity by design — these are defaults a
+ *  component or a consumer overrides by simply declaring the property. */
+export function touchDefaultsCss() {
+  return `/* GENERATED from src/css/touch-surfaces.mjs — do not edit here.
+ *
+ * Tappable primitives opt out of double-tap-to-zoom. A browser that still
+ * recognises that gesture has to WAIT after the first tap to see whether a
+ * second one is coming, which reads as a late, mushy tap on exactly the
+ * surfaces a phone UI is built from. \`manipulation\` keeps panning and
+ * pinch-zoom (so the page stays zoomable — never \`none\` here, that would be an
+ * a11y regression) and drops only the double-tap.
+ * Community convention — no primary Apple/WebKit source names it; see
+ * docs/ios-conformance.md. Named components only, so a consumer's own elements
+ * are untouched. See 20260803-038. */
+${whereList()} {
+  touch-action: manipulation;
+}
+
+/* And on touch, kill the UA tap-highlight square so it never flashes past a
+ * rounded control. Consumers were adding this by hand per component; it is a
+ * first-class touch default. See 20260802-020. */
+@media (pointer: coarse) {
+${whereList('  ')} {
+    -webkit-tap-highlight-color: transparent;
+  }
+}
+`;
+}

package/tools/gizmo.mjs

@@ -0,0 +1,144 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui/gizmo — bearing language and keyboard traversal for .juno-gizmo
+// ════════════════════════════════════════════════════════════════════════
+//  Two things a stylesheet cannot do, and both are the reason the component
+//  belongs upstream rather than in each app:
+//
+//  1. SAYING THE BEARING. "N" is a letter, not an accessible name, and
+//     "37deg" is a number a screen-reader user has to convert. `bearingLabel`
+//     turns an angle into the words a person would use.
+//  2. ONE FOCUS STOP. The gizmo is a composite widget: Tab reaches it once,
+//     arrow keys move between marks (wrapping, because a compass ring wraps),
+//     Enter activates. Eight separate tab stops for eight compass points is
+//     the thing apps ship and the thing that makes the widget unusable by
+//     keyboard.
+//
+//  Stateless, like junoui/tree: the app owns the camera. This moves focus and
+//  lets the marks' own click handlers fire; it never writes an angle.
+// ════════════════════════════════════════════════════════════════════════
+
+const MARK = '.juno-gizmo__mark';
+
+/** The 16 compass points, as words rather than letters. */
+const POINTS = [
+  'north',
+  'north-north-east',
+  'north-east',
+  'east-north-east',
+  'east',
+  'east-south-east',
+  'south-east',
+  'south-south-east',
+  'south',
+  'south-south-west',
+  'south-west',
+  'west-south-west',
+  'west',
+  'west-north-west',
+  'north-west',
+  'north-north-west',
+];
+
+/** Normalise any angle into [0, 360). */
+export const normalizeBearing = (deg) => ((Number(deg) % 360) + 360) % 360;
+
+/**
+ * A bearing as a person would say it: `37` → `"north-east"`.
+ *
+ * Sixteen points, nearest wins, and the boundaries are half a sector wide so
+ * 348.75..360 and 0..11.25 are both "north" — a naive `Math.round(deg / 22.5)`
+ * yields index 16 near 360 and reads off the end of the table.
+ */
+export function bearingLabel(deg) {
+  const d = normalizeBearing(deg);
+  return POINTS[Math.round(d / 22.5) % 16];
+}
+
+/**
+ * The full spoken description: direction, degrees, and the tilt when there is
+ * one. This is what goes in the live region — the ring itself is decoration to
+ * a screen reader, and a rotating needle announces nothing.
+ */
+export function orientationLabel(heading, pitch = null) {
+  const d = Math.round(normalizeBearing(heading));
+  const base = `Facing ${bearingLabel(d)}, ${d} degrees`;
+  return pitch === null || pitch === undefined
+    ? `${base}.`
+    : `${base}. Tilted ${Math.round(Number(pitch))} degrees.`;
+}
+
+/**
+ * Wire the gizmo as one focus stop. Returns a teardown function.
+ *
+ * Idempotent — enhancing twice replaces the first listener rather than
+ * stacking two, so a framework re-running an effect does not double-move focus
+ * on every keypress.
+ */
+export function enhanceGizmo(root) {
+  if (!root) throw new Error('enhanceGizmo: no root element');
+  root._junoGizmoTeardown?.();
+
+  const marks = () => [...root.querySelectorAll(MARK)].filter((m) => !m.disabled);
+
+  // Seed the roving tabindex: the mark the app marks current, else the first.
+  const seed = () => {
+    const list = marks();
+    if (!list.length) return;
+    for (const m of list) m.tabIndex = -1;
+    (list.find((m) => m.getAttribute('aria-current') === 'true') ?? list[0]).tabIndex = 0;
+  };
+  seed();
+
+  const onKeyDown = (event) => {
+    const list = marks();
+    const at = list.indexOf(event.target.closest(MARK));
+    if (at < 0) return;
+
+    // WRAPPING, because a compass ring wraps. Clamping at the ends is the
+    // behaviour of a slider, and it would make west unreachable from north by
+    // the short way round.
+    const move = (next) => {
+      event.preventDefault();
+      const target = list[(next + list.length) % list.length];
+      for (const m of list) m.tabIndex = -1;
+      target.tabIndex = 0;
+      target.focus();
+    };
+
+    switch (event.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        return move(at + 1);
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        return move(at - 1);
+      case 'Home':
+        return move(0);
+      case 'End':
+        return move(list.length - 1);
+      default:
+        // Enter and Space are the button's own; intercepting them would mean
+        // reimplementing activation, and a <button> already does it right.
+        return;
+    }
+  };
+
+  const onFocusIn = (event) => {
+    const mark = event.target.closest(MARK);
+    if (!mark || !root.contains(mark)) return;
+    // The pointer path: a click focuses a mark without passing through the
+    // keyboard move above, and the invariant has to hold for both.
+    for (const m of marks()) m.tabIndex = -1;
+    mark.tabIndex = 0;
+  };
+
+  root.addEventListener('keydown', onKeyDown);
+  root.addEventListener('focusin', onFocusIn);
+  const teardown = () => {
+    root.removeEventListener('keydown', onKeyDown);
+    root.removeEventListener('focusin', onFocusIn);
+    delete root._junoGizmoTeardown;
+  };
+  root._junoGizmoTeardown = teardown;
+  return teardown;
+}

package/tools/testing.mjs

@@ -0,0 +1,177 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui/testing — guards a consumer can run against its own source
+// ════════════════════════════════════════════════════════════════════════
+//  Framework-agnostic: throws an Error with a readable message, so it works
+//  under vitest, node:test, jest or a plain script. No dependencies.
+//
+//    import { assertJunoClasses } from 'junoui/testing';
+//    assertJunoClasses(['src/**/*.tsx']);
+//
+//  WHAT IT ANSWERS, and what it does not. It answers "junoui defines a rule
+//  mentioning this class". It does not answer "the class does what your
+//  component assumes" — a class that exists but was repurposed upstream
+//  passes. What it catches with certainty is a name that matches NOTHING,
+//  which is the whole of the defect it was written for: eleven such names
+//  once compiled silently in a consumer and rendered a phone dialog as
+//  unstyled UA defaults, with its confirm button off the bottom of the screen.
+//
+//  See docs/conformance-kit.md.
+// ════════════════════════════════════════════════════════════════════════
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** `juno-` or the role form `juno--`, then BEM segments.
+ *  The leading boundary keeps `--juno-warning` out: a custom property is
+ *  always preceded by a hyphen and a class never is. Getting this wrong makes
+ *  the guard report components that have no defect. */
+const CLASS_RE = /(?<![-\w])juno-{1,2}[a-z0-9]+(?:[-_]{1,2}[a-z0-9]+)*/g;
+
+/** The manifest this build ships. */
+export function loadJunoClasses() {
+  return JSON.parse(readFileSync(join(HERE, '..', 'dist', 'classes.json'), 'utf8'));
+}
+
+/**
+ * Source with comments removed.
+ *
+ * Crude by design — it does not parse string literals, so a `//` inside one
+ * truncates that line. Worth the simplicity: a class name does not live inside
+ * a URL, and the alternative is a second implementation of a compiler to
+ * answer a question about strings. Comments MUST be stripped: a file that
+ * documents a typo in order to explain it would otherwise be reported for it.
+ */
+export function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, ' ');
+}
+
+/**
+ * `juno-*` class names appearing in a source file, comments excluded.
+ *
+ * Matches anywhere in the code rather than parsing JSX: a class reaches the
+ * DOM through a template literal, a ternary or a helper as often as through a
+ * literal `className="…"`, and a matcher that only understood the literal form
+ * would skip the conditional ones — which is exactly where a typo hides.
+ */
+export function junoClassesIn(source) {
+  return [...new Set([...stripComments(source).matchAll(CLASS_RE)].map((m) => m[0]))].sort();
+}
+
+/** Minimal glob: supports `**`, `*` and `?`. No braces, no negation — a
+ *  consumer wanting more can pass an explicit file list instead. */
+function globToRegExp(pattern) {
+  let out = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        out += '.*';
+        i++;
+        if (pattern[i + 1] === '/') i++;
+      } else out += '[^/]*';
+    } else if (c === '?') out += '[^/]';
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp('^' + out + '$');
+}
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, acc);
+    else acc.push(p);
+  }
+  return acc;
+}
+
+/** Files matching any of `patterns`, resolved from `cwd`. */
+export function resolveFiles(patterns, cwd = process.cwd()) {
+  const res = patterns.map(globToRegExp);
+  const roots = new Set();
+  for (const p of patterns) {
+    const literal = p.split(/[*?]/)[0];
+    const base = literal.endsWith('/') ? literal : dirname(literal);
+    roots.add(base === '' || base === '.' ? cwd : join(cwd, base));
+  }
+  const files = [];
+  for (const root of roots) {
+    let st;
+    try {
+      st = statSync(root);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+    for (const f of walk(root)) {
+      const rel = relative(cwd, f).split(sep).join('/');
+      if (res.some((r) => r.test(rel))) files.push(rel);
+    }
+  }
+  return files.sort();
+}
+
+/**
+ * Throw if any file names a `juno-*` class this build does not define.
+ *
+ * @param patterns  globs or explicit paths, relative to `cwd`
+ * @param options.allowed  names the CONSUMER defines in its own stylesheet.
+ *   Each one is a claim the caller is making; check it against that stylesheet
+ *   rather than treating this as a waiver list.
+ * @param options.surface  `'all'` (default) or `'public'`.
+ *
+ *   'all' is the default deliberately, against this kit's own first proposal.
+ *   Measured on the 0.7.0 build: 310 classes have rules, 277 are named in
+ *   docs/. The 33-name difference is NOT an internals list — it is
+ *   `juno-sr-only`, `juno-bg-s0`, `juno-hide-below-lg`, `juno-eyebrow` and
+ *   friends, i.e. public utilities nobody wrote up. Defaulting to 'public'
+ *   would have failed consumers for using shipped API. 'public' remains
+ *   available for a stricter check, and the docs gap is junoui's to close.
+ */
+export function assertJunoClasses(patterns, options = {}) {
+  const { allowed = [], surface = 'all', cwd = process.cwd() } = options;
+  const manifest = loadJunoClasses();
+  // The claim is "junoui ships NOTHING by this name", not "this is not a
+  // class". A consumer writes `junoPx('juno-pillbar-gap')` and `#juno-i-${n}`,
+  // and no regex over source text can tell those from a class name — so a
+  // guard that only knew about classes would report correct code. Measured on
+  // a real consumer: 8 of 24 reports were tokens, an icon-id template and a
+  // keyframe, all of them names junoui does ship.
+  const shipped = [...manifest.keyframes, ...manifest.tokens, ...manifest.icons];
+  const defined = new Set(
+    surface === 'public'
+      ? [...manifest.public, ...manifest.roles, ...shipped]
+      : [...manifest.all, ...shipped],
+  );
+  const waived = new Set(allowed);
+
+  const files = Array.isArray(patterns)
+    ? resolveFiles(patterns, cwd)
+    : resolveFiles([patterns], cwd);
+  if (files.length === 0) {
+    // A guard that inspected nothing and passed is the failure mode this
+    // whole kit exists to stop.
+    throw new Error(
+      `assertJunoClasses: no files matched ${JSON.stringify(patterns)} under ${cwd} — ` +
+        `the check would have passed vacuously`,
+    );
+  }
+
+  const offenders = [];
+  for (const f of files) {
+    for (const cls of junoClassesIn(readFileSync(join(cwd, f), 'utf8'))) {
+      if (!defined.has(cls) && !waived.has(cls)) offenders.push(`${f}: ${cls}`);
+    }
+  }
+  if (offenders.length) {
+    throw new Error(
+      `junoui ${manifest.version} ships nothing named by ${offenders.length} \`juno-*\` name(s) ` +
+        `(surface: ${surface}, ${files.length} file(s) checked):\n  ` +
+        offenders.join('\n  '),
+    );
+  }
+  return { files: files.length, checked: defined.size };
+}