@adia-ai/web-components 0.8.40 → 0.8.42

package/components/list/list.class.js

@@ -28,7 +28,9 @@
  * When `selectable`:
  *   - Children (role="listitem") become keyboard-focusable via roving tabindex.
  *   - Click selects the child; key is its id or data-key.
- *   - aria-selected is set on all children.
+ *   - [selected] (ADR-0056, #1363 B7) and aria-selected are both set on
+ *     all children — [selected] is the declared API state, aria-selected
+ *     is wiring.
  *   - Fires `selection-change` with { key, previousKey }.
  */
 
@@ -73,6 +75,7 @@ export class UIList extends UIElement {
       // (patient-visit rail's roving tabindex, gh#746).
       if (this.#stampedSelection) {
         for (const ch of this.#items()) {
+          ch.removeAttribute('selected');
           ch.removeAttribute('aria-selected');
           ch.removeAttribute('tabindex');
         }
@@ -87,6 +90,11 @@ export class UIList extends UIElement {
     for (const ch of items) {
       const k = this.#keyOf(ch);
       const selected = k && k === key;
+      // [selected] (ADR-0056, #1363 B7) is the declared, reflected API
+      // surface — parent-managed, mirrors <segment-ui>. aria-selected
+      // stays as-is: ARIA is wiring, not API.
+      if (selected) ch.setAttribute('selected', '');
+      else ch.removeAttribute('selected');
       ch.setAttribute('aria-selected', selected ? 'true' : 'false');
       ch.setAttribute('tabindex', selected ? '0' : '-1');
       if (selected) focusTarget = ch;
@@ -173,6 +181,11 @@ export class UIListItem extends UIElement {
     icon:        { type: String, default: '', reflect: true },
     text:        { type: String, default: '', reflect: true },
     description: { type: String, default: '', reflect: true },
+    // ADR-0056 (gh#1303, #1363 B7): declared reflected selection-item
+    // state, parent-managed — <list-ui>[selectable] stamps this instead
+    // of leaving selection visible only via aria-selected. Mirrors
+    // <segment-ui>'s [selected].
+    selected:    { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;

package/components/list/list.css

@@ -67,7 +67,18 @@
     background: var(--a-bg-hover);
   }
 
-  :scope[selectable] > [role="listitem"][aria-selected="true"] {
+  /* [selected] is the declared, reflected state hook (ADR-0056, #1363 B7)
+     — list.class.js stamps it in lockstep with aria-selected; ARIA stays
+     wiring, not the style hook. Matched on the tag directly (not only
+     [role="listitem"]): UIList's adopt-or-stamp (gh#753) lets a
+     consumer-authored role (e.g. role="button") survive on <list-item-ui>
+     — #items() still selects/stamps it by TAG, so the style hook must
+     too, or a role-overridden selected row silently loses its selected
+     colors. The role fallback stays for non-list-item-ui children that
+     opt into role="listitem" themselves (list-ui also hosts "arbitrary
+     children", list.yaml). */
+  :scope[selectable] > list-item-ui[selected],
+  :scope[selectable] > [role="listitem"][selected] {
     background: var(--list-bg-selected);
     color: var(--list-fg-selected);
     border-inline-start-color: var(--list-border-selected);

package/components/list/list.d.ts

@@ -1,8 +1,8 @@
 /**
  * `<list-ui>` — Styled flat list with optional row dividers and icons — each row
 is a <list-item-ui> child. Selectable mode via [selectable] +
-[selectedKey] / `select` event. Composes <icon-ui> for row leading
-glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+[selectedKey] / `selection-change` event. Composes <icon-ui> for row
+leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
 <tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
 (tabular data with columns). Use list-ui for non-navigable,
 non-tabular vertical rows — comment lists, file lists, message
@@ -41,10 +41,10 @@ so content sits at the list-ui edges (canonical edge-to-edge style).
   divider: boolean;
   /** Enable selection on child listitems (roving tabindex + aria-selected). */
   selectable: boolean;
-  /** ID (or data-key) of the currently-selected child listitem. */
+  /** ID (or data-key) of the currently-selected child listitem — drives each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept as `selectedKey` rather than renamed to `value` (segmented/tabs/ select's parent-selection prop name): list rows are identified by DOM id/data-key, not an option value, and ADR-0056 itself governs only the child's own [selected] state surface, not this naming — a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up). */
   selectedKey: string;
-  /** Item spacing */
-  spacing: string;
+  /** Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset. */
+  spacing: 'sm' | 'md' | 'lg';
 
   addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
@@ -59,6 +59,8 @@ export class UIListItem extends UIElement {
   description: string;
   /** Optional leading icon name (Phosphor). */
   icon: string;
+  /** Whether this row is the current selection. Managed by the parent <list-ui>[selectable] — don't set directly; the parent's [selectedKey] is the single source of truth (ADR-0056). */
+  selected: boolean;
   /** Primary text. Renders as semibold inline body. */
   text: string;
 }

package/components/list/list.yaml

@@ -10,8 +10,8 @@ version: 1
 description: |
   Styled flat list with optional row dividers and icons — each row
   is a <list-item-ui> child. Selectable mode via [selectable] +
-  [selectedKey] / `select` event. Composes <icon-ui> for row leading
-  glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+  [selectedKey] / `selection-change` event. Composes <icon-ui> for row
+  leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
   <tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
   (tabular data with columns). Use list-ui for non-navigable,
   non-tabular vertical rows — comment lists, file lists, message
@@ -40,14 +40,22 @@ props:
     type: boolean
     default: false
   selectedKey:
-    description: ID (or data-key) of the currently-selected child listitem.
+    description: >-
+      ID (or data-key) of the currently-selected child listitem — drives
+      each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept
+      as `selectedKey` rather than renamed to `value` (segmented/tabs/
+      select's parent-selection prop name): list rows are identified by
+      DOM id/data-key, not an option value, and ADR-0056 itself governs
+      only the child's own [selected] state surface, not this naming —
+      a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up).
     type: string
     default: ""
     attribute: selected-key
   spacing:
-    description: Item spacing
+    description: Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset.
     type: string
     default: md
+    enum: [sm, md, lg]
 events:
   selection-change:
     description: "Fired on selection-change."
@@ -68,10 +76,12 @@ a2ui:
   rules:
     - rule: 'Generic vertical list container — hosts <list-item-ui> or arbitrary children.'
       reason: 'Lowest-friction list primitive.'
-    - rule: 'For interactive selection lists use <nav-ui> (single-select navigation) or <menu-ui> (action menu); list-ui is content display.'
-      reason: 'Different interaction contracts.'
+    - rule: 'list-ui supports single selection natively via [selectable] + [selectedKey] (ADR-0056, #1363 B7) — the parent stamps the matching <list-item-ui>''s [selected] + aria-selected and fires selection-change. For route-aware navigation use <nav-ui> instead; for a popover action menu use <menu-ui> instead — both have different interaction contracts than a plain selectable list.'
+      reason: 'list-ui selectable is the supported non-navigation, non-menu selection surface; nav-ui/menu-ui remain the right choice for their own contracts.'
     - rule: 'For data-grid / sortable / sticky-header needs use <table-ui> instead.'
       reason: 'Table has different semantics.'
+    - rule: 'list-ui carries no fire-and-forget "action" mode. [selectable] keeps a persisted single selection (`selectedKey` / `aria-selected`, roving tabindex); for rows that activate immediately with no persisted selection state use <action-list-ui> + <action-item-ui> instead.'
+      reason: 'Container-level decision (#1363 C5): kept separate rather than absorbed as a mode axis — stateful selection and fire-and-forget activation are genuinely different interaction contracts, and list-item-ui''s selection state is under active convergence elsewhere (#1379); rationale in gh#1374 Findings.'
 anti_patterns: []
 examples:
   - name: basic-list

package/components/list-window/list-window.a2ui.json

@@ -179,6 +179,7 @@
       "10k-rows"
     ],
     "name": "UIListWindow",
+    "parts": {},
     "related": [
       "List",
       "ListItem",

package/components/list-window/list-window.class.js

@@ -44,6 +44,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { isNode } from '../../core/dom.js';
 
 export class UIListWindow extends UIElement {
   static properties = {
@@ -616,7 +617,7 @@ export class UIListWindow extends UIElement {
       try { content = renderFn(item, index); }
       catch (err) { console.warn('[list-window-ui] render() threw:', err); }
     }
-    if (content instanceof Node) {
+    if (isNode(content)) {
       row.appendChild(content);
     } else if (content != null) {
       row.textContent = String(content);

package/components/loading-overlay/loading-overlay.a2ui.json

@@ -88,6 +88,7 @@
       "wait"
     ],
     "name": "UILoadingOverlay",
+    "parts": {},
     "related": [
       "Spinner",
       "Skeleton",

package/components/mark/mark.a2ui.json

@@ -40,7 +40,7 @@
         "wrong": "<mark>matched</mark>"
       }
     ],
-    "category": "typography",
+    "category": "display",
     "composes": [],
     "events": {},
     "examples": [
@@ -57,6 +57,7 @@
       "emphasis"
     ],
     "name": "UIMark",
+    "parts": {},
     "related": [
       "text",
       "tag"

package/components/mark/mark.yaml

@@ -3,7 +3,7 @@ name: UIMark
 tag: mark-ui
 status: stable
 component: Mark
-category: typography
+category: display
 version: 1
 description: |
   Highlighted inline text — token-driven theme-aware wrapper around the

package/components/menu/menu-divider.a2ui.json

@@ -33,6 +33,7 @@
       "menu-rule"
     ],
     "name": "UIMenuDivider",
+    "parts": {},
     "related": [
       "Menu",
       "MenuItem",

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/MenuItem.json",
   "title": "MenuItem",
-  "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.",
+  "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)",
   "type": "object",
   "allOf": [
     {
@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "description": {
+      "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`.",
+      "type": "string",
+      "default": ""
+    },
     "component": {
       "const": "MenuItem"
     },
@@ -27,7 +32,7 @@
       "default": ""
     },
     "subtitle": {
-      "description": "Optional secondary description line rendered under the label.",
+      "description": "DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)",
       "type": "string",
       "default": ""
     },
@@ -68,18 +73,20 @@
       "dropdown-item"
     ],
     "name": "UIMenuItem",
+    "parts": {},
     "related": [
       "Menu",
       "MenuDivider",
       "Button",
-      "NavItem"
+      "NavItem",
+      "ActionItem"
     ],
     "slots": {
       "icon": {
         "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
       },
       "subtitle": {
-        "description": "Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted."
+        "description": "Custom secondary-line content override; falls through to the `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063, gh#1563) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
       },
       "text": {
         "description": "Custom label content; falls through to `[text]` prop if not slotted."

package/components/menu/menu-item.yaml

@@ -13,7 +13,7 @@ component: MenuItem
 category: navigation
 version: 1
 description: |-
-  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.
+  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)
 
 props:
   icon:
@@ -25,7 +25,20 @@ props:
     type: string
     default: ""
   subtitle:
-    description: Optional secondary description line rendered under the label.
+    description: >-
+      DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same
+      type/default/rendered position; kept working as a dual-read compat
+      shim (one-time console.warn when it's the name that resolves).
+      Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface,
+      deliberately left unrenamed in this pass — see its own description.)
+    type: string
+    default: ""
+  description:
+    description: >-
+      Optional secondary description line rendered under the label.
+      Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` —
+      converges menu-item onto the ~20-component corpus majority that
+      already names this concept `description`.
     type: string
     default: ""
   value:
@@ -49,7 +62,11 @@ slots:
   text:
     description: Custom label content; falls through to `[text]` prop if not slotted.
   subtitle:
-    description: Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted.
+    description: >-
+      Custom secondary-line content override; falls through to the
+      `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063,
+      gh#1563) if not slotted. The slot's own name is unchanged by that
+      rename — this is a distinct, deliberately-unrenamed surface.
   trailing:
     description: Trailing element pinned to the far edge (shortcut hint, check mark).
 
@@ -79,6 +96,15 @@ a2ui:
       Use slot="icon" / slot="text" only when you need custom markup
       (e.g. <avatar-ui slot="icon">, <kbd slot="trailing"> shortcut
       hint).
+    - >-
+      <action-item-ui> (child of <action-list-ui>) shares this row contract
+      (icon/text/subtitle/value/variant/disabled props, icon/text/subtitle/
+      trailing slot overrides) for inline, non-popover command rows — use
+      it instead when the surface isn't a <menu-ui> popover (#1363 C5).
+      NOTE (ADR-0063, gh#1563): <menu-item-ui>'s own `subtitle` PROP is now
+      a deprecated alias for `description` — <action-item-ui> still uses
+      `subtitle` as its own primary spelling and was NOT renamed in this
+      pass (flagged as a discovered follow-up candidate, not fixed here).
 
 keywords:
   - menu-item
@@ -91,6 +117,7 @@ related:
   - MenuDivider
   - Button
   - NavItem
+  - ActionItem
 
 synonyms:
   menu-item: [dropdown-item, menu-row, popover-action]

package/components/menu/menu-label.a2ui.json

@@ -39,6 +39,7 @@
       "menu-heading"
     ],
     "name": "UIMenuLabel",
+    "parts": {},
     "related": [
       "Menu",
       "MenuItem",

package/components/menu/menu.a2ui.json

@@ -16,8 +16,8 @@
     "component": {
       "const": "Menu"
     },
-    "gap": {
-      "description": "Gap in px",
+    "offset": {
+      "description": "Pixel offset between the anchor (trigger) and the menu popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053); matches popover-ui's own `[offset]` (same anchorPopover() helper).",
       "type": "number",
       "default": 4
     },
@@ -81,6 +81,7 @@
       "right-click"
     ],
     "name": "UIMenu",
+    "parts": {},
     "related": [
       "MenuItem",
       "MenuDivider",

package/components/menu/menu.class.js

@@ -35,7 +35,7 @@ export class UIMenu extends UIElement {
   static properties = {
     open:      { type: Boolean, default: false, reflect: true },
     placement: { type: String,  default: 'bottom-start', reflect: true },
-    gap:       { type: Number,  default: 4, reflect: true },
+    offset:    { type: Number,  default: 4, reflect: true },
   };
 
   static template = () => null;
@@ -103,7 +103,7 @@ export class UIMenu extends UIElement {
     this.#anchorCleanup?.();
     this.#anchorCleanup = anchorPopover(trigger, pop, {
       placement: this.placement,
-      gap: this.gap,
+      gap: this.offset,
     });
 
     // Focus first enabled item (only when opened via keyboard).
@@ -258,7 +258,14 @@ export class UIMenuItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
+    // ADR-0063 (gh#1563) — `subtitle` is DEPRECATED (menu-item was the sole
+    // ~20-component-corpus outlier using `subtitle` where every sibling
+    // uses `description`); `description` is canonical. `subtitle` stays
+    // declared (dual-read compat, 0.8.42). The `subtitle` SLOT (a separate
+    // surface — see menu-item.yaml) is deliberately unchanged; only the
+    // PROP renames.
     subtitle: { type: String,  default: '', reflect: true },
+    description: { type: String, default: '', reflect: true },
     value:    { type: String,  default: '', reflect: true },
     variant:  { type: String,  default: 'default', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
@@ -266,12 +273,32 @@ export class UIMenuItem extends UIElement {
 
   static template = () => null;
 
+  // ADR-0063 (gh#1563) one-shot-per-class deprecation warn for [subtitle].
+  static #warnedSubtitle = false;
+
   // Set when connected() stamped role="menuitem" itself; a consumer-provided
   // role (e.g. admin-roster's role="menuitemradio", gh#616) is never touched
   // — that consumer also owns tabindex and any checked-state aria.
   #roleStamped = false;
 
   connected() {
+    // ADR-0063 (gh#1563) compat shim — resolve BEFORE #stamp() reads
+    // `this.description`, so there's no wrong-then-right flash. New-name
+    // precedence: [description] wins outright when present; only fall
+    // back to (and mirror) [subtitle] when [description] is absent.
+    if (!this.hasAttribute('description') && this.hasAttribute('subtitle')) {
+      this.description = this.subtitle;
+      if (!UIMenuItem.#warnedSubtitle) {
+        UIMenuItem.#warnedSubtitle = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[AdiaUI] <menu-item-ui [subtitle]> is deprecated — use ' +
+          '[description] instead (ADR-0063, gh#1563). Kept working as-is; ' +
+          'no behavior change.',
+        );
+      }
+    }
+
     // role="menuitem" ONLY when actually inside a menu container. A menu-ui
     // closes by moving its items back into its own light DOM (see #hide()),
     // where there is no role="menu"/menubar ancestor — a bare role="menuitem"
@@ -324,10 +351,10 @@ export class UIMenuItem extends UIElement {
       this.appendChild(span);
     }
 
-    if (this.subtitle && !this.#ownChild('[slot="subtitle"]')) {
+    if (this.description && !this.#ownChild('[slot="subtitle"]')) {
       const sub = this.#stampMark(document.createElement('span'));
       sub.setAttribute('slot', 'subtitle');
-      sub.textContent = this.subtitle;
+      sub.textContent = this.description;
       this.appendChild(sub);
     }
   }
@@ -357,15 +384,16 @@ export class UIMenuItem extends UIElement {
     const textEl = this.#ownChild('[slot="text"]');
     if (this.#wasStamped(textEl)) textEl.textContent = this.text;
 
-    // Sync subtitle — only touch elements we stamped.
+    // Sync subtitle (backed by the `description` prop — ADR-0063, gh#1563)
+    // — only touch elements we stamped.
     const subEl = this.#ownChild('[slot="subtitle"]');
-    if (this.subtitle) {
+    if (this.description) {
       if (subEl) {
-        if (this.#wasStamped(subEl)) subEl.textContent = this.subtitle;
+        if (this.#wasStamped(subEl)) subEl.textContent = this.description;
       } else {
         const el = this.#stampMark(document.createElement('span'));
         el.setAttribute('slot', 'subtitle');
-        el.textContent = this.subtitle;
+        el.textContent = this.description;
         this.appendChild(el);
       }
     } else if (this.#wasStamped(subEl)) {

package/components/menu/menu.d.ts

@@ -22,8 +22,8 @@ export interface MenuActionEventDetail {
 export type MenuActionEvent = CustomEvent<MenuActionEventDetail>;
 
 export class UIMenu extends UIElement {
-  /** Gap in px */
-  gap: number;
+  /** Pixel offset between the anchor (trigger) and the menu popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053); matches popover-ui's own `[offset]` (same anchorPopover() helper). */
+  offset: number;
   /** Controls visibility via popover API */
   open: boolean;
   /** Preferred position relative to the anchor element */
@@ -41,11 +41,13 @@ export class UIMenuDivider extends UIElement {
 }
 
 export class UIMenuItem extends UIElement {
+  /** Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`. */
+  description: string;
   /** Disabled state — blocks pointer + keyboard activation. */
   disabled: boolean;
   /** Optional leading Phosphor icon name. */
   icon: string;
-  /** Optional secondary description line rendered under the label. */
+  /** DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.) */
   subtitle: string;
   /** Item label text. */
   text: string;

package/components/menu/menu.yaml

@@ -13,8 +13,8 @@ description: Dropdown action menu with roving focus and keyboard navigation. Use
 composes:
   - icon-ui  # leading affordances on menu items (created in render)
 props:
-  gap:
-    description: Gap in px
+  offset:
+    description: Pixel offset between the anchor (trigger) and the menu popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053); matches popover-ui's own `[offset]` (same anchorPopover() helper).
     type: number
     default: 4
   open:
@@ -83,7 +83,7 @@ a2ui:
       Set [placement="top-start"] or [placement="top-end"] when the
       trigger sits near the bottom of the viewport (statusbar / footer
       menus); default [placement="bottom-start"] otherwise. Adjust
-      [gap] (default 4px) only when chrome demands it.
+      [offset] (default 4px) only when chrome demands it.
 anti_patterns: []
 examples:
   - name: basic-menu

package/components/modal/modal.a2ui.json

@@ -66,6 +66,7 @@
       "modal"
     ],
     "name": "UIModal",
+    "parts": {},
     "related": [
       "Drawer",
       "Card",

package/components/nav/nav.a2ui.json

@@ -98,6 +98,7 @@
       "links"
     ],
     "name": "UINav",
+    "parts": {},
     "related": [
       "NavGroup",
       "NavItem",

package/components/nav/nav.class.js

@@ -78,8 +78,20 @@ export class UINav extends UIElement {
     if (this.variant !== 'section') this.#updateTooltips();
   }
 
+  /**
+   * Collapsed = explicit [collapsed], or a rail narrower than 96px.
+   * linkedom (SSR — gh#1436's render sweep) has no getBoundingClientRect
+   * at all, so only the attribute can answer there. (A ZERO rect from a
+   * real pre-layout connect is the separate, unswept shape-3 question in
+   * ssr-compatibility's failure-shapes.md — not decided here.)
+   */
+  get #isCollapsed() {
+    return this.collapsed ||
+      (typeof this.getBoundingClientRect === 'function' && this.getBoundingClientRect().width <= 96);
+  }
+
   #updateTooltips() {
-    const isCollapsed = this.collapsed || this.getBoundingClientRect().width <= 96;
+    const isCollapsed = this.#isCollapsed;
     for (const group of this.querySelectorAll(':scope > nav-group-ui')) {
       const header = group.querySelector(':scope > [slot="header"]');
       if (header) header.title = isCollapsed ? group.text : '';
@@ -143,8 +155,7 @@ export class UINav extends UIElement {
 
     const group = e.target.closest('nav-group-ui');
     if (group && this.contains(group)) {
-      const isCollapsed = this.collapsed || this.getBoundingClientRect().width <= 96;
-      if (isCollapsed) {
+      if (this.#isCollapsed) {
         // The flyout popover is appended INSIDE the group, so an option
         // click bubbles here after the option's own handler has selected
         // and hidePopover()'d — re-showing would instantly reopen the

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

@@ -92,6 +92,7 @@
       "menu"
     ],
     "name": "UINavGroup",
+    "parts": {},
     "related": [
       "Nav",
       "NavItem",

package/components/nav-group/nav-group.class.js

@@ -99,7 +99,9 @@ export class UINavGroup extends UIElement {
     // whole subtree includes this host's own [selected], which render()
     // reads anyway; render() writes only the icon's [weight], which the
     // attributeFilter excludes, so the observer can't feed back.
-    if (!this.#selectionObserver) {
+    // Guarded like the other Observer sites (gh#285 §1 pattern) — SSR shims
+    // have no MutationObserver; teardown already uses `?.disconnect()`.
+    if (!this.#selectionObserver && typeof MutationObserver !== 'undefined') {
       this.#selectionObserver = new MutationObserver(this.#onChildSelection);
       this.#selectionObserver.observe(this, {
         subtree: true,

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

@@ -96,6 +96,7 @@
       "sidebar"
     ],
     "name": "UINavItem",
+    "parts": {},
     "related": [
       "Nav",
       "NavGroup",

package/components/noodles/noodles.a2ui.json

@@ -156,6 +156,7 @@
       "noodles"
     ],
     "name": "UINoodles",
+    "parts": {},
     "related": [
       "Canvas",
       "EditorCanvas"

package/components/noodles/noodles.class.js

@@ -24,6 +24,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { isElement } from '../../core/dom.js';
 
 let nextId = 0;
 
@@ -159,6 +160,9 @@ export class UINoodles extends UIElement {
 
   #scheduleUpdate() {
     if (this.#rafId) return;
+    // No rAF (SSR shim — gh#1436's render sweep) → no frame and no layout
+    // to measure connectors against; the client redraws on hydrate.
+    if (typeof requestAnimationFrame !== 'function') return;
     this.#rafId = requestAnimationFrame(() => {
       this.#rafId = null;
       this.#performUpdate();
@@ -251,7 +255,7 @@ export class UINoodles extends UIElement {
   // ── Element resolution ──────────────────────────────────────
 
   #resolveElement(ref) {
-    if (ref instanceof HTMLElement) return ref;
+    if (isElement(ref)) return ref;
     if (typeof ref === 'string') return this.querySelector(`#${CSS.escape(ref)}`);
     if (typeof ref === 'number') return this.#getPortChildren()[ref] ?? null;
     return null;

package/components/number-format/number-format.a2ui.json

@@ -143,6 +143,7 @@
       "intl"
     ],
     "name": "UINumberFormat",
+    "parts": {},
     "related": [
       "stat",
       "text",