@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-option.md

@@ -0,0 +1,231 @@
+<!-- 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 there is something to
+  clear on **either** axis this control owns: a committed selection, or *visible* filter text. See
+  "the clear button covers two axes" below
+- `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.
+
+**The clear button covers two axes, and announces only the one that moved.** A combobox owns both a
+committed selection and an in-progress filter query, so the button renders whenever either has
+something to clear, and one press clears both:
+
+- Clearing a selection emits `input`, then `change`, then `lr-clear` — and, if the query was also
+  non-empty, `lr-filter` with an empty `value`.
+- A **query-only** clear (nothing selected, just typed text) emits `lr-filter` with an empty
+  `value` and deliberately **no** `change` and **no** `lr-clear`. There was no selection
+  transition to report, so announcing one would be a lie. Don't listen for `lr-clear` to detect
+  "the user emptied the field" — listen for `lr-filter` when you care about the query.
+- The query half of the render gate is scoped to states where the query is actually *visible*: an
+  open listbox in single-select, or any time in `multiple` mode. A closed single-select shows the
+  selected label rather than the query, so a stale query alone never surfaces a button offering to
+  clear text the user cannot see.
+
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided), plus two adornment slots:
+- `start` — content at the inline-start of the trigger row, before the selected-value tags and the
+  filter input. It is decorative chrome, **not** an option: only `<lr-option>` elements in the
+  default slot are ever collected into the option list.
+- `end` — content after the filter input and the built-in clear action, and before the expand icon,
+  so consumer content never sits outboard of the dropdown chevron.
+
+**CSS parts:** `form-control`, `form-control-label`, `combobox`, `start` and `end` (the two
+adornment-slot wrappers, each `hidden` while nothing is slotted into it), `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.
+
+`--lr-combobox-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of
+a hovered or keyboard-active `[part='option']` row — the same per-component indirection
+`lr-select`'s identical `--lr-select-option-active-bg` uses, so a consumer can retheme just this
+row state without hijacking the shared `--lr-color-brand-quiet` token library-wide.
+
+`--lr-combobox-trigger-height` pins an **exact** input-container height (both floors and caps it),
+for pixel-matching an `<lr-input>` or `<lr-select>` in the same toolbar row. It is **undeclared by
+default**, leaving `--lr-combobox-trigger-min-height` as a floor only and the row free to grow —
+see "exact-height hatches" under `lr-input` for why `auto` is not a way to opt back out. Intended
+for a single-row combobox: in `multiple` mode, a tag row long enough to wrap overflows the pinned
+box visibly (nothing is clipped or made unreachable), so leave it unset there.
+
+**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,48 @@
+<!-- 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), `page-current` (the button for the current `page`), `thumbnail` (the thumbnail canvas
+wrapper), `page-number` (the visible page number), `heat` (the heat-marker cluster), `heat-dot` (one
+heat marker), `heat-dot-accent`, `heat-dot-success`, `heat-dot-warning`, `heat-dot-danger` and
+`heat-dot-neutral` (the tone-specific name on each marker), and `heat-dot-overflow` (the `+n`
+marker).
+
+Page rows are rendered into the embedded `<lr-virtual-list>`'s own shadow root and forwarded with
+`exportparts`, so `lr-page-rail::part(page)` and the rest reach them from a consuming stylesheet.
+State variants each carry a second name in the element's part list rather than a state attribute,
+because `::part()` cannot be followed by an attribute selector: the current row is
+`part="page page-current"` and a danger marker is `part="heat-dot heat-dot-danger"`, and `::part()`
+matches with `part~=` semantics, so both names select the same element.
+
+**Themeable custom properties:** `--lr-page-rail-height` (default `var(--lr-size-24rem)`) — block
+size of the virtualized rail. `--lr-page-rail-current-bg` (default `var(--lr-color-brand-quiet)`) —
+background of the `page-current` button, kept while the row is hovered so the current page stays
+identifiable under the pointer.

package/llms/components/lr-pagination.md

@@ -0,0 +1,91 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-pagination`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/pagination/pagination.js';` (registers the tag; side-effect import)
+- **Class** `LyraPagination`, also available unregistered from `@aceshooting/lyra-ui/components/data/pagination/pagination.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-pagination`
+
+Controlled page navigation for server-side or client-side data sets: previous/next buttons, a
+validated numeric page jump, a localized item-range summary, and a polite announcement after the
+host applies a requested page. The component owns no data fetching and never mutates `page`.
+
+**Properties and getters:**
+- `page: number = 1` (reflected) — the currently applied page. Runtime values are presented within
+  the valid `1..pageCount` range, but the public property itself remains controlled and is not
+  rewritten by the component
+- `pageSize: number = 20` (attribute `page-size`) — items per page; finite values are truncated to
+  a non-negative integer for the derived calculations, and zero produces no pages
+- `totalItems: number = 0` (attribute `total-items`) — total item count; finite values are truncated
+  to a non-negative integer for display and page-count calculations
+- `pageCount: number` (readonly getter) — `ceil(totalItems / pageSize)` after the normalization
+  above, or `0` when either normalized input is zero
+- `disabled: boolean = false` (reflected)
+- `loading: boolean = false` (reflected) — disables all controls and sets `aria-busy="true"` on the
+  internal navigation landmark
+- `hideSummary: boolean = false` (attribute `hide-summary`, reflected) — omits the built-in range
+  summary while retaining the controls
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected) — changes control height and type size
+- `itemLabel: string = ''` (attribute `item-label`) — custom item noun used in the summary; empty
+  selects the localized singular `item` or plural `items` key
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — host accessible-name override
+  forwarded to the internal `<nav>` landmark; takes precedence over `label`
+- `label: string = 'Pagination'` — fallback accessible name for the internal `<nav>` landmark
+- `pageLabel: string = 'Page'` (attribute `page-label`) — accessible name for the page-jump input
+- `previousLabel: string = 'Previous'` (attribute `previous-label`), `nextLabel: string = 'Next'`
+  (attribute `next-label`) — accessible names for the icon-only directional buttons
+
+Built-in property defaults resolve through the locale registry. A property value customized away
+from its built-in default is treated as an explicit per-instance wording override.
+
+**Events:** `lr-page-change` (`detail: { page: number }`, bubbles and composes, non-cancelable) —
+emitted for a valid, different requested page. The host applies `event.detail.page` back to `page`
+after routing, fetching, or any other policy decision.
+The internal page input's `focus` and `blur` are also bridged as bubbling, composed host events.
+
+**Methods:** `focus(options?)` and `blur()` forward to the numeric page input.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `summary`, `controls`, `previous-button`, `previous-icon`, `page-field`,
+`page-input`, `page-count`, `next-button`, `next-icon`, `live-region`.
+
+**Themeable custom properties:** `--lr-pagination-control-size` and
+`--lr-pagination-font-size` (both default from `size`), `--lr-pagination-control-padding` (default
+`var(--lr-space-xs)`) — inner padding of the previous/next buttons and the page input, deliberately
+uniform across every `size` tier because the control's outer footprint is already fixed by
+`--lr-pagination-control-size`, so this only adjusts the icon/digit inset — plus shared color,
+spacing, border, radius, disabled-opacity, and focus-ring tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lr-pagination total-items="237" page-size="20"></lr-pagination>
+<script>
+  const pagination = document.querySelector('lr-pagination');
+  pagination.addEventListener('lr-page-change', async (event) => {
+    await loadPage(event.detail.page);
+    pagination.page = event.detail.page;
+  });
+</script>
+```
+
+**Known gotchas:**
+- user activation only emits an intent. Until the host applies a new `page`, the numeric input
+  returns to the currently controlled value; assigning the page triggers the localized
+  `role="status"` announcement
+- the jump input accepts only whole pages in `1..pageCount`; empty, fractional, and out-of-range
+  drafts expose `aria-invalid="true"` and emit nothing
+- zero items, zero page size, `disabled`, and `loading` all disable the navigation controls. The
+  empty summary is still rendered via the localized `paginationEmptySummary` message
+  (`'{total} {itemLabel}'`, producing `0 items` in the default locale) unless `hide-summary` is set
+- below a 20rem container allocation the summary and controls stack; the breakpoint responds to
+  the component's own inline size, not the viewport. Previous/next icons also mirror under RTL
+
+---

package/llms/components/lr-path-strip.md

@@ -0,0 +1,55 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-path-strip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/path-strip/path-strip.js';` (registers the tag; side-effect import)
+- **Class** `LyraPathStrip`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/path-strip/path-strip.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-path-strip`
+
+A linear node → relation → node chain rendering "why A connects to B" (GraphRAG local-search
+reasoning paths) as a compact, horizontally scrollable strip. One-dimensional and presentational: no
+path finding, no branching, no per-element popovers.
+
+**Properties:**
+- `path: LyraPathElement[] = []` (attribute: false) — a flat alternating sequence:
+  `{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string; directed?: boolean;
+  reverse?: boolean }`
+- `label: string = ''`
+
+**Events:** `lr-entity-activate` (`detail: { id }`, a node element activated),
+`lr-relation-activate` (`detail: { relation, sourceId?, targetId? }`, an edge element activated —
+source/target resolved from the adjacent node elements, `undefined` when the path is malformed at
+that position).
+
+**Slots:** none.
+
+**CSS parts:** `base` (hosts the delegated roving-tabindex keydown handler), `node` (a `<button>`),
+`relation` (a `<button>`), `arrow` (`aria-hidden`, logical — mirrors under RTL), `empty` (shown when
+`path` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-path-strip></lr-path-strip>
+<script>
+  document.querySelector('lr-path-strip').path = [
+    { kind: 'node', node: { id: 'a', label: 'Ada Lovelace' } },
+    { kind: 'edge', relation: 'wrote', directed: true },
+    { kind: 'node', node: { id: 'b', label: 'Notes on the Analytical Engine' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- Purely presentational rendering of a caller-supplied path — it never computes shortest paths or
+  fetches relationship data itself, and never branches (one linear chain per instance).
+
+---

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

@@ -0,0 +1,94 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-pdf-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraPdfViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `pdfjs-dist` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-pdf-viewer`
+
+Fetches a PDF and renders its pages with the optional `pdfjs-dist` peer. Pages are virtualized through
+`lr-virtual-list`, and PDF.js's selectable text layer is positioned over each rendered canvas.
+
+Adopts `DocumentAnchorTarget`: `page`, `text-quote`, and `region` anchors resolve, and `highlights`
+paint through one `<lr-highlight-layer>` per page, stacked between the canvas and the text layer
+(canvas → highlights → text layer) so starting a text selection over a cited passage keeps working.
+Pointer activation is hit-tested at the page-wrapper level (the text layer on top intercepts most
+direct pointer events); keyboard activation reaches the highlight layer's own roving-tabindex rects
+directly, since z-stacking doesn't affect tab order. Residual: a click that *ends a text-selection
+drag* over a highlighted passage never activates it — the selection-in-progress check exists exactly
+to tell that apart from a genuine activation click.
+
+**Properties:** `src` and `name` are strings. `page: number = 1` is the one-based current page and
+`zoom: number = 1` is clamped to `0.25`–`4`. `maxHeight: string = ''` (attribute `max-height`) is a
+CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
+page list — declaratively, writing it inline on `[part="base"]`. `anchorKinds` is a readonly
+`['page', 'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
+
+**Events:**
+- `lr-render-error` — `detail: { error }` — fetching, parsing, or rendering (page canvas or text
+  layer) failed.
+- `lr-load` — `detail: { pageCount }` — the document reached `ready`. `page` is reset to `1` first.
+- `lr-page-change` — `detail: { page, pageCount }` — fired for scroll-driven page crossings as well
+  as `page` assignments and `nextPage()`/`previousPage()`/`goToPage()`.
+- `lr-zoom-change` — `detail: { zoom }`.
+- `lr-search-change` — `detail: { query, matchCount, activeIndex }` — from `search()`/`searchNext()`/
+  `searchPrevious()`/`clearSearch()`. A `src` change resets search state *silently* (no event), since
+  match page/offset coordinates only mean anything for the document they were found in.
+- `lr-highlight-activate` — `detail: { id }` — a painted highlight was clicked or activated via
+  Enter/Space. On a pointer hit-test, the last entry of `highlights` covering the point wins.
+- `lr-text-select` — `detail: { text, anchor, rects }` — a selection ended inside a page's text
+  layer. `anchor` is the computed anchor (`null` when none resolves), carrying the resolved `page`
+  when it is a `text-quote`.
+- `lr-anchor-result` — `detail: { found }` — fired after an `anchor` assignment or a
+  `scrollToAnchor()` call.
+
+**Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
+controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
+of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
+`renderPageThumbnail(page, canvas, options?)` renders `page` into a caller-owned `canvas` at
+`options.width` CSS px (default 96), devicePixelRatio-aware, resolving `false` when not ready or out
+of range. `goToPage(page)` scrolls the virtualized list to `page`, resolving `true` once mounted (or
+`false` for an out-of-range value, without changing `page`). `getOutline()` resolves the document's
+table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` when there is none.
+`search(query)` resolves the match count across all pages (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()` and `searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and painted marks.
+
+**CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `page-canvas`
+(the canvas one page's content is painted onto), `text-layer`, `text-span` (one generated text run
+inside a page's text layer — PDF.js creates these imperatively, and they carry the part so a rule can
+reach them without a descendant combinator), `search-match` (a `<mark>` painted into a mounted page's
+text layer around one search match), `search-match-active` (the currently active match, also carries
+`search-match`), `spinner`, and `error`. Search painting is best-effort: a page outside the
+virtualized render window is skipped and repainted once its text layer mounts, and a match spanning a
+text-layer span boundary that `Range.surroundContents()` can't wrap stays unpainted (still reachable
+via `searchNext()`).
+
+`page`, `page-canvas`, `text-layer`, `text-span`, `search-match` and `search-match-active` are
+rendered inside the virtualizing `lr-virtual-list`'s own shadow root and forwarded out through
+`exportparts`, so `lr-pdf-viewer::part(page)` (and each of the others) works from a consumer
+stylesheet exactly like the parts in this viewer's own shadow root. The selection tint over a page's
+text is styled on `text-span` rather than on `text-layer`, because a highlight pseudo-element is
+matched against the element the selected text originates in:
+`lr-pdf-viewer::part(text-span)::selection { background: … }`.
+
+**Themeable custom properties:** `--lr-pdf-viewer-height` (default `var(--lr-size-24rem)`) — block
+size of the virtualized page list (`[part="pages"]`); also settable via the `maxHeight` property,
+which writes this token inline on `[part="base"]`. Everything below the page list is retuned
+through the exported parts above rather than through dedicated custom properties.
+
+**Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
+a lazy `application/pdf` renderer with `<lr-document-viewer>` so the PDF library is loaded only when
+a PDF is opened. Deviates from the shared degraded-render contract: an absent `pdfjs-dist` renders
+`[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
+rendering without it.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the PDF.