@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-source-list.md

@@ -0,0 +1,144 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-source-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/source-list/source-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraSourceList`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/source-list/source-list.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-source-card` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-source-list` / `lr-source-card`
+
+A collapsible "Sources" panel for one chat message (`lr-source-list`) that groups a set of
+`lr-source-card` entries. First-party invention (no Web Awesome equivalent). Cards are meant to be
+direct light-DOM children of the list (plain composition — no `.items` array prop, the same shape
+`<lr-split>`'s panels take), though `lr-source-card` renders and functions fine standalone.
+
+### `lr-source-list`
+
+**Properties:**
+- `expanded: boolean = false` (reflected) — whether the card list is currently shown. Starts
+  collapsed by default so a message's sources don't eat vertical space until asked for.
+- `label: string = ''` — header text used when `label-plural` isn't set, e.g. `"Sources"`.
+- `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
+  header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
+  its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
+  to the literal word `"Sources"`.
+
+**Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
+handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
+
+**Events:** `lr-toggle` (`detail: { expanded: boolean }`) — the header was activated, expanding or
+collapsing the list.
+
+**Slots:** default — `<lr-source-card>` elements (or any content, though the card pairing is the
+intended usage).
+
+**CSS parts:** `base` (outer container), `header` (the clickable `<button>` toggling `expanded`),
+`toggle` (the chevron indicator inside the header), `list` (wrapper around the default slot, `hidden`
+while collapsed).
+
+**Themeable custom properties:** shared tokens only — `--lr-color-border`, `--lr-color-surface`,
+`--lr-color-text`, `--lr-color-brand` / `-brand-quiet`, `--lr-radius`, `--lr-space-xs`/`-s`/
+`-m`, `--lr-transition-fast`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+### `lr-source-card`
+
+**Properties:**
+- `sourceId: string = ''` (attribute `source-id`) — stable identifier matching a
+  `<lr-citation-badge>` elsewhere on the page.
+- `title: string = ''` — the source's display title, e.g. a filename. Falls back to `"Untitled
+  source"` when empty.
+- `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
+  parsed/validated as a number), appended to the title as `" — p. {page}"`.
+- `href?: string` — optional URL, echoed back (unopened) in `lr-open`'s detail.
+- `compact: boolean = false` (reflected) — tighter root padding and row gap, for the dense citation
+  lists these cards usually render in — the same convention as `lr-empty`'s `compact`. Purely a
+  density knob: the border and background stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card inside a `<lr-source-list>`
+  (or any container already drawing its own border/dividers) doesn't double the frame. `plain` wins
+  over `compact` when both are set — nothing left to tighten. The title and toggle keep their brand
+  color and hover underline under `plain`, since neither ever depended on the card chrome.
+
+**Events:**
+- `lr-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
+  more"/"Show less" toggle was activated. Unrelated to the parent `lr-source-list`'s own
+  expand/collapse, which only ever hides/shows the *set* of cards, never a single card's own content.
+- `lr-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
+  component never navigates on its own (a controlled component, the same convention
+  `<lr-tool-call-chip>`'s `lr-tool-call-chip-select` follows); a listener decides what "open"
+  means.
+
+**Slots:** `excerpt` (a short preview; when left empty, the `excerpt` part collapses away entirely —
+its wrapper is `hidden`, not just visually empty), `full` (the complete source text/chunk, hidden
+behind the "Show more"/"Show less" toggle — when left empty, no toggle renders at all; removing all
+`full`-slotted content while expanded auto-collapses it back).
+
+**CSS parts:** `base` (outer container), `title` (the clickable title/page heading, a `<button>`),
+`excerpt` (wrapper around the `excerpt` slot, `hidden` when the slot has no assigned content), `full`
+(wrapper around the `full` slot, `hidden` while collapsed), `toggle` (the "Show more"/"Show less"
+button — only rendered when the `full` slot has content).
+
+**Themeable custom properties:** `--lr-source-card-compact-padding` (default `var(--lr-space-xs)`) —
+`[part='base']`'s padding while `compact`; `--lr-source-card-compact-gap` (default
+`var(--lr-space-2xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense citation list can be tuned without re-pointing shared spacing tokens
+elsewhere. Plus shared tokens — `--lr-color-border`, `--lr-color-surface`,
+`--lr-color-text` / `-text-quiet`, `--lr-color-brand`, `--lr-radius`, `--lr-space-xs`/`-s`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-source-list label-plural="2 sources">
+  <lr-source-card source-id="doc-1" title="annual_report.pdf" page="12">
+    <span slot="excerpt">Revenue grew 12% year over year...</span>
+    <span slot="full">Revenue grew 12% year over year, driven primarily by...</span>
+  </lr-source-card>
+  <lr-source-card source-id="doc-2" title="q3_notes.md">
+    <span slot="excerpt">No matching full-text chunk for this source.</span>
+  </lr-source-card>
+</lr-source-list>
+<script type="module">
+  // Elsewhere, a <lr-citation-badge>'s activation handler can scroll to and
+  // highlight the matching card -- neither component needs extra API surface
+  // for that, only source-id to be targeted by:
+  document.addEventListener('lr-citation-activate', (e) => {
+    const card = document.querySelector(`lr-source-card[source-id="${e.detail.sourceId}"]`);
+    card?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  });
+</script>
+```
+
+`lr-source-list` removes the card list from the accessibility tree (not just visually hides it)
+while collapsed, via the native `hidden` attribute on `[part="list"]` — a screen reader user tabbing
+past the header never lands on off-screen source cards they can't currently see. Both components
+track slot presence in JS state (`slottedCount` on the list, `hasFullSlot` on the card) rather than
+relying on CSS `:empty`, since a `[part]` wrapper always contains a literal `<slot>` child regardless
+of assigned content; both also reconcile that state in `firstUpdated()` as a fallback for slot-
+forwarding scenarios or engines that don't fire `slotchange` for content already present at parse
+time.
+
+**Known gotchas:**
+- This library has no built-in i18n/pluralization (the same stance `<lr-empty>`'s plain
+  `description` prop takes) — `lr-source-list`'s header text is entirely consumer-supplied via
+  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
+  `"Sources"` fallback.
+- `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
+  independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
+  individual card's `fullExpanded` state, and there is no cross-talk between the two components at
+  all beyond DOM nesting.
+- `lr-source-card` actively strips a bare host-level `title` attribute right after Lit syncs it into
+  the `title` property — otherwise the whole card would grow an unsolicited native tooltip repeating
+  the title text on hover. Set `title` only as a property/attribute meant to become the rendered
+  heading; don't rely on it surviving as a DOM attribute afterward.
+
+---

package/llms/components/lr-source-picker.md

@@ -0,0 +1,75 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-source-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/source-picker/source-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraSourcePicker`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/source-picker/source-picker.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-source-picker`
+
+A checkbox tree/list scoping which sources ground the next answer: tri-state folders, select-all,
+type icons, search. **Not `FormAssociated`, deliberately**: this is a scoping panel, not a form
+control — the selection is immediate app state consumed by the next retrieval call, exactly the
+stance `lr-tool-select-dialog` already takes.
+
+**Properties:**
+- `sources: LyraSourceEntry[] = []` (attribute: false) — `LyraSourceEntry { id: string; label:
+  string; mimeType?: string; name?: string; children?: LyraSourceEntry[] }`; flat (no `children`) or
+  a tree — presence of `children` makes a row a group/folder with tri-state select
+- `selectedIds: string[] = []` (attribute: false) — controlled; the host assigns this back from
+  `lr-sources-change`
+- `showSelectAll: boolean = true` (attribute `show-select-all`)
+- `searchable: boolean = true`
+- `label: string = ''`
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the tree's computed
+  accessible name; wins over `label` and the localized default, and attribute-reflects from a
+  host-level `aria-label` so plain markup gets ARIA-name forwarding
+
+**Events:** `lr-sources-change` (`detail: { selectedIds }`, the complete updated leaf-id array,
+fired after every toggle including select-all).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `search` (the built-in filter `lr-input`, only when `searchable`),
+`select-all` (only when `showSelectAll`), `summary` ("{selected} of {total} selected"), `tree`
+(`role="tree"`), `item` (`role="treeitem"`), `checkbox` (tri-state glyph), `icon` (the
+`lr-file-icon` type badge), `label`, `empty` (`noData` when `sources` is empty, `noMatches` when a
+filter empties the tree).
+
+**Themeable custom properties:** `--lr-source-picker-checked-bg` — the background of a fully-checked
+selection control: the `select-all` pill (whose resting default is `var(--lr-color-brand-quiet)`) and
+a fully-selected entry's `[part='checkbox']` (whose resting default is `var(--lr-color-brand)`). The
+two keep their distinct defaults while it is unset; setting it unifies both.
+`--lr-source-picker-checked-border` (default `var(--lr-color-brand)`) — the border color of every
+checked *or* mixed selection control. `--lr-source-picker-mixed-bg` (default
+`color-mix(in srgb, var(--lr-color-brand) 50%, var(--lr-color-surface))`) — the background of a
+partially-selected entry's `[part='checkbox']`, so a tri-state folder reads as distinct from a fully
+selected one. All three are inline `var()` fallbacks at the point of use rather than `:host`
+declarations, so each can be set on the element *or on any ancestor*:
+`::part(checkbox)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as
+the only lever, repainting every other brand surface with it. Plus shared tokens otherwise.
+
+**Optional peer deps:** none.
+
+```html
+<lr-source-picker></lr-source-picker>
+<script>
+  const picker = document.querySelector('lr-source-picker');
+  picker.sources = [
+    { id: 'folder-1', label: 'Reports', children: [{ id: 'doc-1', label: 'Q3.pdf', mimeType: 'application/pdf' }] },
+  ];
+  picker.addEventListener('lr-sources-change', (e) => (retrievalScope = e.detail.selectedIds));
+</script>
+```
+
+**Known gotchas:**
+- Deliberately not form-associated — `lr-sources-change` is the only wiring; there's no
+  `name`/`value`/`FormData` participation the way a genuine form control would have.
+
+---

package/llms/components/lr-span-waterfall.md

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-span-waterfall`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/span-waterfall/span-waterfall.js';` (registers the tag; side-effect import)
+- **Class** `LyraSpanWaterfall`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/span-waterfall/span-waterfall.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-span-waterfall`
+
+The horizontal-timeline projection of the same `LyraSpan[]` `<lr-trace-tree>` consumes: a time
+axis, one row per span in start order, status-toned bars (Langfuse timeline / Temporal
+event-history style).
+
+**Properties:** `spans: LyraSpan[] = []` (attribute: false) — `LyraSpan { id: string; parentId?:
+string; name: string; kind: 'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other';
+startMs: number; endMs?: number; status: 'pending' | 'running' | 'success' | 'error' | 'denied';
+tokensIn?: number; tokensOut?: number; costText?: string; detail?: string }`, exported from
+`trace-tree/span.ts`. `startMs`/`endMs` are milliseconds **relative to the trace start**, not
+wall-clock timestamps; `endMs` is absent while the span is still running. `costText` is preformatted
+by the host (e.g. `"$0.0012"`) and rendered verbatim, never parsed or summed. One flat array powers
+both this component (timeline projection via `startMs`/`endMs`) and `lr-trace-tree` (hierarchy
+projection via `parentId`) — never two shapes. `activeSpanId: string | null = null`
+(attribute `active-span-id`), `viewStartMs: number | null = null` (attribute `view-start-ms`) and
+`viewEndMs: number | null = null` (attribute `view-end-ms`) — override the auto-computed time
+window, `hideAxis: boolean = false` (attribute `hide-axis`), and `label: string = ''`.
+
+**Events:** `lr-span-select` — `detail: { id: string }`, a bar/row was activated (click, Enter,
+Space).
+
+**CSS parts:** `base`, `axis` (the time-ruler row, hidden when `hideAxis`), `tick`, `tick-label`,
+`row`, `name` (the row's name gutter), `bar-track`, `bar` (the interactive, focusable status-toned
+bar), `meta` (secondary row info, shown inline under 480px), `status-text`, `duration`, `empty` (shown
+when `spans` is empty), and `live-region`.
+
+**Themeable custom properties:** `--lr-span-waterfall-name-width` (default `8rem`),
+`--lr-span-waterfall-stripe-speed` (a `running` span's striped-bar animation duration; defaults to
+`--lr-transition-ambient`), and `--lr-span-waterfall-row-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row.
+
+That last one follows the convention every **state-scoped** custom property in this family uses, and
+it is worth reading once: it is an inline `var()` fallback at its point of use and is deliberately
+**not** declared on `:host`, so it can be set on the element *or on any ancestor* and still reach the
+rule that consumes it. It exists because Shadow Parts forbids an attribute selector after `::part()`
+— `::part(row)[data-active]` and every selector like it is invalid CSS — so before it, the only way
+to restyle a state-dependent surface was to override a library-wide `--lr-color-*` token, which repaints
+every other surface reading that token. Every `*-active-*`, `*-selected-*` and per-state color
+property below works the same way.

package/llms/components/lr-sparkline.md

@@ -0,0 +1,60 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-sparkline`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/sparkline/sparkline.js';` (registers the tag; side-effect import)
+- **Class** `LyraSparkline`, also available unregistered from `@aceshooting/lyra-ui/components/data/sparkline/sparkline.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-sparkline`
+
+Zero-dependency inline SVG trend chart (mirrors `<wa-sparkline>`).
+
+**Properties:**
+- `values: number[] = []`
+- `type: 'line' | 'bar' | 'area' = 'line'`
+- `min?: number` (defaults to data minimum)
+- `max?: number` (defaults to data maximum)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
+  generated summary on the internal SVG
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `line`, `area`, `bar`
+
+**Themeable custom properties:** `--lr-color-brand` (pure CSS cascade, no JS/`getComputedStyle`
+bridging needed), `--lr-sparkline-stroke-width` (default `1.5` — stroke width of the line/area
+path), and `--lr-sparkline-area-opacity` (default `0.15` — fill opacity of the area under the
+line, `type="area"` only).
+
+**Optional peer deps:** none.
+
+```html
+<lr-sparkline type="area"></lr-sparkline>
+<script>
+  document.querySelector('lr-sparkline').values = [3, 5, 4, 8, 6, 9, 7];
+</script>
+```
+
+**Known gotchas:**
+- The semantic `role="img"` and accessible name live on the SVG that owns the graphic. The generated
+  summary is localized, formats the last value with `effectiveLocale`, and can be replaced through
+  `accessibleLabel`/host `aria-label`. It remains a concise summary rather than a tabular fallback.
+- flat data (every value equal, so the auto-computed range spans zero) now renders a centered
+  midline/mid-height bars instead of collapsing every point to the bottom edge, and a single-value
+  series renders a visible flat line (a zero-length path was previously invisible). **Every** `type`
+  (`line`/`area`/`bar`) decimates a `values` array past 500 points down to at most 500 plotted
+  samples — evenly sampled by index, always keeping the first and last value exactly, not
+  aggregated/averaged. `type="bar"` caps at 500 rendered `<rect>`s directly; `line`/`area` cap the
+  point count baked into the single `<path>`'s `d` string instead (an uncapped path string also
+  grows unbounded, even though the element count stays at one `<path>`). Auto `min`/`max` is still
+  scanned from the *full* pre-decimation `values` array, so a real extreme value that decimation
+  happens to drop can't silently narrow the rendered scale.
+
+---

