@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-model-settings-panel.md

@@ -0,0 +1,99 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-model-settings-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/model-settings-panel/model-settings-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraModelSettingsPanel`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/model-settings-panel/model-settings-panel.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-model-settings-panel`
+
+A fixed composition of `<lr-model-select>` and `<lr-slider>` into one agent-configuration card:
+pick a provider's model, then tune its sampling temperature. First-party invention (no Web Awesome
+equivalent). Not a generic layout shell — it exists so a consumer doesn't have to re-wire the same
+two child `lr-change` events into one combined settings object by hand every time this pairing
+comes up.
+
+Every prop here is a plain pass-through to (or mirror of) the matching child control's own prop of
+the same/similar name — see `lr-model-select` and `lr-slider` themselves for the exact semantics
+of `catalog`/`allowCustom` and `temperatureMin`/`temperatureMax`/`temperatureStep`.
+
+**Properties:**
+- `provider: string = ''` — informational provider badge, passed straight through to the internal
+  `lr-model-select`.
+- `catalog?: LyraModelCatalog` (attribute: false, JS-only) — `string[] | { id: string; label: string
+  }[]` (every entry must be one shape or the other, never mixed); passed straight through to the
+  internal `lr-model-select`.
+- `modelValue: string = ''` (attribute `model-value`) — the current model id.
+- `allowCustom: boolean = false` (attribute `allow-custom`) — lets the model control accept a value
+  outside `catalog`; passed straight through.
+- `temperature: number = 1` — the current sampling temperature. `1` is the midpoint of the default
+  `[0, 2]` range and matches both OpenAI's and Anthropic's own provider default; reassign it yourself
+  if your provider differs.
+- `temperatureMin: number = 0` (attribute `temperature-min`)
+- `temperatureMax: number = 2` (attribute `temperature-max`)
+- `temperatureStep: number = 0.1` (attribute `temperature-step`)
+- `layout: 'vertical' | 'compact' = 'vertical'` (reflected) — `vertical` stacks full-width rows with
+  visible labels; `compact` runs the same two rows side by side with a smaller, uppercase temperature
+  caption, for toolbars/sidebars where the vertical layout's height doesn't fit.
+- `disabled: boolean = false` (reflected) — disables the panel as a unit by forwarding to *both*
+  internal `lr-model-select` and `lr-slider`; a wrapping `<fieldset disabled>` alone would not
+  reach either, since a form-associated control's own `disabled` IDL property/attribute is never
+  mutated by fieldset cascading.
+
+**Events:** `lr-change` — `detail: { modelValue: string; inCatalog: boolean; temperature: number }`.
+Fires whenever *either* child control's own `lr-change` fires, and always carries the full current
+settings snapshot, not just whichever field actually changed. `inCatalog` is recomputed fresh from
+`catalog`/`modelValue` on every emission (mirroring `lr-model-select`'s own `effectiveEntries` logic)
+rather than cached from the last child event, so it's still correct even when `modelValue` was just
+assigned directly instead of via the child's own event.
+
+**Slots:** none — this is a fixed two-control composition, not a generic layout shell.
+
+**CSS parts:** `base`, `model-row`, `temperature-row`, `temperature-label`, `temperature-value`
+
+**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+`--lr-space-l/-m/-s/-xs`, `--lr-color-border`, `--lr-radius`, `--lr-color-surface`,
+`--lr-color-text`, `--lr-color-text-quiet`.
+
+**Optional peer deps:** none — it composes the library's own `<lr-model-select>` and `<lr-slider>`
+internally (both imported unconditionally as side effects, not optional).
+
+```html
+<lr-model-settings-panel
+  provider="OpenAI"
+  .catalog=${['gpt-4o', 'gpt-4o-mini', 'gpt-4.1']}
+  model-value="gpt-4o"
+  temperature="0.7"
+  @lr-change=${(e) => console.log(e.detail)}
+></lr-model-settings-panel>
+
+<lr-model-settings-panel layout="compact" .catalog=${catalog}></lr-model-settings-panel>
+```
+
+The internal `lr-slider` renders with its own value readout suppressed (`.showValue=${false}`);
+the current temperature is instead shown via this component's own `[part="temperature-value"]` span,
+which interpolates `temperature` verbatim with no `toFixed`/formatting applied — a value like `0.1`
+shows as `0.1`, and any floating-point noise a slider drag produces would render digit-for-digit. The
+panel's own `temperature` property mirrors the nested slider's *live* value on every one of its
+`lr-input` events (drag/key-repeat), not just its committed `lr-change` — so `temperature` (and
+the visible readout) tick continuously during a drag, but the panel's own `lr-change` event only
+fires once the slider's own `lr-change` commits (pointerup/keyup) or the model changes; reading
+`.temperature` mid-drag will already reflect the live position even though no `lr-change` has fired
+yet for it.
+
+**Known gotchas:**
+- `catalog` is JS-only (`attribute: false`) — set it via a property binding (`.catalog=`), never as
+  an HTML attribute, same requirement as the underlying `lr-model-select`.
+- `layout="compact"` removes the host's own `max-inline-size` cap (`28rem` in `vertical` layout)
+  entirely, so a compact panel can grow as wide as its container/flex context allows.
+- The nested `lr-model-select`'s own `max-inline-size` (sized for a standalone dropdown) is
+  overridden to `100%`/`none` inside `[part="model-row"]` so it fills the card's full width — a
+  detail only worth knowing if you're targeting `lr-model-select` internals with your own CSS
+  through this component.
+
+---

package/llms/components/lr-mutation-observer.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-mutation-observer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/mutation-observer/mutation-observer.js';` (registers the tag; side-effect import)
+- **Class** `LyraMutationObserver`, also available unregistered from `@aceshooting/lyra-ui/components/utility/mutation-observer/mutation-observer.class.js`
+- **Family** `components/utility/` — 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-mutation-observer`
+
+Lifecycle-managed wrapper around the native `MutationObserver`. All element children in the default
+slot are observed and their mutation records are emitted as a composed event; the wrapper itself
+adds no layout.
+
+**Properties:** `disabled: boolean = false` (reflected), `childList: boolean = true` (attribute
+`child-list`), `observeAttributes: boolean = false` (attribute `attributes`), `characterData: boolean = false` (attribute
+`character-data`), `subtree: boolean = true`, and `attributeFilter: string[] = []`.
+
+**Events:** `lr-mutation` with `{ records: MutationRecord[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---

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

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-neighbor-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/neighbor-list/neighbor-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraNeighborList`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/neighbor-list/neighbor-list.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-neighbor-list`
+
+One entity's relationship rows: relation, direction, neighbor, with per-row navigate and
+expand-in-graph affordances. Never computes neighbors itself (the host derives rows from its own
+graph data) and never mutates a graph.
+
+**Properties:**
+- `rows: LyraNeighborRow[] = []` (attribute: false) — `LyraNeighborRow { relation: string; direction:
+  'in' | 'out' | 'both'; node: LyraEntity }`
+- `groupByRelation: boolean = false` (attribute `group-by-relation`) — inserts a `group-header` row per
+  distinct `relation`
+- `expandable: boolean = false` — renders a per-row expand-in-graph icon button
+- `virtualizeAt: number = 100` (attribute `virtualize-at`) — row count above which the list virtualizes
+- `label: string = ''`
+
+**Events:** `lr-entity-activate` (`detail: { id }`, a row's node button was activated),
+`lr-node-expand` (`detail: { id }`, a row's expand button was activated — deliberately the same
+name and detail shape as `lr-graph`'s own event, so one host handler serves both).
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`), `row`
+(`role="listitem"`), `direction` (`aria-hidden` glyph), `relation`, `node-label`, `node-meta`
+(secondary type/degree text, when present), `expand-button` (only when `expandable`), `empty`
+(shown when `rows` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-neighbor-list expandable group-by-relation></lr-neighbor-list>
+<script>
+  document.querySelector('lr-neighbor-list').rows = [
+    { relation: 'works_for', direction: 'out', node: { id: 'e2', label: 'Analytical Engine Co.' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- `lr-node-expand`'s detail shape is intentionally identical to `lr-graph`'s own event of the
+  same name, so a single listener wired to both handles "expand this node's neighborhood" uniformly.
+
+---

package/llms/components/lr-node-palette.md

@@ -0,0 +1,67 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-node-palette`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/node-palette/node-palette.js';` (registers the tag; side-effect import)
+- **Class** `LyraNodePalette`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/node-palette/node-palette.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-node-palette`
+
+The searchable, categorized node library for workflow editors: drag an item onto a canvas, or place
+it by keyboard. Never creates nodes or touches a canvas's data itself — the drop/place handshake ends
+at `lr-node-add`/`lr-palette-place`; the host mutates `nodes`. Fully decoupled from
+`lr-flow-canvas` (no `for` resolution, unlike the other three companions) — it only needs to agree
+with a `droppable` canvas on the `FLOW_PALETTE_MIME_TYPE` drag payload shape.
+
+**Properties:**
+- `items: PaletteItem[] = []` (attribute: false) — `PaletteItem { type: string; label: string;
+  description?: string; category?: string; keywords?: string[]; icon?: unknown; disabled?: boolean }`;
+  `type` is the `FlowNode.type` a placement/drop creates, `category` groups items under
+  first-appearance-ordered headings, `disabled` renders an item visible but not draggable/placeable
+- `label: string = ''` — accessible name for the search field/listbox
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the listbox's
+  computed accessible name; wins over `label` and the localized default, and attribute-reflects
+  from a host-level `aria-label`
+
+**Events:** `lr-palette-place` (`detail: { type }`, a pointer click or Enter/Space — the
+click/keyboard alternative to dragging), `lr-select` (`detail: { item }`, emitted alongside
+`lr-palette-place` on both gestures, carrying the full item).
+
+**Slots:** `header` (content above the search field, e.g. a heading or tabs), `footer` (content
+below the list).
+
+**CSS parts:** `base`, `search`, `list` (the listbox), `group-header`, `item`, `item-icon`,
+`item-label`, `item-description`, `empty` (no-results message), `live-region` (result-count
+announcement).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-node-palette id="palette"></lr-node-palette>
+<lr-flow-canvas id="canvas" droppable style="height:480px"></lr-flow-canvas>
+<script>
+  document.getElementById('palette').items = [
+    { type: 'http-request', label: 'HTTP Request', category: 'Actions' },
+    { type: 'transform', label: 'Transform', category: 'Actions' },
+  ];
+  document.getElementById('canvas').addEventListener('lr-node-add', (e) => {
+    console.log('drop payload type:', e.detail.type, e.detail.position);
+  });
+</script>
+```
+
+**Known gotchas:**
+- A drag from this palette carries `FLOW_PALETTE_MIME_TYPE` as its `DataTransfer` type — only a
+  `droppable` `lr-flow-canvas` (or a host reimplementing the same MIME type) accepts it.
+- Clicking or activating an item by keyboard fires `lr-palette-place`/`lr-select` immediately, no
+  drag required — the host decides where the new node lands (there's no pointer position to derive
+  one from on a keyboard placement).
+
+---

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

@@ -0,0 +1,65 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-notebook-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/notebook-viewer/notebook-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraNotebookViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/notebook-viewer/notebook-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-notebook-viewer`
+
+Read-only Jupyter notebook (nbformat 4.x) renderer, composing existing components per cell.
+Execution is a hard non-goal. Markdown cells render through `lr-markdown`, code cells through
+`lr-code-block` (using the notebook's kernel language for syntax highlighting), and raw cells as
+plain preformatted text. A code cell's `execute_result`/`display_data` outputs prefer, in order,
+`image/png`, `image/jpeg`, `image/svg+xml` (sanitized), `text/html` (sanitized), `application/json`
+(via `lr-json-viewer`), then `text/plain`. Stream/error outputs render as plain preformatted text
+(tinted `danger` for stderr/tracebacks). Sanitizing raw HTML/SVG output markup lazy-loads the
+optional peer `dompurify`; without it, the output renders a localized notice instead of raw markup.
+Cells are virtualized through `lr-virtual-list`. `node-path` anchors resolve `path[0]` as a cell
+index; `fragment` anchors resolve a cell's own `id`. No execution, no kernels, no editing, no
+ipywidgets.
+
+**Properties:** `src: string = ''` — URL to fetch and parse as a notebook; ignored once `notebook` is
+set. `notebook?: object | string` (property only) — an already-parsed notebook document, or its raw
+JSON text; wins over `src` and is parsed (and validated) synchronously. `name: string = ''` —
+accessible label, and matched against a `fragment` anchor's cell id. `outputCollapseLines: number =
+40` (attribute `output-collapse-lines`) — a plain-text output longer than this many lines renders
+collapsed behind a toggle; `0` disables collapsing. `maxHeight: string = ''` (attribute
+`max-height`) — once set, the notebook scrolls internally past this height. `anchorKinds` is a
+readonly `['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for the
+shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
+matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
+`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and flashing the
+target cell; `clearSearch()` clears the query and matches.
+
+**Events:** `lr-load` — `detail: { cellCount, language }`, fired once a notebook has been parsed
+and validated (`language` from `metadata.language_info.name`/`kernelspec.language`, else `''`).
+`lr-highlight-activate` — `detail: { id }`. `lr-search-change` — `detail: { query, matchCount,
+activeIndex }`. `lr-render-error` — `detail: { error }`, fetching, parsing, or validating the
+notebook failed.
+
+**CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
+`data-active`), `cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`,
+`output` (`data-output-type`, `data-stream`), `output-toggle`, `error`, `spinner`.
+
+**Themeable custom properties:** `--lr-notebook-viewer-max-height` (default `none`).
+
+**Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
+`shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
+`text/plain`).
+
+```html
+<lr-notebook-viewer .notebook=${result} max-height="30rem"
+  @lr-load=${(e) => console.log(e.detail.cellCount, 'cells')}
+></lr-notebook-viewer>
+```
+
+A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
+localized error and fires `lr-render-error` instead of the notebook.

package/llms/components/lr-number-input.md

@@ -0,0 +1,44 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-number-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/input/number-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraNumberInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/input/number-input.class.js`
+- **Family** `components/forms/` — 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-number-input`
+
+A migration-friendly numeric alias of `lr-input` — a subclass whose constructor and
+`connectedCallback()` both set `type = 'number'`. It adds no API of its own; everything below is
+`lr-input`'s surface, unchanged.
+
+**Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
+(`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
+`autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), `enterKeyHint` (`enterkeyhint`), and
+`min`/`max`/`step` (the native numeric constraint validation). `clearable` and `passwordVisible`
+(`password-visible`) are inherited but inert — see gotchas.
+
+**Events:** `input`/`change` (native-style, composed), `lr-input`/`lr-change`
+(`detail: { value }`), `focus`/`blur` (re-dispatched bubbling + composed from the internal native
+input), and `lr-clear` (inherited, never fired here).
+
+**Slots:** `label`, `hint`, `error`, `start`, `end`.
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start`, `end`,
+`hint`, `error`, plus the inherited `clear-button` and `password-toggle`, neither of which this
+alias ever renders.
+
+**Themeable custom properties:** inherited from `lr-input`, identical in meaning —
+`--lr-input-control-min-height`, `--lr-input-padding-block`, `--lr-input-padding-inline` and
+`--lr-input-font-size` (the last three swap per `size`).
+
+**Known gotchas:**
+- `clearable`/`clear-button`/`lr-clear` are inert: the clear action only renders for
+  `type="text"`/`"search"`. `password-visible`/`password-toggle` are likewise inert, since the
+  toggle only renders for `type="password"`.
+- `type` is re-forced to `number` on every connect, but a later `el.type = 'text'` on a connected
+  element is not reverted — use `lr-input` when the type has to change.

package/llms/components/lr-option.md

@@ -0,0 +1,196 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-option`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/combobox/option.js';` (registers the tag; side-effect import)
+- **Class** `LyraOption`, also available unregistered from `@aceshooting/lyra-ui/components/forms/combobox/option.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-combobox` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-combobox` / `lr-option`
+
+Filterable single/multi-select combining a text input with a listbox. Mirrors the core
+`<wa-combobox>` API under the `lr-` prefix. **Form-associated** (hand-rolled internals, not the
+shared `FormAssociated` mixin — see gotchas).
+
+### `lr-combobox`
+
+**Properties:**
+- `multiple: boolean = false` (reflected)
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — same scale as `lr-select`'s `size`;
+  also scales the "+N" overflow tag and decorative expand icon; `size="s"` shares its outer
+  control height with `lr-input`, `lr-select`, and `lr-segmented` without part overrides)
+- `placeholder: string = ''`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`; also reflected as
+  `aria-required` on `<input part="combobox-input">` immediately, and `aria-invalid` once the field
+  has been touched, see gotchas)
+- `name: string = ''`
+- `label: string = ''`
+- `hint: string = ''`
+- `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
+  overridden by slotted `error` content when provided)
+- `open: boolean = false` (reflected)
+- `clearable: boolean = false` (reflected) — displays the clear button while a value is selected
+- `withClear: boolean = false` (attribute `with-clear`) — deprecated compatibility alias for
+  `clearable`; either property enables the same clear button
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`), `spellcheck: boolean = true`,
+  `autocapitalize: string = ''`, and `autoCorrect: string = ''` (attribute `autocorrect`) — native
+  editing-assistance attributes forwarded to the internal filter input
+- `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected tags
+  show before collapsing to `+N`)
+- `emptyText: string = 'No results'` (attribute `empty-text`)
+- `loadingText: string = 'Loading…'` (attribute `loading-text` — listbox row shown while a `source`
+  fetch is in flight)
+- `overflowText: string = '+{n} more — refine your search'` (attribute `overflow-text` — listbox row
+  shown when `maxRender` caps the row list; `{n}` is replaced with the hidden count)
+- `filter: OptionFilter | null = null` (attribute: false — `(option, query) => boolean`; default
+  matches `label`/`searchText` case-insensitively; ignored while `source` is set)
+- `source: ComboboxSource | null = null` (attribute: false — `(query: string) =>
+  Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>` list with an async
+  lookup, debounced ~200ms after each keystroke and re-run on clear/pick. `loadingText` is shown
+  while a call is in flight; a stale in-flight call that resolves after a newer one (or after
+  disconnect) is dropped via a monotonic token)
+- `maxRender: number = 200` (attribute `max-render` — caps how many rows render at once, always
+  keeping the current selection visible even if it's outside the cap; the excess renders as one
+  `overflowText` row instead of being dropped silently)
+- `value: string | string[]` — a getter/setter: plain `string` in single mode, `string[]` in
+  `multiple` mode
+- `selectedRows: ComboboxSourceRow[]` (read-only getter) — structured rows for the current
+  selection, including any opaque `data` payload supplied by an async source. Selected async rows
+  remain available after the query changes or a later source result no longer contains them
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — selection getters/setters forwarded
+  to the internal input
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the internal input. `setRangeText()` synchronizes the filter query and visible options.
+
+`ComboboxSourceRow = { value: string; label: string; sub?: string; icon?: unknown; badge?: string |
+number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: string; disabled?:
+boolean }` — the row shape used by the async `source` path. `icon` renders as a decorative leading
+visual, `badge` as trailing metadata, `accessibleLabel` can provide richer spoken text than the
+visible label, and `data` is retained without being rendered for retrieval through `selectedRows`.
+The light-DOM `<lr-option>` path normalizes its supported label/sub/dot/group fields to the same
+internal row model.
+
+**Events:** typing in the filter exposes the original bubbling/composed, non-cancelable `InputEvent`
+as exactly one host `input` event and does not fire `change`. An actual user selection mutation —
+pointer or keyboard selection, multiple-value toggle, tag/Backspace removal, or clear — emits exactly
+one bubbling/composed, non-cancelable plain `input` `Event`, immediately followed by the same shape
+of `change` `Event`. Re-picking the current single value and programmatic/default/reset/restore
+writes are silent. The clear button emits one `lr-clear` after its `input`/`change` pair.
+`lr-filter` (`detail: { value: string }`) reports the in-progress filter text on every user-driven
+keystroke — the live as-you-typed search string, deliberately *not* `value`, which is the committed
+selection. It is the supported way to read that text; reaching into the shadow root for
+`[part="combobox-input"]`'s value is not. Named `lr-filter` rather than `lr-input` precisely because
+`lr-input`'s detail on `<lr-input>` is the committed value, and the two must not share a name while
+carrying different strings. It fires for user input only: picking a row, the clear button,
+`form.reset()`, dismissing the listbox, a programmatic `value` write, and `setRangeText()` all blank
+the filter silently, mirroring how `<lr-input>`'s `lr-input` only reports user edits.
+
+`lr-show` and `lr-hide` report listbox visibility transitions.
+The internal input's `focus` and `blur` are re-dispatched as bubbling, composed host events.
+
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided)
+
+**CSS parts:** `form-control`, `form-control-label`, `combobox`, `tags`, `tag`,
+`tag__remove-button`, `combobox-input`, `clear-button`, `expand-icon`, `listbox`, `option`,
+`option-dot` (the leading status dot, when a row's `dotColor` is set), `option-icon` (the decorative
+leading visual for an async row), `option-label`, `option-sub` (a row's secondary line, when `sub`
+is set), `option-badge` (an async row's trailing metadata), `option-overflow` (the "+N more"
+indicator from `maxRender`), `error`, `hint`
+
+**Themeable custom properties:** `--lr-combobox-trigger-padding`,
+`--lr-combobox-trigger-min-height`, `--lr-combobox-font-size`, `--lr-combobox-tag-padding`,
+`--lr-combobox-tag-font-size`, and `--lr-combobox-expand-size` (the decorative icon box; each
+standard size supplies an aligned default), plus shared tokens.
+
+**Optional peer deps:** none.
+
+### `lr-option`
+
+**Properties:**
+- `value: string = ''`
+- `disabled: boolean = false`
+- `selected: boolean = false` (reflected — set by the parent combobox, but also **read** on initial
+  mount, see below)
+- `group: string = ''` (section header)
+- `searchText: string = ''` (attribute `search-text` — extra text the filter matches beyond the
+  visible label)
+- `sub: string = ''` (optional secondary line rendered under the label, e.g. a status/date summary)
+- `dotColor: string = ''` (attribute `dot-color` — optional CSS color for a small leading status
+  dot, any valid CSS color)
+- `label` is a **read-only getter**: explicit `label` attribute wins, else trimmed `textContent`.
+
+```html
+<lr-combobox id="cb" label="Country" placeholder="Search…" with-clear>
+  <lr-option value="fr">France</lr-option>
+  <lr-option value="de" search-text="deutschland">Germany</lr-option>
+</lr-combobox>
+<script type="module">
+  document.getElementById('cb').addEventListener('change', (e) => console.log(e.target.value));
+</script>
+```
+
+```html
+<!-- Async data source instead of light-DOM <lr-option> children: -->
+<lr-combobox id="cb2" label="Fruit (async)" with-clear></lr-combobox>
+<script type="module">
+  document.getElementById('cb2').source = async (query) => {
+    const rows = await fetchFruit(query); // your own lookup
+    return rows.map((r) => ({
+      value: r.id,
+      label: r.name,
+      icon: renderFruitIcon(r),       // decorative; hidden from assistive technology
+      badge: r.category,
+      accessibleLabel: `${r.name}, ${r.category}`,
+      data: r,                        // retained in cb2.selectedRows after selection
+    }));
+  };
+</script>
+```
+
+Multi-select submits as **repeated `FormData` entries** (not a joined string) —
+`new FormData(form).getAll(name)` behaves like a native multi-value control. An unnamed multi-select
+(`multiple` with no `name`) contributes nothing to the form at all, matching a nameless native
+`<select multiple>`, rather than falling back to a shared literal key that could collide with
+another unnamed combobox in the same form.
+Session-history/autofill state is stored as a name-independent JSON string array. A valid string
+array restores the selection (single mode keeps its first entry); malformed or wrong-shape state
+restores an empty selection. Restored state wins even when it arrives before the first option
+collection, while `form.reset()` still returns to the declarative selected default. Restoration is
+synchronous and fires no `input`/`change` event.
+
+**Known gotchas:**
+- `with-clear` remains supported for compatibility, but new code should use the mirrored
+  `clearable` property/attribute.
+- a host-level `aria-label` attribute on `<lr-combobox>` now takes priority over `label`/
+  `placeholder`/`"Combobox"` when resolving the accessible name on `[part="combobox-input"]` —
+  previously it was silently ignored. Matches the same fallback on `<lr-select>`.
+- `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
+  **after the field has been touched** (first `blur`) — a `required` field with a validity error
+  doesn't look invalid to assistive tech before that, by design (avoids flashing invalid styling on
+  first render). Blurring the input (Tab away) now also closes an open listbox, the same as a
+  native `<select>`'s popup, not just a click outside or Escape.
+- `dotColor`/`sub`/`group` are read from light-DOM `<lr-option>` children as before, but are also
+  first-class fields on `ComboboxSourceRow` for the async `source` path — an async lookup can drive
+  the same grouped/dot/sub-text rendering a static option list can.
+- `icon`, `badge`, `accessibleLabel`, and `data` are async-source row features rather than
+  `<lr-option>` properties. Icons are decorative (`aria-hidden`); use `accessibleLabel` when the
+  visible label/sub/badge combination needs a fuller spoken name. `data` is deliberately opaque and
+  is available only through the read-only `selectedRows` getter.
+- Full ARIA 1.2 combobox pattern (`role=combobox`, roving `aria-activedescendant`, real DOM focus
+  kept on the input) is implemented correctly — a genuine strength, safe to build on. Declaratively-
+  selected options (`<lr-option value="b" selected>`) are seeded into the selection (mirroring
+  native `<select><option selected>`) both the first time options are collected **and** for any
+  later batch slotted in afterward (e.g. a lazily-populated list appended post-connect) — only the
+  `form.reset()` default itself is captured exclusively from that very first pass; a later pick, or
+  a later batch of newly-`selected` options, never redefines what a reset restores to.
+
+---

package/llms/components/lr-page-rail.md

@@ -0,0 +1,37 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-page-rail`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.js';` (registers the tag; side-effect import)
+- **Class** `LyraPageRail`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/page-rail/page-rail.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-page-rail`
+
+A virtualized vertical thumbnail rail for page-addressed documents, with per-page highlight heat
+markers. Two modes: **wired** (`viewer`/`for` supply a live page source, e.g. `<lr-pdf-viewer>` —
+thumbnails render lazily as rows materialize, and the rail tracks page/count from the viewer's own
+events) and **mediated** (`page-count`/`page` are host-bound directly, rows render a placeholder
+glyph — still a fully functional pager). In wired mode the viewer's `page` is the single source of
+truth.
+
+**Properties:** `viewer: PageThumbnailSource | null = null` (attribute: false) — the wired viewer.
+`for: string = ''` — an id selector alternative to setting `viewer` directly. `pageCount: number = 0`
+(attribute `page-count`) and `page: number = 1` (reflected) — mediated-mode page state.
+`highlights: LyraHighlight[] = []` (attribute: false) — drives the per-page heat markers.
+`thumbWidth: number = 96` (attribute `thumb-width`) and `label: string = ''`.
+
+**Events:** `lr-page-select` — a page row was activated (click, or Enter/Space on a focused row).
+`detail: { page }`. In wired mode the rail also sets `viewer.page` itself.
+
+**CSS parts:** `base` (the rail), `pages` (the embedded `<lr-virtual-list>`), `page` (one page
+button), `thumbnail` (the thumbnail canvas wrapper), `page-number` (the visible page number), `heat`
+(the heat-marker cluster), and `heat-dot` (one tone-colored heat marker, or the `+n` overflow
+marker).
+
+**Themeable custom properties:** `--lr-page-rail-height` (default `var(--lr-size-24rem)`) — block
+size of the virtualized rail.