@cahyo-dimas/freeday 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.23.0] — 2026-08-13
+Consumption round 6 (`improvement-notes/006`). The reporter filed two of the three as **their own**
+bugs rather than the kit's — and they were right about the code, but in both cases the kit had a way
+to make the mistake impossible and had not taken it. Those are the two most valuable findings here.
+### Fixed
+- **`initAll(ctx)` now enhances `ctx` itself, not just its descendants.** `querySelectorAll` never
+  matches its own root, so a framework ref placed **on** the widget — `<div ref="menu" data-fdy-menu>`,
+  which is the ordinary shape when a component's root element *is* the widget — meant the one element
+  that needed enhancing was the only one that could not be found. It failed with **no error, no
+  warning, and a UI that looked finished**: the markup rendered and simply never opened. Measured
+  before the fix: `data-fdy-menu-ready` stayed `null` and `aria-expanded` stayed `"false"` while
+  `initAll` was present and callable the whole time; `initAll(parent)` worked. One `matches()` line
+  per selector, in **all 21 enhancers** (`drawer` and `cfl` needed their inline trigger callbacks
+  hoisted first). Init was already idempotent via each widget's `-ready` flag, so a root that is also
+  matched by the descendant query costs nothing. `useFreeday` (Vue/React) and `FreedayBlazor.initAll`
+  delegate to these, so they inherit the fix with no change of their own.
+- **The stepper connector no longer draws through the markers when `__btn` is omitted.** The lift now
+  lives on `.fdy-step__marker` — the part that must always exist — instead of only on
+  `.fdy-step__btn`. The connector is `position:absolute; z-index:0`, and a positioned box paints
+  *after* in-flow inline content in the same stacking context, so a marker that was merely inline got
+  painted over: not for lack of a z-index, but for lack of being positioned at all. An
+  indicator-only stepper (no navigation, so no button) is a reasonable thing to write and it produced
+  a visible defect in shipped UI. Measured: hit-testing the marker's centre returned the connector's
+  own `.fdy-step` before, the marker after. `__btn` keeps its z-index for the navigable case.
+### Added
+- **`.fdy-avatar--xs`** (1.5rem, `--text-xs`) — an avatar inside a control had nothing to reach for:
+  `.fdy-btn--sm` is `calc(var(--control-h) - var(--space-2))` = **2rem**, exactly `--avatar--sm`'s
+  size, so the monogram filled a small button edge to edge and the ghost border crossed the circle
+  (measured: trigger 32px tall, avatar 32×32). 1.5rem inside 2rem leaves the ~4px the kit's other
+  controls give their icons. The report suggested `--text-2xs`; that token does not exist — `--text-xs`
+  is the smallest the kit has, and inventing a type step for one avatar size is not worth it.
+### Added — guards
+- **`browser/root-init.mjs`** — mounts a widget *after* load, initialises it through its own root, and
+  drives a **real click** to prove it opens; repeated for a second enhancer so the fix reads as the
+  shared pattern rather than a one-off. Mutation-checked on both. Being marked `-ready` is explicitly
+  not accepted as passing: an early version of this check reported success against markup the enhancer
+  had actually bailed on.
+### Docs
+- `COMPONENTS.md`: `initAll(root)` documents that the root may be the widget itself; the stepper
+  section states that `__btn` is **optional** and shows the read-only indicator markup (the parts list
+  never said which parts were optional); avatar gains its size table with the in-control guidance.
+- Both `useFreeday` docstrings now show the ref-on-the-widget shape alongside the wrapping one.
+
 ## [1.22.0] — 2026-08-12
 Two bodies of work. **(a)** three more findings from consumption round 5 — the report grew §5-§7
 after 1.21.0 was cut; **(b)** a **routing** failure found in the same adopted project, which had been

package/COMPONENTS.md

@@ -65,7 +65,9 @@ Two consequences for you:
 ## Enhancers — hook, script, global, events
 
 Every enhancer is zero-dependency, auto-initialises once on `DOMContentLoaded`, and is idempotent:
-re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. Events are bubbling
+re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. **`root` may be the widget
+itself or an ancestor of it** — both work, so a framework ref placed directly on the enhanced
+element is fine. Events are bubbling
 `CustomEvent`s; the payload is in `event.detail`.
 
 | Markup hook | Script | Global | Emits |
@@ -526,6 +528,18 @@ Linear multi-step flow: marker → check, one panel at a time, back/next. Needs
 
 # Data
 
