@adia-ai/web-components 0.5.6 → 0.5.8

package/components/input/input.test.js

@@ -0,0 +1,123 @@
+/**
+ * input-ui — focused unit tests for the §199 (v0.5.7) leading/trailing
+ * affordance-slot wiring.
+ *
+ * Pre-§199 the yaml declared `slot="leading"` + `slot="trailing"` since
+ * v1 but nothing rendered them — consumer-authored buttons sat OUTSIDE
+ * the field chrome. §199 closes the schema-vs-impl gap by moving
+ * consumer-supplied affordance nodes into [slot="field"] at the right
+ * insertion points on connected().
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './input.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('input-ui — §199 leading/trailing affordance slots', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders a baseline input without any affordances (no regression)', () => {
+    const el = mount('<input-ui value="hello"></input-ui>');
+    const field = el.querySelector(':scope > [slot="field"]');
+    expect(field).not.toBeNull();
+    expect(field.querySelector('[slot="text"]')).not.toBeNull();
+    expect(field.querySelector('[slot="leading"]')).toBeNull();
+    expect(field.querySelector('[slot="trailing"]')).toBeNull();
+  });
+
+  it('moves consumer [slot="trailing"] into [slot="field"]', () => {
+    const el = mount(`
+      <input-ui value="Theme 1" suffix="Light">
+        <button slot="trailing" data-test="open" aria-label="Open">↗</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const trailing = field.querySelector(':scope > [slot="trailing"]');
+    expect(trailing).not.toBeNull();
+    expect(trailing.dataset.test).toBe('open');
+    // No stray trailing nodes left as direct children of <input-ui>
+    expect(el.querySelector(':scope > [slot="trailing"]')).toBeNull();
+  });
+
+  it('moves consumer [slot="leading"] into [slot="field"]', () => {
+    const el = mount(`
+      <input-ui value="https://...">
+        <button slot="leading" data-test="link" aria-label="Open link">↗</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const leading = field.querySelector(':scope > [slot="leading"]');
+    expect(leading).not.toBeNull();
+    expect(leading.dataset.test).toBe('link');
+    expect(el.querySelector(':scope > [slot="leading"]')).toBeNull();
+  });
+
+  it('positions trailing after suffix and before controls (number mode)', () => {
+    const el = mount(`
+      <input-ui type="number" value="42" suffix="kg">
+        <button slot="trailing" data-test="reset">↺</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const children = Array.from(field.children);
+    const suffixIdx = children.findIndex((c) => c.getAttribute('slot') === 'suffix');
+    const trailingIdx = children.findIndex((c) => c.getAttribute('slot') === 'trailing');
+    const controlsIdx = children.findIndex((c) => c.getAttribute('slot') === 'controls');
+    expect(suffixIdx).toBeGreaterThanOrEqual(0);
+    expect(trailingIdx).toBeGreaterThanOrEqual(0);
+    expect(controlsIdx).toBeGreaterThanOrEqual(0);
+    expect(suffixIdx).toBeLessThan(trailingIdx);
+    expect(trailingIdx).toBeLessThan(controlsIdx);
+  });
+
+  it('positions leading after label (when label present)', () => {
+    const el = mount(`
+      <input-ui label="Theme" value="Theme 1">
+        <button slot="leading" data-test="picker">🎨</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const children = Array.from(field.children);
+    const labelIdx = children.findIndex((c) => c.getAttribute('slot') === 'label');
+    const leadingIdx = children.findIndex((c) => c.getAttribute('slot') === 'leading');
+    const textIdx = children.findIndex((c) => c.getAttribute('slot') === 'text');
+    expect(labelIdx).toBeGreaterThanOrEqual(0);
+    expect(leadingIdx).toBeGreaterThanOrEqual(0);
+    expect(textIdx).toBeGreaterThanOrEqual(0);
+    expect(labelIdx).toBeLessThan(leadingIdx);
+    expect(leadingIdx).toBeLessThan(textIdx);
+  });
+
+  it('supports multiple trailing nodes in author order', () => {
+    const el = mount(`
+      <input-ui value="hello">
+        <button slot="trailing" data-test="a">A</button>
+        <button slot="trailing" data-test="b">B</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const trailings = Array.from(field.querySelectorAll(':scope > [slot="trailing"]'));
+    expect(trailings.map((n) => n.dataset.test)).toEqual(['a', 'b']);
+  });
+
+  it('preserves contenteditable surface alongside affordances', () => {
+    const el = mount(`
+      <input-ui value="Theme 1" suffix="Light">
+        <button slot="trailing" data-test="open">↗</button>
+      </input-ui>
+    `);
+    const text = el.querySelector('[slot="text"]');
+    expect(text).not.toBeNull();
+    expect(text.getAttribute('contenteditable')).toBe('plaintext-only');
+    expect(text.textContent).toBe('Theme 1');
+  });
+});

package/components/input/input.yaml

@@ -153,11 +153,24 @@ events:
     description: Fired when Enter commits the value.
 slots:
   leading:
-    description: Leading icon slot, sized to --content-height. Collapses text inline padding when present.
+    description: |-
+      Leading affordance slot, inside the field chrome, before the
+      value. Sized to chrome height. Author `<button-ui slot="leading"
+      icon="..." variant="ghost" size="sm">` (or any inline element)
+      for inline actions before the value — e.g. a link-icon button
+      next to a URL input. Wired §199 v0.5.7.
   text:
     description: Contenteditable text surface for user input
   trailing:
-    description: Trailing icon slot, sized to --content-height. Collapses text inline padding when present.
+    description: |-
+      Trailing affordance slot, inside the field chrome, after the
+      value (and after [slot="suffix"] if present). Sized to chrome
+      height. Author `<button-ui slot="trailing" icon="..."
+      variant="ghost" size="sm" aria-label="...">` for inline actions
+      like copy / clear / open-in-modal. For trailing text/icon
+      labels (e.g. "Light" in a theme picker), use the `suffix` prop
+      instead — affordance slots are for interactive buttons, not
+      text. Wired §199 v0.5.7.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/nav/nav.a2ui.json

@@ -48,7 +48,12 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
-    "composes": [],
+    "composes": [
+      "nav-group-ui",
+      "nav-item-ui",
+      "icon-ui",
+      "popover-ui"
+    ],
     "events": {
       "nav-select": {
         "description": "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }.",

package/components/nav/nav.yaml

@@ -14,6 +14,12 @@ description: |
   collapsed. [variant="section"] is a subnav rail with quieter chrome
   and a [heading] kicker rendered via CSS.
 
+composes:
+  - nav-group-ui
+  - nav-item-ui
+  - icon-ui
+  - popover-ui
+
 props:
   variant:
     type: string

package/components/nav-group/nav-group.a2ui.json

@@ -58,7 +58,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
-    "composes": [],
+    "composes": [
+      "icon-ui",
+      "badge-ui",
+      "nav-item-ui"
+    ],
     "events": {
       "group-toggle": {
         "description": "Fired when the header toggles via click/keyboard. Detail: { text, open }.",

package/components/nav-group/nav-group.css

@@ -9,7 +9,7 @@
     --nav-group-font-size:     var(--a-ui-size);
     --nav-group-font-size-sm:  var(--a-ui-sm);
     --nav-group-font-size-lg:  var(--a-ui-lg);
-    --nav-group-font-weight:   var(--a-font-weight-normal);
+    --nav-group-font-weight:   var(--a-weight-normal);
     --nav-group-fg:            var(--a-fg);
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);

package/components/nav-group/nav-group.yaml

@@ -14,6 +14,11 @@ description: |
   expansion. Inline click + keyboard (Enter/Space) toggle is supported
   when [collapsible] (default true).
 
+composes:
+  - icon-ui
+  - badge-ui
+  - nav-item-ui
+
 props:
   text:
     type: string

package/components/nav-item/nav-item.a2ui.json

@@ -63,7 +63,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
-    "composes": [],
+    "composes": [
+      "icon-ui",
+      "badge-ui"
+    ],
     "events": {
       "nav-select": {
         "description": "Bubbles when the item is activated. Detail: { item, text, value }.",

package/components/nav-item/nav-item.css

@@ -39,7 +39,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     --nav-item-font-size:       var(--a-ui-size);
     --nav-item-font-size-sm:    var(--a-ui-sm);
     --nav-item-font-size-lg:    var(--a-ui-lg);
-    --nav-item-font-weight:     var(--a-font-weight-normal);
+    --nav-item-font-weight:     var(--a-weight-normal);
     --nav-item-fg:              var(--a-ui-text-subtle);
     --nav-item-fg-hover:        var(--a-ui-text-hover);
     --nav-item-fg-selected:     var(--a-ui-text-selected);

package/components/nav-item/nav-item.yaml

@@ -14,6 +14,10 @@ description: |
   <nav-ui>; clicking or activating an item calls nav.select(this) and
   bubbles a `nav-select` event.
 
+composes:
+  - icon-ui
+  - badge-ui
+
 props:
   text:
     type: string

package/components/select/select.d.ts

@@ -40,6 +40,8 @@ export class UISelect extends UIFormElement {
   /** Allow values not in the option list (combobox mode). */
   freeText: boolean;
   divider: boolean;
