@ponchia/ui 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -5,6 +5,76 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.6.8 — 2026-06-16
+
+Patch release for the deep UI-framework audit: broader browser/package gates,
+clean-consumer verification, and runtime fixes found while hardening the public
+surface. No breaking changes, no `MIGRATIONS.json` entry.
+
+### Added
+
+- **Tarball and clean-consumer gates.** `check:consumer-surface` now imports
+  public JS/JSON subpaths from the packed package, resolves concrete CSS/doc/
+  font subpaths without optional peers, and verifies behavior initializers stay
+  SSR-safe. `check:consumer-types` installs the tarball into a clean TypeScript
+  consumer and compiles every typed `@ponchia/ui/...` package subpath.
+- **Matrix ownership gates.** `check:component-matrix`,
+  `check:behavior-matrix`, `check:helper-matrix`, and `check:binding-matrix`
+  now require shipped CSS leaves, public behavior exports, helper modules, and
+  framework bindings to have explicit docs, type, unit, or browser ownership.
+- **Public docs and package hygiene gates.** `check:doc-links` validates local
+  links and heading anchors across shipped docs, authoring docs, and the docs
+  viewer route list. `check:schemas`, `check:visual-baselines`,
+  `check:playwright-container`, and stronger `check:contract` / `check:report`
+  coverage close stale public snippets, missing visual baselines, and invalid
+  report/schema surfaces.
+- **Broader browser coverage.** The Playwright suite now pins docs viewer deep
+  links, cascade-layer behavior, source focusing, renderer geometry, behavior
+  cleanup/idempotency, connector transforms, annotation motion/overflow,
+  command interactions, crosshair payloads, responsive overflow, and more
+  forced-colors/reduced-motion contracts.
+- **Packed example smoke coverage.** The example runner now builds and smokes
+  the packed examples from one registry, with richer runtime assertions,
+  desktop/mobile visual health, and optional Chromium/Firefox/WebKit coverage.
+  Astro joins the packed-tarball smoke matrix.
+- **Renderer theme helper coverage.** Chart, Mermaid, D2, and Vega package
+  helpers now have type/runtime coverage that checks default exports,
+  theme-selection fallbacks, resolved colors, and `var()` leak prevention.
+
+### Fixed
+
+- **Standalone dot readouts survive `report-kit.css`.** `crosshair.css` now
+  scopes pinned readout-chip styling to `.ui-crosshair .ui-readout`, so the
+  core dot-matrix `.ui-readout` keeps its normal inline layout when a report
+  imports the full report kit.
+- **Rendered docs deep links work.** `docs/index.html` now preserves
+  `doc.md#section` routes, generates deterministic heading IDs, keeps
+  same-page anchors inside the current doc route, and drops the invalid
+  meta-CSP `frame-ancestors` directive that browsers reported as a console
+  error.
+- **Command adapter docs match the shipped matrix.** `docs/command.md`, the
+  stability matrix, package-contract provenance, and `llms.txt` now name the
+  Svelte action and Vue directive/plugin paths alongside the React/Solid/Qwik
+  bindings.
+- **CodeQL review findings.** Docs slug helpers no longer use incomplete
+  regex-based tag stripping, and wildcard package-subpath expansion replaces
+  every placeholder rather than only the first one.
+
+### Changed
+
+- `npm run check` now owns the unit suite through `check:unit`; CI, release
+  workflow validation, PR templates, release docs, and package-contract docs
+  all describe the same aggregate gate instead of duplicating `npm test`.
+- Release hygiene now verifies the aggregate check includes unit coverage and
+  prevents duplicate release-workflow unit runs from drifting out of sync.
+- `check:exports` now pins package-level CSS metadata: the top-level `style`
+  field, root export targets, `files`, and CSS-preserving `sideEffects`.
+- Type-only coverage now instantiates Svelte action and Vue directive
+  declarations from consumer-shaped code, including invalid root-shape
+  assertions.
+- The default bundle budget is recalibrated to 91 kB raw / 15.65 kB gzip after
+  the audited bundle landed below that ceiling at 87.9 kB raw / 15.0 kB gzip.
+
 ## 0.6.7 — 2026-06-15
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~87kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~88kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
@@ -67,12 +67,12 @@ 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.7/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/bronto.css">
 ```
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~87 kB raw / ~15 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~88 kB raw / ~15 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */

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

@@ -237,6 +237,24 @@ function validateOffset(opts) {
   };
 }
 
+function annotationConnectorType(value) {
+  const type = value ?? 'callout';
+  if (type === 'callout' || type === 'elbow' || type === 'curve') return type;
+  throw new TypeError('type must be "callout", "elbow" or "curve"');
+}
+
+function directLabelAxis(value) {
+  const axis = value ?? 'y';
+  if (axis === 'x' || axis === 'y') return axis;
+  throw new TypeError('axis must be "x" or "y"');
+}
+
+function directLabelShape(value) {
+  const shape = value ?? 'straight';
+  if (shape === 'straight' || shape === 'elbow' || shape === 'curve') return shape;
+  throw new TypeError('shape must be "straight", "elbow" or "curve"');
+}
+
 function trimForCircle(dx, dy, subject) {
   const len = Math.hypot(dx, dy);
   const radius = dimension('subject.radius', subject.radius);
@@ -673,7 +691,7 @@ const SUBJECT_BUILDERS = {
  * @returns {AnnotationParts}
  */
 export function annotationParts(opts = {}) {
-  const type = opts.type ?? 'callout';
+  const type = annotationConnectorType(opts.type);
   const transform = annotationTransform({ x: opts.x ?? 0, y: opts.y ?? 0 });
   const dx = finite('dx', opts.dx, 0);
   const dy = finite('dy', opts.dy, 0);
@@ -764,9 +782,9 @@ export function declutterLabels(items, opts = {}) {
  */
 export function directLabels(items, opts = {}) {
   if (!Array.isArray(items)) throw new TypeError('items must be an array');
-  const axis = opts.axis === 'x' ? 'x' : 'y';
+  const axis = directLabelAxis(opts.axis);
   const cross = finite('cross', opts.cross, 0);
-  const shape = opts.shape === 'elbow' || opts.shape === 'curve' ? opts.shape : 'straight';
+  const shape = directLabelShape(opts.shape);
 
   const anchors = items.map((it) => ({
     anchor: { x: finite('anchor.x', it?.anchor?.x), y: finite('anchor.y', it?.anchor?.y) },

package/behaviors/carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA0K3C"}
+{"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"}

package/behaviors/carousel.js

@@ -5,8 +5,44 @@ import {
   bindOnce,
   scrollIntoViewSafe,
   collectHosts,
+  closestSafe,
 } from './internal.js';
 
+const snapshotAttrs = (el) =>
+  Array.from(el.attributes, ({ name, value }) => ({
+    name,
+    value,
+  }));
+
+const restoreAttrs = (el, attrs) => {
+  for (const { name } of Array.from(el.attributes)) el.removeAttribute(name);
+  for (const { name, value } of attrs) el.setAttribute(name, value);
+};
+
+const snapshotNode = (el, { html = false } = {}) =>
+  el
+    ? {
+        el,
+        attrs: snapshotAttrs(el),
+        ...(html ? { innerHTML: el.innerHTML } : {}),
+      }
+    : null;
+
+const restoreNode = (state) => {
+  if (!state) return;
+  restoreAttrs(state.el, state.attrs);
+  if ('innerHTML' in state) state.el.innerHTML = state.innerHTML;
+};
+
+const clampIndex = (value, max) => Math.max(0, Math.min(max, value));
+
+const renderedStatusIndex = (status) => {
+  const match = /^(\d+)\s*\/\s*\d+$/.exec(status?.textContent?.trim() ?? '');
+  if (!match) return -1;
+  const value = Number(match[1]);
+  return Number.isInteger(value) ? value - 1 : -1;
+};
+
 /**
  * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
  * swipe (and momentum) are the browser's, not hand-rolled. This wires the
@@ -54,36 +90,12 @@ export function initCarousel({ root } = {}) {
     const nextBtn = box.querySelector('[data-bronto-carousel-next]');
     const loop = box.hasAttribute('data-bronto-carousel-loop');
 
-    // 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');
-
-    let index = Math.max(
-      0,
-      slides.findIndex((s) => s.hasAttribute('data-bronto-carousel-current')),
+    const authoredIndex = slides.findIndex((s) => s.hasAttribute('data-bronto-carousel-current'));
+    const renderedThumbIndex = thumbs.findIndex((t) => t.getAttribute('aria-current') === 'true');
+    const statusIndex = renderedStatusIndex(status);
+    let index = clampIndex(
+      renderedThumbIndex >= 0 ? renderedThumbIndex : statusIndex >= 0 ? statusIndex : authoredIndex,
+      n - 1,
     );
 
     // While a button/keyboard nav is smooth-scrolling, the IntersectionObserver
@@ -139,15 +151,15 @@ export function initCarousel({ root } = {}) {
       goTo(target);
     };
     const onClick = (e) => {
-      if (prevBtn && e.target.closest('[data-bronto-carousel-prev]')) {
+      if (prevBtn && closestSafe(e.target, '[data-bronto-carousel-prev]')) {
         goTo(index - 1);
         return;
       }
-      if (nextBtn && e.target.closest('[data-bronto-carousel-next]')) {
+      if (nextBtn && closestSafe(e.target, '[data-bronto-carousel-next]')) {
         goTo(index + 1);
         return;
       }
-      const thumb = e.target.closest('.ui-carousel__thumb');
+      const thumb = closestSafe(e.target, '.ui-carousel__thumb');
       if (thumb) {
         const i = thumbs.indexOf(thumb);
         if (i >= 0) goTo(i);
@@ -181,20 +193,64 @@ export function initCarousel({ root } = {}) {
       );
     }
 
-    render();
     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.
-      slides.forEach((s) => io?.observe(s));
+      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);
       };
     });
     cleanups.push(bound);

package/behaviors/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["combobox.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAqO3C"}
+{"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"}

package/behaviors/combobox.js

@@ -7,6 +7,7 @@ import {
   scrollIntoViewSafe,
   wrapIndex,
   collectHosts,
+  closestSafe,
 } from './internal.js';
 
 /**
@@ -54,12 +55,80 @@ 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');
     if (!input || !list) continue;
     const empty = box.querySelector('.ui-combobox__empty');
-    const listId = list.id || (list.id = `bronto-cb-list-${nextFieldUid()}`);
+    const optionStates = new WeakMap();
+    let listId = '';
+
+    const rememberOptionState = (option) => {
+      if (optionStates.has(option)) return;
+      optionStates.set(option, {
+        hidden: option.hidden,
+        active: option.classList.contains('is-active'),
+        attrs: snapshotAttrs(option, ['id', 'role', 'aria-selected']),
+      });
+    };
+
+    const rememberState = () => ({
+      input: snapshotAttrs(input, [
+        'role',
+        'aria-controls',
+        'aria-autocomplete',
+        'aria-expanded',
+        'aria-activedescendant',
+        'autocomplete',
+      ]),
+      list: {
+        hidden: list.hidden,
+        attrs: snapshotAttrs(list, ['id', 'role', 'aria-label']),
+      },
+      empty: empty
+        ? {
+            hidden: empty.hidden,
+            attrs: snapshotAttrs(empty, ['role']),
+          }
+        : null,
+      options: optionStates,
+    });
+
+    const restoreState = (state) => {
+      restoreAttrs(input, state.input);
+      list.hidden = state.list.hidden;
+      restoreAttrs(list, state.list.attrs);
+      if (empty && state.empty) {
+        empty.hidden = state.empty.hidden;
+        restoreAttrs(empty, state.empty.attrs);
+      }
+      for (const option of options) {
+        const optionState = state.options.get(option);
+        if (!optionState) continue;
+        option.hidden = optionState.hidden;
+        option.classList.toggle('is-active', optionState.active);
+        restoreAttrs(option, optionState.attrs);
+      }
+    };
+
     // Re-readable so the opt-in MutationObserver (`data-bronto-combobox-live`)
     // can pick up async/replaced option nodes without a full re-init. `visible`,
     // `filter`, `move`, etc. close over this binding, so reassigning it is enough.
@@ -67,51 +136,11 @@ export function initCombobox({ root } = {}) {
     const syncOptions = () => {
       options = [...list.querySelectorAll('[role="option"], .ui-combobox__option')];
       options.forEach((o, i) => {
+        rememberOptionState(o);
         if (!o.id) o.id = `${listId}-opt-${i}`;
         o.setAttribute('role', 'option');
       });
     };
-    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');
-    list.hidden = true;
-    // 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');
-    }
 
     let active = -1;
     const visible = () => options.filter((o) => !o.hidden);
@@ -243,7 +272,7 @@ export function initCombobox({ root } = {}) {
       }
     };
     const onOptionClick = (e) => {
-      const opt = e.target.closest('[role="option"], .ui-combobox__option');
+      const opt = closestSafe(e.target, '[role="option"], .ui-combobox__option');
       if (opt) select(opt);
     };
     const onDocClick = (e) => {
@@ -251,6 +280,49 @@ export function initCombobox({ root } = {}) {
     };
 
     const bound = bindOnce(box, 'combobox', () => {
+      const state = rememberState();
+      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);
@@ -268,6 +340,8 @@ export function initCombobox({ root } = {}) {
         input.removeEventListener('keydown', onKey);
         list.removeEventListener('click', onOptionClick);
         document.removeEventListener('click', onDocClick);
+        restoreState(state);
+        active = -1;
       };
     });
     cleanups.push(bound);

package/behaviors/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["command.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA+J3C;;;;;WAzLa,MAAM;;;;WACN,MAAM"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["command.js"],"names":[],"mappings":"AAYA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA0N3C;;;;;WApPa,MAAM;;;;WACN,MAAM"}