+**`__btn` is optional.** For a **read-only indicator** put `__marker` + `__label` straight in the
+`<li>`; for a **navigable** stepper wrap them in `<button class="fdy-step__btn">` (add `disabled`
+for a step that is not reachable yet). Both render identically — the marker carries its own lift
+over the connector line, so omitting `__btn` cannot make the connector draw through the numbers.
+
+```html
+<ol class="fdy-stepper">
+  <li class="fdy-step is-complete"><span class="fdy-step__marker">1</span><span class="fdy-step__label">Email</span></li>
+  <li class="fdy-step is-active"><span class="fdy-step__marker">2</span><span class="fdy-step__label">Verify</span></li>
+</ol>
+```
+
 ## Table — `.fdy-table`
 Semantic static table. Wrap in `.fdy-table-wrap` (bordered surface) or `.fdy-table-scroll`
 (horizontal scroll). Always a `<caption>` (use `.fdy-visually-hidden` if it shouldn't show) and
@@ -813,6 +827,10 @@ Initials or image. Sizes `--sm` / default / `--lg`; `.fdy-avatar-group` stacks t
 group). `--tone-1`…`--tone-8` are decorative tints (WCAG AA in both themes) to distinguish
 same-initial avatars — hash the index off the **full** name, not the initials.
 
+Sizes: `--xs` 1.5rem · *(base)* 2.5rem · `--sm` 2rem · `--lg` 3.5rem. Use **`--xs` inside a control**
+— `.fdy-btn--sm` is itself 2rem tall, so an `--sm` avatar fills a small button edge to edge and the
+ghost border cuts across the circle.
+
 ## Chip — `.fdy-chip`
 Three roles inside a `.fdy-chips` row:
 

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.0)
+[![Release](https://img.shields.io/badge/release-v1.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.0)
+[![Release](https://img.shields.io/badge/release-v1.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/adapters/react/useFreeday.js

@@ -9,6 +9,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref={root}> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref={root} data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events are native bubbling CustomEvents — add listeners on the root (they
  * bubble) and read event.detail. See index.d.ts for the detail types.
  */

package/adapters/vue/useFreeday.js

@@ -10,6 +10,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref="root"> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref="root" data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events come straight through as native bubbling CustomEvents — bind them with
  * plain v-on (e.g. @fdy-cascade-change) and read event.detail. See index.d.ts
  * for the detail types.

package/dist/freeday-autocomplete.js

@@ -122,7 +122,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-carousel.js

@@ -98,7 +98,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cascade.js

@@ -243,7 +243,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cfl.js

@@ -179,28 +179,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chart.js

@@ -416,7 +416,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chip.js

@@ -69,6 +69,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }

package/dist/freeday-datepicker.js

@@ -306,9 +306,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-datetime.js

@@ -70,7 +70,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-drawer.js

@@ -16,19 +16,24 @@
     });
   }
 
+  function bindTrigger(btn) {
+    if (btn.dataset.fdyDrawerBound === '1') return;
+    var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
+    if (!dialog) return;
+    initDrawer(dialog);
+    btn.dataset.fdyDrawerBound = '1';
+    btn.addEventListener('click', function () {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    });
+  }
+
   function initTriggers(context) {
     var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), function (btn) {
-      if (btn.dataset.fdyDrawerBound === '1') return;
-      var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
-      if (!dialog) return;
-      initDrawer(dialog);
-      btn.dataset.fdyDrawerBound = '1';
-      btn.addEventListener('click', function () {
-        if (typeof dialog.showModal === 'function') dialog.showModal();
-        else dialog.setAttribute('open', '');
-      });
-    });
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-drawer]')) bindTrigger(ctx);
+    if (ctx.matches && ctx.matches('.fdy-drawer')) initDrawer(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), bindTrigger);
     // Init any drawer dialogs even without a wired trigger (backdrop/close still work).
     Array.prototype.forEach.call(ctx.querySelectorAll('.fdy-drawer'), initDrawer);
   }

package/dist/freeday-form.js

@@ -168,7 +168,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-validate]'), initForm);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-validate]')) initForm(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-validate]'), initForm);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-mask.js

@@ -100,6 +100,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-mask]')) initMask(root);
+    if (root.matches && root.matches('[data-fdy-password]')) initReveal(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-mask]'), initMask);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-password]'), initReveal);
   }

package/dist/freeday-menu.js

@@ -80,7 +80,10 @@
   }
 
   function initAll(ctx) {
-    Array.prototype.forEach.call((ctx || document).querySelectorAll('[data-fdy-menu]'), initMenu);
+    var root = ctx || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-menu]')) initMenu(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-menu]'), initMenu);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-rating.js

@@ -37,7 +37,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-rating]'), initRating);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-rating]')) initRating(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-rating]'), initRating);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-select.js

@@ -189,11 +189,10 @@
   }
 
   function initAll(context) {
-    var scope = context || document;
-    Array.prototype.forEach.call(
-      scope.querySelectorAll('[data-fdy-combo]'),
-      initCombo
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-combo]')) initCombo(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-combo]'), initCombo);
   }
 
   // One global handler closes the open combo on an outside click.

package/dist/freeday-slider.js

@@ -21,7 +21,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-slider]'), initSlider);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-slider]')) initSlider(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-slider]'), initSlider);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-stepper.js

@@ -77,7 +77,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-stepper]'), initStepper);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-stepper]')) initStepper(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-stepper]'), initStepper);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-table.js

@@ -459,10 +459,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-table]'),
-      initTable
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-table]')) initTable(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-table]'), initTable);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-tabs.js

