@ponchia/ui 0.6.8 → 0.6.9

package/CHANGELOG.md

@@ -5,6 +5,61 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.6.9 — 2026-06-20
+
+### Changed
+
+- **Product doctrine and 1.0 readiness.** `CONTRIBUTING.md`, `ROADMAP.md`,
+  `docs/architecture.md`, and `docs/stability.md` now codify the
+  core-vs-opt-in surface boundary, the refusal list, registry-first gate
+  maintenance, packed-tarball proof, a gate-backed 1.0 readiness ledger, and
+  release evidence policy for public-safe downstream proof. The stability
+  matrix now includes explicit rows for every exported opt-in CSS leaf plus
+  the public machine-readable/theme subpath families.
+- **Registry-backed gate ownership.** `check:report`,
+  `check:component-matrix`, `check:exports`, and `check:consumer-surface` now
+  share internal registries for the reporting toolbox, exported CSS leaves, and
+  optional framework peers instead of carrying separate hand-maintained lists.
+  The matrix gates also share one proof-owner helper for cached file reads,
+  owner-file existence, word matching, and required text evidence.
+- **Native complexity budget.** `check:complexity` is now part of the
+  aggregate `npm run check` chain. It uses the existing TypeScript parser to
+  keep function-level cyclomatic complexity at 12 or lower and function size
+  under budget without carrying per-function exception baselines.
+- **Gate-backed annotation package boundary.** The annotation docs now make the
+  split with `@ponchia/annotations` explicit: `@ponchia/ui/annotations` remains
+  the dependency-free Bronto static-helper compatibility surface, while richer
+  placement, renderer, editing, and adapter work belongs in the sibling
+  annotation package. `check:public-metadata` now guards that doctrine,
+  `check:exports` rejects packed code or declaration references to the sibling
+  package, and no runtime or public type dependency is added to `@ponchia/ui`.
+- **Public source hygiene guard.** `check:public-hygiene` now rejects internal
+  audit-ticket markers across repository source files, and still scans the
+  packed public text files for private terms, local paths, and secret-looking
+  assignments. `check:doc-links` also rejects executable URL schemes in public
+  authoring docs. The pass also brought
+  `behaviors/inert.js` under the generated declaration emit inputs so
+  `check:dts-emit` covers its public `.d.ts` surface.
+
+### Verified
+
+- **Release evidence.** `npm run check` passed for `0.6.9`, including
+  `check:pack`, `check:consumer-surface`, `check:consumer-types`,
+  `check:examples`, `check:publint`, and `check:attw`. No default-bundle budget
+  movement; this release is gate/docs/declaration hardening rather than a
+  runtime surface expansion.
+- **Downstream proof.** The packed current tarball installed into a disposable
+  copy of a real React/Vite app consumer that imports `@ponchia/ui/classes`,
+  `@ponchia/ui/behaviors`, `@ponchia/ui/tokens/resolved.json`, and
+  `@ponchia/ui/vega`; its `typecheck` and production `build` both passed.
+
+### Fixed
+
+- **Report sidecar hash validation.** `report-claims.v1` now requires
+  `contentHash` values to use exact SHA digest lengths (`sha256`, `sha384`, or
+  `sha512`) instead of accepting any hex payload after a supported algorithm
+  prefix.
+
 ## 0.6.8 — 2026-06-16
 
 Patch release for the deep UI-framework audit: broader browser/package gates,
@@ -462,7 +517,7 @@ and D2. The data-viz **palette** (`--chart-*`, `tokens/charts.json`) and the
 
 ### Fixed
 
-- **Published-type drift (code-quality audit).** `ui.meter({ tone: 'info' })` and
+- **Published-type drift.** `ui.meter({ tone: 'info' })` and
   `ui.bracketNote({ tone: 'success' })` emit real classes at runtime, but the
   generated `.d.ts` tone unions (hand-mirrored in `gen-dts.mjs`) omitted them, so
   a TS consumer got a spurious type error for a value that renders. The unions
