@adia-ai/web-components 0.5.15 → 0.5.17

package/CHANGELOG.md

@@ -11,6 +11,62 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.17] - 2026-05-16
+
+### Fixed
+- §339 (FB-41; P2) — `<swatch-ui>` `[auto-contrast]` overrode `[label-position="overlay"]` position. Two `@scope (swatch-ui)` rules at equal specificity (0,3,1) collided on `> [data-label] { position }`; source order favored auto-contrast's `position: relative` over overlay's `position: absolute` → label dropped below tile (host doubled to 2× block-h). Blocks the canonical `label-position="overlay" + auto-contrast` pattern §253 enabled. Fix: drop `position: relative` from `[auto-contrast]` data-label + data-detail rules — z-index works on positioned elements (overlay supplies position: absolute), and non-overlay defaults are flex flow where z-index is irrelevant. 3 NEW vitest cases lock the CSS source structurally.
+- §340 (FB-42; P2) — `<list-item-ui>` `render()` text-branch asymmetry. Icon + description branches had create-if-missing paths; text branch only updated existing stamped spans. Template engine `.text=${expr}` (canonical authoring pattern per USAGE.md) arrives AFTER `connectedCallback` `#stamp()` — `this.text` was `''` at stamp time so no span created, `render()` fired but couldn't recover → primary text silently invisible. Fix: mirror description branch's create-if-missing + remove-when-cleared pattern. NEW `list.test.js` with 5 vitest cases (create-on-prop-set / update / remove / parity-with-description / consumer-stamp non-interference).
+
+### Tests
+- §338 (FB-40; misdiagnosed) — 4 NEW vitest cases in `core/template.test.js` lock the existing FEEDBACK-06 comment-aware `inTag()` fix (line 55-78). FB-40 reported apostrophes-in-HTML-comments crashes claiming the parser mis-classifies subsequent `${…}` placeholders; the cited mechanism is incorrect — `inTag()` has skipped past `<!--…-->` wholesale since FEEDBACK-06 (pre-v0.5.x). The 4 new tests empirically verify the fix covers apostrophe-comment + double-quote-comment + multi-apostrophe + apostrophe+em-dash cases. RESPONSE-40 requests stack-trace evidence for the actual crash mechanism since the cited apostrophe diagnosis is empirically wrong against current source.
+
+## [0.5.16] - 2026-05-16
+
+### v0.5.16 §331 — `<swatch-ui>` chrome-slot wrapper-span deep-walk (FB-39; P1)
+
+Closes FB-39. P1 lifecycle gap that FB-38's "C1.3 unblocked" close-out missed: §326 (v0.5.15) fixed the late-direct-append case but NOT the template-render wrapper-span case. AdiaUI's `html\`\`` template engine wraps each interpolated child fragment in a `<span style="display: contents">` (per `core/template.js:212` `wrap()`). When consumer writes `html\`<swatch-ui>${badgeFrag}</swatch-ui>\``, the `<span slot="chrome">` ends up nested INSIDE the wrapper, not as a direct child. `#stamp()`'s `Array.from(this.children).filter(n => n.getAttribute?.('slot') === 'chrome')` returned `[]`; `innerHTML = ''` wiped the wrapper spans + chrome content; `#absorbChromeSlot()` ran on destroyed DOM.
+
+Blocked Tokens Studio's C1.3 dogfood migration (chrome elements silently destroyed) + >95% of AdiaUI consumers using `html\`\`` templates.
+
+#### Fixed — `components/swatch/class.js` (dual-site deep-walk)
+
+- `#stamp()`'s chrome extraction extends from direct-children-only to also walk `querySelectorAll('[slot="chrome"]')` on non-chrome wrapper-span children. Catches both static-HTML (direct child) AND template-render (nested in wrapper) paths.
+- `#absorbChromeSlot()` gains a parallel deep-walk for wrapper-spanned chrome children that arrive AFTER `#stamp()` (parent template re-render path). Hoists nested chrome out of any non-internal wrapper into the canonical sibling-of-tile slot via `this.insertBefore(child, this.#badgeEl)`.
+- Wrapper spans stay in place post-hoist (`display: contents` makes them invisible to CSS layout; removing them risks interfering with the parent template engine's diff tracking via the `PART` symbol).
+
+#### Added — `components/swatch/swatch.test.js` (6 → 9 cases)
+
+3 NEW vitest cases under "FB-39 / §331":
+- `hoists chrome child from inside wrapper span at #stamp() time (template-interpolation path)` — single-wrapper-single-chrome case.
+- `handles MULTIPLE chrome children nested in separate wrapper spans` — multi-`${...}` template interpolation; each fragment lands in its own wrapper.
+- `hoists chrome from late-arriving wrapper span (post-stamp template re-render)` — parent re-renders + appends a new wrapper-span carrying chrome after `#stamp()` already ran.
+
+Total `swatch.test.js`: 9/9 passing (4 §325 + 2 §326 + 3 §331).
+
+#### Migration
+
+Consumers using `<swatch-ui>` with chrome-slot composition via `html\`\`` templates (`<swatch-ui>${badge}${dot}</swatch-ui>`) now get chrome children placed at canonical position post-§331. The consumer-side workaround (skip chrome composition or use bare `<swatch-ui>` without chrome) can be retired. No consumer code changes required — the §331 fix is invisible to consumers writing canonical templates.
+
+### v0.5.x (Unreleased) §330 — `slider-ui` "Next" design + `segmented-ui` initial-render fix
+
+**`slider-ui`** — full visual redesign to iOS/macOS-style pill slider. Pill-shaped track (`var(--a-toggle-size)` = 16/20/24px for sm/md/lg), primary-color progressive fill (`--a-primary-bg`), white chrome thumb (`--a-chrome-light`) with 2:1 width:height ratio and 2px internal padding on all sides. Mathematical geometry documented inline in CSS: `fill_width(p) = t + p·(W−t)`, `thumb_center(p) = t/2 + p·(W−t)`; fill starts at thumb-width (p=0) and grows incrementally to full track width (p=1). Two-layer thumb architecture: transparent full-height container provides grab area; `::before` renders the inward-padded white pill. `class.js` `#valueFromX()` maps full track width to [min,max]; `#valueFromX()` simplified back to direct rect ratio. `data-dragging` CSS transition lock kills the `left` transition during pointer moves for instant visual feedback. `slider.examples.html` gains Sizes section (lg/md/sm/14px/12px) + updated CSS token table.
+
+**`segmented-ui`** — initial rendering race fix. Added `ResizeObserver` on self + `document.fonts.ready` promise in `connected()`; both call `#updateIndicator()` when layout stabilizes so the animated pill positions correctly after font load or resize. Previously the indicator computed once at mount and stayed misaligned — only corrected on next user interaction.
+
+Files: `slider.css`, `slider.class.js`, `slider.examples.html`, `slider.yaml`, `segmented.class.js`.
+
+### Added
+- §333 `<color-input>` gains canonical demo-shell loader pair to restore catalog symmetry with the other 92 primitives. NEW `color-input.html` (52-line shell pattern matching `color-picker.html`: tokens base + composed primitive CSS + composed primitive JS per ADR-0027 + `fetch('./color-input.examples.html')`) + NEW `color-input.examples.html` (7 sections: default · initial values · format hex vs oklch · popover placement · §313 generation constraints `max-chroma`/`max-l`/`min-l`/`hue-drift-max`/`base-hue` · disabled · inside a form). Closes gemini-review refactor-backlog P3-1.
+- §332 `<swiper-ui>` gains `chrome="toolbar"` layout mode with companion `label` + `counter` props. Default chrome (overlay paddles + centered dots below) is unchanged. Toolbar chrome stamps a header row (label on the left, paddles on the right) above the track and a footer row (counter on the left, dots on the right) below — supports gallery-style compositions where consumers want the chrome out of the slide area. `#stampToolbarChrome()` builds the head + foot rows; `#updateCounter()` writes "N / M" (page-based, snap-aware) into `[data-swiper-counter]` on every scroll. New examples at `/site/components/swiper` § chrome (photo gallery / featured products / autoplay testimonials). Counter is page-based so it tracks the dot count correctly for multi-column + center-snap.
+- §329 `<code-ui>` gains a `<template>`-child authoring path — wrap the source in `<template>…</template>` and write literal `<` / `>` without entity-escaping. `#stampBlock` reads `template.innerHTML`, dedents the wrapper column via a new static `#dedent()` helper, and feeds the result to CodeMirror. The HTML parser treats `<template>` content as inert (it lives in a `DocumentFragment`, not rendered), so embedded `<nav-ui>` / `<button-ui>` / etc. don't get upgraded inside the template. Three authoring paths now in priority order: (1) `[text]` attribute, (2) `<template>` child, (3) escaped textContent (back-compat — existing examples unchanged). Demo at `/site/components/code` § "escape-free authoring via &lt;template&gt;"; dogfooded on `patterns/app-nav` structure example. (Carry-forward from worktree §318.)
+
+### Fixed
+- §332 `<swiper-ui>` — comprehensive consumer-feedback hardening pass (9 distinct fixes consolidated). (a) **Click-and-drag preempted by native HTML5 image-drag**: `<img>` inside slide cards fired `dragstart` before our 5px pointermove threshold was reached, suspending pointer events. Fix: `dragstart` listener gated on `this.#drag !== null` (set by `#onPointerDown`) so genuine drag-out of intentionally draggable slide content stays available. (b) **Pagination dots ignored `--swiper-columns`**: stamping one dot per slide regardless of `slides-per-view`. New `#getPageCount()` returns `max(1, slides − cols + 1)` for start/end snap (reads `--swiper-columns` via `getComputedStyle(track)`); `ResizeObserver` on the host re-stamps when container queries shift the cv across breakpoints. `next/prev/play` cap at last page; dot labels read "Page N" (was "Slide N", misleading once dot-index ≠ slide-index). (c) **CSS `container-type` on the wrong element** — `container-type: inline-size` was on `[data-swiper-track]` but `@container` rules targeted `:scope` (the host = track's PARENT, not a descendant). Container queries match descendants of the container, so the rules fell through to whatever further-up ancestor had a container set (the docs shell) and incorrectly stamped `cols=2-3` on every swiper. Moved `container-type: inline-size; container-name: swiper;` to host; `@container swiper (...)` rules now target `:scope > [data-swiper-track]` (a real descendant). JS `#getColumns()` reads from the track via `getComputedStyle` so both `[slides-per-view]` (cascades from host) and `@container` (writes on track) converge. (d) **Snap-aware active tracking** — IntersectionObserver "leftmost intersecting" couldn't distinguish the last two snap positions for center/end snap (both kept the last two slides >50% visible). Replaced with `scroll` listener + `#computeActiveIndex()` that walks every slide, computes its snap target (`left` / `left + width/2 − trackWidth/2` / `left + width − trackWidth` per snap mode), clamps to `[0, maxScroll]`, and picks the closest target to `scrollLeft`. `#pageToSlideIndex` / `#slideToPageIndex` map between page and slide indices (identity for start/center; end-snap shifts by `cols − 1`); snap-aware `goTo()` scrolls to the computed target so dot clicks land without a "scroll to left edge, then scroll-snap re-correct" jank step. `#getPageCount()` returns `slides.length` for `snap="center"` (each slide is its own page; 4-slides-@-cols=2 now stamps 4 dots, not 3). (e) **Loop / autoplay demos didn't visibly demonstrate looping** — at responsive widths (≥960px → cols=3) the 3-slide demos had `pageCount=1`, paddles produced no visible effect. Pinned demos to `slides-per-view="1"`; added a new combined "loop + autoplay" example. (f) **`gap` only accepted token indices despite docs claiming "any CSS length"**: `render()` blindly wrapped `gap` in `var(--a-space-${gap})`. For `gap="1rem"` that became `var(--a-space-1rem)` (undefined token) → property invalidated → CSS gap fell back to 0; three demo variants (`gap=0/1rem/2rem`) all rendered identically. Fix: numeric-only strings resolve to space tokens, anything else used as a raw CSS length. (g) **Dot CSS lost in toolbar chrome**: `:scope > [data-swiper-dots] > button` (direct-child combinator) stopped matching when dots moved inside `[data-swiper-foot]`; buttons fell back to browser defaults (wide gray bars). Relaxed all five dot rules to `:scope [data-swiper-dots]` (descendant combinator). (h) **Active dot rendered much larger than inactive** — `background: <color>` shorthand in `:hover` and `[aria-current="true"]` rules silently RESET `background-clip` back to its initial `border-box`, so the colored area filled the full 1rem outer hitbox and `border-radius: 100rem` rounded that into a ~16px circle (vs the 6px content-box-clipped circle for inactive). Fix: longhand `background-color: <color>` so `background-clip: content-box` from the base rule is preserved. Active dot now has a deliberate +4px (`--a-space-1`) size delta via NEW `--swiper-dot-size-active` token; padding back-computed so the 1rem hitbox stays invariant. Focus ring moved from outer `var(--a-focus-ring)` to inset 2px shadow so focus doesn't change footprint either. **Pitfall worth knowing for future CSS work: `background: <color>` shorthand resets `background-clip`/`background-origin`/`background-position`/etc. to initial — use `background-color: <color>` to preserve them.**
+- §327 P2 correctness — `<code-ui language="…">` (every `/site/patterns/*` page) rendered as flow-wrapped plain text with chrome header below the content + no syntax highlighting. Root cause: the `textContent` key in `static properties` of `code/class.js`, `button/class.js`, `tag/class.js`, `badge/class.js` made `UIElement.installProps()` shadow the native `HTMLElement.prototype.textContent` setter. `this.textContent = ''` in `code-ui`'s `#stampBlock` became a signal-write no-op — original authored HTML-escaped source stayed in the element above the stamped chrome, and CodeMirror mounted with an empty doc (1 cm-line, 19.5px tall editor below leftover authored text). Same hazard on `<tag-ui>` produced visible empty pills across every `/site/traits/*` page's API table (the `chip()` helper in `traits/_api-table.js` and 3 other call sites all do `t.textContent = text` after `createElement('tag-ui')`). Fix: removed the `textContent` entry from each of the 4 class.js files. Yaml + `.d.ts` entries kept (renderer routes via `setAttribute('text', …)` for non-text-bearing tags; doesn't depend on JS prop declarations). New drift class #7 (native-DOM-accessor collision). **Carry-forward note:** initially staged as §316 on a worktree branch (2026-05-15) before v0.5.14 cut; §316-§318 were claimed by parallel peer work that shipped via v0.5.15. Renumbered to §327 on re-apply to main against v0.5.15 HEAD (2026-05-16).
+
+### Docs
+- §328 source-side polish: re-flowed 6 one-line `<code-ui>` blocks across `stat`/`pagination`/`rating`/`count-up`/`theme-panel`/`theming` USAGE sections — multi-attribute single tags now author each attribute on its own line for readability + consistency with how the rest of the corpus is authored. (Carry-forward from worktree §317.)
+
 ## [0.5.15] - 2026-05-16
 
 > **Scope note:** §325 + §326 were originally planned as a separate v0.5.16 cycle (see retired `docs/plans/0.5.16-release-plan.md`); absorbed into v0.5.15 since both landed within the same release window (same-day commits prior to bump). The peer's v0.5.16 plan-doc explicitly anticipated this absorption option ("Hermes's call per `/lockstep-release`"). v0.5.16 plan-doc marked SHIPPED-IN-V0.5.15.

package/components/badge/class.js

@@ -40,7 +40,11 @@ const STATUS_MAP = {
 export class UIBadge extends UIElement {
   static properties = {
     text:    { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive
+    // prop — `installProps()` would override the native DOM setter, so
+    // `el.textContent = '…'` would silently no-op. Yaml keeps the prop
+    // entry for renderer metadata, but the JS class must not declare
+    // it. v0.5.x §327.
     variant: { type: String,  default: 'default', reflect: true },
     size:    { type: String,  default: 'md', reflect: true },
     icon:    { type: String,  default: '',        reflect: true },

package/components/button/class.js

@@ -19,7 +19,11 @@ import { getIcon } from '../../core/icons.js';
 export class UIButton extends UIElement {
   static properties = {
     text:     { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive
+    // prop — `installProps()` would override the native DOM setter, so
+    // `el.textContent = '…'` would silently no-op instead of updating
+    // child text. Yaml keeps the prop entry for renderer metadata, but
+    // the JS class must not declare it. v0.5.x §327.
     variant:  { type: String,  default: 'solid', reflect: true },
     color:    { type: String,  default: '', reflect: true },
     size:     { type: String,  default: 'md', reflect: true },

package/components/code/class.js

@@ -62,7 +62,13 @@ export class UICode extends UIElement {
     language:     { type: String,  default: '', reflect: true },
     inline:       { type: Boolean, default: false, reflect: true },
     text:         { type: String,  default: '', reflect: true },
-    textContent:  { type: String,  default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive prop.
+    // `installProps()` would override the native DOM setter with a signal
+    // setter, breaking `this.textContent = ''` in #stampBlock (the wipe
+    // becomes a no-op, leaving the authored HTML-escaped source visible
+    // above the stamped chrome and feeding an empty doc to CodeMirror).
+    // Initial content is read via the native getter in #stampBlock; live
+    // updates flow through the reactive `text` property. v0.5.x §327.
     lineNumbers:  { type: Boolean, default: false, reflect: true, attribute: 'line-numbers' },
     editable:     { type: Boolean, default: false, reflect: true },
     bare:         { type: Boolean, default: false, reflect: true },
@@ -132,10 +138,25 @@ export class UICode extends UIElement {
   }
 
   #stampBlock() {
-    // Prefer the `text` attribute when present; otherwise read the authored
-    // textContent. Either way, the block is rebuilt from semantic elements
-    // so whitespace in source HTML doesn't leak into the rendered <code>.
-    const raw = (this.text || this.textContent || '').trim();
+    // Content-source priority:
+    //   1. `text` attribute  — reactive, programmatic.
+    //   2. `<template>` child — escape-free authoring path. The HTML parser
+    //      treats `<template>` content as inert (DocumentFragment, not
+    //      rendered); we read `template.innerHTML` to recover the literal
+    //      source. Author can write `<code-ui language="html"><template>
+    //      <nav-ui>…</nav-ui></template></code-ui>` without `&lt;`/`&gt;`
+    //      escaping. Indent is normalized via #dedent() so the inner block
+    //      doesn't carry the wrapper's indentation. (v0.5.x §329)
+    //   3. Authored textContent — original path, requires HTML entities
+    //      for `<` and `>` (same constraint as `<pre><code>`).
+    // The block is rebuilt from semantic elements so whitespace in source
+    // HTML doesn't leak into the rendered <code>.
+    const tmpl = this.querySelector(':scope > template');
+    const raw = this.text
+      ? this.text.trim()
+      : tmpl
+        ? UICode.#dedent(tmpl.innerHTML)
+        : (this.textContent || '').trim();
     this.textContent = '';
 
     // Header — omitted in [bare] mode. Consumers that need zero chrome
@@ -206,6 +227,22 @@ export class UICode extends UIElement {
     this.appendChild(pre);
   }
 
+  /** Normalize indentation pulled from a `<template>` child. Strips
+   *  the common leading whitespace from every non-empty line so the
+   *  inner block reads as if it were authored at column 0. Equivalent
+   *  in spirit to Python's `textwrap.dedent` or a tagged-template
+   *  `dedent` helper. (v0.5.x §329) */
+  static #dedent(s) {
+    const trimmed = s.replace(/^\n+|\n+$/g, '');
+    if (!trimmed) return '';
+    const lines = trimmed.split('\n');
+    const indents = lines
+      .filter((l) => l.trim().length > 0)
+      .map((l) => l.match(/^[ \t]*/)[0].length);
+    const min = indents.length ? Math.min(...indents) : 0;
+    return min > 0 ? lines.map((l) => l.slice(min)).join('\n') : trimmed;
+  }
+
   async #mountEditor() {
     if (this.#pendingMount || this.#cmView) return;
     const gen = this.#mountGen;

package/components/code/code.a2ui.json

@@ -156,7 +156,7 @@
     ],
     "slots": {
       "default": {
-        "description": "Raw text fallback when the text property is not set"
+        "description": "Raw text fallback when the text property is not set. Two authoring shapes:\n(a) HTML-entity-escaped text (`&lt;nav-ui&gt;`) — same constraint as `<pre><code>`,\nsince the HTML parser treats unescaped tags as child elements; or\n(b) a `<template>` child whose `innerHTML` carries the literal source —\nescape-free authoring path. Indentation is dedented from the wrapper\ncolumn so the template's inner block reads at column 0. (v0.5.x §329)\n"
       }
     },
     "states": [

package/components/code/code.d.ts

@@ -40,6 +40,33 @@ export interface CodeLanguageLoadErrorEventDetail {
 }
 export type CodeLanguageLoadErrorEvent = CustomEvent<CodeLanguageLoadErrorEventDetail>;
 
+/**
+ * `<code-ui>` — syntax-highlighted code block (CodeMirror 6 under the hood).
+ *
+ * Three content-source paths in priority order:
+ *
+ *   1. `[text]` attribute — reactive, programmatic; updates re-render the block.
+ *
+ *   2. `<template>` child — escape-free authoring path (v0.5.x §329). Author
+ *      the source with literal `<` / `>` (the HTML parser treats `<template>`
+ *      content as inert; it lives in a `DocumentFragment` instead of being
+ *      upgraded into DOM elements). The wrapper indent is dedented so the
+ *      inner block reads at column 0.
+ *
+ *      ```html
+ *      <code-ui language="html">
+ *        <template>
+ *          <nav-ui>
+ *            <nav-item-ui text="Home"></nav-item-ui>
+ *          </nav-ui>
+ *        </template>
+ *      </code-ui>
+ *      ```
+ *
+ *   3. Authored textContent — original path. HTML samples require entity
+ *      escaping (`&lt;`/`&gt;`/`&amp;`), same constraint as `<pre><code>`,
+ *      since the parser treats unescaped tags as child elements.
+ */
 export class UICode extends UIFormElement {
   /** CodeMirror language slug — `javascript` / `typescript` / `html` / `css` / `json` / `markdown` / `python` etc. */
   language: string;

package/components/code/code.yaml

@@ -93,7 +93,13 @@ events:
         description: The underlying load failure.
 slots:
   default:
-    description: Raw text fallback when the text property is not set
+    description: |
+      Raw text fallback when the text property is not set. Two authoring shapes:
+      (a) HTML-entity-escaped text (`&lt;nav-ui&gt;`) — same constraint as `<pre><code>`,
+      since the HTML parser treats unescaped tags as child elements; or
+      (b) a `<template>` child whose `innerHTML` carries the literal source —
+      escape-free authoring path. Indentation is dedented from the wrapper
+      column so the template's inner block reads at column 0. (v0.5.x §329)
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/list/class.js

@@ -227,9 +227,24 @@ export class UIListItem extends UIElement {
       iconEl.remove();
     }
 
-    // Sync text — only touch elements we stamped.
+    // Sync text — mirror the icon + description branches: create-if-missing
+    // path so post-connect property bindings (template engine `.text=${expr}`)
+    // can stamp the span when `#stamp()` ran with `this.text === ''`. §340
+    // (FB-42) — without this, primary text is silently invisible when set
+    // via property binding (the canonical authoring pattern per USAGE.md).
     const textEl = this.#ownChild('[slot="text"]');
-    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+    if (this.text) {
+      if (textEl) {
+        if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+      } else {
+        const el = this.#stampMark(document.createElement('span'));
+        el.setAttribute('slot', 'text');
+        el.textContent = this.text;
+        this.appendChild(el);
+      }
+    } else if (this.#wasStamped(textEl)) {
+      textEl.remove();
+    }
 
     // Sync description — only touch elements we stamped.
     const descEl = this.#ownChild('[slot="description"]');

package/components/list/list.test.js

@@ -0,0 +1,106 @@
+/**
+ * <list-item-ui> behavioral tests.
+ *
+ * Initial scope: FB-42 / §340 regression coverage — `render()`'s text
+ * branch can now create the slot element when `this.text` is set
+ * post-connect (e.g. via template-engine property binding), matching
+ * the icon + description branches' create-if-missing pattern.
+ *
+ * Test setup note: happy-dom connects custom elements synchronously
+ * during innerHTML parsing. To exercise the post-connect property-set
+ * timing (template-engine path), tests use `document.createElement` +
+ * `host.appendChild()` to connect with empty `text`, then set the
+ * property AFTER connect to trigger render()'s recovery path.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./list.js');
+});
+
+describe('<list-item-ui> render() text branch — post-connect property binding (FB-42 / §340)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('creates [slot="text"] span when .text is set AFTER connectedCallback (template-engine timing)', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    // connectedCallback fires here with this.text === '' — span NOT stamped
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+
+    // Template engine sets the property post-connect
+    li.text = 'Primary text via property binding';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('Primary text via property binding');
+  });
+
+  it('updates existing [slot="text"] span when .text changes', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'initial');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('initial');
+
+    li.text = 'updated';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]').textContent).toBe('updated');
+  });
+
+  it('removes stamped [slot="text"] span when .text is cleared', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'will be removed');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).not.toBeNull();
+
+    li.text = '';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+  });
+
+  it('text branch parity with description branch — both create-if-missing post-connect', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+    expect(li.querySelector('[slot="description"]')).toBeNull();
+
+    li.text = 'primary';
+    li.description = 'secondary';
+    await new Promise((r) => setTimeout(r, 30));
+
+    expect(li.querySelector('[slot="text"]')?.textContent).toBe('primary');
+    expect(li.querySelector('[slot="description"]')?.textContent).toBe('secondary');
+  });
+
+  it('does not stamp [slot="text"] for unauthored consumer-provided text content', async () => {
+    // If the consumer provides their own [slot="text"] child (e.g. for
+    // richer markup), the render() branch must NOT touch it.
+    const li = document.createElement('list-item-ui');
+    const userSpan = document.createElement('span');
+    userSpan.setAttribute('slot', 'text');
+    userSpan.innerHTML = '<strong>bold</strong> user';
+    li.appendChild(userSpan);
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    li.text = 'attempt to set';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const span = li.querySelector('[slot="text"]');
+    expect(span).toBe(userSpan); // identity preserved
+    expect(span.innerHTML).toBe('<strong>bold</strong> user'); // markup preserved
+  });
+});

package/components/segmented/class.js

@@ -36,6 +36,8 @@ export class UISegmented extends UIFormElement {
   #indicator = null;
   #bound = false;
   #transitionRaf = null;
+  #resizeObs = null;
+  #fontWait = null;
 
   connected() {
     super.connected();
@@ -52,6 +54,20 @@ export class UISegmented extends UIFormElement {
       const first = this.querySelector('segment-ui:not([disabled])');
       if (first) this.value = first.value || first.getAttribute('value') || '';
     }
+
+    // Recalculate indicator when layout shifts (font load, resize, content change)
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObs = new ResizeObserver(() => this.#updateIndicator(this.#segments));
+      this.#resizeObs.observe(this);
+    }
+
+    // Also wait for fonts to settle — a common source of initial-layout drift
+    if (document.fonts?.ready) {
+      this.#fontWait = document.fonts.ready.then(() => {
+        this.#fontWait = null;
+        this.#updateIndicator(this.#segments);
+      });
+    }
   }
 
   disconnected() {
@@ -60,6 +76,12 @@ export class UISegmented extends UIFormElement {
       cancelAnimationFrame(this.#transitionRaf);
       this.#transitionRaf = null;
     }
+    this.#resizeObs?.disconnect();
+    this.#resizeObs = null;
+    if (this.#fontWait) {
+      // Promise can't be cancelled; the then-handler checks this.isConnected
+      this.#fontWait = null;
+    }
     this.removeEventListener('click', this.#handleClick);
     this.removeEventListener('keydown', this.#handleKeydown);
     this.#indicator = null;

package/components/slider/class.js

@@ -63,6 +63,7 @@ export class UISlider extends UIFormElement {
   #trackEl = null;
   #thumbEl = null;
   #dragging = false;
+  #dragOffset = 0;
 
   get #pct() {
     const range = this.max - this.min;
@@ -140,9 +141,10 @@ export class UISlider extends UIFormElement {
     }
 
     const pct = this.#pct;
-    const fill = this.querySelector('[slot="fill"]');
-    if (fill) fill.style.width = `${pct}%`;
-    if (this.#thumbEl) this.#thumbEl.style.left = `${pct}%`;
+    // Write progress to CSS custom property for pure-CSS positioning.
+    // --slider-pct is a fraction (0.0–1.0) used in calc() alongside
+    // --slider-travel so thumb + fill stay inside the track.
+    this.style.setProperty('--slider-pct', String(pct / 100));
 
     const valueEl = this.querySelector('[slot="value"]');
     if (valueEl) valueEl.textContent = this.#format(this.value);
@@ -152,9 +154,34 @@ export class UISlider extends UIFormElement {
     this.syncValue(String(this.value));
   }
 
+  /**
+   * Inverse geometry: given a *desired* thumb-center viewport-x, compute
+   * the slider value such that the thumb center lands exactly at that
+   * coordinate (clamped at the min/max extremes).
+   *
+   * Forward geometry (in slider.css):
+   *   thumb_center(p) = t/2 + p · (W − t)
+   *
+   * Inverse (solve for p, clamped):
+   *   p = clamp01((target − t/2) / (W − t))
+   *
+   * Two call paths share this:
+   *   • #onTrackClick — clientX is the click position; thumb center lands
+   *     under the cursor (or snaps to the t/2 end-zone when clicked beyond).
+   *   • #onPointerMove — (clientX − dragOffset) is the *intended* thumb
+   *     center (offset preserves where the user originally grabbed the
+   *     thumb, so dragging feels relative rather than snap-to-cursor).
+   */
   #valueFromX(clientX) {
-    const rect = this.#trackEl.getBoundingClientRect();
-    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    if (!this.#trackEl || !this.#thumbEl) return this.min;
+    const trackRect = this.#trackEl.getBoundingClientRect();
+    const thumbRect = this.#thumbEl.getBoundingClientRect();
+    const W = trackRect.width;
+    const t = thumbRect.width;
+    const travel = W - t;
+    if (travel <= 0) return this.min;
+    const target = clientX - trackRect.left;            // desired thumb-center, track-relative
+    const ratio = Math.max(0, Math.min(1, (target - t / 2) / travel));
     const raw = this.min + ratio * (this.max - this.min);
     return this.#snap(raw);
   }
@@ -178,6 +205,28 @@ export class UISlider extends UIFormElement {
     if (this.disabled) return;
     e.preventDefault();
     this.#dragging = true;
+    this.setAttribute('data-dragging', '');
+    // Capture the offset between the click point and the thumb's
+    // *logical* center (derived from `this.value` via the same forward
+    // equation the CSS uses). We deliberately do NOT read the thumb's
+    // bounding rect here — the CSS `left` transition can leave the
+    // physical rect mid-animation between values, producing a stale
+    // offset that would translate into a snap on the first move.
+    // Logical center is transition-immune and matches what #valueFromX
+    // inverts.
+    if (this.#trackEl && this.#thumbEl) {
+      const trackRect = this.#trackEl.getBoundingClientRect();
+      const thumbRect = this.#thumbEl.getBoundingClientRect();
+      const W = trackRect.width;
+      const t = thumbRect.width;
+      const travel = W - t;
+      const range = this.max - this.min;
+      const p = range > 0 ? (this.value - this.min) / range : 0;
+      const logicalCenter = trackRect.left + t / 2 + p * travel;
+      this.#dragOffset = e.clientX - logicalCenter;
+    } else {
+      this.#dragOffset = 0;
+    }
     this.#thumbEl.setPointerCapture(e.pointerId);
     this.#thumbEl.addEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.addEventListener('pointerup', this.#onPointerUp);
@@ -185,11 +234,16 @@ export class UISlider extends UIFormElement {
 
   #onPointerMove = (e) => {
     if (!this.#dragging) return;
-    this.#setValue(this.#valueFromX(e.clientX));
+    // Subtract the captured offset so the thumb center tracks the
+    // cursor relative to where the user originally pressed, avoiding
+    // the initial snap.
+    this.#setValue(this.#valueFromX(e.clientX - this.#dragOffset));
   };
 
   #onPointerUp = (e) => {
     this.#dragging = false;
+    this.#dragOffset = 0;
+    this.removeAttribute('data-dragging');
     this.#thumbEl.releasePointerCapture(e.pointerId);
     this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);

package/components/slider/slider.a2ui.json

@@ -153,13 +153,19 @@
     "tag": "slider-ui",
     "tokens": {
       "--slider-fill": {
-        "description": "Filled track / thumb color"
+        "description": "Filled portion / progress color (was mixed accent, now primary)"
       },
-      "--slider-thumb-size": {
-        "description": "Thumb diameter"
+      "--slider-thumb-height": {
+        "description": "Thumb pill height (track-height − 2× inset)"
+      },
+      "--slider-thumb-width": {
+        "description": "Thumb pill width (2× thumb-height, driven by track-height)"
       },
       "--slider-track": {
-        "description": "Track background color"
+        "description": "Unfilled track background color"
+      },
+      "--slider-track-height": {
+        "description": "Full track height (scales via universal [size] attribute)"
       }
     },
     "traits": [],