@@ -52,10 +52,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-tabs]'),
-      initTabs
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tabs]')) initTabs(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tabs]'), initTabs);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-timepicker.js

@@ -167,7 +167,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-timepicker]'), initTime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-timepicker]')) initTime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-timepicker]'), initTime);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-tree.js

@@ -81,7 +81,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-tree]'), initTree);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tree]')) initTree(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tree]'), initTree);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-upload.js

@@ -193,7 +193,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-dropzone]'), initDropzone);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-dropzone]')) initDropzone(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-dropzone]'), initDropzone);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday.bundle.css

@@ -586,6 +586,11 @@ a { color: var(--color-primary); }
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}
@@ -1457,7 +1462,12 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}

package/dist/freeday.css

@@ -216,6 +216,11 @@ a { color: var(--color-primary); }
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}
@@ -1087,7 +1092,12 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}

package/dist/freeday.js

@@ -124,7 +124,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {
@@ -288,7 +291,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {
@@ -545,7 +551,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {
@@ -738,28 +747,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {
@@ -1189,7 +1203,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {
@@ -1272,6 +1289,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }
@@ -1593,9 +1613,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {
@@ -1679,7 +1702,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {
@@ -1709,19 +1735,24 @@
     });
   }
 
+  function bindTrigger(btn) {
+    if (btn.dataset.fdyDrawerBound === '1') return;
+    var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
+    if (!dialog) return;
+    initDrawer(dialog);
+    btn.dataset.fdyDrawerBound = '1';
+    btn.addEventListener('click', function () {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    });
+  }
+
   function initTriggers(context) {
     var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), function (btn) {
-      if (btn.dataset.fdyDrawerBound === '1') return;
-      var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
-      if (!dialog) return;
-      initDrawer(dialog);
-      btn.dataset.fdyDrawerBound = '1';
-      btn.addEventListener('click', function () {
-        if (typeof dialog.showModal === 'function') dialog.showModal();
-        else dialog.setAttribute('open', '');
-      });
-    });
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-drawer]')) bindTrigger(ctx);
+    if (ctx.matches && ctx.matches('.fdy-drawer')) initDrawer(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), bindTrigger);
     // Init any drawer dialogs even without a wired trigger (backdrop/close still work).
     Array.prototype.forEach.call(ctx.querySelectorAll('.fdy-drawer'), initDrawer);
   }
@@ -1905,7 +1936,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-validate]'), initForm);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-validate]')) initForm(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-validate]'), initForm);
   }
 
   if (document.readyState === 'loading') {
@@ -2019,6 +2053,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-mask]')) initMask(root);
+    if (root.matches && root.matches('[data-fdy-password]')) initReveal(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-mask]'), initMask);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-password]'), initReveal);
   }
@@ -2114,7 +2151,10 @@
   }
 
   function initAll(ctx) {
-    Array.prototype.forEach.call((ctx || document).querySelectorAll('[data-fdy-menu]'), initMenu);
+    var root = ctx || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-menu]')) initMenu(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-menu]'), initMenu);
   }
 
   if (document.readyState === 'loading') {
@@ -2235,7 +2275,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-rating]'), initRating);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-rating]')) initRating(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-rating]'), initRating);
   }
 
   if (document.readyState === 'loading') {
@@ -2438,11 +2481,10 @@
   }
 
   function initAll(context) {
-    var scope = context || document;
-    Array.prototype.forEach.call(
-      scope.querySelectorAll('[data-fdy-combo]'),
-      initCombo
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-combo]')) initCombo(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-combo]'), initCombo);
   }
 
   // One global handler closes the open combo on an outside click.
@@ -2489,7 +2531,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-slider]'), initSlider);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-slider]')) initSlider(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-slider]'), initSlider);
   }
 
   if (document.readyState === 'loading') {
@@ -2580,7 +2625,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-stepper]'), initStepper);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-stepper]')) initStepper(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-stepper]'), initStepper);
   }
 
   if (document.readyState === 'loading') {
@@ -3053,10 +3101,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-table]'),
-      initTable
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-table]')) initTable(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-table]'), initTable);
   }
 
   if (document.readyState === 'loading') {
@@ -3122,10 +3170,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-tabs]'),
-      initTabs
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tabs]')) initTabs(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tabs]'), initTabs);
   }
 
   if (document.readyState === 'loading') {
@@ -3306,7 +3354,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-timepicker]'), initTime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-timepicker]')) initTime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-timepicker]'), initTime);
   }
 
   if (document.readyState === 'loading') {
@@ -3507,7 +3558,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-tree]'), initTree);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tree]')) initTree(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tree]'), initTree);
   }
 
   if (document.readyState === 'loading') {
@@ -3714,7 +3768,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-dropzone]'), initDropzone);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-dropzone]')) initDropzone(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-dropzone]'), initDropzone);
   }
 
   if (document.readyState === 'loading') {

package/docs/getting-started.md

@@ -184,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.22.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.23.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs",
+    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit"

package/src/components/avatar.css

@@ -1,6 +1,11 @@
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}

package/src/components/stepper.css

@@ -7,7 +7,12 @@
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}