package/llms/components/lr-spinner.md

@@ -0,0 +1,32 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-spinner`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/spinner/spinner.js';` (registers the tag; side-effect import)
+- **Class** `LyraSpinner`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/spinner/spinner.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-spinner`
+
+An indeterminate busy indicator with a localized `role="status"` name.
+
+**Properties:** `labelPlacement: 'none' | 'after' = 'none'` (attribute `label-placement`, reflected)
+and `accessibleLabel: string | null = null` (attribute **`aria-label`**, not `accessible-label`) —
+names `[part="base"]`'s `role="status"`; unset falls back to the localized "Loading…".
+
+**Events:** none.
+
+**Slots:** default — optional label text. `label-placement="after"` renders it inline next to the
+indicator; `'none'` (the default) keeps it visually clipped but still in the DOM.
+
+**CSS parts:** `base` (the `role="status"` wrapper), `spinner` (the animated ring; `aria-hidden`),
+`label` (the default-slot wrapper).
+
+**Themeable custom properties:** `--lr-spinner-size` (default `--lr-size-1-25rem` — both
+dimensions), `--lr-spinner-track-width` (default `--lr-border-width-medium` — ring thickness),
+`--lr-spinner-duration` (default `800ms` — one full rotation; the animation is dropped entirely
+under `prefers-reduced-motion: reduce`). The ring colors come from `--lr-color-brand`/`-brand-quiet`.

package/llms/components/lr-split.md

@@ -0,0 +1,233 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-split`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/split/split.js';` (registers the tag; side-effect import)
+- **Class** `LyraSplit`, also available unregistered from `@aceshooting/lyra-ui/components/layout/split/split.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-split`
+
+Resizable panels for dashboard layouts. Direct **light-DOM children are the panels**; a divider is
+auto-inserted between each adjacent pair.
+
+**Properties:**
+- `sizes: number[] = []` (attribute: false — percentages per panel, auto-computed equally if
+  omitted/mismatched)
+- `defaultSizes: number[] = []` (attribute: false) — initialization-only fallback: a valid restored
+  `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal distribution.
+  Later reassignment never overwrites live drag/persisted state — set it once, at mount.
+- `min: number = 10` (min % per panel)
+- `orientation: 'horizontal'|'vertical' = 'horizontal'` (reflected) — the axis used at/above
+  `orientationBreakpoint` (or always, when that's unset).
+- `orientationBreakpoint?: number | string` (attribute `orientation-breakpoint`) — opt-in inline-size
+  breakpoint measured on `[part='base']`; unset (the default) means no behavior change at all, and
+  no `ResizeObserver` is armed. Below it, `narrowOrientation` becomes the effective axis instead of
+  `orientation`. Accepts a bare pixel number (`900`, `orientation-breakpoint="900"`) or a CSS length
+  string: `'900px'`, `'56.25rem'`, `'3em'`. Under the default `orientationBreakpointBasis='container'`,
+  `rem` resolves against the document root's **computed** font size (the rule a `@container` query
+  follows) and `em` against this element's own computed font size. The length is **re-resolved on
+  every measurement**, never cached at first render, so a root font-size change moves the crossing
+  width with no invalidation step on the consumer's side. Anything that isn't a resolvable length
+  behaves exactly as unset (no observation, no `data-effective-orientation`): `''`, `'auto'`,
+  garbage, a non-finite number, and deliberately `%`, `vw`/`vh` and `calc()` — a viewport-relative
+  threshold would mix reference boxes against a measurement of the element's own allocation. For a
+  genuinely viewport-relative breakpoint set `orientationBreakpointBasis='viewport'` instead.
+- `orientationBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
+  `orientation-breakpoint-basis`) — which box `orientationBreakpoint` is compared against. Unset,
+  behavior is identical to before this property existed. `'container'` measures this component's own
+  `[part='base']` via `ResizeObserver` and compares strictly `<`. `'viewport'` evaluates
+  `matchMedia('(max-width: <breakpoint>)')` and arms no `ResizeObserver` for the orientation feature
+  at all, so the shared observer stays armed only for `collapse`; its comparison is inclusive (`<=`),
+  because that is what native `max-width` means — deliberate, so the crossing point matches a CSS
+  `@media` rule authored with the same length exactly.
+  **`rem`/`em` mean different things under the two bases, and this is the reason `'viewport'` exists.**
+  Inside a media query, relative units resolve against the browser's *initial* font size and ignore
+  any `html { font-size }` override; under `'container'` they resolve against live computed font
+  sizes. The two agree unless an app re-points the root font size. So when the breakpoint must stay
+  in lockstep with a CSS `@media` rule, `'viewport'` is the exact match — the browser evaluates the
+  same query, live, across browser zoom and user font-size preferences, with no px re-derivation.
+- `narrowOrientation: 'horizontal'|'vertical' = 'vertical'` (reflected, attribute `narrow-orientation`)
+- `effectiveOrientation: 'horizontal'|'vertical'` (readonly getter) — the live resize/layout axis
+  actually in effect; identical to `orientation` whenever `orientationBreakpoint` is unset or
+  doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
+  `orientationBreakpoint` resolves to a usable length).
+- `storageKey?: string` (attribute `storage-key` — persists sizes to `localStorage` under
+  `` `lr-split:${key}:${panelCount}` ``, scoped by panel count so a stale layout for a different
+  panel count is ignored)
+- `panelConstraints: (PanelConstraint | null)[] = []` (attribute: false) — `PanelConstraint { minPx?:
+  number; maxPx?: number; minPercent?: number; maxPercent?: number }`, index-aligned with `sizes`; a
+  `null`/missing entry (or an omitted bound within an entry) leaves that side of that panel purely
+  percent-based (the existing `min`-only behavior). Combining a px and a percent bound on the same
+  side resolves to the stricter one (larger for min, smaller for max) via a native CSS `max()`/`min()`
+  in the rendered `clamp()` flex-basis. `sizes`, the `lr-resize` payload, and localStorage persistence
+  stay percent-based regardless — only the effective drag/keyboard clamp bounds (and the rendered
+  `flex-basis`, via a native CSS `clamp()` so a constrained panel stays pinned between its bounds
+  across container resizes with no extra `ResizeObserver`) change for a constrained panel.
+- `collapse: 'start'|'end'|'none' = 'none'` (reflected) — opt-in responsive collapse for one panel:
+  `'start'`/`'end'` is a *logical* position (RTL-aware, matching CSS logical properties — the panel at
+  the document's visual leading/trailing edge, not a raw array index). `lr-split` only owns the
+  width-collapse mechanics/state signaling below; it renders no icon-only UI itself — the collapsing
+  panel's own slotted content is expected to adapt itself (e.g. via its own `@container` query reading
+  the panel's clamped width or `data-collapse-state`, see below).
+- `railWidth: string = '3.5rem'` (attribute `rail-width`) — the fixed CSS length the collapsing panel
+  clamps to in `'rail'` state.
+- `railBreakpoint: number | string = 640` (attribute `rail-breakpoint`) — below this width, the
+  collapsing panel switches from its normal drag-resizable percent width to the fixed `railWidth`.
+  Accepts a bare pixel number (`640`, `rail-breakpoint="640"` — the original form) or a CSS length
+  string: `'640px'`, `'68.75rem'`, `'3em'`. Under the default `collapseBreakpointBasis='container'`
+  it is compared against this component's own measured `[part='base']` inline size (a
+  `ResizeObserver`, active only while `collapse !== 'none'`), and `rem` resolves against the
+  document root's **computed** font size while `em` resolves against this element's own; the length
+  is re-resolved on every measurement, never cached. Anything the grammar rejects — `''`, `'auto'`,
+  garbage, a non-finite number, and deliberately `%`, `vw`/`vh`, `calc()` and `var()` — falls back
+  to the `640` default rather than switching the feature off (unlike `orientationBreakpoint`, this
+  breakpoint has a documented default to fall back to). A negative length is floored at `0`, i.e.
+  never crossed. Must stay above `floatBreakpoint` — an inverted pair is sanitized by raising this
+  one to match, collapsing the `'rail'` band away rather than reporting a wide container as
+  collapsed.
+- `floatBreakpoint: number | string = 400` (attribute `float-breakpoint`) — below this narrower
+  width, the collapsing panel instead becomes an absolutely-positioned overlay ("floating card") on
+  top of the other pane(s), removed from the normal flex flow; the sibling(s) take the full width.
+  Same accepted forms, basis, and sanitization as `railBreakpoint`; an unparseable value falls back
+  to the `400` default.
+- `collapseBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
+  `collapse-breakpoint-basis`) — which box `railBreakpoint`/`floatBreakpoint` are measured against.
+  Unset, behavior is identical to before this property existed. `'container'` observes this
+  component's own `[part='base']` inline size via `ResizeObserver` and compares strictly `<`;
+  `'viewport'` evaluates `matchMedia('(max-width: <breakpoint>)')` for each of the two thresholds,
+  which is inclusive (`<=`) — native `max-width` semantics, deliberately, so the crossing point
+  matches a CSS `@media` rule authored with the same length exactly. Use `'viewport'` to collapse in
+  step with a page-level responsive layout (a shell whose own `@media` rules restack at the same
+  width) rather than with this split's own allocation; it is also what lets the browser resolve a
+  `rem` breakpoint with real `@media` semantics (against the *initial* font size, ignoring an
+  `html { font-size }` override). Both bands are classified from both queries together on every
+  change, so a fast resize crossing both thresholds at once still lands on one correct state and
+  fires `lr-split-collapse-change` once; under `'viewport'` the first paint is already correct — no
+  `ResizeObserver` round-trip — and that initial state is not announced as a transition.
+- `collapseState: 'wide'|'rail'|'floating'` (reflected, attribute `collapse-state`) — a public
+  accessor with force/auto semantics mirroring `<lr-app-rail>`'s `mode`: normally derived
+  automatically from the measured container width, but assigning it a concrete value pins it there
+  (stopping automatic breakpoint tracking) — useful for a consumer-driven toggle (e.g. a button that
+  forces `'floating'` regardless of width). Assigning the write-only `'auto'` sentinel releases the
+  pin and immediately re-derives the state from the current measured width; the getter never returns
+  `'auto'`.
+- `open: boolean = false` (reflected) — whether the `'floating'` collapse state's drawer is shown.
+  While `collapseState` is `'floating'` and `open` is `false` (the default), the collapsing panel
+  renders nothing (`hidden`, out of the accessibility tree) instead of the always-visible overlay
+  card this state rendered before `open` existed. Setting `open = true` reveals it as a
+  focus-trapped floating panel with a `[part="backdrop"]` scrim; Escape or a backdrop click set
+  `open` back to `false`. Leaving `'floating'` while `open` is still `true` also closes it, the same
+  way `<lr-app-rail>` closes its mobile overlay when leaving `'mobile'` while open.
+
+`collapse`'s three resulting states — `'wide'` (default, today's plain layout) / `'rail'` / `'floating'`
+— are exposed as: a `data-collapse-state` attribute on both the host and the collapsing panel element
+itself (absent for `'wide'`/`collapse="none"`); and the `lr-split-collapse-change` event below. The
+divider adjacent to the collapsed panel is drag/keyboard-disabled (`aria-disabled="true"`) while
+collapsed. `collapse="none"` (the default) is byte-for-byte identical to pre-collapse-feature behavior.
+
+`dividerLabel?: (index: number, panelCount: number) => string` (attribute: false) customizes the
+localized accessible label generated for each auto-inserted divider.
+
+**Events:** `lr-resize` (`detail: { sizes }`, fired on every drag step/release **and** every
+keyboard step), `lr-split-collapse-change` (`detail: { state: 'wide'|'rail'|'floating' }`, fired only
+on a real `collapse`-state transition, never on every resize/render),
+`lr-split-constraints-invalid` (`detail: SplitConstraintIssueDetail`, fired once when the configured
+panel minimums/maximums cannot fit the track; the infeasible set is rejected for interaction and a
+normalized percent minimum is used instead), `lr-split-orientation-change` (`detail: { orientation }`,
+fired only when an enabled `orientationBreakpoint` actually changes `effectiveOrientation`)
+
+**Slots:** default (each direct child element is one panel).
+
+**CSS parts:** `base` (`position: relative`, so the `'floating'` state can anchor to it), `divider`
+(carries `aria-disabled="true"` and is drag/keyboard-inert while its adjacent panel is collapsed),
+`backdrop` (the `'floating'` drawer's scrim — only rendered while `collapseState === 'floating'` and
+`open`)
+
+**Themeable custom properties:** `--lr-split-overlay-color` (default `var(--lr-color-overlay)`) —
+the `'floating'` drawer's `[part='backdrop']` scrim; scoped to `[part='base']`, not the viewport.
+Otherwise shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-split storage-key="dashboard-main" min="15">
+  <div>Panel A</div>
+  <div>Panel B</div>
+  <div>Panel C</div>
+</lr-split>
+```
+
+Keyboard: focus a divider (`Tab`), then `ArrowRight`/`ArrowLeft` (horizontal) or
+`ArrowDown`/`ArrowUp` (vertical) to resize by a fixed 2% step — RTL-aware for horizontal layouts
+(under `direction: rtl`, the forward/backward keys and drag-delta sign both swap so they still track
+the visually-adjacent panel).
+
+**Known gotchas:**
+- `panelCount` now reacts to `slotchange` (not just the initial `connectedCallback()` read), and
+  `ensureSizes()` rebalances existing sizes proportionally when a panel is added or removed after
+  mount instead of discarding the whole layout — a conditionally-shown side panel no longer leaves
+  `panelCount`/`sizes`/divider count stale.
+- divider `aria-valuemax` is now computed per adjacent pair (`sizes[i] + sizes[i+1] - min`) rather
+  than a blanket `100 - min`, so it's accurate for 3+-panel layouts too, not just exactly two panels
+  — this formula still only accounts for the plain percent `min`, though: with `panelConstraints`
+  set, a panel's real achievable range can be narrower (or expressed in px) than what
+  `aria-valuemin`/`aria-valuemax` report. Each divider also now has its own `aria-label` ("Resize
+  divider between panel N and panel N+1") distinguishing it from any other divider in a
+  multi-divider layout.
+- infeasible aggregate constraints (for example, three panels with `min=40`) are reported through
+  `lr-split-constraints-invalid`; interaction rejects that set and uses a normalized percent minimum
+  with aggregate slack, so the divider remains operable instead of silently freezing.
+- concurrent drags are tracked per `pointerId` (not a single scalar), so a multi-touch drag on two
+  different dividers moves both independently instead of the second pointer clobbering the first's
+  drag state; `pointercancel`/`lostpointercapture` (not just `pointerup`) both end a drag.
+- `localStorage.getItem`/`setItem` calls are now both wrapped in their own `try`/`catch` (in addition
+  to the `JSON.parse` result already being caught), so a blocked or quota-exceeded store fails
+  silently instead of throwing from inside a `pointerup`/`keydown` handler. A persisted layout whose
+  panel count no longer matches, or whose sizes are already below the current `min` floor, is
+  rejected rather than restored.
+- Pointer-drag lifecycle (pointer capture, window-listener cleanup on both drag-end and
+  `disconnectedCallback`) is solid and safe to rely on.
+- `orientationBreakpoint` shares its `[part='base']` `ResizeObserver` with `collapse` (one observer,
+  not two) — arming logic covers either feature being opted into independently.
+- **Switching a basis moves the crossing point by exactly 1px.** Container basis compares strictly
+  `<` against a measured width; viewport basis asks `matchMedia('(max-width: …)')`, which is
+  inclusive (`<=`). So at a breakpoint of `640`, a container-basis split is still `'wide'` at 640px
+  while a viewport-basis one has already collapsed. This is deliberate on both sides: `<` is the
+  right comparison for "how much room do I actually have", and `<=` is what a CSS `@media` rule with
+  the same length does, which is the whole point of the viewport basis.
+- `collapseBreakpointBasis='viewport'` does **not** drop the `ResizeObserver` the way the
+  orientation feature's viewport basis does. The measured width it feeds is still read by a
+  container-basis `orientationBreakpoint` and by the `collapseState = 'auto'` release path, which
+  re-derives from the current measured width. Collapse's basis changes only *which values* the
+  classification consults, never whether the split measures itself.
+- `railBreakpoint`/`floatBreakpoint` are typed `number | string`. Authored as attributes they read
+  back as **strings** (`el.railBreakpoint === '640'`, not `640`) — the same value, a different type.
+  Compare with `Number(el.railBreakpoint)` rather than `===`, or assign the property directly when a
+  numeric identity matters.
+- **Picking a basis.** `orientationBreakpointBasis='container'` (the default) observes the
+  component's own allocated inline size, so it fits a component that is the sole flex/grid item in
+  the container being measured. It does **not** fit a component sitting beside a fixed-width sibling
+  in a row that stacks via a CSS `@media` rule: while the row is a row, this element's width shrinks
+  with the viewport; the instant the row stacks (a pure-CSS event no component can observe) it jumps
+  to the *full* row width — wider than it was just before the transition. Because the measured width
+  is not monotonic across that transition, no single container threshold both stays wide while the
+  row is a row and goes narrow exactly when it stacks. A fixed-width sibling is worse still: its own
+  width never changes with the viewport at all, so no container breakpoint on it can react to the
+  stacking.
+  That layout is what `orientationBreakpointBasis='viewport'` is for. Give every sibling the same
+  `orientation-breakpoint` and `orientation-breakpoint-basis='viewport'` and they flip together, in
+  lockstep with the CSS rule that stacks the row:
+  ```html
+  <lr-stepper orientation-breakpoint="56.25rem" orientation-breakpoint-basis="viewport"></lr-stepper>
+  <lr-split   orientation-breakpoint="56.25rem" orientation-breakpoint-basis="viewport"></lr-split>
+  <style>@media (max-width: 56.25rem) { .shell { flex-direction: column; } }</style>
+  ```
+  A consumer-side `matchMedia()` controller driving the `orientation` attribute directly is still
+  supported and still correct — it is simply no longer required for this case.
+
+---