+  /** §207 (v0.5.7): hint text below the field, wired to aria-describedby. */
+  hint: string;
 
   /**
    * Dynamic option list. Setting `.options = [...]` stamps option elements at

package/components/slider/slider.d.ts

@@ -20,6 +20,10 @@ export class UISlider extends UIFormElement {
   step: number;
   label: string;
   suffix: string;
+  /** §184 (v0.5.5, FEEDBACK-08 §4): debounce `input` event by this many ms. 0 = no throttle. */
+  throttle: number;
+  /** §184 (v0.5.5, FEEDBACK-08 §4): hint text rendered below the track, wired to aria-describedby. */
+  hint: string;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/switch/switch.d.ts

@@ -20,6 +20,8 @@ export class UISwitch extends UIFormElement {
   label: string;
   /** Size — `sm` / `md` / `lg`. */
   size: '' | 'sm' | 'md' | 'lg';
+  /** §207 (v0.5.7): hint text rendered below the switch, wired to aria-describedby. */
+  hint: string;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/table/class.js

@@ -95,7 +95,15 @@ export class UITable extends UIElement {
   // consumer markup). Aggregated by installIconLoadersForRegistered()
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['caret-right', 'caret-up-down', 'table'];
+  static requiredIcons = [
+    'caret-right',
+    'caret-up-down',
+    'table',
+    'arrow-up',
+    'arrow-down',
+    'funnel-simple',
+    'funnel-simple-fill',
+  ];
 
   static properties = {
     sortable:   { type: Boolean, default: false, reflect: true },

package/components/table/table.yaml

@@ -200,6 +200,10 @@ requiredIcons:
   - caret-right
   - caret-up-down
   - table
+  - arrow-up
+  - arrow-down
+  - funnel-simple
+  - funnel-simple-fill
 a2ui:
   rules: []
 anti_patterns: []

package/components/table-toolbar/class.js

@@ -124,6 +124,11 @@ export class UITableToolbar extends UIElement {
     variant:     { type: String,  default: 'default',  reflect: true },
   };
 
+  // §205 (v0.5.7): dynamic sort-indicator icons (class.js:576 — nested ternary
+  // `dir === 'asc' ? 'arrow-up' : dir === 'desc' ? 'arrow-down' : 'caret-up-down'`).
+  // Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
+  static requiredIcons = ['arrow-up', 'arrow-down', 'caret-up-down'];
+
   static template = () => null;
 
   #target = null;

package/components/table-toolbar/table-toolbar.yaml

@@ -113,6 +113,10 @@ tokens:
     description: Title font size
   --table-toolbar-title-weight:
     description: Title font weight
+requiredIcons:
+  - arrow-up
+  - arrow-down
+  - caret-up-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/text/text.a2ui.json

@@ -41,7 +41,6 @@
       "enum": [
         "body",
         "heading",
-        "subheading",
         "title",
         "subsection",
         "display",
@@ -51,13 +50,7 @@
         "deck",
         "section",
         "metric",
-        "code",
-        "h1",
-        "h2",
-        "h3",
-        "h4",
-        "h5",
-        "h6"
+        "code"
       ],
       "default": "body"
     }

package/components/text/text.css

@@ -48,6 +48,19 @@
   :scope[variant="kicker"]     { --text-family: var(--a-kicker-family);  --text-weight: var(--a-kicker-weight);  --text-size: var(--a-kicker-size);  --text-leading: var(--a-kicker-leading);  --text-tracking: var(--a-kicker-tracking);  --text-case: uppercase;             --text-color: var(--a-kicker-color); }
   :scope[variant="code"]       { --text-family: var(--a-code-family);    --text-weight: var(--a-code-weight);    --text-size: var(--a-code-size);    --text-leading: var(--a-code-leading);    --text-tracking: var(--a-code-tracking);    --text-case: var(--a-code-case);    --text-color: var(--a-code-color); }
 
+  /* §210 (v0.5.7, FEEDBACK-17 §1): three token-backed variants whose
+     `--a-<role>-{family,weight,leading,tracking,case,color,size}` tokens
+     ship in `styles/typography.css` but had no matching :scope rule —
+     authoring `<text-ui variant="subsection|deck|metric">` per the
+     documented yaml enum silently rendered as `body` defaults. The
+     `subheading` + `h1`–`h6` enum entries are deliberately omitted from
+     this batch: their tokens don't ship anywhere (verified in this same
+     arc), so the enum entries are retired from text.yaml / text.d.ts /
+     text.a2ui.json. */
+  :scope[variant="subsection"] { --text-family: var(--a-subsection-family); --text-weight: var(--a-subsection-weight); --text-size: var(--a-subsection-size); --text-leading: var(--a-subsection-leading); --text-tracking: var(--a-subsection-tracking); --text-case: var(--a-subsection-case); --text-color: var(--a-subsection-color); }
+  :scope[variant="deck"]       { --text-family: var(--a-deck-family);       --text-weight: var(--a-deck-weight);       --text-size: var(--a-deck-size);       --text-leading: var(--a-deck-leading);       --text-tracking: var(--a-deck-tracking);       --text-case: var(--a-deck-case);       --text-color: var(--a-deck-color); }
+  :scope[variant="metric"]     { --text-family: var(--a-metric-family);     --text-weight: var(--a-metric-weight);     --text-size: var(--a-metric-size);     --text-leading: var(--a-metric-leading);     --text-tracking: var(--a-metric-tracking);     --text-case: var(--a-metric-case);     --text-color: var(--a-metric-color); }
+
   /* ── Truncation (single-line) ── */
   :scope[truncate] {
     overflow: hidden;

package/components/text/text.d.ts

@@ -22,5 +22,5 @@ export class UIText extends UIElement {
   /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
   truncate: boolean;
   /** Typography variant — sets role tokens (size/weight/tracking/color). */
-  variant: 'body' | 'heading' | 'subheading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  variant: 'body' | 'heading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code';
 }

package/components/text/text.test.js

@@ -0,0 +1,106 @@
+/**
+ * text-ui variant rendering tests — §210 (v0.5.7, FEEDBACK-17 §1).
+ *
+ * Verifies the 12 documented enum values in `text.yaml`/`text.d.ts`/
+ * `text.a2ui.json` all render distinctly per the `:scope[variant=…]`
+ * rules in `text.css`. Pre-§210 the three token-backed variants
+ * `subsection` / `deck` / `metric` silently rendered as `body`
+ * defaults because the matching `:scope` rules were missing — the
+ * yaml + d.ts advertised them but the CSS didn't consume the tokens.
+ *
+ * Plus a guard: the 6 phantom enum entries removed in §210
+ * (`subheading`, `h1`-`h6`) must NOT be in the .d.ts type union or
+ * the a2ui.json enum — they had no shipped tokens and rendering them
+ * was always body-defaults.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import '../../core/element.js';
+import './text.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+// jsdom doesn't evaluate @scope rules in `getComputedStyle()`. We
+// validate the CSS by reading the rule out of text.css text and
+// asserting the variant-specific properties are present — coarse
+// but catches the §210 regression class (rule missing entirely).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEXT_CSS = readFileSync(resolve(HERE, 'text.css'), 'utf8');
+const TEXT_DTS = readFileSync(resolve(HERE, 'text.d.ts'), 'utf8');
+const TEXT_A2UI = JSON.parse(readFileSync(resolve(HERE, 'text.a2ui.json'), 'utf8'));
+
+describe('text-ui §210 — variant enum vs CSS rule completeness', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // ── Mounting smoke — every documented variant constructs without crash ──
+  const documentedVariants = [
+    'body', 'heading', 'title', 'subsection', 'display', 'caption',
+    'label', 'kicker', 'deck', 'section', 'metric', 'code',
+  ];
+
+  it.each(documentedVariants)('mounts <text-ui variant="%s"> without error', async (variant) => {
+    const t = mount(`<text-ui variant="${variant}">Sample</text-ui>`);
+    await tick();
+    expect(t).toBeDefined();
+    expect(t.getAttribute('variant')).toBe(variant);
+  });
+
+  // ── CSS-side: every documented variant has a :scope rule ──
+  it.each(documentedVariants)('text.css ships a :scope[variant="%s"] rule', (variant) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[variant="${variant}"\\]`));
+  });
+
+  // ── Three token-backed variants restored in §210 ──
+  it.each(['subsection', 'deck', 'metric'])(
+    'text.css :scope[variant="%s"] consumes role tokens (not body defaults)',
+    (variant) => {
+      // The rule must reference the role-specific token, not fall through
+      // to var(--a-body-*) defaults.
+      const ruleMatch = TEXT_CSS.match(
+        new RegExp(`:scope\\[variant="${variant}"\\]\\s*\\{([^}]+)\\}`)
+      );
+      expect(ruleMatch, `rule missing for variant="${variant}"`).toBeTruthy();
+      const rule = ruleMatch[1];
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-family\\)`));
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-weight\\)`));
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-size\\)`));
+    }
+  );
+
+  // ── Type-side: 6 phantom entries removed in §210 ──
+  const removedPhantoms = ['subheading', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+
+  it.each(removedPhantoms)('text.d.ts variant union does NOT contain phantom "%s"', (variant) => {
+    expect(TEXT_DTS).not.toMatch(new RegExp(`'${variant}'`));
+  });
+
+  it.each(removedPhantoms)('text.a2ui.json variant enum does NOT contain phantom "%s"', (variant) => {
+    expect(TEXT_A2UI.properties.variant.enum).not.toContain(variant);
+  });
+
+  // ── a2ui.json enum and .d.ts union and CSS rules are mutually consistent ──
+  it('a2ui.json variant enum matches .d.ts union and CSS rules 1:1', () => {
+    const a2uiVariants = TEXT_A2UI.properties.variant.enum;
+    const dtsUnionMatch = TEXT_DTS.match(/variant:\s*((?:'[^']+'\s*\|?\s*)+);/);
+    expect(dtsUnionMatch).toBeTruthy();
+    const dtsVariants = [...dtsUnionMatch[1].matchAll(/'([^']+)'/g)].map(m => m[1]);
+
+    expect(a2uiVariants.sort()).toEqual(dtsVariants.sort());
+    expect(a2uiVariants.sort()).toEqual([...documentedVariants].sort());
+
+    // Every variant has a CSS rule.
+    for (const v of a2uiVariants) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[variant="${v}"\\]`));
+    }
+  });
+});

package/components/text/text.yaml

@@ -34,7 +34,6 @@ props:
     enum:
       - body
       - heading
-      - subheading
       - title
       - subsection
       - display
@@ -45,12 +44,6 @@ props:
       - section
       - metric
       - code
-      - h1
-      - h2
-      - h3
-      - h4
-      - h5
-      - h6
 events: {}
 slots: {}
 states:

package/components/timeline/class.js

@@ -87,6 +87,11 @@ export class UITimelineItem extends UIElement {
     spinner:     { type: Boolean, default: false,     reflect: true },
   };
 
+  // §205 (v0.5.7): dynamic chevron icons stamped on expanded-state ternary
+  // (class.js:167). Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
+  // Note: `this.icon` consumer-supplied — not declared here.
+  static requiredIcons = ['caret-down', 'caret-right'];
+
   static template = () => null;
 
   #outcomes = [];

package/components/timeline/timeline.yaml

@@ -40,6 +40,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-down
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/toggle-scheme/class.js

@@ -78,6 +78,12 @@ export class UIToggleScheme extends UIElement {
   #mqlHandler = null;
   #onPress = null;
   #stamped = false;
+  // §200 (v0.5.7, FEEDBACK-10 §1): set true after first user-driven scheme
+  // mutation (button press OR programmatic setScheme/toggle). Until then,
+  // the `scheme` attribute is treated as "reactive consumer-driven" — any
+  // post-connect attribute application re-runs #initState() so the reactive
+  // value wins over the template-strip race.
+  #userTouched = false;
 
   connected() {
     if (!this.#stamped) {
@@ -87,6 +93,26 @@ export class UIToggleScheme extends UIElement {
     this.#initState();
   }
 
+  attributeChangedCallback(name, oldVal, newVal) {
+    // §200 (v0.5.7, FEEDBACK-10 §1): UIElement.attributeChangedCallback syncs
+    // attr → property. After it runs, if the `scheme` attribute changed AFTER
+    // connect AND the user hasn't yet chosen explicitly, re-run #initState()
+    // so the reactive consumer value wins over the template-engine's strip-
+    // then-restamp race. Once the user clicks the button or calls
+    // setScheme()/toggle() programmatically, #userTouched flips true and we
+    // stop auto-reinit so user choice survives subsequent re-renders.
+    super.attributeChangedCallback(name, oldVal, newVal);
+    if (
+      name === 'scheme' &&
+      this.isConnected &&
+      this.#stamped &&
+      !this.#userTouched &&
+      oldVal !== newVal
+    ) {
+      this.#initState();
+    }
+  }
+
   disconnected() {
     if (this.#button && this.#onPress) {
       this.#button.removeEventListener('press', this.#onPress);
@@ -98,6 +124,7 @@ export class UIToggleScheme extends UIElement {
 
   /** Flip between light and dark — defeats auto. */
   toggle() {
+    this.#userTouched = true;
     const next = this.activeScheme === DARK ? LIGHT : DARK;
     this.#apply(next, 'programmatic');
   }
@@ -106,6 +133,7 @@ export class UIToggleScheme extends UIElement {
    * @param {"light"|"dark"|"auto"} s
    */
   setScheme(s) {
+    this.#userTouched = true;
     if (s === AUTO) {
       this.#clearTargetOverride();
       const resolved = this.#resolvePrefersScheme();
@@ -135,6 +163,9 @@ export class UIToggleScheme extends UIElement {
       // so consumers see one semantic event, not the inner button's.
       e.stopPropagation();
       if (this.disabled) return;
+      // §200 (v0.5.7): mark user-touched so post-connect reactive `scheme`
+      // attribute writes don't override the user's explicit choice.
+      this.#userTouched = true;
       const next = this.activeScheme === DARK ? LIGHT : DARK;
       this.#apply(next, 'press');
     };