@@ -634,16 +689,16 @@ and D2. The data-viz **palette** (`--chart-*`, `tokens/charts.json`) and the
   token source as a read-only export for foreign renderers (in-DOM ink is
   `--button-text`). `contrast.md` now prints APCA `Lc` to one decimal so an
   advisory shortfall (e.g. `Lc 44.9`) no longer rounds to a passing-looking `45`.
-- Raw bundle budget 81 → 82 kB for the component-audit accessibility/state
+- Raw bundle budget 81 → 82 kB for the accessibility/state
   blocks (gzip held ~14.1 kB — the additions are repetitive media-query and
   `:has()`/`:not()` rules that compress well).
-- **Code-quality audit (16-agent) — two new gates + targeted dedup, no churn.**
+- **Code-health pass — two new gates + targeted dedup, no churn.**
   A code-health pass (complexity / duplication / AI-slop / missing-best-practice)
   that deliberately left working, gate-protected code alone. Added:
   `check:recipe-types` (factory↔`.d.ts` option parity, above) and `check:chain`
   (every `check:*` script is wired into the aggregate `check` chain — closes the
   silent-coverage-drop class; it would have caught a forgotten gate). Reconciled
-  a latent bug — `clamp()` had silently diverged between `connectors` and
+  a latent bug — `clamp()` had drifted between `connectors` and
   `annotations`; the two now share one scalar/geometry kernel (the guarded form).
   Dedup that removed real duplication: a shared `collectHosts()` /
   `scrollIntoViewSafe()` / `wrapIndex()` in `behaviors/internal.js` (~9 behaviors),

package/README.md

