@adia-ai/web-components 0.6.49 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.0] — 2026-05-31
+
+### Added — component features from the docs-QA pass
+
+- **`<stat-ui bleed>`** — horizontal-bleed KPI tile. With a `slot="chart"` child, value/label/change stack on the left while the chart fills the right column at full height and bleeds to the card's top/right/bottom edges (the horizontal counterpart to a chart in a `<section bleed>`). First-class reflected Boolean attr (yaml + `static properties`; not a `data-*` hook).
+- **`<page-ui>` region model** — `--page-inset` vertical rhythm between `header`/`section`/`footer` children + `[bleed]` (edge-to-edge, cancels the page `[padding]`) + `section[padding]` (padded sub-surface), mirroring card-ui's section model. The docs promised `@scope` styled the regions but no such rules existed — regions stacked with zero spacing.
+- **`<timeline-ui>` `--timeline-marker-box-size`** — unified marker footprint (1rem; 0.875rem at `size=sm`) the dot/icon/spinner center within; icon-mode chips gain a ring (`--timeline-icon-border`) so they read as markers even when the muted fill blends with the surface.
+- **`<integration-card-ui>` provider→icon fallback** — a card with only `[provider]` (no `[logo]`) now renders a per-provider Phosphor glyph (slack→chat-circle, github→git-branch, …) or a generic `plug`, instead of a blank logo disc.
+- **`<kbd-ui>` `size="lg"`** — added the missing `lg` to the size enum (CSS + docs already shipped three sizes; the yaml capped at sm/md).
+
+### Fixed — docs-QA pass (browser-verified)
+
+- **`<datetime-picker-ui>`** — committed value now uses the picker-family value color (`--a-ui-text`, bright) + `space-between` alignment (value left, caret right), matching input-ui/select-ui/time-picker (was a centered, dim default button); `[data-has-value]` gates the brightening.
+- **`<kbd-ui>`** — `md` glyph was `--a-ui-tiny` (10px), identical to `sm`; now `--a-ui-xs` (12px) for a real 10/12/14 sm/md/lg ramp.
+- **`<empty-state-ui>`** — heading moved from `--a-ui-lg` (15px control-label ramp; only 1.07× the description) to `--a-heading-md` (17px → 1.21×); the `[minimal]` inline variant keeps the heading bolder + non-muted so it stays distinct from the description.
+- **`<heatmap-ui>`** — `type="day-grid"` keeps fixed cell tracks + scrolls horizontally (GitHub-contributions model) instead of crushing fixed cells into an overlapping smear in narrow containers; `matrix`/`density` keep fitting-and-shrinking.
+- **`<option-card-ui>` `layout="tile"`** — DOM-order-independent (via `order`) with the radio pinned to the card's top-right (cleared the base `grid-area:indicator` that stranded it in a collapsed 8px gutter); token-driven padding. Fixes plan-picker's tile cards.
+- **`<preview-ui>` form-demo width** — the docs render cell capped `<field-ui>` at `max-width:28rem` (448px) together with bare form controls; since field-ui is a full-width form _row_ (its own CSS is `width:100%`), the cap stranded it mid-cell, reading as "not using the available space" on wide single-block demos. Split the rule: field-ui now fills the stage (no cap); bare atomic controls (input/select/combobox/textarea/tags-input/color-input) keep the 28rem measure cap so a lone control doesn't sprawl. (bug-55 follow-up)
+
+### Changed — demos + corpus hygiene (docs-QA pass)
+
+- **`<field-ui>` demos** — migrated in-chrome affordances (copy / clear / ⌘K) onto `input-ui`'s `leading`/`trailing` slots (inside the input box); field's `trailing`/`action` reserved for beside-field captions + submit buttons. Slots table + A2UI guidance now state the boundary. Short in-chrome _status_ text (e.g. "Required") now uses `input-ui`'s `suffix`/`prefix` attribute rather than a `<span slot="trailing">` _outside_ the input — keeps the status inside the field chrome and lets the input fill the full field width (demo `field-default-trailing-caption` → `field-default-inchrome-required`). (bug-55)
+- **`<inline-edit-ui>` form-participation demo** — key-labelled rows (title/description) + instructional placeholder so the form-field semantics are legible.
+- **`<integration-card-ui>` CRUD-drawer demo** — fixed an invisible drawer: the demo used `side="trailing"`, which is not in the `drawer-ui` `side` enum (`left|right|top|bottom`), so the panel `showModal()`'d but rendered at `opacity:0` collapsed in the top-left. Switched to `side="right"`. (bug-50)
+- **Dead `size="sm"` swept** off layout primitives (`row-ui`/`col-ui`/`grid-ui`) + bare `<span slot="action">` across `patterns/` demos (68 sites repo-wide) — the attribute is a no-op on those tags and polluted the gen-UI corpus.
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) for the docs-QA CSS/JS changes + the breaking removals.
+
+### Removed (BREAKING) — `<avatar-ui name="…">` deprecated alias retired
+
+- **`<avatar-ui>` no longer accepts the `name` attribute** — use `text` instead.
+  `name` was a deprecated alias for `text` since 0.4.x (`deprecated_since: "0.4.x"`,
+  scheduled for v0.6.0; the codebase reached v0.6.50 still carrying it). Retired in
+  full: removed from `avatar.yaml`, the `static properties` map + `displayName`
+  fallback + the one-shot deprecation `console.warn` + the `#nameWarned` flag in
+  `avatar.class.js`, the `name: string` typing in `avatar.d.ts`, and the
+  regenerated `avatar.a2ui.json` sidecar. The `<img>` `alt` now derives from
+  `displayName` (= `text`). **Migration:** `<avatar-ui name="Ada">` →
+  `<avatar-ui text="Ada">`. No in-repo markup, demo, or corpus chunk used the
+  alias (the corpus was swept long ago; the one stray demo was fixed in
+  `d3b482c61`). _Pre-1.0 breaking change — bump MINOR on the next cut._
+
+### Removed (BREAKING) — `<chart-ui>` `aspect` + `heading` retired (OD-CHART-02)
+
+- **`<chart-ui>` no longer accepts `aspect` or `heading`** — both were
+  deprecated-but-functional with no removal date; retired across yaml + class.js +
+  d.ts + css + sidecar.
+  - **`aspect`** (`std`/`wide`/`square`/`tall` — derived the chart's implicit
+    height from width): charts without an explicit height now always use the
+    standard 4:3 ratio (the prior default, so default charts are unchanged; only
+    explicit `aspect="wide|square|tall"` changes). **Migration:** size the chart
+    via its parent (width/height on the enclosing card/container).
+  - **`heading`** (rendered a title element + fed `aria-label`): **Migration:** put
+    the visual title in an enclosing `card-ui` `<header><span slot="heading">`; for
+    a descriptive accessible name set `aria-label` directly. With neither,
+    `aria-label` now falls back to `"<type> chart"` (e.g. "bar chart"). Verified:
+    69 demo charts render, 0 console errors. _Pre-1.0 breaking — bump MINOR._
+
+### Removed — `<avatar-ui size>` long-form aliases (were non-functional)
+
+- **`<avatar-ui size>` drops `small`/`medium`/`large`/`xlarge`** — use the
+  canonical `xs`/`sm`/`md`/`lg`/`xl`. These were declared in `avatar.yaml` +
+  `avatar.d.ts` "for back-compat" but had **no CSS implementation** (`avatar.css`
+  only defines `:scope[size="xs|sm|md|lg|xl"]`), so `size="small"` silently
+  rendered at the base default size — they never worked. Runtime behavior is
+  unchanged; this removes the misleading values from the typed API + the sidecar
+  the LLM prompt builder reads (training-data noise). No in-repo markup used them.
+
+### Changed — global styles assigned to `@layer` cascade layers (ADR-0038)
+
+- `packages/web-components/styles/` now assigns every rule to a named cascade layer — `@layer reset, tokens, elements, components, utilities, context, overrides` — so precedence is **declared once** instead of faked per-rule via specificity/`:where()`. The published bundle + barrel carry the layers; **rule content is unchanged** — only layer membership. Cuts: `resets.css` → `reset`; `colors/` + `foundation/` → `tokens`; `type/elements.css` → `elements`; the 128 scoped components → `components`; `api/{sizing,text,layout}` + `[variant]` → `utilities`; `themes.css` + `prose.css` → `context`; `overrides` declared topmost and **reserved (empty)** for consumer rules. A consumer rule in `@layer overrides` now wins by layer order with no `!important` and no specificity war (proven: a `(0,0,1)` `badge-ui{font-weight:321}` override beats both the component's `@scope` 500 and a `[weight="bold"]` 700).
+- **One intentional behavior change (IPC-04).** Utility attributes — `[weight]` `[color]` `[transform]` `[text-align]` `[variant]` — now **override** a component's own `@scope` rule (they sit in `utilities`, above `components`). Previously they lost to component `@scope` by scope-proximity, and api/text.css documented that limitation — now retired. Measured blast radius: **39 component×property honorings across 128 components** (25 `color`, 10 `font-weight`, 3 `text-align`, 1 `text-transform`), zero breakage. Every *other* cut is behavior-neutral (real-browser computed-style probe 0 diffs; token identity byte-identical). The `ul/ol[role="list"]` reset and the `h1–h6` role defaults were relocated into `type/elements.css` (element-default refinements that must win by specificity *within* the `elements` layer). See ADR-0038 + `docs/specs/cascade-layer-architecture.md`.
+
+### Added — `<select-ui>` per-option `icon` / `avatar`, reflected in the trigger
+
+- **`components/select/{select.class.js,select.css,select.yaml}`** — `<option>` now accepts `icon` (Phosphor name) and `avatar` (image URL): `<option value="light" icon="sun">`. Each option renders its glyph in the listbox row **and** the trigger reflects the **selected** option's icon/avatar (theme pickers, assignee/account switchers). Previously a host-level `[icon]` was static — selecting "Light" still showed the fixed `moon`. `#parseOptions` now captures `icon`/`avatar` from declarative `<option>`/`<optgroup>` children (and the `.options` array shape gains `icon?`/`avatar?`); a new `#syncLeading()` reconciles the trigger's `[slot="leading"]` to the selected option on every render (avatar beats icon; host `[icon]`/`[avatar]` is the fallback). Only manages the component-stamped trigger (`[data-select-leading]`) — a consumer-custom trigger owns its own leading. Multi-select is unaffected (chips). +CSS for `[role="option"] img[data-option-avatar]`; sidecar regenerated. Verified in-browser: trigger shows `sun` for selected "Light", updates to `moon` on selecting "Dark"; per-option avatars render in trigger + rows; 21/21 unit tests green.
+
+### Changed — block-level display by default + universal `[inline]` attribute (ADR-0037)
+
+- Composite / control / container primitives now default to a **block-level** host `display` (`flex`/`block`/`grid`); the new universal **`[inline]`** boolean opts back to inline-level (`inline-flex`/`inline-block`/`inline-grid`). Flipped 14 primitives: `button` (text → full-width block, icon-only held inline via `:not([text])`), `color-input`, `date-range-picker`, `datetime-picker`, `time-picker`, `breadcrumb`, `pagination`, `segmented`, `toggle-group`, `toggle-scheme`, `menu`, `popover`, `image`, `qr-code`. **Text-flow atoms stay inline** (`text` `link` `mark` `number-format` `relative-time` `inline-edit` `inline-message` `badge` `tag` `chip` `kbd` `icon` `radio` `check` `switch` `avatar` `swatch` `rating` `spinner`). CSS-only — per-component `:scope[inline]` (specificity 0,2,0 reliably overrides `:scope`); no yaml/JS/sidecar (universal-attribute precedent: `[grow]`/`[hidden]`). **Inside `row-ui`/`col-ui`/`grid-ui` the flip is a no-op** (flex/grid items are blockified), so real-composition rendering is unchanged — only standalone-in-block-flow goes full-width. `field`/`fields` carve out `[inline]` for their single-row *layout* mode. `api/layout.css` documents the per-component rationale. See ADR-0037 + `docs/specs/attribute-api-system.md` §5.
+
+### Changed — `chevron` → `caret` terminology sweep (FEEDBACK-90, ADR-0036 follow-up)
+
+- Renamed residual `chevron` terminology to `caret` across 14 component files so the codebase carries one vocabulary (matching the `slot="caret"` convention + the Phosphor `caret-*` icon names). **`agent-artifact`** is the only behavioral surface: `[data-artifact-chevron]` → `[data-artifact-caret]` + `#chevronEl` → `#caretEl` (internal-render collapse indicator — a data-attr styling hook, not a slot, same as `agent-trace`/`agent-reasoning`). The rest is comment/description terminology (`timeline`; `table`/`select` yaml + regenerated a2ui descriptions; `input`/`pagination`/`action-list`/`calendar-grid`/`calendar-picker` comments). **Carve-out:** kept breadcrumb's `data-chunk="…-chevron-sep"` corpus identifier — the separator is semantically a chevron, not a disclosure caret, and renaming a harvested chunk name is a separate re-harvest. No consumer-facing behavior change.
+
+### Fixed — form-field demos collapsed to content-width in `<preview-ui>` (demos)
+
+- **`components/preview/preview.css`** — a `<field-ui>` (and bare text-field controls) is a flex item in the render cell, so form-field demos sized to their content — a placeholder-only `combobox-ui` shrank to a ~52px "Sel…" stub (input/select were also content-width, just less obvious). The render cell now stretches `field-ui` + text-field controls (`input-ui`/`select-ui`/`combobox-ui`/`textarea-ui`/`tags-input-ui`/`color-input-ui`) to the cell width, capped at `28rem` so single-block stages don't sprawl. Lifts **every** form-field demo to a realistic width at once (combobox 52→202px rows / 448px single-block); non-form demos (buttons, badges, …) keep content-width. Verified 0 console errors across 12 component + pattern pages.
+
+### Fixed — `<combobox-ui>` `[size]` didn't step the field height
+
+- **`components/combobox/combobox.css`** — the editable `[data-input]` span picked up `8px` block padding from an outer source that out-cascaded the `@scope` rule, pinning the field to ~36px at **every** `[size]` (sm/md/lg measured 36.2 / 37.6 / 39px — barely distinguishable). A higher-specificity guard (`combobox-ui [data-field] [data-input] { padding-block: 0 }`) zeroes it so the field height tracks `--a-size` like `input-ui`/`select-ui` — now **24 / 30 / 36px** for sm/md/lg. (The 8px source isn't in combobox/global/inline CSS — likely a leaked reset or a `contenteditable="plaintext-only"` behavior; flagged for a follow-up audit.)
+
+### Added — `<combobox-ui>` demo depth (demos)
+
+- **`components/combobox/combobox.examples.html`** — +5 attribute sections closing the depth gap surfaced by the demo-coverage audit (was ~7/17 demonstrable attributes): `prefix`/`suffix` slot (search-icon prefix), `highlight-match`, `loading`, `disabled`, `readonly`. All render correctly now that the width fix above is in place (the prefix demo had appeared collapsed only because of the content-width bug).
+
+### Fixed — `<alert-ui>` `slot="action"` rendered wedged between icon and message
+
+- **`components/alert/alert.css`** — a trailing `[slot="action"]` button rendered on the **left** (between the leading icon and the message) instead of trailing right, contradicting the documented "right-aligned trailing affordance." Cause: `alert.js` appends the auto-stamped `[slot="content"]`/`[slot="leading"]` *after* any author-provided action button, and the standard render path (unlike the dunning path) gave the action/close slots no `order`, so they sorted in DOM order. Added explicit `order: 1` (action) + `order: 2` (close) so the layout is always `icon → content → action → close`, with content's `flex: 1` pushing both affordances to the trailing edge. Latent since the feature shipped — first exercised by the new demo (no prior `alert-ui` consumer used `slot="action"`). Verified via DOM geometry probe (`iconX < contentX < actionX ≤ closeX`).
+
+### Fixed — `<alert-ui>` dunning `due-at` showed the previous calendar day
+
+- **`components/alert/alert.class.js`** — `#formatDueDate()` parsed a date-only ISO string (`"2026-05-20"`) as UTC midnight, which a behind-UTC locale then formatted as the *previous* day ("May 19"). Date-only strings are now pinned to local midnight (`"…T00:00:00"`) so the authored calendar day is preserved; full timestamps (with time/offset) keep their exact instant. Invisible in jsdom (UTC) — only manifested in a real browser, so the lenient existing tests (`/May/`, `/2026/`) stayed green (30/30); also corrects the shared `billing-overview` dunning banner.
+
+### Added — `<alert-ui>` demo depth (demos)
+
+- **`components/alert/alert.examples.html`** — +3 sections taking attribute coverage 33% → **100%** (demo-coverage audit): `title`+`description` (two-line headline/body), `action slot` (trailing button), and the full `dunning` payment-failed pattern (SPEC-006 — `pattern`/`amount`/`currency`/`due-at`/`card-last4`/`reason` across all four reasons + a warning grace-period), plus the `dismissible` alias. Props/Events/Slots tables extended to document the dunning API (`actions` slot, `dunning-action` event). Grounded against SPEC-006 + the real `billing-overview` consumer; surfaced the two `alert-ui` fixes above.
+
+### Fixed — `<switch-ui>` `[hint]` rendered beside the label instead of below
+
+- **`components/switch/switch.css`** — the `[hint]` caption is documented (yaml + props table + the rule's own comment "Caption beneath the toggle row") as rendering BELOW the label, but the base `inline-flex` row laid the stamped `[slot="hint"]` out as a third inline item beside the label. A `:has([slot="hint"])`-scoped `flex-wrap` + `flex-basis: 100%` now wraps the hint onto its own full-width line, indented under the label. No display-model change (stays `inline-flex`); hint-less switches are 100% unchanged (the hint span is stamped only when `[hint]` is set). Latent since §184 — surfaced by the demo-depth pass.
+
+### Fixed — `<list-ui>` `[selectable]` selection chrome was never applied (upgrade race)
+
+- **`components/list/list.class.js`** — `selectable` + `selected-key` set no visual selection (`aria-selected` null on every row). Light-DOM upgrade race: `render()`'s `#items()` filtered children by `role="listitem"`, but each `<list-item-ui>` sets that role in its OWN `connected()`, which hasn't run when the parent first `render()`s → `#items()` returned `[]` → `aria-selected` never stamped → the `[aria-selected="true"]` selection CSS never matched. `#items()` now also matches by tag name (`LIST-ITEM-UI`, present pre-upgrade); the attribute persists through the child's later upgrade. Latent since the selection feature shipped (no demo exercised it); +0 test changes, 5/5 green.
+
+### Added — primitive demo-depth wave, Phase 3 (demos)
+
+- Drove six audit-`critical` primitives to full attribute coverage (demo-coverage audit), each authored from source/spec grounding and browser-probed (0 console errors, visual QA): **`swatch`** 27% → 100% (detail/copyable/copy-value, badge gamut pips, selectable/selected, label-position overlay + auto-contrast); **`color-picker`** 44% → 100% (OKLCH generation constraints — max-chroma / min-l·max-l / base-hue·hue-drift-max — plus corrected the `format` demo to the real `[hex, oklch]` enum and dropped a non-existent `required` prop from its table); **`switch`** 43% → 100% (hint, name/value/required); **`list`** 40% → 100% (contained, selectable/selected-key, + real `selection-change` event docs); **`context-menu`** 33% → 100% (open, long-press-ms); **`toggle-scheme`** 33% → 92% (scoped `target` + icon/label-light/dark + color + storage-prefix; the read-only reflected `active-scheme` is intentionally not authored, + corrected two table defaults vs yaml). Demo-only `examples.html` changes except the two `switch`/`list` fixes above.
+
+## [0.6.50] — 2026-05-30
+
+### Changed — `slot="caret"` disclosure-indicator convention + FEEDBACK-89 (ADR-0036)
+
+- **`components/tree/` (`tree-item-ui`) + `components/pane/` (`pane-ui`)** — renamed the expand/collapse indicator slot `slot="chevron"` → **`slot="caret"`** (and tokens `--*-chevron-*` → `--*-caret-*`, e.g. `--tree-caret-size`, `--pane-caret-fg`), standardizing on the slot name already used by `accordion-item-ui` / `nav-group-ui` / `select-ui` and matching the Phosphor `caret-*` icon vocabulary. **No backward-compat alias** (hard rename; the caret is auto-stamped, so blast radius is small). See [ADR-0036](../../.brain/adrs/0036-caret-slot-disclosure-convention.md).
+- **`tree-item-ui` adopt-or-stamp (FEEDBACK-89)** — `#stamp()` now adopts a consumer's declarative `slot="caret"` and `slot="actions"` children into the auto-stamped row instead of leaving them as siblings below it. A `<button-ui slot="actions">` (the natural way to add a per-row action — add / rename / overflow) now lands inline in the styled, hover-revealed actions area. The host `#onClick` already excludes `[slot="actions"] *` from row selection, so adoption is click-safe. +3 unit tests.
+- **`dist/` CDN bundles** (`web-components.min.css` + `web-components.min.js`) regenerated to carry the renamed `--*-caret-*` tokens + caret stamp logic.
+
 ## [0.6.49] — 2026-05-30
 
 ### Changed — card-ui header slot sweep + `nav-group-ui` fixes (demos)

package/components/action-list/action-list.css

@@ -98,7 +98,7 @@ action-item-ui:hover [slot="icon"] {
     text-overflow: ellipsis;
   }
 
-  /* Default slot (trailing content: kbd, badge, chevron) pushed to far right */
+  /* Default slot (trailing content: kbd, badge, caret) pushed to far right */
   & > :not([slot="icon"]):not([slot="text"]) {
     flex-shrink: 0;
     margin-inline-start: auto;

package/components/agent-artifact/agent-artifact.class.js

@@ -58,7 +58,7 @@ export class UIAgentArtifact extends UIElement {
     tone:      { type: String,  default: 'neutral', reflect: true },
   };
 
-  // §205 (v0.5.7): dynamic chevron icons stamped on collapse/expand state
+  // §205 (v0.5.7): dynamic caret icons stamped on collapse/expand state
   // transition (agent-artifact.class.js:119+188). Per FEEDBACK-16 §1 + §209 slot-11 ternary-
   // walker discovery. Note: `this.icon` consumer-supplied — not declared here.
   static requiredIcons = ['caret-right', 'caret-down'];
@@ -69,7 +69,7 @@ export class UIAgentArtifact extends UIElement {
   #iconEl = null;
   #titleEl = null;
   #kindEl = null;
-  #chevronEl = null;
+  #caretEl = null;
   #bodyEl = null;
 
   connected() {
@@ -80,7 +80,7 @@ export class UIAgentArtifact extends UIElement {
     this.#headerEl?.removeEventListener('click', this.#onHeaderClick);
     this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
     this.#headerEl = this.#iconEl = this.#titleEl = null;
-    this.#kindEl = this.#chevronEl = this.#bodyEl = null;
+    this.#kindEl = this.#caretEl = this.#bodyEl = null;
   }
 
   #onHeaderClick = (e) => {
@@ -120,8 +120,8 @@ export class UIAgentArtifact extends UIElement {
       this.#kindEl.setAttribute('variant', TONE_TO_BADGE_VARIANT[this.tone] || 'default');
       this.#kindEl.hidden = !this.kind;
     }
-    if (this.#chevronEl) {
-      this.#chevronEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
+    if (this.#caretEl) {
+      this.#caretEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
     }
     if (this.#bodyEl) {
       this.#bodyEl.hidden = this.collapsed;
@@ -187,12 +187,12 @@ export class UIAgentArtifact extends UIElement {
     for (const btn of secondaryBtns) actions.appendChild(btn);
     for (const btn of primaryBtns) actions.appendChild(btn);
 
-    this.#chevronEl = document.createElement('icon-ui');
-    this.#chevronEl.setAttribute('color', 'muted');
-    this.#chevronEl.setAttribute('data-artifact-chevron', '');
-    this.#chevronEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
+    this.#caretEl = document.createElement('icon-ui');
+    this.#caretEl.setAttribute('color', 'muted');
+    this.#caretEl.setAttribute('data-artifact-caret', '');
+    this.#caretEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
 
-    this.#headerEl.append(this.#iconEl, this.#titleEl, this.#kindEl, actions, this.#chevronEl);
+    this.#headerEl.append(this.#iconEl, this.#titleEl, this.#kindEl, actions, this.#caretEl);
 
     // Body
     this.#bodyEl = document.createElement('div');

package/components/agent-artifact/agent-artifact.css

@@ -89,7 +89,7 @@
     flex-shrink: 0;
   }
 
-  [data-artifact-chevron] {
+  [data-artifact-caret] {
     flex-shrink: 0;
     transition: transform var(--agent-artifact-duration, var(--agent-artifact-duration-default));
   }

package/components/agent-reasoning/agent-reasoning.class.js

@@ -105,6 +105,8 @@ export class UIAgentReasoning extends UIElement {
   #summaryEl = null;
   #bodyEl = null;
   #bound = false;
+  #resizeObserver = null;
+  #spineRaf = 0;
 
   get entries() { return this.#entries; }
 
@@ -114,6 +116,19 @@ export class UIAgentReasoning extends UIElement {
     this.#startTime = Date.now();
     this.#timerInterval = setInterval(() => this.#tickTimers(), 1000);
     this.#buildShell();
+    // Re-measure the connector spine when row heights shift (text reflow on
+    // resize moves the dot Ys). The spine writes only absolutely-positioned
+    // ::before vars, so observing the host can't feed back into a resize loop.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObserver = new ResizeObserver(() => {
+        if (this.#spineRaf) return;
+        this.#spineRaf = requestAnimationFrame(() => {
+          this.#spineRaf = 0;
+          this.#layoutSpine();
+        });
+      });
+      this.#resizeObserver.observe(this);
+    }
   }
 
   // Single delegated handler for every nested timeline-item's toggle event.
@@ -136,6 +151,12 @@ export class UIAgentReasoning extends UIElement {
       clearTimeout(this.#finishTimer);
       this.#finishTimer = null;
     }
+    if (this.#spineRaf) {
+      cancelAnimationFrame(this.#spineRaf);
+      this.#spineRaf = 0;
+    }
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
     this.#summaryEl?.removeEventListener('click', this.#onSummaryClick);
     this.#summaryEl?.removeEventListener('keydown', this.#onSummaryKey);
     this.#bodyEl?.removeEventListener('timeline-toggle', this.#onStepToggle);
@@ -379,7 +400,7 @@ export class UIAgentReasoning extends UIElement {
       <span data-reasoning-meta>
         ${total ? `<span data-reasoning-counter>${done}/${total}</span>` : ''}
         <span data-reasoning-time>${elapsed}s</span>
-        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-chevron></icon-ui>
+        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-caret></icon-ui>
       </span>
     `;
 
@@ -404,6 +425,36 @@ export class UIAgentReasoning extends UIElement {
         this.#bodyEl.appendChild(this.#renderNonStep(entry));
       }
     }
+
+    this.#layoutSpine();
+  }
+
+  // Draw one continuous connector line down the marker column from the first
+  // step dot to the last — bridging plan / thought / iteration interstitials
+  // that otherwise fragment the per-block timeline connectors into stubs. The
+  // endpoints are measured (not pure CSS) because interstitial row heights are
+  // dynamic; the per-item connectors are suppressed in CSS (the spine owns the
+  // line). No spine for 0–1 dots (nothing to connect → no trailing line).
+  #layoutSpine() {
+    const body = this.#bodyEl;
+    if (!body) return;
+    if (this.collapsed) { body.removeAttribute('data-spine'); return; }
+    const items = body.querySelectorAll('timeline-item-ui');
+    if (items.length < 2) { body.removeAttribute('data-spine'); return; }
+
+    const bodyTop = body.getBoundingClientRect().top;
+    // Dot center within an item = top:(1.4em − dot)/2 + 1px + dot/2 = 0.7em + 1px
+    // (the dot size cancels), where em is the item's computed font-size.
+    const dotY = (el) => {
+      const r = el.getBoundingClientRect();
+      const fs = parseFloat(getComputedStyle(el).fontSize) || 14;
+      return (r.top - bodyTop) + 0.7 * fs + 1;
+    };
+    const top = dotY(items[0]);
+    const height = Math.max(0, dotY(items[items.length - 1]) - top);
+    body.style.setProperty('--reasoning-spine-top', `${Math.round(top)}px`);
+    body.style.setProperty('--reasoning-spine-h', `${Math.round(height)}px`);
+    body.setAttribute('data-spine', '');
   }
 
   #makeTimeline() {

package/components/agent-reasoning/agent-reasoning.css

@@ -122,35 +122,56 @@
     grid-template-columns: subgrid;
     grid-column: 1 / -1;
     row-gap: var(--agent-reasoning-gap-row, var(--agent-reasoning-gap-row-default));
+    position: relative;
   }
 
   [data-reasoning-body][hidden] { display: none; }
 
+  /* ═══════ Connector spine ═══════
+     A single continuous line down the marker column from the first step dot to
+     the last, bridging plan / thought / iteration interstitials so the run
+     reads as one timeline rather than fragmented per-block stubs. Endpoints are
+     JS-measured into --reasoning-spine-top / -h (#layoutSpine) — interstitial
+     heights are dynamic, so pure CSS can't place them. The x matches the step
+     dot center (timeline-item uses var(--timeline-marker-w, 1.25rem) for its
+     dot math). Sits behind the dots (z-index 0 < the dots' z-index 1). The
+     per-item timeline connectors are suppressed below so they don't double-draw. */
+  [data-reasoning-body][data-spine]::before {
+    content: '';
+    position: absolute;
+    left: calc(var(--timeline-marker-w, 1.25rem) / 2 - var(--agent-reasoning-line-w, 1.5px) / 2);
+    top: var(--reasoning-spine-top, 0);
+    height: var(--reasoning-spine-h, 0);
+    width: var(--agent-reasoning-line-w, 1.5px);
+    background: var(--agent-reasoning-border, var(--agent-reasoning-border-default));
+    z-index: 0;
+  }
+
   /* All direct children of body span the grid */
   [data-reasoning-body] > * {
     grid-column: 1 / -1;
   }
 
+  /* Step rows + their readouts use the mono family — a technical step trace
+     (generate:/validate:/…) reads better fixed-width, matching the reference.
+     The iteration header ([data-reasoning-iter-n]) keeps the UI sans font. */
+  [data-reasoning-body] timeline-item-ui {
+    font-family: var(--a-font-family-code);
+  }
+
   /* ═══════ Thought — horizontal dash in marker column, text in content ═══════ */
 
+  /* Thoughts are free-form annotations beside the spine — text in the content
+     column, no marker dot/dash (the continuous spine passes behind them). */
   [data-reasoning-thought] {
     display: grid;
     grid-template-columns: subgrid;
     align-items: center;
     line-height: 1.5;
-    color: var(--agent-reasoning-fg, var(--agent-reasoning-fg-default));
+    color: var(--agent-reasoning-fg-muted, var(--agent-reasoning-fg-muted-default));
     animation: _ar-fade var(--agent-reasoning-duration, var(--agent-reasoning-duration-default)) var(--agent-reasoning-easing, var(--agent-reasoning-easing-default));
   }
 
-  [data-reasoning-thought]::before {
-    content: '';
-    grid-column: marker;
-    height: 1px;
-    background: var(--agent-reasoning-border, var(--agent-reasoning-border-default));
-    align-self: center;
-    width: 100%;
-  }
-
   [data-reasoning-thought] > [data-reasoning-thought-text] {
     grid-column: content / -1;
     min-width: 0;
@@ -159,15 +180,15 @@
 
   /* ═══════ Plan — card in content+aside, marker empty ═══════ */
 
+  /* Plan reads as a flat up-front checklist in the content column — no bordered
+     box (that competed with the now-flattened iteration sections, the original
+     bug-03 "inconsistent card hierarchy" complaint). The PLAN label + ordered
+     list carry the distinction; the spine passes down its left. */
   [data-reasoning-plan] {
     grid-column: content / -1;
     display: flex;
     flex-direction: column;
     gap: var(--a-space-1);
-    padding: var(--a-space-2) var(--a-space-3);
-    border: 1px solid var(--agent-reasoning-border, var(--agent-reasoning-border-default));
-    border-radius: var(--agent-reasoning-radius, var(--agent-reasoning-radius-default));
-    background: var(--agent-reasoning-iter-bg, var(--agent-reasoning-iter-bg-default));
   }
 
   [data-reasoning-plan-label] {
@@ -191,6 +212,10 @@
 
   /* ═══════ Iteration — card with its own grid ═══════ */
 
+  /* Iterations read as continuous timeline sections (a status-icon header row
+     + its nested steps tied by the timeline connector), NOT as bordered cards
+     that compete with the PLAN block. Flattened: no border / no fill / no box
+     padding — just the grid + row rhythm. (bug-03) */
   [data-reasoning-iteration] {
     display: grid;
     grid-template-columns:
@@ -199,14 +224,6 @@
       [aside] auto;
     column-gap: var(--agent-reasoning-gap-col, var(--agent-reasoning-gap-col-default));
     row-gap: var(--a-space-2);
-    padding: var(--agent-reasoning-iter-padding, var(--agent-reasoning-iter-padding-default));
-    border: 1px solid var(--agent-reasoning-iter-border, var(--agent-reasoning-iter-border-default));
-    border-radius: var(--agent-reasoning-radius, var(--agent-reasoning-radius-default));
-    background: var(--agent-reasoning-iter-bg, var(--agent-reasoning-iter-bg-default));
-  }
-
-  [data-reasoning-iteration][data-active] {
-    background: var(--agent-reasoning-iter-bg-active, var(--agent-reasoning-iter-bg-active-default));
   }
 
   [data-reasoning-iter-header] {
@@ -282,3 +299,13 @@
     [data-reasoning-spinner] { animation: none; }
   }
 }
+
+/* ═══════ Suppress timeline's own per-row connector inside agent-reasoning ═══════
+   The continuous body spine (see [data-reasoning-body][data-spine]::before)
+   owns the connector here; timeline-item's own ::after would double-draw and
+   fragment at every block boundary (each timeline-ui block stamps data-last on
+   its own last item, dropping that segment mid-run). This lives OUTSIDE @scope
+   and carries [data-step-id] (stamped on every step by #makeStepItem) to clear
+   timeline.css's :scope::after specificity ([0,1,1] → this is [0,1,3]). The
+   step dots (::before) are untouched. */
+agent-reasoning-ui timeline-item-ui[data-step-id]::after { display: none; }

package/components/agent-trace/agent-trace.css

@@ -27,7 +27,7 @@
     --agent-trace-detail-label-col-default: 9rem;
 
     /* ── Motion ── */
-    --agent-trace-chevron-dur-default:   var(--a-duration-fast);
+    --agent-trace-caret-dur-default:   var(--a-duration-fast);
   }
 
   :scope {
@@ -50,7 +50,7 @@
     border-radius: var(--a-radius-sm);
     padding: var(--a-space-0-5) var(--a-space-1);
     margin: calc(var(--a-space-0-5) * -1) calc(var(--a-space-1) * -1);
-    transition: background var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: background var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
   [data-trace-root] > summary:hover {
@@ -94,12 +94,12 @@
     margin-inline: 2px;
   }
 
-  [data-trace-chevron] {
+  [data-trace-caret] {
     flex-shrink: 0;
-    transition: transform var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: transform var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
-  [data-trace-root][open] [data-trace-chevron] {
+  [data-trace-root][open] [data-trace-caret] {
     transform: rotate(90deg);
   }
 
@@ -225,20 +225,20 @@
     text-align: end;
   }
 
-  /* Chevron in the trailing column */
-  [data-trace-row-chevron] {
+  /* Caret in the trailing column */
+  [data-trace-row-caret] {
     --a-icon-size: 0.875em;
     justify-self: end;
     align-self: center;
-    transition: transform var(--a-duration-fast) var(--agent-trace-chevron-dur, var(--a-duration-fast));
+    transition: transform var(--a-duration-fast) var(--agent-trace-caret-dur, var(--a-duration-fast));
     color: var(--agent-trace-fg-muted, var(--agent-trace-fg-muted-default));
   }
 
-  details[data-trace-row][open] > summary > [data-trace-row-chevron] {
+  details[data-trace-row][open] > summary > [data-trace-row-caret] {
     transform: rotate(90deg);
   }
 
-  [data-trace-row-chevron-spacer] {
+  [data-trace-row-caret-spacer] {
     width: 0.875em;
     justify-self: end;
   }

package/components/agent-trace/agent-trace.js

@@ -128,7 +128,7 @@ class UIAgentTrace extends UIElement {
     this.#rootEl.innerHTML = `
       <summary>
         <span data-trace-status>${pillsHTML}</span>
-        <icon-ui name="caret-right" color="muted" size="sm" data-trace-chevron></icon-ui>
+        <icon-ui name="caret-right" color="muted" size="sm" data-trace-caret></icon-ui>
       </summary>
       <div data-trace-body>
         ${this.#metrics.length ? `<div data-trace-rows${hasAnyDetails ? ' data-has-details' : ''}>${headerRow}${rowsHTML}</div>` : ''}
@@ -156,8 +156,8 @@ class UIAgentTrace extends UIElement {
       <span data-trace-aux>${aux}</span>
       ${hasAnyDetails
         ? (hasDetails
-            ? '<icon-ui name="caret-right" color="muted" data-trace-row-chevron></icon-ui>'
-            : '<span data-trace-row-chevron-spacer aria-hidden="true"></span>')
+            ? '<icon-ui name="caret-right" color="muted" data-trace-row-caret></icon-ui>'
+            : '<span data-trace-row-caret-spacer aria-hidden="true"></span>')
         : ''}
     `;
 

package/components/alert/alert.class.js

@@ -331,7 +331,14 @@ export class UIAlert extends UIElement {
 
   #formatDueDate() {
     if (!this.dueAt) return '';
-    const d = new Date(this.dueAt);
+    // A date-only ISO string ("2026-05-20") parses as UTC midnight, which a
+    // behind-UTC locale then formats as the PREVIOUS calendar day. Consumers
+    // author these as plain calendar dates, so pin them to local midnight to
+    // preserve the authored day. Full timestamps (with time / offset) keep
+    // their exact instant.
+    const d = /^\d{4}-\d{2}-\d{2}$/.test(this.dueAt)
+      ? new Date(`${this.dueAt}T00:00:00`)
+      : new Date(this.dueAt);
     if (Number.isNaN(d.getTime())) return '';
     try {
       const lang = this.getAttribute('lang') || this.lang || undefined;

package/components/alert/alert.css

@@ -107,10 +107,18 @@
 
   /* Trailing action area — optional single button or small button group.
      flex-shrink:0 keeps it from collapsing; align-self:start anchors it
-     to the first text line under the `align-items:start` root. */
+     to the first text line under the `align-items:start` root.
+     `order: 1` sorts it AFTER the content slot regardless of DOM order:
+     alert.js appends the auto-stamped [slot="content"] / [slot="leading"]
+     *after* any author-provided [slot="action"], so without an explicit
+     order the action button renders wedged between the icon and the
+     message instead of trailing. content's `flex: 1` then pushes the
+     action (+ close) to the right edge. Mirrors the dunning path, which
+     already assigns explicit per-slot order integers. */
   :scope [slot="action"] {
     flex-shrink: 0;
     align-self: start;
+    order: 1;
   }
 
   /* Close button is a `<button-ui icon="x" variant="ghost" size="sm">`
@@ -123,6 +131,10 @@
      rather than disconnected grey. */
   :scope [slot="close"] {
     flex-shrink: 0;
+    /* Sort last (after content order:0 and action order:1) so the dismiss
+       button is the right-most affordance. content's flex:1 pushes both
+       action + close to the trailing edge. */
+    order: 2;
     min-height: calc(var(--alert-font, var(--alert-font-default)) * var(--alert-line-height, var(--alert-line-height-default)));
     --button-fg-ghost: var(--alert-fg, var(--alert-fg-default));
     --button-fg-ghost-hover: var(--alert-icon-fg, var(--alert-icon-fg-default));

package/components/avatar/avatar.a2ui.json

@@ -21,14 +21,6 @@
       "type": "string",
       "default": ""
     },
-    "name": {
-      "description": "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead.",
-      "type": "string",
-      "default": "",
-      "deprecated": true,
-      "deprecated_reason": "Use `text` instead. Will be removed in v0.6.0.",
-      "deprecated_since": "0.4.x"
-    },
     "shape": {
       "description": "Avatar shape",
       "type": "string",
@@ -39,18 +31,14 @@
       "default": "circle"
     },
     "size": {
-      "description": "Avatar size. Canonical scale (xs/sm/md/lg/xl); long-form aliases (small/medium/large/xlarge) accepted for back-compat.",
+      "description": "Avatar size — canonical scale.",
       "type": "string",
       "enum": [
         "xs",
         "sm",
         "md",
         "lg",
-        "xl",
-        "small",
-        "medium",
-        "large",
-        "xlarge"
+        "xl"
       ],
       "default": "md"
     },