@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,145 @@
+<!-- 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 `role="heading"` 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.
+- `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.
+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`.
+
+**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)
+
+**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 `role="heading"`
+marker)
+
+**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>
+```
+
+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` is accepted today purely for forward API compatibility; setting it has no visible effect
+  yet.
+
+---

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

@@ -0,0 +1,78 @@
+<!-- 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()`).
+
+**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,104 @@
+<!-- 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-*`).
+
+**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.
+
+---

package/llms/components/lr-xml-viewer.md

@@ -0,0 +1,58 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-xml-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/xml-viewer/xml-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraXmlViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/xml-viewer/xml-viewer.class.js`
+- **Family** `components/viewers/` — 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-xml-viewer`
+
+Collapsible, copyable, `DOMParser`-based tree view for XML documents, mirroring `lr-json-viewer`'s
+UX (`collapsed-depth`, `copyable`, structural-path-keyed expand state that survives a same-shape
+`xml` reassignment) adapted for XML's own node kinds: elements with attributes, text, comments, CDATA
+sections, and processing instructions. Namespace-literal: qualified names render exactly as authored,
+with no namespace-URI-aware matching. `DOMParser` never resolves external entities or DTDs, so XXE
+injection is structurally out of reach. Not `lr-json-viewer` (JS values); not `lr-html-viewer`
+(sanitized *rendered* HTML). No XPath/XSLT evaluation, no editing, no schema validation.
+
+**Properties:** `src: string = ''` — URL to fetch and parse; ignored once `xml` is set. `xml?:
+string` (property only) — raw XML text to parse and render; wins over `src`, and setting it parses
+synchronously. `name: string = ''` — accessible label. `collapsedDepth?: number` (attribute
+`collapsed-depth`) — elements at or beyond this nesting depth (root = 0) start collapsed. `copyable:
+boolean = false` (reflected) — shows copy-to-clipboard affordances, one for the whole document plus
+one per element. `maxHeight: string = ''` (attribute `max-height`). `anchorKinds` is a readonly
+`['node-path']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target
+contract) — each numeric path segment is the 0-based index within the parent's *element* children,
+and an optional trailing string segment `'@attrName'` addresses one attribute.
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
+every element's tag name, attribute names/values, and own text (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping);
+`clearSearch()` clears the query and matches.
+
+**Events:** `lr-copy` — `detail: { text }`. `lr-search-change` — `detail: { query, matchCount,
+activeIndex }`. `lr-render-error` — `detail: { error }`, fetching or parsing failed, including a
+parse error or exceeding the node cap.
+
+**CSS parts:** `base`, `toolbar` (the whole-document copy button row, only when `copyable`),
+`copy-button` (the whole-document one, or a per-node one), `tree`, `node` (`data-active` while it's
+the resolved anchor target, `data-match`, `data-active-match`), `tag` (`data-match`), `attribute`,
+`attribute-name`, `attribute-value` (`data-match`), `text` (`data-match`), `comment`, `cdata`, `pi`,
+`toggle` (an element's expand/collapse button, hidden but present for row alignment on leaf/empty
+elements), `error`, `spinner`.
+
+**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`).
+
+```html
+<lr-xml-viewer .xml=${payload} collapsed-depth="2" copyable
+  search=${query}
+></lr-xml-viewer>
+```
+
+Node cap: 50,000 — exceeding it renders the localized `xmlViewerTooManyNodes` error instead of the
+tree.

package/llms/components/lr-zoomable-frame.md

@@ -0,0 +1,57 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-zoomable-frame`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/zoomable-frame/zoomable-frame.js';` (registers the tag; side-effect import)
+- **Class** `LyraZoomableFrame`, also available unregistered from `@aceshooting/lyra-ui/components/media/zoomable-frame/zoomable-frame.class.js`
+- **Family** `components/media/` — 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-zoomable-frame`
+
+Scrollable inspection frame with bounded zoom controls and keyboard shortcuts. Scrolling provides
+panning when zoomed content exceeds the viewport.
+
+**Properties:**
+- `zoom: number = 1` (attribute `zoom`, reflected), `minZoom: number = 0.5`, `maxZoom: number = 4`,
+  and `zoomStep: number = 0.25` — bounded zoom configuration
+- `src: string = ''` and `alt: string = ''` — optional image source; otherwise the default slot is
+  rendered
+- `accessibleLabel: string | null` (attribute `aria-label`) — host-level accessible name
+
+**Methods:** `zoomIn()`, `zoomOut()`, and `resetZoom()` update the zoom and emit
+`lr-zoom-change` (`detail: { zoom }`). `resetView()` calls `resetZoom()` **and** scrolls the
+viewport back to the origin — `resetZoom()` deliberately preserves the current pan/scroll offset
+(it backs the built-in reset button and the `0` shortcut), `resetView()` is the stronger reset for
+a caller swapping in entirely new content (`<lr-lightbox>` calls it on every navigation). The
+viewport accepts `+`/`=` (zoom in), `-`/`_` (zoom out), and `0` (reset zoom) while focused.
+
+**Slots:** default slot — content to inspect; ignored while `src` is set (an `<img>` renders
+instead).
+
+**Events:** `lr-zoom-change` (`detail: { zoom }`).
+
+**CSS parts:** `base`, `viewport`, `content`, `controls`, `zoom-out`, `zoom-in`, and `reset`.
+
+**Themeable custom properties:** `--lr-zoomable-frame-min-block-size` (default
+`var(--lr-size-10rem)` — the scrollable viewport's minimum block size).
+`--lr-zoomable-frame-zoom` is a read-only hook, not a knob: the component writes the resolved
+zoom factor inline on `[part="content"]`, which `transform: scale()` consumes — setting it from
+outside is overwritten on the next render.
+
+```html
+<lr-zoomable-frame src="map-preview.png" alt="Map preview" aria-label="Map preview"></lr-zoomable-frame>
+```
+
+**Known gotchas:**
+- `zoom`/`minZoom`/`maxZoom`/`zoomStep` are all normalized before any zoom math: `minZoom` falls
+  back to `0.5`, `maxZoom` to `4` (and is floored at the effective `minZoom`), `zoomStep` to
+  `0.25`, each clamped into `[0.01, 1000]`, so a `NaN`/zero/negative attribute can't stall or
+  reverse `zoomIn()`/`zoomOut()`.
+- every zoom is snapped to a multiple of `zoomStep` and rounded to 2 decimals, so `zoom` will not
+  always equal the exact value you assigned.
+
+---