@adia-ai/adia-ui-forge 0.8.61 → 0.8.63

package/skills/primitive-authoring/references/api-contract.md

@@ -1,4 +1,4 @@
-# API Contract — Props, Attributes, Reflection
+# API Contract, Props, Attributes, Reflection
 
 Deep dive on declaring component APIs in AdiaUI. Read this when adding a new prop whose shape doesn't match any obvious pattern in the good-citizen references.
 
@@ -17,14 +17,14 @@ static properties = {
 
 **Field rules:**
 
-- `type` — one of `String`, `Number`, `Boolean`, `Object`, `Array`. The runtime uses this to coerce attribute strings into typed values.
-- `default` — the value the prop takes when no attribute is present AND no JS value has been assigned. For `Boolean` props, default is `false` in the standard shape (see rule 1); `default: true` is a rare, ratified exception carried by connect-time attribute stamping (ADR-0075, gh#961) — never the default shape to reach for. For numeric props, default is `0`, a real value, or `null` for indeterminate — NEVER a sentinel like `-1`.
-- `reflect` — when `true`, JS property changes write back to the HTML attribute so CSS can match it. Required for every state-bearing Boolean. Usually safe to omit for large value props (long strings, big objects).
-- `attribute` — explicit kebab-case mapping when the JS name doesn't auto-convert cleanly. `camelCase` → `camel-case` automatic; override via `attribute: 'max-length'` when you want non-default behavior.
+- `type`, one of `String`, `Number`, `Boolean`, `Object`, `Array`. The runtime uses this to coerce attribute strings into typed values.
+- `default`: the value the prop takes when no attribute is present AND no JS value has been assigned. For `Boolean` props, default is `false` in the standard shape (see rule 1); `default: true` is a rare, ratified exception carried by connect-time attribute stamping (ADR-0075, gh#961), never the default shape to reach for. For numeric props, default is `0`, a real value, or `null` for indeterminate, NEVER a sentinel like `-1`.
+- `reflect`, when `true`, JS property changes write back to the HTML attribute so CSS can match it. Required for every state-bearing Boolean. Usually safe to omit for large value props (long strings, big objects).
+- `attribute`, explicit kebab-case mapping when the JS name doesn't auto-convert cleanly. `camelCase` → `camel-case` automatic; override via `attribute: 'max-length'` when you want non-default behavior.
 
 [verified 2026-08-19] **Literal-string `"false"` parity (ADR-0075).** For a
 `Boolean`-typed prop, `parseAttr` (`core/element.js:93-94`) special-cases the
-literal attribute string `"false"` to parse as JS `false` — a deliberate
+literal attribute string `"false"` to parse as JS `false`, a deliberate
 deviation from strict HTML boolean-attribute semantics (where any presence,
 including `attr="false"`, means `true`). This matches the A2UI transpiler's
 own prior `// (defensive)` special-case
@@ -34,10 +34,10 @@ the Decision: "for `t === Boolean`, the literal string `\"false\"` parses to
 JS `false`; any other present value (including empty string) parses to
 `true`; absence stays `false`." A component author or generation pipeline
 that writes `interactive="false"` on a `default: true` Boolean prop gets the
-intuitive result — do not assume strict HTML semantics here. (`default:
+intuitive result, do not assume strict HTML semantics here. (`default:
 true` itself remains the rare, ratified exception this ADR's blast radius
-runs against — ADR-0063's stamped-attribute mechanism, gh#961 — never the
-default shape "Boolean prop naming — the flip rule" above documents.) Named
+runs against, ADR-0063's stamped-attribute mechanism, gh#961, never the
+default shape "Boolean prop naming, the flip rule" above documents.) Named
 blast radius already shipped and relying on this: `password-strength-ui
 show-label="false"`, `nav-group-ui collapsible="false"`
 (`.examples.html` demos for both).
@@ -47,20 +47,20 @@ show-label="false"`, `nav-group-ui collapsible="false"`
 A real bug caught in iteration 4:
 
 ```javascript
-// BROKEN — silent
+// BROKEN, silent
 allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' },
 
 // FIXED
 allowHalf: { type: Boolean, default: false, reflect: true, attribute: 'allow-half' },
 ```
 
-`attr:` is not a recognized key. The mapper ignores it. The default auto-conversion (`allowHalf` → `allow-half`) happens to produce the same result, so the bug hides — until someone changes the prop name and notices the attribute never wired.
+`attr:` is not a recognized key. The mapper ignores it. The default auto-conversion (`allowHalf` → `allow-half`) happens to produce the same result, so the bug hides, until someone changes the prop name and notices the attribute never wired.
 
 Use `attribute:` verbatim. If you think you're writing `attr:`, stop and correct it before saving.
 
-## Boolean prop naming — the flip rule
+## Boolean prop naming, the flip rule
 
-AdiaUI conventions require `default: false` on Boolean props in the standard shape, unless a ratified exception applies (ADR-0075's connect-time attribute stamping, gh#961 — a rare exception, not a route open to new work). The naming follows:
+AdiaUI conventions require `default: false` on Boolean props in the standard shape, unless a ratified exception applies (ADR-0075's connect-time attribute stamping, gh#961, a rare exception, not a route open to new work). The naming follows:
 
 | Intended default behavior | Wrong name (default:true) | Right name (default:false) |
 | --- | --- | --- |
@@ -73,15 +73,15 @@ AdiaUI conventions require `default: false` on Boolean props in the standard sha
 
 **Naming patterns:**
 
-- `permanent` / `static` / `readonly` — describes the non-default state positively.
-- `no*` / `hide*` / `disable*` — prefixes for "opt-out of a default."
+- `permanent` / `static` / `readonly`, describes the non-default state positively.
+- `no*` / `hide*` / `disable*`, prefixes for "opt-out of a default."
 
 **Don't write:**
 
-- `enabled` (invert to `disabled`), `visible` (invert to `hidden`) — these clash with standard HTML attribute vocabulary.
+- `enabled` (invert to `disabled`), `visible` (invert to `hidden`), these clash with standard HTML attribute vocabulary.
 - Double-negatives like `unhide` or `dontSkip`.
 
-## Enum attribute + container-query auto-snap default — no interpolation
+## Enum attribute + container-query auto-snap default, no interpolation
 
 [verified 2026-08-19] ADR-0074 establishes the cross-component pattern for a
 value-enum attribute whose sensible default is "pick automatically from live
@@ -90,55 +90,54 @@ layout, but let a consumer pin it explicitly": `chart-ui` /
 values (`3:2`, `1:1`, `2:3`), unset by default. Quoting the Decision:
 "Unset (the default, empty string) means auto-snap: a CSS container query on
 the element's own box compares its live aspect ratio against two midpoint
-boundaries … and renders the nearest named ratio's studied layout — never a
+boundaries … and renders the nearest named ratio's studied layout, never a
 scaled/interpolated blend. Setting `ratio` explicitly pins that ratio's
 rendering regardless of the container's actual aspect, overriding the
 container query."
 
 Shape to follow for a new attribute of this kind:
 
-- A plain value-enum attribute, not a boolean — ADR-0063's `no-*`
+- A plain value-enum attribute, not a boolean, ADR-0063's `no-*`
   negation-prefix grammar does not apply.
 - Unset/default means container-query-driven auto-snap against studied
-  breakpoints — discrete snapping between named values, never continuous
+  breakpoints, discrete snapping between named values, never continuous
   interpolation (an in-between state was never individually studied, so it
   can't carry a "deliberately designed" claim).
 - An explicit attribute value always pins and overrides the auto-snap,
   never blends with it.
-- The resolved value reflects back for CSS/consumer introspection —
-  `data-ratio-resolved` on `chart-ui` names which of the enum's snapped or
+- The resolved value reflects back for CSS/consumer introspection, `data-ratio-resolved` on `chart-ui` names which of the enum's snapped or
   pinned values is currently in effect, distinct from the (possibly unset)
   `ratio` attribute itself.
 - Don't fold the new axis into an existing enum attribute that covers a
   different concern (`size` stayed `sm|md|lg`-only; `ratio` didn't grow a
-  compound value like `lg-2:3`) — orthogonal axes get their own attribute.
+  compound value like `lg-2:3`), orthogonal axes get their own attribute.
 
 `table-toolbar-ui[stage]` (ADR-0076) is the second precedent for this same
-shape — see the ADR-0063 conventions list in
+shape, see the ADR-0063 conventions list in
 [token-contract.md](token-contract.md).
 
 Source: [ADR-0074](../../../../../../docs/ops/adr/adr-0074-chart-ratio-attribute-grammar.md).
 
-**[verified 2026-08-23] Failure mode — DOM-ancestry auto-detection is riskier
+**[verified 2026-08-23] Failure mode, DOM-ancestry auto-detection is riskier
 than container-query auto-detection.** ADR-0081 Decision 1 (`chart-ui[labels]`,
 a 3-value enum: `""`/`chip`/`outside`) initially mirrored this same
-auto/explicit-override shape, but auto-detected via DOM ancestry — resolving
+auto/explicit-override shape, but auto-detected via DOM ancestry, resolving
 unset `labels=""` to `chip` whenever the element sat inside a `section[bleed]`
-or `card-ui[padding="none"]` ancestor — instead of a container query on the
+or `card-ui[padding="none"]` ancestor, instead of a container query on the
 element's own box. The 2026-08-21 amendment walked that back entirely after it
 silently flipped 2 of 60 fixtures on the Charts visual-eval floor
 (`comp-chart-in-card-n-*`, pre-existing full-bleed compositions), caught only
-by the floor's pixel-diff gate — neither the unit-test suite nor code review
+by the floor's pixel-diff gate, neither the unit-test suite nor code review
 renders real CSS/layout. Amended decision: unset `labels=""` resolves to
 `outside` unconditionally; `chip` mode activates only via the explicit
-`labels="chip"` attribute — no ancestry detection at all. ADR-0081's Decision
+`labels="chip"` attribute, no ancestry detection at all. ADR-0081's Decision
 2 (a `today` marker attribute) independently rejects clock-derived
 auto-detection for the same reliability reason (cites IDR-0006). Lesson for a
 new auto-snap attribute of this shape: auto-detection is safe when it reads
 the element's *own* rendered geometry (a container query against its own box,
 as `ratio` does); it is risky when it reads *ancestor* DOM state or wall-clock
 time, because neither is guaranteed stable across every composition that
-happens to nest the element — verify any such default against a real
+happens to nest the element, verify any such default against a real
 pixel-diff/visual-eval gate, not unit tests or review alone. Source:
 [ADR-0081](../../../../../../docs/ops/adr/adr-0081-chart-2-0-foundations-attribute-grammar.md)
 Amendment (2026-08-21).
@@ -147,12 +146,11 @@ Amendment (2026-08-21).
 
 [verified 2026-08-25, gh#1984] `core/responsive.js`'s `BREAKPOINTS` export is
 the single canonical reference for any device-class threshold, whether the
-query mechanism is `@media` (the five sanctioned viewport primitives —
-`grid-ui`, `col-ui`, `row-ui`, `block-ui`, `text-ui` — plus top-layer/popover
+query mechanism is `@media` (the five sanctioned viewport primitives, `grid-ui`, `col-ui`, `row-ui`, `block-ui`, `text-ui`, plus top-layer/popover
 positioning with no ancestor box to query) or `@container` (everything else,
-per `adr-0088` — `spec-breakpoint-convention` REQ-004 forbids importing
+per `adr-0088`, `spec-breakpoint-convention` REQ-004 forbids importing
 `core/responsive.js` itself outside those cases). This table MUST match
-`core/responsive.js`'s `BREAKPOINTS` export byte-for-byte — a gap here was
+`core/responsive.js`'s `BREAKPOINTS` export byte-for-byte, a gap here was
 exactly the drift `spec-breakpoint-convention` REQ-007 named and closed:
 
 | Name | Min-width |
@@ -165,25 +163,25 @@ exactly the drift `spec-breakpoint-convention` REQ-007 named and closed:
 
 A `@container`/`@media` rule can't read a CSS custom property at parse time
 (forbidden-pattern #2 in [token-contract.md](token-contract.md)), so these
-values are cited as raw literals in component CSS, never tokenized — but
+values are cited as raw literals in component CSS, never tokenized, but
 every such literal MUST carry a preceding comment naming the rung it
 implements (device-class threshold) or the ergonomic reason for the number
-(a component-intrinsic threshold, exempt from this table entirely — `nav-ui`'s
+(a component-intrinsic threshold, exempt from this table entirely, `nav-ui`'s
 96px icon-rail floor, `table-toolbar-ui`'s compaction stages, `chart-ui`'s
 200px legend-hide are correctly exempt and are NOT migration candidates).
 `packages/web-components/core/breakpoint-observer.js` is the shared
 `ResizeObserver`-to-attribute helper for a component that needs
 JS-observable state (relocating a node, switching a positioning strategy)
-rather than a pure CSS layout switch — see its own module doc for the
+rather than a pure CSS layout switch, see its own module doc for the
 boolean-vs-named-value reflection modes. Full requirements:
 [spec-breakpoint-convention](../../../../../../docs/ops/spec/spec-breakpoint-convention.md).
 
-## Numeric props — `null` over sentinels
+## Numeric props, `null` over sentinels
 
 Indeterminate, unknown, or "not yet set" numeric state uses `null`, not `-1` or `Infinity`:
 
 ```javascript
-// BROKEN — `-1` is a magic sentinel
+// BROKEN, `-1` is a magic sentinel
 value: { type: Number, default: -1, reflect: true }
 // Consumer: if (this.value !== -1) { ... }
 
@@ -192,7 +190,7 @@ value: { type: Number, default: null, reflect: true }
 // Consumer: if (this.value != null) { ... }
 ```
 
-The `progress-ui` component carried `-1` for "indeterminate" for a long time. Branching on a specific number is fragile — someone assigns `-1` meaningfully later and the indeterminate check breaks silently. `null` is unambiguous.
+The `progress-ui` component carried `-1` for "indeterminate" for a long time. Branching on a specific number is fragile, someone assigns `-1` meaningfully later and the indeterminate check breaks silently. `null` is unambiguous.
 
 **Back-compat coercion is allowed:**
 
@@ -215,9 +213,9 @@ HTML's global `title` attribute is the browser tooltip. Using `title` on a custo
 
 Children can have per-item `active` (a Boolean describing that item's state). Parents use `value` (for a selection) or `step` (for an index into a series).
 
-- `<timeline-item-ui active>` — OK, per-item Boolean state.
-- `<timeline-ui step="3">` — correct: parent holds the index.
-- `<timeline-ui active="3">` — wrong: `active` shouldn't carry a non-boolean payload.
+- `<timeline-item-ui active>`, OK, per-item Boolean state.
+- `<timeline-ui step="3">`, correct: parent holds the index.
+- `<timeline-ui active="3">`, wrong: `active` shouldn't carry a non-boolean payload.
 
 ### `error` as a variant
 
@@ -236,10 +234,10 @@ Reserve `error` for validation state (`[error]` on form inputs matches ARIA patt
 
 ### `disabled` on a non-form component
 
-`disabled` has form-participating semantics — it removes the element from the tab order, blocks submission, etc. On a non-form component (a diagram, a toolbar, a noodle editor), use `readonly`:
+`disabled` has form-participating semantics, it removes the element from the tab order, blocks submission, etc. On a non-form component (a diagram, a toolbar, a noodle editor), use `readonly`:
 
-- `<input-ui disabled>` — correct: input is form-participating.
-- `<noodles-ui readonly>` — correct: diagram is read-only, not form-disabled.
+- `<input-ui disabled>`, correct: input is form-participating.
+- `<noodles-ui readonly>`, correct: diagram is read-only, not form-disabled.
 
 ### `multiple` with exclusion semantics
 
@@ -255,34 +253,34 @@ Reserve `error` for validation state (`[error]` on form inputs matches ARIA patt
 
 **[historical, 2026-08-31, ADR-0056 amendment]** `<toggle-group-ui>` /
 `<toggle-option-ui>` were cut outright in `0.8.43` (gh#1617), before the
-migration this ADR's Decision 2 anticipated ever ran — moot, not
+migration this ADR's Decision 2 anticipated ever ran, moot, not
 falsified. `segmented-ui`/`segment-ui` absorbed the role
 (`segmented.yaml`'s `multiple` prop description names the absorption
 directly, gh#1369/#1363 C1). The example above stays as written because it
 illustrates the Boolean-false naming rule against a real historical prop
-name, not because `<toggle-group-ui>` still exists — `segmented-ui`
+name, not because `<toggle-group-ui>` still exists, `segmented-ui`
 deliberately does NOT follow this same polarity (`[multiple]` is
 positive-polarity by design, matching `select-ui[multiple]`; there is no
 `segmented-ui[single]` opt-out), so it is not a drop-in replacement
 example for this rule.
 
-## Selection-item state — a declared, reflected `selected` prop, never a private `data-*` stamp
+## Selection-item state, a declared, reflected `selected` prop, never a private `data-*` stamp
 
-A **selection-item primitive** (one selectable option inside a selection-group parent — `segment-ui` in `segmented-ui`; historically also `toggle-option-ui` in `toggle-group-ui`, cut in `0.8.43`/gh#1617 — see the dated note below) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
+A **selection-item primitive** (one selectable option inside a selection-group parent, `segment-ui` in `segmented-ui`; historically also `toggle-option-ui` in `toggle-group-ui`, cut in `0.8.43`/gh#1617, see the dated note below) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
 
 ```javascript
-// child — the declared API surface
+// child, the declared API surface
 static properties = {
   selected: { type: Boolean, default: false, reflect: true },
 };
 ```
 
 ```yaml
-# child yaml — the SoT the catalog and A2UI grammar read
+# child yaml, the SoT the catalog and A2UI grammar read
 selected:
   description: >-
     Whether this option is currently selected. Managed by the parent
-    <group> container — don't set directly; the group's `value` is the
+    <group> container, don't set directly; the group's `value` is the
     single source of truth.
   type: boolean
   default: false
@@ -290,18 +288,18 @@ selected:
 ```
 
 ```css
-/* child css — the state hook is the reflected attribute */
+/* child css: the state hook is the reflected attribute */
 segment-ui[selected] { … }
 ```
 
 Rules:
 
 - **The parent's `value` is the single source of truth**; the parent writes `selected` on its children (`segmented.class.js:146,149` sets/removes the attribute; `toggle-group.class.js:104-111` assigns `opt.selected`). Authors and generated markup drive the group's `value`, never `[selected]` on a child (`toggle-group.yaml`'s rules block says so in so many words).
-- **No private `data-*` stamp for API-conceptual state.** `data-selected` hides the state from the yaml SoT, the catalog, and generative authoring — a consumer or the A2UI grammar cannot express "this option is selected" against a stamp that no schema declares. `toggle-group-ui` used to stamp `data-selected` + style `:scope[data-selected]`; it converged onto `segment-ui`'s mechanism (`toggle-option.yaml:38-46`, `toggle-group.css:14`, `toggle-group.test.js:64` asserts the stamp is gone).
-- **Parent-stamped ARIA stays as-is — ARIA is wiring, not API.** `segment-ui` derives `aria-checked` from `selected` (`segment.class.js:42`); `toggle-option-ui` derives `aria-pressed` (`toggle-group.class.js:65`). The reflected prop is the API; the ARIA attribute follows it.
-- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`) is the current, live reference. **[historical, 2026-08-31, ADR-0056 amendment]** `toggle-option-ui`/`toggle-group-ui` were the converged second instance at ratification time, but both were cut outright in `0.8.43` (gh#1617), before any migration ran — `segmented-ui`/`segment-ui` absorbed the role. A new selection-item primitive copies `segment-ui`'s shape directly; there is no second live instance to extend by analogy anymore (the divergence gh#1303 describes was between `segment-ui` and the now-deleted `toggle-option-ui`).
+- **No private `data-*` stamp for API-conceptual state.** `data-selected` hides the state from the yaml SoT, the catalog, and generative authoring, a consumer or the A2UI grammar cannot express "this option is selected" against a stamp that no schema declares. `toggle-group-ui` used to stamp `data-selected` + style `:scope[data-selected]`; it converged onto `segment-ui`'s mechanism (`toggle-option.yaml:38-46`, `toggle-group.css:14`, `toggle-group.test.js:64` asserts the stamp is gone).
+- **Parent-stamped ARIA stays as-is, ARIA is wiring, not API.** `segment-ui` derives `aria-checked` from `selected` (`segment.class.js:42`); `toggle-option-ui` derives `aria-pressed` (`toggle-group.class.js:65`). The reflected prop is the API; the ARIA attribute follows it.
+- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`) is the current, live reference. **[historical, 2026-08-31, ADR-0056 amendment]** `toggle-option-ui`/`toggle-group-ui` were the converged second instance at ratification time, but both were cut outright in `0.8.43` (gh#1617), before any migration ran, `segmented-ui`/`segment-ui` absorbed the role. A new selection-item primitive copies `segment-ui`'s shape directly; there is no second live instance to extend by analogy anymore (the divergence gh#1303 describes was between `segment-ui` and the now-deleted `toggle-option-ui`).
 
-Migration note: removing `data-selected` was a breaking change for external CSS that targeted it, so it shipped in two halves — the additive `selected` prop in `0.8.39`, the stamp removal on the `0.8.40` breaking wave with a migration-guide entry (`packages/web-components/CHANGELOG.md`; the ADR text names the wave `0.9.0` — it shipped as `0.8.40`).
+Migration note: removing `data-selected` was a breaking change for external CSS that targeted it, so it shipped in two halves, the additive `selected` prop in `0.8.39`, the stamp removal on the `0.8.40` breaking wave with a migration-guide entry (`packages/web-components/CHANGELOG.md`; the ADR text names the wave `0.9.0`, it shipped as `0.8.40`).
 
 Source: ADR-0056 (ratified 2026-08-15, gh#1303).
 
@@ -329,7 +327,7 @@ class UIInput extends UIFormElement {
   };
 
   connected() {
-    super.connected(); // MUST call — registers ElementInternals
+    super.connected(); // MUST call, registers ElementInternals
     // ...
   }
 
@@ -347,9 +345,9 @@ class UIInput extends UIFormElement {
 
 Key details:
 
-- **Always `super.connected()` and `super.disconnected()`** — without them, form-association doesn't register.
-- **`this.syncValue(str)`** — call this whenever the value changes to update the form-submitted string. Accepts a string.
-- **Inheriting properties** — spread `UIFormElement.properties` into your own `static properties` so you don't re-declare `name`, `disabled`, `required`.
+- **Always `super.connected()` and `super.disconnected()`**, without them, form-association doesn't register.
+- **`this.syncValue(str)`**, call this whenever the value changes to update the form-submitted string. Accepts a string.
+- **Inheriting properties**, spread `UIFormElement.properties` into your own `static properties` so you don't re-declare `name`, `disabled`, `required`.
 
 ## Event conventions
 
@@ -373,9 +371,9 @@ render() {
 
 Rule of thumb: if CSS can do the work via an attribute selector (`:scope[disabled] { ... }`), prefer CSS. Reserve `render()` for propagating state into child inputs, recalculating positions, or reflecting data changes that attribute selectors can't express.
 
-## Popover `placement` defaults — picked by popover-to-trigger width ratio
+## Popover `placement` defaults, picked by popover-to-trigger width ratio
 
-Every popover-bearing primitive exposes a consumer-overridable `placement` attribute (declare it in the yaml SoT, with the default documented in the prop description). The DEFAULT is selected by the popover's natural width relative to its trigger — never by component identity:
+Every popover-bearing primitive exposes a consumer-overridable `placement` attribute (declare it in the yaml SoT, with the default documented in the prop description). The DEFAULT is selected by the popover's natural width relative to its trigger, never by component identity:
 
 | Case | Default |
 |---|---|
@@ -384,6 +382,6 @@ Every popover-bearing primitive exposes a consumer-overridable `placement` attri
 | Trigger sits at a container's right edge **by construction** (toolbar spillover, right-pinned "more") | `bottom-end` |
 | Non-bottom-axis surfaces | component-specific: `tooltip-ui` → `top`, `nav-group-ui` collapsed flyout → `right` |
 
-Rationale: `bottom-start` on a wide popover under a right-anchored trigger fires `anchor.js`'s right-edge overflow recovery, snapping the panel far past the trigger's left edge (the v0.6.35 date-range-picker incident — ~800px panel under a ~280px button). Centered `bottom` shifts at most half the overflow distance. Classification is done once at authoring time; borderline cases resolve by what the popover *wants*: if it `matchWidth`s the trigger it is trigger-width regardless of absolute size. "The consumer placed their button on the right of the layout" is a call-site `placement="bottom-end"` override, never a default. The overflow-recovery logic in `anchor.js` is the safety net and stays unchanged — the default's job is to make recovery rarely fire.
+Rationale: `bottom-start` on a wide popover under a right-anchored trigger fires `anchor.js`'s right-edge overflow recovery, snapping the panel far past the trigger's left edge (the v0.6.35 date-range-picker incident, ~800px panel under a ~280px button). Centered `bottom` shifts at most half the overflow distance. Classification is done once at authoring time; borderline cases resolve by what the popover *wants*: if it `matchWidth`s the trigger it is trigger-width regardless of absolute size. "The consumer placed their button on the right of the layout" is a call-site `placement="bottom-end"` override, never a default. The overflow-recovery logic in `anchor.js` is the safety net and stays unchanged: the default's job is to make recovery rarely fire.
 
 Source: ADR-0034.

package/skills/primitive-authoring/references/authoring-cycle.md

@@ -1,47 +1,47 @@
-# Authoring cycle — author a NEW primitive or MODIFY an existing one
+# Authoring cycle, author a NEW primitive or MODIFY an existing one
 
-The 5-step procedure run AFTER [primitive-audit.md](primitive-audit.md) clears (new primitive) — or jumping straight to Step 2 when modifying an existing one.
+The 5-step procedure run AFTER [primitive-audit.md](primitive-audit.md) clears (new primitive), or jumping straight to Step 2 when modifying an existing one.
 
 ---
 
-## Step 1 — Read the contract and the reference components
+## Step 1, Read the contract and the reference components
 
 Before writing or editing, load these four files. They are the ground truth:
 
-- `.claude/docs/specs/component-token-contract.md` — the authoritative invariants. Skim the whole thing if you haven't read it this session; focus on "Variants vs Modes" and "Sanctioned Mode Attributes" if you're adding a new layout-affecting attribute.
-- `packages/web-components/core/element.js` — `UIElement` base class. The `static properties` schema, `connected()`/`disconnected()`/`render()` lifecycle, and attribute-mapping conventions are all defined here.
-- `packages/web-components/core/form.js` — `UIFormElement`. Only needed if the new component participates in forms (inputs, selects, checkboxes, etc.).
+- `.claude/docs/specs/component-token-contract.md`, the authoritative invariants. Skim the whole thing if you haven't read it this session; focus on "Variants vs Modes" and "Sanctioned Mode Attributes" if you're adding a new layout-affecting attribute.
+- `packages/web-components/core/element.js`, `UIElement` base class. The `static properties` schema, `connected()`/`disconnected()`/`render()` lifecycle, and attribute-mapping conventions are all defined here.
+- `packages/web-components/core/form.js`, `UIFormElement`. Only needed if the new component participates in forms (inputs, selects, checkboxes, etc.).
 - At least one good-citizen reference that matches the shape of what you're building. Pick from: `button-ui`, `card-ui`, `input-ui`, `textarea-ui`, `check-ui`. Read both the `.js` and the `.css`.
 
-## Step 2 — Classify the work before you write
+## Step 2, Classify the work before you write
 
 Before typing, answer:
 
-1. **Is this cosmetic or structural?** If the change affects `display`, `flex-direction`, `grid-template`, `padding`, layout geometry — it's a mode, not a variant. Modes require an entry in the Sanctioned Mode Attributes table (`.claude/docs/specs/component-token-contract.md` `Modes` section). Do not introduce undocumented layout-changing variants.
+1. **Is this cosmetic or structural?** If the change affects `display`, `flex-direction`, `grid-template`, `padding`, layout geometry, it's a mode, not a variant. Modes require an entry in the Sanctioned Mode Attributes table (`.claude/docs/specs/component-token-contract.md` `Modes` section). Do not introduce undocumented layout-changing variants.
 
 2. **Does the new prop fit the Boolean-default-false rule?** If the default behavior is "on," negate the prop name before writing (`closable` is wrong if closable is the default; `permanent` is right).
 
 3. **Does the component hold state that CSS needs to read?** If yes, every state-bearing Boolean declares `{ type: Boolean, default: false, reflect: true }`.
 
-4. **Does the component add listeners, timers, or observers?** If yes, plan the `disconnected()` method at the same time as `connected()` — do not defer. The symmetric pair is one unit of work, never two.
+4. **Does the component add listeners, timers, or observers?** If yes, plan the `disconnected()` method at the same time as `connected()`, do not defer. The symmetric pair is one unit of work, never two.
 
-## Step 3 — Apply the non-negotiable rules
+## Step 3, Apply the non-negotiable rules
 
 These rules are the distilled lessons from a 5-iteration audit. Each one corresponds to a real bug that was fixed in the codebase. Full rationale and the bug histories are in [anti-patterns.md](anti-patterns.md).
 
 ### API / Attributes
 
-1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `noCursor`, `average` → `noAverage`, `pause-on-hover` → `noPauseOnHover`. `no-*` is the canonical negation prefix (ADR-0063 decision 1) — a new rename lands on `no-*` directly, never `hide-*`.
+1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `noCursor`, `average` → `noAverage`, `pause-on-hover` → `noPauseOnHover`. `no-*` is the canonical negation prefix (ADR-0063 decision 1), a new rename lands on `no-*` directly, never `hide-*`.
 
 2. **No magic-value sentinels in numeric props.** Indeterminate = `null`, not `-1`. Consumers branch on `value == null`, which is explicit.
 
-3. **Use `attribute:` not `attr:`.** `attr:` is a silent typo — the mapper ignores it and the kebab-case HTML attribute never wires. This cost a real bug in `rating-ui`.
+3. **Use `attribute:` not `attr:`.** `attr:` is a silent typo, the mapper ignores it and the kebab-case HTML attribute never wires. This cost a real bug in `rating-ui`.
 
 4. **State-bearing Booleans reflect.** `{ type: Boolean, default: false, reflect: true }`. Without `reflect`, CSS can't match `:scope[disabled]`, hover/active/selected states break silently.
 
-5. **Reserved-name anti-patterns.** Avoid: `title` (collides with HTML tooltip attribute), `active` on parent components (use `value` for a selection or `step` for an index — per-item `active` on children is fine), `error` in variant names (use `danger`; reserve `error` for validation state), `disabled` on non-form-participating components (use `readonly`), `multiple` with exclusion semantics (use a negated positive like `single`).
+5. **Reserved-name anti-patterns.** Avoid: `title` (collides with HTML tooltip attribute), `active` on parent components (use `value` for a selection or `step` for an index, per-item `active` on children is fine), `error` in variant names (use `danger`; reserve `error` for validation state), `disabled` on non-form-participating components (use `readonly`), `multiple` with exclusion semantics (use a negated positive like `single`).
 
-6. **Element tag ends in `-ui`; JS class is `UI<Component>`.** `<foo-ui>` ↔ `class UIFoo extends UIElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update — see `.claude/docs/specs/component-token-contract.md`.
+6. **Element tag ends in `-ui`; JS class is `UI<Component>`.** `<foo-ui>` ↔ `class UIFoo extends UIElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update, see `.claude/docs/specs/component-token-contract.md`.
 
 ### CSS
 
@@ -57,12 +57,12 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
      }
 
      :scope {
-       /* ── Base styles — consume only component tokens ── */
+       /* ── Base styles, consume only component tokens ── */
        background: var(--component-bg);
        color: var(--component-fg);
      }
 
-     /* ── Variants / states third — override TOKENS only ── */
+     /* ── Variants / states third, override TOKENS only ── */
      :scope[variant="outlined"] {
        --component-bg: transparent;
        --component-border: var(--a-border);
@@ -84,7 +84,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 ### JS Lifecycle
 
-1. **Every `addEventListener` in `connected()` has a matching `removeEventListener` in `disconnected()`.** Handler must be a stable `#field` arrow (`#onClick = (e) => { ... }`), never an inline arrow passed to `addEventListener`. Inline arrows can't be removed — `removeEventListener` needs reference equality.
+1. **Every `addEventListener` in `connected()` has a matching `removeEventListener` in `disconnected()`.** Handler must be a stable `#field` arrow (`#onClick = (e) => { ... }`), never an inline arrow passed to `addEventListener`. Inline arrows can't be removed, `removeEventListener` needs reference equality.
 
 2. **`UIFormElement` subclasses call `super.connected()` and `super.disconnected()`.** `ElementInternals` registration depends on it. Omitting `super` strands the form-association.
 
@@ -92,7 +92,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 4. **Null cached DOM refs in `disconnected()`.** `this.#fooEl = null` after removing its listeners. Prevents stale-tree GC pinning when the component is re-attached.
 
-5. **Never declare `disconnected()` twice in one class.** The second silently overrides the first — this exact bug lost `ResizeObserver` cleanup in `chart.js` for several commits. If you find yourself needing a "second disconnected," merge it into the existing one.
+5. **Never declare `disconnected()` twice in one class.** The second silently overrides the first, this exact bug lost `ResizeObserver` cleanup in `chart.js` for several commits. If you find yourself needing a "second disconnected," merge it into the existing one.
 
 6. **Popover/tooltip overlays created in `connected()` are removed in `disconnected()`.** Anything appended to `document.body` or `<body>` via the Popover API needs explicit cleanup; they don't GC with the host.
 
@@ -100,7 +100,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 ### Field composition
 
-1. **Do not add a `label` attribute to a new form-associated control.** `<field-ui label="…">` is the canonical labeled-field wrapper. It owns the real `<label for="…">` and binds to the slotted control's id for proper click-to-focus — a pattern the embedded per-control `label` attribute can't provide (no `[for]`, just a shadow slot). Existing controls (input-ui, select-ui, textarea-ui, switch-ui, check-ui, radio-ui, slider-ui, calendar-picker-ui, upload-ui, range-ui) still accept the legacy `label` attr but log a one-shot console.warn; **no new control should declare one**. Wrap instead:
+1. **Do not add a `label` attribute to a new form-associated control.** `<field-ui label="…">` is the canonical labeled-field wrapper. It owns the real `<label for="…">` and binds to the slotted control's id for proper click-to-focus, a pattern the embedded per-control `label` attribute can't provide (no `[for]`, just a shadow slot). Existing controls (input-ui, select-ui, textarea-ui, switch-ui, check-ui, radio-ui, slider-ui, calendar-picker-ui, upload-ui, range-ui) still accept the legacy `label` attr but log a one-shot console.warn; **no new control should declare one**. Wrap instead:
 
    ```html
    <!-- right -->
@@ -120,8 +120,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
    ```css
    @scope (my-composite-ui) {
-     /* 1. Composite paints the ring via :focus-within —
-        wraps both the control and any siblings inside the shell. */
+     /* 1. Composite paints the ring via :focus-within, wraps both the control and any siblings inside the shell. */
      :scope:focus-within {
        box-shadow: var(--my-composite-focus-ring);
      }
@@ -131,7 +130,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
      }
 
      /* 2. Suppress the inner control's own focus affordance.
-        The @scope block's containment IS the signal — no data
+        The @scope block's containment IS the signal, no data
         attribute or explicit opt-in needed; selectors targeting
         inner elements only apply when they're inside this host. */
      textarea-ui [slot="text"]:focus {
@@ -148,12 +147,12 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
    ```
 
    **When to use this (not field-ui):**
-   - **field-ui** is a _wrapper composite_ — it adds chrome (label / hint / error / required) around a control, but the control is still the primary focus target. Control owns the ring.
-   - **chat-input-ui** (and future equivalents) are _shell composites_ — the composite IS the control; the inner textarea is an implementation detail. Host owns the ring.
+   - **field-ui** is a _wrapper composite_, it adds chrome (label / hint / error / required) around a control, but the control is still the primary focus target. Control owns the ring.
+   - **chat-input-ui** (and future equivalents) are _shell composites_: the composite IS the control; the inner textarea is an implementation detail. Host owns the ring.
 
    A user's mental model is the discriminator: do they think of the composite as a single control, or as a labeled/wrapped version of an inner control? The former is a shell; the latter is a wrapper.
 
-## Step 4 — Run the 30-second self-check
+## Step 4, Run the 30-second self-check
 
 Before declaring the work done, run through this checklist. If anything fails, fix before committing.
 
@@ -184,63 +183,61 @@ Before declaring the work done, run through this checklist. If anything fails, f
 - [ ] Cached DOM refs (`this.#fooEl`) are nulled in `disconnected()`.
 - [ ] Class declares `disconnected()` exactly once.
 
-## Step 4b — Author the yaml SoT (+ regenerate the sidecar)
+## Step 4b, Author the yaml SoT (+ regenerate the sidecar)
 
-A component isn't just its `.js`/`.css` — the `<name>.yaml` is the SOURCE OF
+A component isn't just its `.js`/`.css`: the `<name>.yaml` is the SOURCE OF
 TRUTH the whole pipeline reads (docs site, A2UI registries, consumer
 harnesses, `.d.ts` codegen). Every new primitive ships one; every prop/slot/
 event change updates it. Field-by-field contract:
-[yaml-contract.md](yaml-contract.md). Then regenerate — never hand-edit the
+[yaml-contract.md](yaml-contract.md). Then regenerate, never hand-edit the
 sidecar (`sidecar-prewrite-guard` blocks it anyway):
 
 ```bash
 npm run build:components            # yaml → <name>.a2ui.json + catalog + .d.ts
-node scripts/build/components.mjs --verify   # "clean — N files up-to-date"
+node scripts/build/components.mjs --verify   # "clean, N files up-to-date"
 ```
 
-A primitive also needs BOTH barrel registrations — the CSS `@import` in
+A primitive also needs BOTH barrel registrations, the CSS `@import` in
 `styles/components.css` AND the JS `export` in `components/index.js`
 (`scripts/audit/check-components-js-barrel.mjs` gates the second). Either
-registration drifts the built `dist/` bundles — regenerate them in the same
+registration drifts the built `dist/` bundles, regenerate them in the same
 change (`npm run build:bundle-css && npm run build:bundle-js`) and commit the
 `dist/` updates, or CI's `check:{css,js}-bundles-fresh` gates fail on the PR
 (gh#390's PR shipped without this and failed exactly there). Both commands,
-not just one — `theme-provider.min.js` (a JS bundle) inlines the co-emitted
+not just one, `theme-provider.min.js` (a JS bundle) inlines the co-emitted
 `dist/web-components.sheet.js` twin, so a CSS-only edit still drifts a JS
 bundle if only `build:bundle-css` runs (bit the v0.8.13 theme-panel work
 twice).
 
 **Rebuild JS bundles from an `npm ci` scratch checkout, never a pnpm-bootstrapped worktree.**
 `node scripts/dev/bootstrap-worktree.mjs`'s pnpm install produces `dist/*.min.js` output
-~30% larger than CI's npm-ci install (a lockfile/hoisting difference, not a code difference)
-— running `build:bundle-js` in such a worktree commits drift instead of fixing it, and a
+~30% larger than CI's npm-ci install (a lockfile/hoisting difference, not a code difference), running `build:bundle-js` in such a worktree commits drift instead of fixing it, and a
 local `check:js-bundles-fresh` run there will falsely pass against its own inflated bundle.
 When a PR built in a pnpm worktree needs a JS-bundle rebuild: commit the CSS-side changes
-first if any (`build:bundle-css` has no install-shape risk — LightningCSS's bundling is
-deterministic from source — so the branch's committed `dist/web-components.sheet.js` is
+first if any (`build:bundle-css` has no install-shape risk, LightningCSS's bundling is
+deterministic from source, so the branch's committed `dist/web-components.sheet.js` is
 trustworthy going into the next step, satisfying the CSS-before-JS ordering above), then
 `git worktree add <scratch-path> <branch>`, `npm ci` there (real npm-shaped install), run
 `build:bundle-js`, copy only the changed `dist/*.min.js` file(s) back into the working
 worktree, commit there with an explicit pathspec, then remove the scratch worktree. This
 is the correction to gh#1825's own PR body, which deferred the rebuild to "CI's
-derived-artifact pipeline" — wrong per ADR-0069 (`dist/` is Class C, committed and
+derived-artifact pipeline", wrong per ADR-0069 (`dist/` is Class C, committed and
 PR-blocking, never derive-resync'd); the scratch-checkout procedure above is what actually
 landed the fix, 2026-08-21.
 
 **Never `@import` a remote URL from any file `build:bundle-css` bundles.**
 LightningCSS's `bundleAsync` (the engine behind it) resolves every `@import`
-as a local filesystem path, remote `http(s)` URLs included — a CSS-level
+as a local filesystem path, remote `http(s)` URLs included, a CSS-level
 `@import url('https://fonts.googleapis.com/...')` breaks the build with
 `ResolverError: No such file or directory`, not a lint warning; there's no
 `bundleAsync` option to skip or externalize one `@import`. Link web fonts
 (or anything else external) as a real `<link>` in the consumer's `<head>`
-instead — see `styles/theme-fonts-url.txt` for the pattern this repo's 12
+instead, see `styles/theme-fonts-url.txt` for the pattern this repo's 12
 named themes use. A generated CSS file's own fix doesn't survive its next
-regen unless the generator is fixed too, not just the committed output —
-the standing "generated artifacts are never hand-edited" invariant
+regen unless the generator is fixed too, not just the committed output: the standing "generated artifacts are never hand-edited" invariant
 (AGENTS.md) cuts both ways.
 
-## Step 5 — Run the project's verification gates
+## Step 5, Run the project's verification gates
 
 Before committing, run the project's verify scripts. These catch the drift-shaped bugs the checklist can miss:
 
@@ -256,11 +253,11 @@ If a gate fails, fix before declaring done.
 
 ## Cross-references
 
-- [primitive-audit.md](primitive-audit.md) — the §0 gate (run BEFORE this)
-- [api-contract.md](api-contract.md) — deep dive on prop naming, type choices, reflection policy
-- [css-patterns.md](css-patterns.md) — exhaustive CSS architecture (@scope, variants, modes)
-- [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listener patterns
-- [anti-patterns.md](anti-patterns.md) — full failure-mode catalogue, file:line refs
-- [worked-example.md](worked-example.md) — badge-ui + counter-ui walkthroughs
-- [yaml-contract.md](yaml-contract.md) — the `<name>.yaml` SoT schema (Step 4b)
-- [token-contract.md](token-contract.md) — token audit (post-implementation check)
+- [primitive-audit.md](primitive-audit.md), the §0 gate (run BEFORE this)
+- [api-contract.md](api-contract.md), deep dive on prop naming, type choices, reflection policy
+- [css-patterns.md](css-patterns.md), exhaustive CSS architecture (@scope, variants, modes)
+- [lifecycle-patterns.md](lifecycle-patterns.md), timers, observers, popovers, listener patterns
+- [anti-patterns.md](anti-patterns.md), full failure-mode catalogue, file:line refs
+- [worked-example.md](worked-example.md), badge-ui + counter-ui walkthroughs
+- [yaml-contract.md](yaml-contract.md), the `<name>.yaml` SoT schema (Step 4b)
+- [token-contract.md](token-contract.md), token audit (post-implementation check)