@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,234 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-virtual-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraVirtualList`, also available unregistered from `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.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-virtual-list`
+
+A generic windowed/virtualized list host. Renders only the items within the current viewport (plus
+`overscan` padding rows on each side) as real DOM, regardless of how large `items` is, so a
+multi-thousand-row chat-history sidebar (or a long message thread) stays cheap to scroll. Content is
+entirely caller-supplied: `renderItem(item, index)` returns whatever `lit-html` value should represent
+that row, and `keyFunction(item, index)` gives it a stable identity for DOM reconciliation. First-party
+invention (no Web Awesome equivalent).
+
+**Properties:**
+- `items: unknown[] = []` (attribute: false) — the full, non-windowed item collection. JS-only; set via
+  a property/lit-html binding (`.items=`), not an HTML attribute.
+- `renderItem: (item: unknown, index: number) => unknown = () => nothing` (attribute: false) — renders
+  one row's content, typically returning a `lit-html` `TemplateResult`. JS-only.
+- `keyFunction?: (item: unknown, index: number) => string | number` (attribute: false) — derives a
+  row's stable reconciliation key. JS-only. Falls back to the item's index in `items` when omitted,
+  which is only a safe identity while `items` never reorders/inserts/removes — provide this whenever
+  possible, or scroll position and per-row DOM state (e.g. an `<audio>` element's playback position)
+  can attach to the wrong row across a mutation.
+- `groups?: VirtualListGroup[]` (attribute: false) — renders a labeled marker at each group's
+  `startIndex`, positioned independently of the row window (so it stays in place as its rows scroll
+  past). Groups are sorted by `startIndex`; a `startIndex` that's non-integer, out of range, or a
+  duplicate of an earlier group's is silently dropped rather than rendered wrong. An entry whose
+  `label` is the **empty string** renders no marker at all — it is a pure position anchor, for a host
+  that renders its own group header as an ordinary row (and would otherwise end up with two stacked
+  headers) but still needs this component to know where each group starts, e.g. to drive
+  `renderStickyGroup` below. Omitting `label` entirely still falls back to rendering `key`.
+- `renderStickyGroup?: (group: VirtualListGroup) => unknown` (attribute: false) — renders a pinned
+  copy of whichever `groups` entry the viewport is currently inside, into a `[part="sticky-group"]`
+  overlay that stays at the top of the scroll viewport and is pushed out by the overlap as the next
+  group's header arrives (rather than swapped abruptly at the boundary). Native `position: sticky` on
+  the rows or markers themselves cannot do this: every row is absolutely positioned and
+  transform-offset by the windowing math, which makes sticky structurally inert. Unset (the default)
+  renders no overlay element whatsoever and changes nothing about the list's output. The overlay is a
+  *visual copy* of content that already exists in the list, which fixes its contract:
+  - it is `aria-hidden`, and ordinary focusable HTML inside it is forced to `tabindex="-1"`, so the
+    real row keeps sole ownership of the heading semantics and of the tab order (a focus-delegating
+    custom element rendered into the copy needs its own `tabindex="-1"`; `inert` is deliberately not
+    used, because it would also block the pointer opt-in below);
+  - it is `pointer-events: none` by default — opt back in with
+    `lr-virtual-list::part(sticky-group) { pointer-events: auto; }` when the copied header content is
+    interactive;
+  - it is never measured as a row, so a group header that is also a real row is not double-counted in
+    `row-height="auto"` mode;
+  - its measured height is applied as `scroll-padding-block-start` on the scroll container and
+    subtracted from top-aligned scroll targets, so `active-id`, `scrollToIndex({ align: 'start' })`
+    and native keyboard scrolling all stop *below* the band instead of parking the row behind it.
+
+  The callback runs on every scroll-driven update, so keep it cheap and side-effect free. While the
+  viewport is above the first group there is nothing to pin: the band shows nothing, but it stays
+  mounted (called with the first group, rendered hidden) so its height is known before the first
+  programmatic jump rather than only after it.
+- `rowHeight: string = 'auto'` (attribute `row-height`) — `'auto'` measures each row's real height via
+  `ResizeObserver`; a numeric string (e.g. `"56"`) fixes every row to that many pixels. Anything else
+  (non-numeric, zero, negative, non-finite) silently falls back to `'auto'` rather than throwing.
+- `itemRole: 'listitem' | 'row' = 'listitem'` (attribute `item-role`) — `'listitem'` (default)
+  preserves the plain `role="list"`/`role="listitem"` mapping with `aria-setsize`/`aria-posinset`.
+  `'row'` additionally maps `[part="base"]` to `role="rowgroup"`, `[part="spacer"]` to
+  `role="presentation"`, and each row to `role="row"` with `aria-rowindex` instead — for a consumer
+  composing its own `role="table"` wrapper and header row around this component (see
+  `lr-dataset-viewer`).
+- `rowIndexOffset: number = 0` (attribute `row-index-offset`) — added to a row's 1-based index to
+  compute `aria-rowindex` in `item-role="row"` mode (e.g. `1` when a consumer renders its own header
+  row occupying `aria-rowindex="1"` outside this component). No effect in `'listitem'` mode.
+- `overscan: number = 6` — extra rows rendered beyond the visible viewport on each side; finite
+  values are floored and clamped to 0–100, while non-finite values use the default 6, so an invalid
+  runtime value cannot disable windowing and render the entire collection.
+- `activeId: string = ''` (attribute `active-id`) — when set and it matches a row's `keyFunction`
+  result (compared with `Object.is` against the typed value — attribute values arrive as strings, so
+  assign the property directly for a numeric key), that row is smoothly scrolled into view whenever
+  this changes, and rendered with `aria-current="true"`.
+- `loading: boolean = false` (reflected) — sets `aria-busy` on the scroll container and a `cursor:
+  progress` style; does not by itself gate `lr-load-more` (see below).
+- `hasMore: boolean = false` (attribute `has-more`, reflected) — when true, scrolling near the bottom
+  fires `lr-load-more` (gated by `loading`).
+
+**Exported types:** `VirtualListRange { start: number; end: number }` (the `lr-visible-range-changed`
+detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
+shape consumed by `groups` above; `VirtualListScroll { scrollTop: number; viewportHeight: number }` —
+the `lr-scroll` detail shape.
+The package root also exports `groupByRecency(items, options?)`, a DOM-free helper that returns
+non-empty Today/Yesterday/Previous 7 Days/Older buckets, preserves input order within each bucket,
+and accepts a timestamp extractor, reference date, and label overrides.
+
+**Methods:** `scrollToIndex(index, options?)` — the programmatic counterpart to `active-id`'s
+automatic scroll-into-view, for a host that needs to scroll to a specific row without changing which
+row is "active." `options.align` is `'start'`, `'end'`, or `'auto'` (default — no scroll at all when
+already fully visible); `options.behavior` (default `'smooth'`) is forced to `'auto'` under
+`prefers-reduced-motion: reduce`. `index` is clamped to `0…items.length-1`.
+`offsetForIndex(index)` returns the pixel top row `index` renders at, in the same coordinate space as
+the scroll container's `scrollTop`; it is clamped to `0…items.length`, so `offsetForIndex(items.length)`
+is the total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
+row whose box contains that offset, clamped at both ends, `-1` for an empty list — so
+`indexAtOffset(offsetForIndex(i)) === i` and `indexAtOffset(scrollContainer.scrollTop)` is the row at
+the top of the viewport. In `row-height="auto"` mode both are estimate-based for any row that (or
+above which) has not been measured yet, and converge as those `ResizeObserver` measurements land;
+fixed numeric `row-height` offsets are exact from the first render. Both read the most recent render,
+so `await el.updateComplete` after assigning `items` before querying.
+
+**Getters:** `scrollContainer: HTMLElement | undefined` — the real scroll container (`[part="base"]`),
+`undefined` before the first render; for a host that needs the live scroll position or wants to scroll
+the list itself without reaching into the shadow root. `renderedRows: HTMLElement[]` — the row
+wrappers (`[part="row"]`) that currently exist as real DOM, in item order (the current window, not the
+whole collection; empty before the first render). It exists for hosts that must *reach* a rendered row
+rather than style it — keyboard focus management across a windowed list, where the row to focus may
+not have existed a frame earlier, and which `exportparts` cannot serve since it forwards styling, not
+element references. Treat both as read-only: positioning, keys, and lifetime belong to the windowing
+math, and any row element can be recycled or removed on the next update.
+
+**Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
+`has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
+bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
+window away from the end, re-arms it), `lr-visible-range-changed` (`detail: VirtualListRange`, the
+current visible, non-overscanned item index range — fired only when it actually changes), `lr-scroll`
+(`detail: VirtualListScroll` — the scroll container moved; emitted from the same animation frame that
+already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
+when the position did not change. Unlike `lr-visible-range-changed`, which only fires on index-range
+changes, this reports *sub-row* movement, which is what scroll-linked layout needs)
+
+**Slots:** none — all content comes from `renderItem`.
+
+**CSS parts:** `base` (the scrollable container, `role="list"` — or `role="rowgroup"` in
+`item-role="row"` mode — `tabindex="0"`), `spacer` (the full-content-height inner element
+establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
+rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
+`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned marker; not
+rendered for an entry whose `label` is the empty string), `sticky-group` (the pinned copy of the
+current group, present only while `renderStickyGroup` is set — `aria-hidden` and
+`pointer-events: none` by default; style it with `pointer-events: auto` to make copied interactive
+content clickable, and it shows nothing while the viewport is above the first group)
+
+**Themeable custom properties:** `--lr-virtual-list-height` (default `24rem` — the host's bounded
+scroll extent; component-specific since a virtualized list is meaningless without a sized viewport),
+plus shared `--lr-focus-ring-width/-color/-offset` (inward-offset ring on `[part="base"]`, negative
+so it isn't clipped by the container's own `overflow: auto`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-virtual-list
+  .items=${sessions}
+  .renderItem=${(item, index) => html`
+    <lr-conversation-item
+      id=${item.id}
+      title=${item.title}
+      .timestamp=${item.updatedAt}
+      ?active=${item.id === currentId}
+    ></lr-conversation-item>
+  `}
+  .keyFunction=${(item) => item.id}
+  active-id=${currentId}
+  ?has-more=${hasMorePages}
+  ?loading=${isLoadingMore}
+  @lr-load-more=${() => loadNextPage()}
+  @lr-visible-range-changed=${(e) => console.log('visible', e.detail.start, e.detail.end)}
+></lr-virtual-list>
+```
+
+```html
+<!-- Sticky group headers: the header is a real row, so the `groups` entries are position anchors
+     only (`label: ''`), and the pinned copy opts back into pointer events for its own toggle. -->
+<lr-virtual-list
+  .items=${rows}
+  .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
+  .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
+  .renderStickyGroup=${(group) => headerTemplate(group)}
+></lr-virtual-list>
+<style>
+  lr-virtual-list::part(sticky-group) { pointer-events: auto; }
+</style>
+```
+
+Every row — in both `row-height` modes — is positioned by a `transform: translateY(offset)` computed
+from a single cumulative offsets array, rather than by page flow; this is what lets a small DOM window
+exist while the scrollbar still reflects the true total content height. That array is rebuilt only
+when `items`, `row-height`, or `keyFunction` change, or a row's measured height changes — **not** on
+every update, so a pure scroll-position tick (potentially every `rAF` while scrolling) only re-runs the
+cheap range/visibility math, never the `O(n)` offsets rebuild (which, in `row-height="auto"` mode, also
+means a `keyFunction` call per item). In `row-height="auto"` mode, unmeasured rows contribute a fixed
+estimate to that array until their real `ResizeObserver`-reported height lands, so only rows after a
+newly-measured one shift on each measurement rather than the whole list reflowing. The offsets rebuild,
+when it does run, is an `O(n)` loop appropriate for hundreds to a few thousand rows (a scrollable
+history sidebar); it is not the right approach for a hundred-thousand-row list without further work
+(e.g. a Fenwick/segment tree for `O(log n)` offset queries+updates).
+
+**Known gotchas:**
+- `items`, `renderItem`, `keyFunction`, and `groups` are all `attribute: false` — they must be set as
+  JS properties (`.items=`, `.renderItem=`, …), never as HTML attribute strings.
+- The container is `role="list"` with rows `role="listitem"`, deliberately not `listbox`/`option` —
+  this component only provides windowing, not the roving-tabindex/`aria-activedescendant`
+  keyboard-interaction contract a real `listbox` requires. `active-id` only scrolls a row into view and
+  marks it `aria-current`; it is not a selection widget. Compose your own selection behavior on top if
+  needed.
+- `[part="base"]` carries `tabindex="0"` unconditionally, since `renderItem`'s caller-supplied content
+  isn't guaranteed to contain a focusable element and an otherwise-unreachable-by-keyboard scroll
+  region would result.
+- `aria-setsize`/`aria-posinset` are computed from a row's real index in the full `items` array, not its
+  position among the currently-rendered DOM window, so assistive tech still announces e.g. "item 12 of
+  340" correctly even though only a handful of rows exist in the DOM at a time.
+- `groups`, `renderStickyGroup`, `offsetForIndex()`/`indexAtOffset()` and the `lr-scroll` event are
+  all expressed against the *same* windowing math, so they agree with each other — but that math is
+  estimate-based in `row-height="auto"` mode until the rows involved have been measured. Read a
+  position after `await el.updateComplete`, and expect the value to converge rather than be final on
+  the first frame.
+- A sticky band only appears when `renderStickyGroup` *and* at least one valid `groups` entry are
+  both present; `groups` alone renders positioned markers with nothing pinned, and
+  `renderStickyGroup` alone renders no overlay element at all.
+- **A row that renders a popup needs the focused-row lift, and this is why `[part='row']` has one.**
+  Each row carries `will-change: transform` (a compositor hint for the per-frame translate), which
+  makes every row its own stacking context. Rows otherwise carry no `z-index`, so they paint in DOM
+  order and each one paints over the previous. Anything a row renders that overflows its own box —
+  an `<lr-menu>` popup in a row-action menu, a tooltip, an outward focus ring — is therefore painted
+  *underneath* every following row, no matter how high its own `z-index` is: that `z-index` only
+  orders siblings inside the row's own context. The last row always looks correct, which is exactly
+  why a short fixture never catches it. `[part='row']:focus-within` lifts the row to
+  `--lr-layer-content` for precisely as long as something inside it holds focus — the lifetime of an
+  open popup — and costs nothing otherwise. The value deliberately *matches* `[part='group']`'s
+  rather than exceeding it, so the two land on the same layer and DOM order decides: groups render
+  before the rows, so a focused row wins while (and only while) it holds focus, which is right — a
+  group header is a non-interactive `pointer-events: none` label.
+
+---

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

@@ -0,0 +1,86 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-voice-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/voice-picker/voice-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraVoicePicker`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/voice-picker/voice-picker.class.js`
+- **Family** `components/conversation/` — 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-voice-picker`
+
+A TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s
+closed-dropdown/free-text-combobox dual mode, stale-value handling, and form-association verbatim
+(see that section for the full mode-switching contract this one shares), extended with a
+TTS-agnostic preview affordance. Preview is event-first: `lr-preview-request` always fires first
+and is cancelable — left un-prevented, a `previewUrl` plays through one internal native `<audio>`
+(validated by `safeMediaSrc()` first); `preventDefault()` or no URL leaves playback to the host's own
+TTS. Requesting the same voice while it's already playing internally stops it instead of
+re-requesting; requesting a different voice switches. Does not synthesize speech, fetch catalogs, or
+persist selection; not a persona picker; `lr-model-select` stays for LLMs.
+
+**Exported types:** `LyraVoiceCatalogEntry { id: string; label: string; language?: string;
+description?: string; previewUrl?: string }` — `language`/`description` render as a quiet
+`[part="option-meta"]` second line. `LyraVoiceCatalog = string[] | LyraVoiceCatalogEntry[]` —
+homogeneous, same union contract as `LyraModelCatalog`.
+
+**Properties:** `provider: string = ''` — informational only (e.g. `'elevenlabs'`); rendered as a
+small leading badge. `catalog?: LyraVoiceCatalog` (attribute: false) — the full voice list; omit (or
+leave empty) to fall back to plain free-text entry. `allowCustom: boolean = false` (attribute
+`allow-custom`, reflected) — let the user type/commit a value that isn't in `catalog`. `preview:
+boolean = true` (reflected) — whether to render preview affordances at all. `label: string = ''`,
+`hint: string = ''`, `errorText: string = ''` (attribute `error-text`), `placeholder: string = ''`,
+`spellcheck: boolean = true` (string-aware converter, same as `lr-model-select`), `autocapitalize:
+string = ''`, `autoCorrect: string = ''` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+`inputMode: string = ''` (attribute `inputmode`), `enterKeyHint: string = ''` (attribute
+`enterkeyhint`), and `open: boolean = false` (reflected) — all mirror `lr-model-select`'s
+identically-named properties.
+
+**Form association:** hand-rolled via `attachInternals()`, mirroring `lr-model-select`: `value`
+getter/setter (the current voice id, `''` when nothing is selected), `name` (reflected), `disabled`
+(reflected), `required` (reflected — enforced via `internals.setValidity()`).
+
+**Methods:** `click()` (override) — same forwarding contract as `lr-model-select`'s own `click()`
+override (see that section for the full rationale): closed-dropdown mode forwards a real `.click()`
+to the trigger `<button>`, whose own `@click` handler opens it; free-text mode instead calls
+`.focus()` on the combobox `<input>`, since a synthetic `.click()` on a text input never dispatches
+`focus` the way a real click's `mousedown` default action does, and this mode's open behavior is
+wired to the input's native `focus` event, not a `click` handler on the input itself. Mirrors
+`<lr-button>`'s identical host `click()` forwarding.
+
+**Events:** `lr-change` — `detail: { value, inCatalog }`. `lr-preview-request` — `detail: {
+voiceId, previewUrl? }`, cancelable. `lr-preview-change` — `detail: { voiceId }`, internal playback
+started (`voiceId`) or stopped (`null`). Plus mirrored native `input`/`change` and re-dispatched
+`focus`/`blur` (picker-family contract, same as `lr-model-select`).
+
+**Slots:** `hint`, `error`.
+
+**CSS parts:** `form-control-label`, `trigger` (closed-dropdown mode), `combobox`/`combobox-input`
+(free-text mode), `provider-badge`, `listbox`, `option`, `option-label`, `option-meta` (the quiet
+`language · description` second line), `option-badge` (the "not in catalog" badge on a synthetic
+stale-value row), `option-preview` (a pointer-only per-row preview icon, `tabindex="-1"`,
+`aria-hidden`), `preview-button` (the standalone, keyboard-reachable preview toggle beside the
+trigger), `expand-icon`, `empty`, `hint`, `error`.
+
+```html
+<lr-voice-picker provider="elevenlabs" .catalog=${voices} allow-custom
+  @lr-change=${(e) => setVoice(e.detail.value)}
+  @lr-preview-request=${(e) => {
+    if (!e.detail.previewUrl) {
+      e.preventDefault();
+      playSample(e.detail.voiceId);
+    }
+  }}
+></lr-voice-picker>
+```
+
+**Known gotchas:**
+- Listbox options must not contain tab-focusable controls, so preview is accessible via the
+  standalone `[part="preview-button"]` beside the trigger (previews the active option while open,
+  else the committed value) — the per-row `[part="option-preview"]` icon is a pointer-only
+  duplicate (`tabindex="-1"`, `aria-hidden="true"`).
+- `catalog` must be homogeneous — the same constraint `lr-model-select`'s `LyraModelCatalog` union
+  documents.

package/llms/components/lr-widget-renderer.md

@@ -0,0 +1,78 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-widget-renderer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/widget-renderer/widget-renderer.js';` (registers the tag; side-effect import)
+- **Class** `LyraWidgetRenderer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/widget-renderer/widget-renderer.class.js`
+- **Family** `components/conversation/` — 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-widget-renderer`
+
+Renders an agent-streamed declarative JSON widget tree through an allowlisted `type -> lyra tag`
+registry: safe generative UI with exactly one action event out. A mapped node's real element is
+created via `document.createElement()` with every prop assigned as a plain JS property (never
+`setAttribute`, never `innerHTML`), and reused by key across a re-resolve so a mapped widget's own
+internal state (an open `<details>`, focus, scroll position) survives a streamed `tree` update.
+Built-in `row`/`col`/`text` structural nodes render through ordinary nested templates instead. Not a
+form runtime (no input/select/form types in the default registry), no expression language or
+data-binding, no remote widget/schema fetching, and it never renders arbitrary HTML or navigates (no
+`href` props are allowlisted anywhere).
+
+**Exported types:** `WidgetNode { type: string; id?: string; props?: Record<string, unknown>;
+children?: (WidgetNode | string)[]; slot?: string; actionId?: string; payload?: unknown }` — `id` is
+a stable reconciliation key (falling back to a structural path), `slot` is honored only when the
+parent type allowlists it, `actionId` arms the type's declared action trigger, and `payload` is
+echoed back in `lr-widget-action`.
+
+**Properties:** `tree: WidgetNode | null = null` (property only) — the declarative widget tree to
+render; `null` renders an empty base. `registry?: WidgetTypeRegistry` (attribute: false) — a
+per-instance override of the module-level default registry.
+
+**Registry module (`widget-renderer/registry.js`):** `registerWidgetType(type, def)` registers (or
+overwrites) a type in the default registry; `def: WidgetTypeDefinition { tag?: string; props?:
+Record<string, 'string' | 'number' | 'boolean'>; forcedProps?: Record<string, unknown>; slots?:
+string[]; action?: { event: string } }` — `tag` is resolved prefix-aware, `props` is a prop allowlist
+(a prop absent here, or whose runtime type doesn't match, is silently skipped — never assigned),
+`forcedProps` always apply and are never overridable by `WidgetNode.props`, `slots` allowlists child
+`slot` names (a disallowed one renders unslotted rather than being dropped), and `action.event` is
+the native/custom DOM event that arms `lr-widget-action` when a node also sets `actionId`.
+`getDefaultWidgetTypeRegistry()` returns the module-level registry `registerWidgetType()` writes to.
+
+**Default registry** (populated by the side-effect entry's `registerDefaultWidgetTypes()`): `text`
+(plain text node), `row`/`col` (internal flex wrappers; props `gap: 's'|'m'|'l'`, `align:
+'start'|'center'|'end'|'stretch'`, `justify: 'start'|'center'|'end'|'between'`), `card` →
+`lr-card` (`appearance`), `badge` → `lr-badge` (`variant`), `button` → `lr-button` (`variant`,
+`appearance`, `size`, `disabled`, `loading`; action: `click`), `stat` → `lr-stat` (`label`,
+`value`, `unit`, `variant`, `caption`, `sub`), `result-card` → `lr-result-card` (`title`),
+`result-field` → `lr-result-field` (`label`, `value`), `markdown` → `lr-markdown` (`content`;
+forced `{ sanitize: true }`), `image` → `lr-media-card` (`src`, `alt`, `filename`; forced `{ kind:
+'image' }`).
+
+**Events:** `lr-widget-action` — `detail: { actionId, payload }`, the single bubbling action
+channel. `lr-render-error` — `detail: { error }`, the root value was structurally unusable
+(non-object, or the depth/size caps made it empty).
+
+**CSS parts:** `base` (the root wrapper, `display: contents`), `row`, `col`, `text` (built-in
+structural nodes only — a mapped lyra component exposes its own parts instead).
+
+Caps: depth 32, 5,000 nodes — excess is skipped with a deduped `console.warn` per type/prop per
+instance. Reconciliation is keyed by `id ?? structural path`, so a streamed re-send patches in
+place and user state (an open `<details>`, focus, scroll) survives.
+
+```ts
+registerWidgetType('sparkline', { tag: tag('sparkline'), props: { data: 'string' } });
+```
+```html
+<lr-widget-renderer .tree=${msg.widget}
+  @lr-widget-action=${(e) => sendToAgent(e.detail.actionId, e.detail.payload)}
+></lr-widget-renderer>
+```
+
+**Optional peer deps:** none new — the default-registry entry directly imports the eight mapped
+components (`markdown` keeps its own `marked`/`dompurify` optional-peer fallback). A host wanting a
+leaner dependency graph registers a custom registry (via the `registry` property) and imports only
+the components it maps.

package/llms/components/lr-widget.md

@@ -0,0 +1,115 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-widget`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/widget/widget.js';` (registers the tag; side-effect import)
+- **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.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-widget`
+
+A titled panel shell with an optional collapse toggle and an optional fullscreen-expand toggle.
+First-party invention (no Web Awesome equivalent). Fullscreen promotes the same host element in
+place (a CSS state, not a clone/portal), so slotted content (a chart, a running simulation, scroll
+position) survives the transition.
+
+**Properties:**
+- `label: string = ''`
+- `sublabel: string = ''`
+- `collapsible: boolean = false` (reflected — shows the collapse/expand chevron button)
+- `collapsed: boolean = false` (reflected)
+- `expandable: boolean = false` (reflected — shows the fullscreen toggle button)
+- `fullscreen: boolean = false` (reflected)
+- `fullscreenInset: string = ''` (attribute `fullscreen-inset`) — raw CSS `inset` shorthand applied to
+  `[part="base"]` and `[part="backdrop"]` while fullscreen instead of the default per-side
+  `max(var(--lr-space-l), <safe-area inset>)`, e.g. `"0 0 0 240px"` to leave a 240px persistent
+  sidebar/toolbar visible during fullscreen
+- `compact: boolean = false` (reflected) — tighter header/body padding, same convention as
+  `lr-empty`'s `compact`
+- `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
+  CSS `inset` independently from `fullscreenInset`; when empty, it follows `fullscreenInset`
+- `views: WidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
+  chart/table toggle inside the same card chrome; `WidgetView { id: string; label: string; icon?:
+  TemplateResult }`. Each entry gets a header toggle button (`[part='view-toggle']`) and a
+  `<slot name="view-${id}">`. Empty (the default) renders today's single unnamed default slot as the
+  sole view, unchanged.
+- `activeView: string = ''` (attribute: false) — the currently active view's `id`; defaults to the
+  first entry of `views` (or `''` when `views` is empty). Settable directly to control the active
+  view externally; also updated internally when a view toggle is clicked.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the label-derived fullscreen
+  dialog name.
+
+**Events:** `lr-collapse-change` (`detail: { collapsed }`, the new state), `lr-fullscreen-change`
+(`detail: { fullscreen }` — also fired when fullscreen is exited via Escape or a backdrop click, not
+just the toggle button), `lr-view-change` (`detail: { viewId }`, the new active view's `id` — fired
+when it changes via a header view-toggle click, not when a consumer sets `activeView` directly)
+
+**Slots:** default (the panel body, rendered only while `views` is empty), `icon` (optional leading
+icon in the title row), `label` (rich label content, overrides the `label` attribute), `sublabel`
+(rich sublabel content, overrides the `sublabel` attribute), `actions` (header action controls,
+rendered before the collapse/expand buttons), `collapse-icon` (replaces the built-in chevron in the
+collapse toggle via native slot fallback; only meaningful while `collapsible`), `fullscreen-icon`
+(replaces the built-in glyph in the fullscreen toggle — the override replaces *both* the "expand"
+and "exit fullscreen" defaults, so the consumer owns that distinction, e.g. by reading the
+`fullscreen` attribute; only meaningful while `expandable`), and one `view-{id}` slot per `views`
+entry, used instead of the default slot
+
+**CSS parts:** `base`, `header`, `title`, `icon` (wrapper around the `icon` slot, hidden entirely when
+empty), `label-group` (wrapper around the label and sublabel), `label`, `sublabel`, `actions`,
+`view-toggles` (the header toggle-button group, only rendered when `views` is non-empty),
+`view-toggle` (a single view toggle button), `collapse-button`, `fullscreen-button`, `body`,
+`backdrop`
+
+**Themeable custom properties:** `--lr-widget-overlay-color` (default `var(--lr-color-overlay)` —
+the fullscreen backdrop scrim color), `--lr-widget-fullscreen-inset` (default per side
+`max(var(--lr-space-l), <safe-area inset>)` — the fullscreen `[part="base"]` inset; the
+`fullscreen-inset` attribute overrides it), and `--lr-widget-backdrop-inset` (defaults to
+`var(--lr-widget-fullscreen-inset)`; the `backdrop-inset` attribute overrides it), plus shared
+tokens (`--lr-space-*`, `--lr-color-border/-surface/-text-quiet`,
+`--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`, `--lr-focus-ring-*`).
+
+Two further properties style the pressed view toggle: `--lr-widget-view-toggle-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-widget-view-toggle-active-color` (default
+`var(--lr-color-brand)`) — the background and text color of the `aria-pressed="true"` toggle. Both
+are **state hooks**: declared as inline `var()` fallbacks at the point of use and never on `:host`,
+so setting either on the element *or on any ancestor* reaches the toggle. That shape exists because
+`::part(view-toggle)[aria-pressed='true']` is not valid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so before these hooks the only way to recolor an active toggle was to
+override the library-wide `--lr-color-brand-quiet`/`--lr-color-brand` tokens, repainting every other
+element that reads them. Left unset, each falls back to exactly the token the rule used before, so
+rendering is unchanged.
+
+**Optional peer deps:** none.
+
+```html
+<lr-widget label="Load profile" sublabel="Last 7 days" collapsible expandable>
+  <span slot="actions"><button>Refresh</button></span>
+  <div>Panel body content — a chart, a table, anything.</div>
+</lr-widget>
+```
+
+While `fullscreen`, `[part="base"]` (not the host itself) takes `role="dialog"` + `aria-modal="true"`
+(with `aria-label` from `label`, falling back to `"Fullscreen panel"`), document scroll is locked
+(ref-counted, safe with multiple simultaneously-fullscreen widgets), and Tab/Shift+Tab are bounded
+to the panel's own focusable content (`actions` slot → collapse/fullscreen buttons → body slot,
+matching visual tab order — resolved shadow-piercingly, so a slotted custom element's real
+focusable target inside its own shadow root is found too) so keyboard focus can't escape to page
+content hidden behind the backdrop. Escape or clicking the backdrop exits fullscreen and returns
+focus to whichever button triggered it. Set `fullscreen-inset` (e.g. `"0 0 0 240px"`) to reserve
+space for a persistent sidebar/toolbar that should stay visible instead of being covered by the
+fullscreen panel/backdrop — it overrides the default `var(--lr-space-l)` inset on every side for
+both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/body padding.
+
+**Known gotchas:**
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if `fullscreen` was still `true`
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- `collapsed` hides the body via `hidden` rather than an animated height transition — collapsing is
+  instant, not a slide.
+
+---

package/llms/components/lr-word-cloud.md

@@ -0,0 +1,112 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-word-cloud`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.js';` (registers the tag; side-effect import)
+- **Class** `LyraWordCloud`, also available unregistered from `@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.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-word-cloud`
+
+Dependency-free SVG word/tag cloud. First-party invention (no Web Awesome equivalent). Lays words
+out via an outward Archimedean-spiral search — heaviest word placed first, each word spiraling from
+the center until it clears every word already placed. Unlike sibling `lr-sparkline`/`lr-heatmap`
+(one `role="img"` glyph standing in for an aggregate value), the individual words here *are* the
+meaningful interactive content — but with up to `MAX_WORDS` (150) of them, making every single one
+its own tab stop would be a poor keyboard experience. Instead, like `lr-heatmap`'s cells, the whole
+`[part="svg"]` is **one tab stop with roving arrow-key focus**: `ArrowRight`/`ArrowDown` move the
+focus cursor to the next word in **declaration order** (not weight/placement order),
+`ArrowLeft`/`ArrowUp` to the previous, `Home`/`End` to the first/last, and `Enter`/`Space` fires
+`lr-word-click` for the currently-focused word. A `[part="focus-ring"]` `<rect>` is drawn around
+the focused word (absent until a word has actually been focused via keyboard or click), and a
+visually-hidden `[part="live-region"]` (`role="status" aria-live="polite"`) announces
+`"${text}, ${weight}"` on every focus move.
+
+**Properties:**
+- `words: WordCloudWord[] = []` (attribute: false) — `{ text: string, weight: number, color?:
+  string, group?: string }`; `weight` drives font size (a negative/non-finite `weight` is clamped to
+  `0` for sizing purposes only — the original value is still echoed verbatim in `lr-word-click`'s
+  `detail`), `color` overrides the palette for that word, `group` shares one palette color across
+  every word with the same `group` value
+- `minFontSize: number = 12` (attribute `min-font-size`) — px, applied to the lowest-weight word;
+  layout clamps positive finite values to at most 512px and uses 1px for invalid/non-positive values
+- `maxFontSize: number = 48` (attribute `max-font-size`) — px, applied to the highest-weight word;
+  normalized by the same 1–512px layout bound (reversed min/max bounds are swapped)
+- `scale: 'linear'|'sqrt' = 'linear'` — `sqrt` compresses the weight→font-size mapping so one heavy
+  word doesn't dwarf the rest, matching `lr-heatmap`'s `scale` property
+- `orientations: 'horizontal'|'mixed' = 'horizontal'` — `mixed` lets ~25% of words render rotated
+  90° for denser packing
+- `palette?: string[]` (attribute: false) — custom categorical colors, cycled by word index (or by
+  `group`); defaults to the `--lr-word-cloud-color-1..8` tokens
+
+**Methods:** `refreshTheme(): void` — forces a relayout so the `--lr-font` custom property is
+re-read from computed style (font-family affects the canvas text measurement layout depends on);
+call this from your own theme-toggle handler, since there's no global theme-change event to
+subscribe to automatically (mirrors `lr-chart`'s `refreshTheme()`).
+
+**Events:** `lr-word-click` (`detail: { text, weight, group }`, fires on click, or Enter/Space on
+the currently-focused word — a no-op if nothing is focused yet)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `svg`, `word` (each `<text>`), `focus-ring` (the rect around the roving-focus
+cursor's word), `live-region` (visually-hidden `role="status" aria-live="polite"` announcement text),
+`empty` (the no-data placeholder — hardcoded `"No data"` text, no property to customize it, unlike
+`lr-empty`/`lr-table`)
+
+**Themeable custom properties:** `--lr-word-cloud-color-1`, `--lr-word-cloud-color-2`,
+`--lr-word-cloud-color-3`, `--lr-word-cloud-color-4`, `--lr-word-cloud-color-5`,
+`--lr-word-cloud-color-6`, `--lr-word-cloud-color-7`, `--lr-word-cloud-color-8` (the default
+categorical palette, cycled by word index or `group`; a data-driven literal exception like
+`lr-heatmap`'s scale-ramp endpoints — exposed as retheme-able custom properties instead of
+hardcoded), plus shared tokens (`--lr-font`,
+`--lr-focus-ring-*`, `--lr-transition-fast`, `--lr-color-text-quiet`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-word-cloud id="cloud" style="height: 20rem"></lr-word-cloud>
+<script type="module">
+  document.getElementById('cloud').words = [
+    { text: 'JavaScript', weight: 90 },
+    { text: 'TypeScript', weight: 75 },
+    { text: 'Lit', weight: 60, group: 'framework' },
+  ];
+  document.getElementById('cloud').addEventListener('lr-word-click', (e) => console.log(e.detail));
+</script>
+```
+
+The host itself gets `role="group"` and an auto-computed `aria-label` (e.g. `"Word cloud of 12
+words"` / `"Word cloud of 1 word"`, counting only words actually rendered — post `MAX_WORDS`-cap and
+post-drop, not the raw `words.length`) **unless** the host already carried its own `role`/`aria-label`
+attribute at first render. That opt-out check runs exactly once (the very first update) and is never
+re-checked afterwards, so setting `role`/`aria-label` yourself *after* the component has already
+rendered at least once only sticks until the next `words`-driven relayout, which overwrites it back
+to the auto default — set it in the initial markup (or before first paint) to opt out permanently.
+
+**Known gotchas:**
+- capped at 150 words (`MAX_WORDS` in `word-cloud-layout.ts`, mirroring `lr-sparkline`'s
+  `MAX_BARS` DOM-node-count guard) — over the cap, the **heaviest** 150 survive and the rest are
+  dropped, regardless of where they fell in the input array (it is not simply "first 150 in, rest
+  dropped"). A pathological input (e.g. one huge word repeated many times) can also exhaust the
+  spiral search's radius bound and get dropped the same way; blank/whitespace-only `text` is dropped
+  too. Every drop reason logs one deduplicated `console.warn` per distinct skipped-count (not one
+  warning per word, and not repeated twice for the same count) — nothing throws.
+- each word's spiral search tests at most 4,096 candidate positions. Together with the 150-word and
+  512px font-size caps, this bounds placement work even for dense or adversarial layouts; a word
+  that exhausts the search budget is reported through the same skipped-word path.
+- text width is measured via a detached `<canvas>` 2D context (`ctx.measureText`) at a hardcoded
+  `font-weight: 600` matching `[part='word']`'s own default CSS — close enough for
+  collision-avoidance spacing, but not pixel-exact, and overriding `[part='word']`'s `font-weight` via
+  `::part()` desyncs measurement from what's actually painted (looser/denser packing, not a crash).
+- rotation (`orientations="mixed"`) is genuinely random per layout (`Math.random()`, not seeded), so
+  which words render rotated changes on every re-layout (any `words`/`minFontSize`/`maxFontSize`/
+  `scale`/`orientations` change) — don't rely on rotation being stable across renders.
+- only one word is ever in the page's tab sequence at a time (the roving cursor on `[part="svg"]`) —
+  there's no way to Tab directly to the Nth word; arrow-key/Home/End your way there, or click it.
+
+---