@@ -67,7 +67,7 @@ npm i @ponchia/ui
 Or drop it in with no build step, straight from a CDN:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/bronto.css">
 ```
 
 ## Quick start
@@ -140,7 +140,7 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
 - **Shells** — a service/app shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
-- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: **figure** stages, SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, a cross-cutting **selection** vocabulary, and CSS Custom Highlight API **highlights**. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust), **interval**, **clamp**, and **lifecycle `state`** leaves.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: **figure** stages, SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, a cross-cutting **selection** vocabulary, and CSS Custom Highlight API **highlights**. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. The richer annotation engine lives in `@ponchia/annotations`; this package keeps only the dependency-free Bronto helper surface. Plus standalone **`source`/provenance** (trust), **interval**, **clamp**, and **lifecycle `state`** leaves.
 - **Reports** _(opt-in)_ — `@ponchia/ui/css/report-kit.css` for a complete static/PDF report vocabulary, or `@ponchia/ui/css/report.css` plus only the leaves a narrow report uses. Covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, `ui-figure` composition, intervals, bounded excerpts, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
 - **Glyphs** — `@ponchia/ui/glyphs`, a 71-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).

package/annotations/index.d.ts.map

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

package/annotations/index.js

@@ -209,8 +209,7 @@ import {
   arrowHead,
   dotMark,
   angleBetween,
-  // Shared scalar/geometry kernel — single source of truth (was copy-pasted,
-  // and the local clamp had silently diverged from the connectors one).
+  // Shared scalar/geometry kernel for annotation and connector path output.
   roundNumber,
   finite,
   dimension,
@@ -220,8 +219,8 @@ import {
   rectPath,
 } from '../connectors/index.js';
 
-// A circle subject is just a filled dot at (x, y) — delegate to the kernel's
-// dotMark so the arc geometry/precision can't diverge. (code-quality audit Q5.)
+// A circle subject is just a filled dot at (x, y); delegate to the connector
+// kernel so arc geometry and numeric precision stay aligned.
 function circlePathAt(x, y, radius) {
   return dotMark({ x, y }, radius);
 }
@@ -670,8 +669,8 @@ export function connectorCurve(opts = {}) {
   return curvePath(start, end, { curvature: 0.35 });
 }
 
-// subject.type → its path builder. A flat dispatch table (replaces an 11-arm
-// if/else) keyed by the SubjectType union; an unknown type throws below. (Q10.)
+// subject.type → its path builder. A flat dispatch table keyed by the
+// SubjectType union; an unknown type throws below.
 const SUBJECT_BUILDERS = {
   circle: circleSubjectPath,
   rect: rectSubjectPath,

package/behaviors/carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA8L3C"}
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AA6HA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAsJ3C"}

package/behaviors/carousel.js

@@ -43,6 +43,86 @@ const renderedStatusIndex = (status) => {
   return Number.isInteger(value) ? value - 1 : -1;
 };
 
+const snapshotCarouselState = ({ viewport, slides, status, prevBtn, nextBtn, thumbs }) => ({
+  viewport: snapshotNode(viewport),
+  slides: slides.map((slide) => snapshotNode(slide)),
+  status: snapshotNode(status, { html: true }),
+  controls: [prevBtn, nextBtn, ...thumbs].filter(Boolean).map((control) => snapshotNode(control)),
+});
+
+function restoreCarouselState(state) {
+  restoreNode(state.viewport);
+  state.slides.forEach(restoreNode);
+  restoreNode(state.status);
+  state.controls.forEach(restoreNode);
+}
+
+function setDefaultButtonType(button) {
+  if (button?.tagName === 'BUTTON' && !button.hasAttribute('type')) button.type = 'button';
+}
+
+function applyCarouselA11y({ box, viewport, slides, status, prevBtn, nextBtn, thumbs, n }) {
+  // ARIA scaffolding — pragmatic carousel semantics (not the full APG
+  // tablist), the same restraint initMenu takes.
+  viewport.setAttribute('role', 'group');
+  viewport.setAttribute('aria-roledescription', 'carousel');
+  if (!viewport.hasAttribute('aria-label')) {
+    viewport.setAttribute(
+      'aria-label',
+      box.getAttribute('data-bronto-carousel-label') || 'Carousel',
+    );
+  }
+  if (!viewport.hasAttribute('tabindex')) viewport.tabIndex = 0;
+  slides.forEach((slide, i) => {
+    slide.setAttribute('role', 'group');
+    slide.setAttribute('aria-roledescription', 'slide');
+    if (!slide.hasAttribute('aria-label')) slide.setAttribute('aria-label', `${i + 1} of ${n}`);
+  });
+  if (status) status.setAttribute('aria-live', 'polite');
+  [prevBtn, nextBtn, ...thumbs].forEach(setDefaultButtonType);
+  if (prevBtn && !prevBtn.hasAttribute('aria-label'))
+    prevBtn.setAttribute('aria-label', 'Previous');
+  if (nextBtn && !nextBtn.hasAttribute('aria-label')) nextBtn.setAttribute('aria-label', 'Next');
+}
+
+function bindCarouselLifecycle({
+  box,
+  viewport,
+  slides,
+  status,
+  prevBtn,
+  nextBtn,
+  thumbs,
+  n,
+  render,
+  onKey,
+  onClick,
+  io,
+  holdProgrammatic,
+  clearProgrammaticTimer,
+}) {
+  const state = snapshotCarouselState({ viewport, slides, status, prevBtn, nextBtn, thumbs });
+  applyCarouselA11y({ box, viewport, slides, status, prevBtn, nextBtn, thumbs, n });
+  render();
+  viewport.addEventListener('keydown', onKey);
+  box.addEventListener('click', onClick);
+  // Observe inside the add callback so observe/disconnect pair with the
+  // binding lifecycle: a re-init tears down the prior binding (which
+  // disconnects the old observer) before this starts, so two observers
+  // never watch the same slides — even for one tick.
+  if (io) {
+    holdProgrammatic();
+    slides.forEach((slide) => io.observe(slide));
+  }
+  return () => {
+    viewport.removeEventListener('keydown', onKey);
+    box.removeEventListener('click', onClick);
+    io?.disconnect();
+    clearProgrammaticTimer();
+    restoreCarouselState(state);
+  };
+}
+
 /**
  * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
  * swipe (and momentum) are the browser's, not hand-rolled. This wires the
@@ -193,66 +273,26 @@ export function initCarousel({ root } = {}) {
       );
     }
 
-    const bound = bindOnce(box, 'carousel', () => {
-      const state = {
-        viewport: snapshotNode(viewport),
-        slides: slides.map((slide) => snapshotNode(slide)),
-        status: snapshotNode(status, { html: true }),
-        controls: [prevBtn, nextBtn, ...thumbs]
-          .filter(Boolean)
-          .map((control) => snapshotNode(control)),
-      };
-
-      // ARIA scaffolding — pragmatic carousel semantics (not the full APG
-      // tablist), the same restraint initMenu takes.
-      viewport.setAttribute('role', 'group');
-      viewport.setAttribute('aria-roledescription', 'carousel');
-      if (!viewport.hasAttribute('aria-label'))
-        viewport.setAttribute(
-          'aria-label',
-          box.getAttribute('data-bronto-carousel-label') || 'Carousel',
-        );
-      if (!viewport.hasAttribute('tabindex')) viewport.tabIndex = 0;
-      slides.forEach((s, i) => {
-        s.setAttribute('role', 'group');
-        s.setAttribute('aria-roledescription', 'slide');
-        if (!s.hasAttribute('aria-label')) s.setAttribute('aria-label', `${i + 1} of ${n}`);
-      });
-      if (status) status.setAttribute('aria-live', 'polite');
-      for (const b of [prevBtn, nextBtn]) {
-        if (!b) continue;
-        if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
-      }
-      for (const b of thumbs) {
-        if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
-      }
-      if (prevBtn && !prevBtn.hasAttribute('aria-label'))
-        prevBtn.setAttribute('aria-label', 'Previous');
-      if (nextBtn && !nextBtn.hasAttribute('aria-label'))
-        nextBtn.setAttribute('aria-label', 'Next');
-
-      render();
-      viewport.addEventListener('keydown', onKey);
-      box.addEventListener('click', onClick);
-      // Observe inside the add callback so observe/disconnect pair with the
-      // binding lifecycle: a re-init tears down the prior binding (which
-      // disconnects the old observer) before this starts, so two observers
-      // never watch the same slides — even for one tick.
-      if (io) {
-        holdProgrammatic();
-        slides.forEach((s) => io.observe(s));
-      }
-      return () => {
-        viewport.removeEventListener('keydown', onKey);
-        box.removeEventListener('click', onClick);
-        io?.disconnect();
-        if (progTimer) clearTimeout(progTimer);
-        restoreNode(state.viewport);
-        state.slides.forEach(restoreNode);
-        restoreNode(state.status);
-        state.controls.forEach(restoreNode);
-      };
-    });
+    const bound = bindOnce(box, 'carousel', () =>
+      bindCarouselLifecycle({
+        box,
+        viewport,
+        slides,
+        status,
+        prevBtn,
+        nextBtn,
+        thumbs,
+        n,
+        render,
+        onKey,
+        onClick,
+        io,
+        holdProgrammatic,
+        clearProgrammaticTimer: () => {
+          if (progTimer) clearTimeout(progTimer);
+        },
+      }),
+    );
     cleanups.push(bound);
   }
 

package/behaviors/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["combobox.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA8S3C"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["combobox.js"],"names":[],"mappings":"AAmIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA6O3C"}

package/behaviors/combobox.js

@@ -10,6 +10,125 @@ import {
   closestSafe,
 } from './internal.js';
 
+const COMBOBOX_OPTION_SELECTOR = '[role="option"], .ui-combobox__option';
+
+const snapshotAttrs = (el, names) => {
+  const out = {};
+  for (const name of names) {
+    out[name] = {
+      had: el.hasAttribute(name),
+      value: el.getAttribute(name),
+    };
+  }
+  return out;
+};
+
+const restoreAttrs = (el, attrs) => {
+  for (const [name, attr] of Object.entries(attrs)) {
+    if (attr.had) el.setAttribute(name, attr.value);
+    else el.removeAttribute(name);
+  }
+};
+
+const inputLabel = (input) =>
+  input.getAttribute('aria-label') || input.labels?.[0]?.textContent?.trim();
+
+const inputHasAccessibleName = (input) =>
+  input.hasAttribute('aria-label') ||
+  input.hasAttribute('aria-labelledby') ||
+  !!input.labels?.length ||
+  input.hasAttribute('title');
+
+function mirrorListboxLabel(input, list) {
+  if (list.hasAttribute('aria-label') || list.hasAttribute('aria-labelledby')) return;
+  const name = inputLabel(input);
+  if (name) list.setAttribute('aria-label', name);
+}
+
+function warnNamelessCombobox(input) {
+  if (inputHasAccessibleName(input) || typeof console === 'undefined') return;
+  console.warn(
+    '[bronto] initCombobox(): the combobox input has no accessible name — add a <label>, aria-label, or aria-labelledby (a placeholder is not enough).',
+  );
+}
+
+function prepareEmptyState(empty) {
+  if (!empty) return;
+  empty.hidden = true;
+  if (!empty.hasAttribute('role')) empty.setAttribute('role', 'status');
+}
+
+function liveOptionObserver(box, list, relist) {
+  if (!box.hasAttribute('data-bronto-combobox-live')) return null;
+  if (typeof MutationObserver !== 'function') return null;
+  const observer = new MutationObserver(relist);
+  observer.observe(list, { childList: true, subtree: true });
+  return observer;
+}
+
+function bindComboboxLifecycle({
+  box,
+  input,
+  list,
+  empty,
+  rememberState,
+  restoreState,
+  assignListId,
+  syncOptions,
+  close,
+  relist,
+  onInput,
+  onKey,
+  onOptionClick,
+  onDocClick,
+  resetActive,
+}) {
+  const state = rememberState();
+  const listId = assignListId();
+  syncOptions();
+  list.setAttribute('role', 'listbox');
+  // Give the listbox its own accessible name (a bare role=listbox is unnamed
+  // to a screen reader) by mirroring the input's real name.
+  // The placeholder is deliberately NOT in this chain: the input warning below
+  // already rejects a placeholder as an inadequate name, so papering the
+  // listbox over with it would contradict that. If there is no real name, the
+  // listbox stays unnamed and the warning is the signal.
+  mirrorListboxLabel(input, list);
+  // A `role="combobox"` with no accessible name is a silent AT failure. A
+  // placeholder is not a robust name (it can vanish and is ignored by some
+  // AT), so warn unless there is a real label/aria-label/aria-labelledby/title
+  // We cannot invent a good name, hence a dev-time warning, not a guess.
+  warnNamelessCombobox(input);
+  input.setAttribute('role', 'combobox');
+  input.setAttribute('aria-controls', listId);
+  input.setAttribute('aria-autocomplete', 'list');
+  input.setAttribute('aria-expanded', 'false');
+  input.setAttribute('autocomplete', 'off');
+  // Hide the empty-state at rest: it must only appear once a filter yields no
+  // matches, never on an idle combobox. Without this an author who omits
+  // `hidden` on `.ui-combobox__empty` ships a box that reads "No matches"
+  // before the user has typed anything. Make it a status live region so its
+  // appearance is announced.
+  prepareEmptyState(empty);
+  close();
+  input.addEventListener('input', onInput);
+  input.addEventListener('keydown', onKey);
+  list.addEventListener('click', onOptionClick);
+  document.addEventListener('click', onDocClick);
+  // Opt-in: keep options in sync with a list mutated after init (async /
+  // remote results). Off by default so the common static case stays free.
+  const observer = liveOptionObserver(box, list, relist);
+  return () => {
+    observer?.disconnect();
+    input.removeEventListener('input', onInput);
+    input.removeEventListener('keydown', onKey);
+    list.removeEventListener('click', onOptionClick);
+    document.removeEventListener('click', onDocClick);
+    restoreState(state);
+    resetActive();
+  };
+}
+
 /**
  * Editable combobox with a filtered listbox popup, implementing the
  * WAI-ARIA APG combobox pattern (the widget the framework most lacked
@@ -55,24 +174,6 @@ export function initCombobox({ root } = {}) {
   const boxes = collectHosts(host, '[data-bronto-combobox]');
   const cleanups = [];
 
-  const snapshotAttrs = (el, names) => {
-    const out = {};
-    for (const name of names) {
-      out[name] = {
-        had: el.hasAttribute(name),
-        value: el.getAttribute(name),
-      };
-    }
-    return out;
-  };
-
-  const restoreAttrs = (el, attrs) => {
-    for (const [name, attr] of Object.entries(attrs)) {
-      if (attr.had) el.setAttribute(name, attr.value);
-      else el.removeAttribute(name);
-    }
-  };
-
   for (const box of boxes) {
     const input = box.querySelector('[role="combobox"], .ui-combobox__input');
     const list = box.querySelector('[role="listbox"], .ui-combobox__list');
@@ -134,7 +235,7 @@ export function initCombobox({ root } = {}) {
     // `filter`, `move`, etc. close over this binding, so reassigning it is enough.
     let options = [];
     const syncOptions = () => {
-      options = [...list.querySelectorAll('[role="option"], .ui-combobox__option')];
+      options = [...list.querySelectorAll(COMBOBOX_OPTION_SELECTOR)];
       options.forEach((o, i) => {
         rememberOptionState(o);
         if (!o.id) o.id = `${listId}-opt-${i}`;
@@ -190,7 +291,6 @@ export function initCombobox({ root } = {}) {
       // Show the human LABEL in the input; emit the `data-value` CODE in the
       // event. The natural pattern is code in `data-value`, label in the text —
       // putting the code in the visible input silently shows the user a raw code.
-      // (component audit C10.)
       const label = opt.textContent.trim();
       const value = opt.dataset.value ?? label;
       input.value = label;
@@ -243,107 +343,61 @@ export function initCombobox({ root } = {}) {
 
     const onInput = () => filter();
     const onKey = (e) => {
-      switch (e.key) {
-        case 'ArrowDown':
-          e.preventDefault();
-          list.hidden ? filter() : move(1);
-          break;
-        case 'ArrowUp':
-          e.preventDefault();
-          move(-1);
-          break;
-        case 'Home':
-          if (activateEdge('first')) e.preventDefault();
-          break;
-        case 'End':
-          if (activateEdge('last')) e.preventDefault();
-          break;
-        case 'Enter':
-          if (selectActive()) e.preventDefault();
-          break;
-        case 'Escape':
-          if (closeIfOpen()) e.preventDefault();
-          break;
-        case 'Tab':
-          close();
-          break;
-        default:
-          break;
-      }
+      const handled = keyHandlers[e.key]?.();
+      if (handled) e.preventDefault();
+    };
+    const keyHandlers = {
+      ArrowDown: () => {
+        if (list.hidden) filter();
+        else move(1);
+        return true;
+      },
+      ArrowUp: () => {
+        move(-1);
+        return true;
+      },
+      Home: () => activateEdge('first'),
+      End: () => activateEdge('last'),
+      Enter: () => selectActive(),
+      Escape: () => closeIfOpen(),
+      Tab: () => {
+        close();
+        return false;
+      },
     };
     const onOptionClick = (e) => {
-      const opt = closestSafe(e.target, '[role="option"], .ui-combobox__option');
+      const opt = closestSafe(e.target, COMBOBOX_OPTION_SELECTOR);
       if (opt) select(opt);
     };
     const onDocClick = (e) => {
       if (!box.contains(e.target)) close();
     };
-
-    const bound = bindOnce(box, 'combobox', () => {
-      const state = rememberState();
+    const assignListId = () => {
       listId = list.id || (list.id = `bronto-cb-list-${nextFieldUid()}`);
-      syncOptions();
-      list.setAttribute('role', 'listbox');
-      // Give the listbox its own accessible name (a bare role=listbox is unnamed
-      // to a screen reader) by mirroring the input's REAL name. (a11y review C30.)
-      // The placeholder is deliberately NOT in this chain: the input warning below
-      // already rejects a placeholder as an inadequate name, so papering the
-      // listbox over with it would contradict that — if there's no real name the
-      // listbox stays unnamed and the warning is the signal. (component audit C28.)
-      if (!list.hasAttribute('aria-label') && !list.hasAttribute('aria-labelledby')) {
-        const name = input.getAttribute('aria-label') || input.labels?.[0]?.textContent?.trim();
-        if (name) list.setAttribute('aria-label', name);
-      }
-      // A `role="combobox"` with no accessible name is a silent AT failure. A
-      // placeholder is not a robust name (it can vanish and is ignored by some
-      // AT), so warn unless there is a real label/aria-label/aria-labelledby/title
-      // (C7). We can't invent a good name, hence a dev-time warning, not a guess.
-      const inputNamed =
-        input.hasAttribute('aria-label') ||
-        input.hasAttribute('aria-labelledby') ||
-        !!input.labels?.length ||
-        input.hasAttribute('title');
-      if (!inputNamed && typeof console !== 'undefined') {
-        console.warn(
-          '[bronto] initCombobox(): the combobox input has no accessible name — add a <label>, aria-label, or aria-labelledby (a placeholder is not enough).',
-        );
-      }
-      input.setAttribute('role', 'combobox');
-      input.setAttribute('aria-controls', listId);
-      input.setAttribute('aria-autocomplete', 'list');
-      input.setAttribute('aria-expanded', 'false');
-      input.setAttribute('autocomplete', 'off');
-      // Hide the empty-state at rest: it must only appear once a filter yields no
-      // matches, never on an idle combobox. Without this an author who omits
-      // `hidden` on `.ui-combobox__empty` ships a box that reads "No matches"
-      // before the user has typed anything. (component audit C10.) Make it a
-      // status live region so its appearance is announced. (component audit C38.)
-      if (empty) {
-        empty.hidden = true;
-        if (!empty.hasAttribute('role')) empty.setAttribute('role', 'status');
-      }
-      close();
-      input.addEventListener('input', onInput);
-      input.addEventListener('keydown', onKey);
-      list.addEventListener('click', onOptionClick);
-      document.addEventListener('click', onDocClick);
-      // Opt-in: keep options in sync with a list mutated after init (async /
-      // remote results). Off by default so the common static case stays free.
-      const observer =
-        box.hasAttribute('data-bronto-combobox-live') && typeof MutationObserver === 'function'
-          ? new MutationObserver(relist)
-          : null;
-      observer?.observe(list, { childList: true, subtree: true });
-      return () => {
-        observer?.disconnect();
-        input.removeEventListener('input', onInput);
-        input.removeEventListener('keydown', onKey);
-        list.removeEventListener('click', onOptionClick);
-        document.removeEventListener('click', onDocClick);
-        restoreState(state);
-        active = -1;
-      };
-    });
+      return listId;
+    };
+
+    const bound = bindOnce(box, 'combobox', () =>
+      bindComboboxLifecycle({
+        box,
+        input,
+        list,
+        empty,
+        rememberState,
+        restoreState,
+        assignListId,
+        syncOptions,
+        close,
+        relist,
+        onInput,
+        onKey,
+        onOptionClick,
+        onDocClick,
+        resetActive: () => {
+          active = -1;
+        },
+      }),
+    );
     cleanups.push(bound);
   }