@adia-ai/web-components 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.8] — 2026-05-20
+
+### Fixed
+- **`core/template.js` — `.camelCaseProp=${expr}` property bindings now route to the canonical setter (FB-55, P1).** Pre-fix: the HTML parser lowercases attribute names inside `<template>.innerHTML` per HTML5 §13.2.5.32, so `.className=${expr}` arrived at the binding scanner as `.classname`. The binding then wrote `element['classname'] = v` — an enumerable expando — never invoking the `HTMLElement.prototype.className` setter. Classes never applied; no warning, no error. Trap affected every camelCase DOM property surface (`.className`, `.innerText`, `.tabIndex`, `.ariaLabel`, `.contentEditable`, `.readOnly`, `.maxLength`, `.minLength`, `.colSpan`, `.rowSpan`) AND every camelCase property declared via `UIElement.static properties` (80+ across primitives — `<color-picker>` `.maxChroma`, `<grid>` `.columnGap`, `<breadcrumb>` `.collapseKeepLeading`, etc.). Even the canonical `<my-panel .minL=${minL}>` example from `README.md:212` silently failed. **Fix: two-layer name resolution** — (1) `PROP_CASE_FIX` static map at `scan()` time covers built-in DOM camelCase (zero-cost lookup, no prototype walk for the common case); (2) lazy prototype-walk fallback at `applyValue()` time finds canonical camelCase property names on the element's instance + prototype chain via case-insensitive match, caching resolution on the part after first hit. Catches UIElement custom-element props installed per-instance in `installProps()` (those don't exist at `scan()` time because the element hasn't been upgraded yet). Backward-compatible: when neither layer finds a case-insensitive match, the original lowercase name is preserved (consumers writing to lowercase expandos unaffected). 10 NEW vitest cases in `core/template.test.js`'s `FB-55` describe block pin the contract. Closes RESPONSE-55 (reviewer-#A expansion to UIElement primitives explicitly covered).
+- **`core/template.js` — nested `${html\`<svg-child/>\`}` interpolations now render in SVG namespace (FB-57, P1).** Pre-fix: each nested `html\`\`` is a separate cached template whose `tpl.innerHTML = m` is parsed at document level without SVG insertion-mode context, so `<circle>`/`<line>`/etc. arrived as `HTMLUnknownElement` (NS `http://www.w3.org/1999/xhtml`). The `<span style="display:contents">` wrapper from `wrap()` didn't fix it because `display: contents` is layout-level, not namespace-level; SVG layout is namespace-strict → present-but-invisible output, zero bounding rect, no error. **Fix: namespace-aware `mount()`** — discriminate via `container.closest('svg, math, foreignObject, annotation-xml')` at mount time; when stamping into an SVG/MathML subtree, recursively re-namespace the cloned fragment via `createElementNS`, transferring attributes via `setAttributeNS` to preserve attr-namespaces (e.g., legacy `xlink:href`). `<foreignObject>` (SVG) and `<annotation-xml encoding="text/html"|"application/xhtml+xml">` (MathML) descendants correctly REVERT to HTML namespace per HTML5 §12.2.5 foreign-content insertion mode. Implementation site: `mount()` rather than `getTemplate()` — keeps the template cache coherent (same `html\`\`` source can stamp into either context without doubling cache entries). 6 NEW vitest cases in `core/template.test.js`'s `FB-57` describe block (inline-SVG regression, nested-SVG fix, direct-stamp into SVG container, foreignObject boundary, MathML, HTML-container no-op). Closes RESPONSE-57 (Option A accepted with implementation-site refinement; Option B rejected as half-measure).
+- **`core/template.js` — partial-interp warning text recommends `class="${expr}"` first (FB-55 #2).** The v0.5.5 §184 warn text put `.className=${expression}` first as the recommended fix for partial class interpolation; that path now works post-FB-55 fix above, but `class="${expr}"` (full-attribute interpolation) is the more discoverable form that doesn't require knowing the camelCase property name. Promoting it first. The `.classList=${{foo: true, bar: false}}` aspirational line is removed — classList is a read-only DOMTokenList accessor, no `PROP_CASE_FIX` entry can make it assignable.
+
+### Docs
+- **`USAGE.md` — three new template-related sections** documenting the FB-55/56/57 cluster:
+  - **§-TBD (v0.6.8) — Host element display defaults (FB-56)** — surfaces the HTML-spec inline default for custom elements + the `:host(:where(*))` zero-specificity recipe used across the in-tree primitive set (30+ flex-container primitives). Documents why `UIElement` doesn't bake a `display` rule into the host (container vs leaf vs passthrough is a consumer-layout decision). Worked symptom + diagnostic recipe ("inspect the host directly — `getComputedStyle(host).display === 'inline'`").
+  - **§-TBD (v0.6.8) — SVG composition + namespacing (FB-57)** — documents three modes (inline, nested-interpolations, imperative-`.innerHTML`) with the `<foreignObject>` boundary semantics and the MathML parallel. Migration is zero — pre-fix code that worked keeps working; pre-fix code that was silently broken (nested SVG interpolations) starts producing visible output.
+  - **§-TBD (v0.6.8) — `.camelCaseProp=${expr}` property binding (FB-55)** — explains the two-layer name resolution, lists affected camelCase property surfaces, documents backward-compatibility for genuine expando consumers, and notes the discoverability trade-off (the simpler `class="${expr}"` doesn't require knowing the camelCase property name).
+- **USAGE.md `§-TBD (v0.6.8) — UIElement lifecycle hooks (FB-59 + FB-43/44/47/58 cluster)`** — new section documenting the canonical hook order: `adoptStyles` → `prepareParts` → **`connected()`** (line 122, inside `untracked()`) → effect first-run with **stamp at line 127** → `render()` → `updated()`. Source-cited from `core/element.js:107-142`. Resolves a cluster-wide misunderstanding about when `connected()` fires relative to the template stamp: it runs BEFORE the stamp wipes consumer-supplied light-DOM children, NOT after. Includes the "Container UIElement pattern" example showing `connected()` → capture children → arm MutationObserver, plus the defensive `if (present.length > 0) keep` cache-fallback pattern (consumer-discovered) that makes capture robust to ordering. Distinguishes `connected()` (recommended subclass hook) vs `connectedCallback()` (rarely overridden W3C hook). Closes FB-59 P3 docs ask + corrects the §B mechanism walkthrough in RESPONSE-58 (sibling followup-RESPONSE retracts the §B order claim).
+
+## [0.6.7] — 2026-05-19
+
+### Added
+- **`<name>.examples.md` ships in npm package** (96 components, ~67KB total).
+  Generated by `scripts/build/generate-examples-md.mjs` from `<name>.examples.html`.
+  External consumers can now read canonical markup fragments directly from
+  `node_modules/@adia-ai/web-components/components/<name>/<name>.examples.md`.
+- **`custom-elements.json` ships in npm package** (W3C Custom Elements Manifest v2.1.0).
+  Generated from per-component yaml files. Enables IDE LSP autocomplete and
+  cross-tool interop (Storybook, VS Code WC extensions).
+- **`npx @adia-ai/web-components doc <name>` CLI** prints yaml summary + live
+  demo URL + first example fragment for any component. Bare `doc` lists all.
+- **`USAGE.md § Data binding with data-stream-*`** new top-level section
+  covering the declarative `data-stream-*` attribute family (was previously
+  undocumented despite being used in 12+ components).
+
 ## [0.6.6] — 2026-05-18
 
 ### Added

package/USAGE.md

@@ -14,11 +14,12 @@ The complete reference for engineers and agents **integrating** AdiaUI into an a
 4. [Property binding patterns (templates / framework integration)](#property-binding-patterns)
 5. [Event contract — `CustomEvent` with `detail`](#event-contract)
 6. [Form participation — `UIFormElement` + `ElementInternals`](#form-participation)
-7. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
-8. [Theming, density, size](#theming-density-size)
-9. [Registration — auto vs explicit](#registration--auto-vs-explicit)
-10. [TypeScript](#typescript)
-11. [Anti-patterns](#anti-patterns)
+7. [Data binding with `data-stream-*`](#data-binding-with-data-stream-)
+8. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
+9. [Theming, density, size](#theming-density-size)
+10. [Registration — auto vs explicit](#registration--auto-vs-explicit)
+11. [TypeScript](#typescript)
+12. [Anti-patterns](#anti-patterns)
 
 ---
 
@@ -461,6 +462,100 @@ form.addEventListener('submit', (e) => {
 
 ---
 
+## Data binding with `data-stream-*`
+
+Many AdiaUI components (`<chart-ui>`, `<heatmap-ui>`, `<table-ui>`, `<stat-ui>`, `<progress-row-ui>`, and ~7 others) support **declarative remote-data binding** via the `data-stream-*` attribute family. You point a component at a URL, and it self-fetches (REST poll) or self-subscribes (SSE) and pushes the result into one of its properties. No JS glue required.
+
+This is the canonical "wire a component to a backend" pattern in AdiaUI. Reach for it before writing a `fetch()` loop in your app code.
+
+### Concept
+
+A component that opts in watches its `data-stream-*` attributes. When `data-stream-src` is set on a connected element, the component starts a transport (poll, SSE, or manual) and assigns each payload to a target property (e.g. `data` on `<table-ui>`, `value` on `<stat-ui>`). Change the attribute and the transport restarts; remove the attribute (or disconnect the element) and the transport tears down.
+
+Because the binding is attribute-driven, it survives SSR, server-rendered partials, htmx swaps, framework hydration, and templating engines that have no concept of property assignment.
+
+### Attribute reference
+
+| Attribute | Purpose | Default |
+|---|---|---|
+| `data-stream-src` | URL — REST endpoint or SSE source. Setting this activates the binding. | (required) |
+| `data-stream-mode` | `"poll"`, `"sse"`, or `"manual"`. `manual` fetches once on connect and on attribute change. | `"poll"` |
+| `data-stream-interval` | Poll interval in milliseconds. Ignored for `sse` / `manual`. | `5000` |
+| `data-stream-path` | Dot-path into the JSON response to extract before binding (e.g. `claims` extracts `response.claims`; `data.items` extracts `response.data.items`). | (whole response) |
+| `data-stream-target` | Which component property receives the payload. | component-specific (`data` for `<table-ui>`, `value` for `<stat-ui>`, `data` for `<chart-ui>`, …) |
+| `data-stream-method` | HTTP method for REST mode. `POST` is supported when you need a request body via headers/config. | `"GET"` |
+| `data-stream-headers` | JSON-stringified object of request headers (e.g. `'{"Authorization":"Bearer …"}'`). | `null` |
+| `data-stream-id` | Logical transport key. Multiple elements with the same `data-stream-id` share one underlying fetch/SSE connection. | (per-element) |
+
+### REST polling
+
+```html
+<table-ui
+  data-stream-src="/api/claims"
+  data-stream-interval="10000"
+  data-stream-target="data"
+></table-ui>
+```
+
+The table fetches `/api/claims` every 10s and assigns the response to its `data` property. If the response is wrapped (e.g. `{ claims: [...] }`), add `data-stream-path="claims"` to drill in.
+
+### SSE streaming
+
+```html
+<stat-ui
+  label="Active"
+  data-stream-src="/api/active-count"
+  data-stream-mode="sse"
+  data-stream-target="value"
+></stat-ui>
+```
+
+Opens an `EventSource` against `/api/active-count`. Each SSE message's `data` field is JSON-parsed (when possible) and pushed into the stat's `value`. The connection closes on disconnect.
+
+### Shared transport
+
+When two or more components need the same source, give them a matching `data-stream-id` and they will share a single fetch/SSE subscription:
+
+```html
+<table-ui
+  data-stream-src="/api/claims"
+  data-stream-id="shared-claims"
+  data-stream-target="data"
+></table-ui>
+
+<stat-ui
+  label="Total"
+  data-stream-src="/api/claims"
+  data-stream-id="shared-claims"
+  data-stream-path="length"
+  data-stream-target="value"
+></stat-ui>
+```
+
+One request feeds both. Each element still applies its own `data-stream-path` and `data-stream-target` independently. The shared transport is reference-counted; the last element to disconnect tears it down.
+
+### SSR / server rendering
+
+`data-stream-*` is **client-only**. Server-rendered markup that contains these attributes is safe — the attributes are just strings on the element — and the transport only activates once the component is upgraded in the browser. This means you can:
+
+- Server-render the initial empty/skeleton state of a `<table-ui>` and let the client take over.
+- Emit `data-stream-*` from any templating layer (Jinja, ERB, Handlebars, htmx fragments) without server-side coupling to the data-stream runtime.
+- Hydrate framework apps without special-casing — React/Vue/Svelte just need to render the attribute; they do not need to subscribe.
+
+If you need a server-rendered first paint of *real* data, render it normally (slot or attribute) — the data-stream binding will replace it on first successful payload.
+
+### Authoritative source
+
+The implementation lives at:
+
+```
+packages/web-components/core/data-stream.js
+```
+
+A component opts in by declaring a `data_stream:` block in its YAML descriptor (see `packages/web-components/components/*/*.yaml`). That block is the source of truth for which target properties are bindable and which defaults apply for that specific component. When in doubt, read the component's YAML and `core/data-stream.js` — this document is a discoverability summary, not a spec.
+
+---
+
 ## Lifecycle
 
 `UIElement` exposes four overridable lifecycle methods. Defaults are no-ops. Override what you need:
@@ -1086,6 +1181,115 @@ Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective
 - HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
 - Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
 
+### §-TBD (v0.6.8) — Host element display defaults (FB-56)
+
+Per the HTML spec, **all custom elements default to `display: inline`** — and `UIElement` subclasses are no exception. When you use a `UIElement` subclass as a layout container (filling a flex parent, holding an SVG canvas, wrapping a fluid grid), the inline default collapses the host to zero height and any `height: 100%` descendant collapses with it.
+
+**Symptom you're hitting this trap:** content renders in DevTools with the expected DOM, but its computed height is 0 because the custom-element host between it and a layout parent has `display: inline`. Inspect the host element directly — `getComputedStyle(host).display === 'inline'` confirms.
+
+If you author a `UIElement` to be a layout container, set an explicit `display` on the host tag — the in-tree convention is `:host(:where(*))` so consumer-app CSS can still override without `!important`:
+
+```js
+import { css } from '@adia-ai/web-components/core/element';
+
+class MyContainer extends UIElement {
+  static styles = css`
+    :host(:where(*)) {       /* zero-specificity wrap; consumers override at (0,0,1) */
+      display: flex;
+      flex-direction: column;
+      flex: 1 1 auto;
+      min-height: 0;
+    }
+  `;
+  static template = (host) => html`<slot></slot>`;
+}
+```
+
+Or, if the host should be transparent to layout (its children inherit the parent's grid/flex context directly):
+
+```css
+my-passthrough-element { display: contents; }
+```
+
+See also: the slot-routing pass-through pattern that's the natural consumer of `display: contents` (cross-referenced from §345's `.map()` vs `repeat()` discussion where `wrap()` spans use the same mechanism).
+
+**`UIElement` does not bake a `display` rule into the host** because container vs leaf vs passthrough is a consumer-layout decision, not a framework one. Per primitive, a global default would risk breaking layouts where the consumer explicitly wants `inline` semantics (e.g. inline badge inside flowing text, `<icon>` rendered alongside surrounding `<text-ui>`, `<kbd-ui>` keystroke marker). The in-tree primitive set spans `inline` / `inline-block` / `block` / `flex` / `grid` / `contents` — no single default fits.
+
+**In-tree convention reference:** scan `packages/web-components/components/*/<name>.css` for the `:host(:where(*))` pattern. The 30+ flex-container primitives (`<editor-shell>`, `<nav>`, `<pane>`, `<page>`, `<card>`, etc.) all use this shape; copy from the closest-fit primitive.
+
+### §-TBD (v0.6.8) — SVG composition + namespacing (FB-57)
+
+`html\`\`` handles SVG content in three modes, with one historical trap closed in v0.6.8.
+
+**Mode 1 — inline SVG in a single template (always worked):**
+
+```js
+html`
+  <svg viewBox="0 0 100 100">
+    <circle cx="50" cy="50" r="10"/>
+    <path d="M 0 0 L 100 100"/>
+  </svg>
+`
+```
+
+When the parser sees `<svg>` in `tpl.innerHTML`, it enters SVG insertion mode for its descendants. Children arrive as proper `SVGElement` instances.
+
+**Mode 2 — nested template interpolations (now works, post-v0.6.8 FB-57 fix):**
+
+```js
+html`
+  <svg viewBox="0 0 100 100">
+    ${dots.map(d => html`<circle cx="${d.x}" cy="${d.y}" r="3"/>`)}
+  </svg>
+`
+```
+
+Each nested `html\`<circle/>\`` is a separate template parsed at document level (no SVG context), so pre-v0.6.8 the circles arrived as `HTMLUnknownElement` — present in the DOM but invisible to SVG layout (zero bounding rect, no stroke, no fill, no error). v0.6.8 `mount()` detects when the container is inside an SVG (or MathML) subtree and re-namespaces the cloned fragment via `createElementNS`. The natural composition pattern works.
+
+**Mode 3 — imperative `.innerHTML` commit (escape hatch for very large SVG):**
+
+For SVG content too large to template cleanly (thousands of nodes, dynamic shape strings):
+
+```js
+class MyChart extends UIElement {
+  static template = (host) => html`<svg viewBox="0 0 ${host.w} ${host.h}"></svg>`;
+  updated() {
+    const svg = this.querySelector('svg');
+    svg.innerHTML = host._buildSvgString();  // SVG-namespaced via SVGSVGElement.innerHTML
+  }
+}
+```
+
+`.innerHTML=${str}` as a template binding also works for this (the property name is already lowercase, so the FB-55 PROP_CASE_FIX entry just maps `innerhtml` → `innerHTML`, and the assignment routes through the SVGSVGElement's `innerHTML` setter which DOES enter SVG insertion mode).
+
+**`<foreignObject>` boundary:** content inside `<foreignObject>` returns to HTML namespace per HTML5 §12.2.5 foreign-content insertion mode. The template engine respects this — interpolations inside `<foreignObject>` are HTML-namespaced even when the outer container is SVG. Use it as the documented escape hatch for HTML widgets embedded in SVG graphs (tooltips, popovers, foreign Cells in dataviz).
+
+**MathML** uses the same mechanism: nested `${html\`<mi/>\`}` inside `<math>` gets re-namespaced to MathML NS. `<annotation-xml encoding="text/html">` is the MathML equivalent of `<foreignObject>` for HTML re-entry.
+
+**Migration:** zero. Pre-v0.6.8 code that already worked (inline SVG + `.innerHTML` commits) keeps working. Code that was silently broken (nested SVG interpolations) starts producing visible output.
+
+### §-TBD (v0.6.8) — `.camelCaseProp=${expr}` property binding (FB-55)
+
+Pre-v0.6.8 trap: the HTML parser lowercases attribute names inside `<template>.innerHTML` per HTML5 §13.2.5.32, so `.className=${expr}` arrived at the binding scanner as `.classname`. The binding then wrote `element['classname'] = v` — a lowercase enumerable **expando** — never invoking the `HTMLElement.prototype.className` setter. CSS classes never applied; no warning, no error.
+
+Same trap affected every camelCase DOM property surface: `.className`, `.innerText`, `.tabIndex`, `.ariaLabel`, `.contentEditable`, `.readOnly`, `.maxLength`, `.minLength`, `.colSpan`, `.rowSpan` — AND every camelCase property declared via `UIElement.static properties` (e.g. `<color-picker>`'s `.maxChroma`, `<grid>`'s `.columnGap`, `<breadcrumb>`'s `.collapseKeepLeading`, plus 80+ others across primitives). Even the canonical reactive-binding example from `README.md` (`<my-panel .minL=${minL}>`) silently failed.
+
+v0.6.8 fix: a two-layer name resolution in `core/template.js`:
+
+1. **`PROP_CASE_FIX` static map** at scan time covers built-in DOM camelCase properties (zero-cost lookup, no prototype walk for the common case).
+2. **Prototype-walk fallback** at `applyValue()` time finds canonical camelCase property names on the element's instance + prototype chain via case-insensitive match — caches the resolution on the part after first hit. Catches UIElement custom-element props installed per-instance in `installProps()`.
+
+```js
+// ✅ Works post-v0.6.8 — both forms route to the canonical setter
+html`<span .className=${'foo bar'}>text</span>`;
+html`<color-picker .maxChroma=${0.3}></color-picker>`;
+html`<my-panel .minL=${minL}></my-panel>`;
+```
+
+**Backward compatibility:** when neither the map nor the prototype walk finds a case-insensitive match, the original lowercase name is preserved. Consumers deliberately writing to lowercase expando properties (`.myexpando=${v}`) are unaffected.
+
+**Discoverability note:** the simpler form `class="${expr}"` (full-attribute interpolation) works without needing to know the camelCase property name and is the v0.6.8 partial-interp warn-text's first recommendation. Reach for `.className=` when you specifically want the property-binding semantics (e.g., when the value carries non-string types, or for performance in tight inner loops).
+
 ### §345 (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
 
 Use **`repeat(items, keyFn, tplFn)`** for any list whose items are signal-driven and should preserve identity across re-renders. Plain `.map()` returns an `Array` of template results, which the template engine materializes via `container.replaceChildren()` on every parent update — correct, but per-item DOM is re-created from scratch.
@@ -1182,6 +1386,83 @@ Use the descendant combinator (a single space) instead, which traverses any dept
 
 Same caveat applies to `:nth-child()` / `:nth-of-type()` / `:first-child` / `:last-child` against the parent — those count actual children (the wrapper-spans), not the items inside. If you need nth-item styling, key it via a data attribute on the item itself rather than relying on positional pseudo-classes against the wrapper layer.
 
+### §-TBD (v0.6.8) — UIElement lifecycle hooks (FB-59 + FB-43/44/47/58 cluster)
+
+UIElement orchestrates the custom-element lifecycle and exposes two extension points: the W3C standard `connectedCallback()` (rarely overridden) and the convenience **`connected()` hook (the recommended subclass extension point)**. Same pattern for `disconnected()`.
+
+#### Canonical hook order
+
+For a UIElement subclass with `static template = () => html\`<x/>\`` mounted into the DOM with consumer-supplied light-DOM children:
+
+1. **`adoptStyles(ctor)`** — adopted stylesheets attached to the document
+2. **`prepareParts(ctor)`** — `static template` markup parsed into the part registry
+3. **`this.connected()`** — subclass hook fires here, inside `untracked(...)`. **Light-DOM children supplied by the parent template are intact at this point.**
+4. **Effect first-run** — `stamp(result, this)` runs here if `ctor.template(this)` returns non-null. This is the call that **wipes consumer-supplied light-DOM children** (via `mount()` → `container.replaceChildren(f)`).
+5. **`this.render()`** — explicit render hook for imperative DOM updates
+6. **`this.updated(changedProps)`** — change-set hook for property-specific reactions
+
+**The key insight for container components: `connected()` runs BEFORE the stamp.** If your container UIElement has both a non-null `static template` AND wants to capture consumer-supplied light-DOM children, do the capture in `connected()`. The wipe runs in step 4, which is after step 3.
+
+Source: `packages/web-components/core/element.js:107-142` — `UIElement.connectedCallback()`. `connected()` fires at line 122 inside `untracked(...)`; the stamp runs at line 127 inside the effect registered at lines 123-137.
+
+#### Container UIElement pattern (FB-43/44/47/58 cluster — the right shape)
+
+When your UIElement is a container for consumer-supplied light-DOM children AND has its own internal `static template`, capture the children in `connected()`:
+
+```js
+class DtsGraph extends UIElement {
+  static template = () => html`<div class="dts-graph-root"></div>`;
+
+  // ✅ connected() runs BEFORE the stamp wipes children — capture here
+  connected() {
+    this._series = [...this.querySelectorAll('dts-graph-band, dts-graph-curve, …')];
+
+    // Optional: MutationObserver for late-arriving children (e.g. parent template
+    // toggles `${cond ? html\`<band/>\` : ''}` and the new band lands later)
+    this._mo = new MutationObserver(() => this._captureSeries());
+    this._mo.observe(this, { childList: true, subtree: true });
+  }
+
+  _captureSeries() {
+    const present = [...this.querySelectorAll('dts-graph-band, …')];
+    // Defensive cache-fallback: post-stamp wipe makes `present` empty, but the
+    // initial capture from connected() above already saved the refs. Keep them.
+    if (present.length > 0) this._series = present;
+  }
+
+  disconnected() {
+    this._mo?.disconnect();
+  }
+}
+```
+
+The `if (present.length > 0) keep` cache-fallback is the architectural pattern that makes the capture robust to either ordering. It works in any lifecycle environment with no specification dependency.
+
+#### `connected()` vs `connectedCallback()` reference
+
+| Hook | Who calls it | When (relative to step list above) | Use case |
+|---|---|---|---|
+| `connectedCallback()` | The browser, per W3C custom-elements spec | Orchestrates the whole sequence | Almost never override — UIElement runs the lifecycle for you |
+| **`connected()`** | UIElement, from within `connectedCallback()` at line 122 | Step 3 — after `prepareParts()`, BEFORE the template stamp | **Subclass setup, light-DOM capture, observer arming, signal effects** |
+| `render()` | The effect, after every signal change | Step 5 — after `stamp()` if the template returned non-null | Imperative DOM updates that don't fit the template engine |
+| `updated(changedProps)` | The effect | Step 6 — after `render()`, when properties changed | React to specific prop changes |
+| `disconnected()` | UIElement, from `disconnectedCallback()` | Element leaves the DOM | Teardown observers, timers, listeners |
+
+#### When NOT to override `connectedCallback()` directly
+
+`UIElement.connectedCallback()` orchestrates the entire lifecycle. Overriding it directly requires re-invoking `super.connectedCallback()` correctly, and you'd have to choose whether your work goes before or after super:
+
+- **BEFORE super**: you miss the `prepareParts(ctor)` call that initializes the part registry. `static template` won't stamp. Other downstream initialization breaks.
+- **AFTER super**: your work runs after step 6 (`updated()`), which means after the stamp wiped your light-DOM children. You'd need to capture in `constructor()` instead — but `constructor()` runs before the element is in the DOM, so light-DOM children aren't appended yet.
+
+`connected()` is the right hook for 99% of consumer code. It runs at exactly the right time: children present, stamp not yet run.
+
+#### Why `connected()` is wrapped in `untracked()`
+
+Per the comment in `element.js:112-121`: `connected()` commonly reads reactive properties via template-literal interpolation (`${this.label}` etc.) when stamping inner DOM. If the outer call path is inside another effect (e.g. a parent's render loop `appendChild`'ing this node), those reads would subscribe the outer effect to this element's signals — invisible cross-element coupling that looks like spooky re-runs on unrelated state changes. The `untracked()` wrapper prevents that subscription leak. The element's own effect (registered at lines 123-137) re-reads the same signals in its own tracking context, so reactivity within the element is unaffected.
+
+This means: inside `connected()`, you CAN read signals/props for setup logic, but those reads won't establish reactive subscriptions. Use the element's own `render()` or signal effects for reactive work; use `connected()` for one-shot setup.
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):