@aceshooting/lyra-ui 4.2.0 → 5.1.0

package/llms/components/lr-diff-view.md

@@ -0,0 +1,86 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-diff-view`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/diff-view/diff-view.js';` (registers the tag; side-effect import)
+- **Class** `LyraDiffView`, also available unregistered from `@aceshooting/lyra-ui/components/utility/diff-view/diff-view.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** `shiki` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-diff-view`
+
+A real two-string line diff (a classic longest-common-subsequence dynamic program, not a Myers
+implementation), rendered as interleaved unified-diff output — not diff-flavored syntax highlighting
+over an already-formatted string (`<lr-code-block>`'s `language="diff"` only lexically colors a
+string the consumer already unified-diffed; it has no two-string-compare entry point of its own).
+First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `oldText: string = ''` (attribute: false) — the "before" text. Default `''` renders an
+  all-additions diff of `newText`.
+- `newText: string = ''` (attribute: false) — the "after" text. Default `''` renders an
+  all-removals diff of `oldText`.
+- `copyable: boolean = false` — shows a copy-to-clipboard button for the full unified-diff text.
+  `false` (the default) renders no button.
+- `layout: 'unified' | 'split' = 'unified'` (reflected) — `'unified'` (the default) renders today's
+  single interleaved `<pre>`; `'split'` renders two side-by-side `[part="side"]` columns derived from
+  the same diff alignment.
+- `language: string = ''` — a shiki-recognized language id. Highlighting activates only when this
+  has a matching entry in `languages` — there is deliberately no default full-table
+  `lr-code-block`-style fallback, so this component never reaches shiki's ~200-language
+  dynamic-import table.
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — grammar definitions this
+  instance can highlight, same shape as `lr-code-block-core`'s own `languages`.
+- `contextLines: number | undefined` (attribute: `context-lines`) — keeps this many unchanged
+  lines around each change and collapses longer unchanged runs into a localized fold marker. The
+  default `undefined` shows every line; negative and non-finite values also disable folding.
+
+**Events:** `lr-copy` (`detail: { text: string }` — the full unified-diff text, fired on
+copy-button activation regardless of whether the clipboard write actually succeeded).
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root wrapper), `line` (a single line; carries
+`data-type="equal"|"add"|"remove"|"empty"|"fold"` — `"empty"` is an unbalanced-replace placeholder cell in
+`layout="split"` and never carries a `+`/`-` prefix; `"fold"` is the localized unchanged-lines
+marker), `copy-button` (the copy affordance, only
+rendered while `copyable`), `side` (one column in `layout="split"`, `data-side="old"|"new"`).
+
+**Themeable custom properties:** `--lr-diff-view-font` (default `var(--lr-font-mono)`), plus
+shared tokens `--lr-color-border`/`-surface`/`-success`/`-success-quiet`/`-danger`/
+`-danger-quiet`/`-text`, `--lr-radius`, `--lr-space-xs`/`-s`, `--lr-font-size-sm`,
+`--lr-line-height-snug`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** `shiki` (the same fine-grained `shiki/core`/`shiki/engine/oniguruma`/
+`shiki/wasm` subset `lr-code-block-core` uses, never `shiki`'s full ~200-language main entry point)
+— only loaded once both `language` and a matching `languages` entry are set; unset/unmatched leaves
+the plain unhighlighted diff text untouched.
+
+```html
+<lr-diff-view copyable></lr-diff-view>
+<script type="module">
+  const diff = document.querySelector('lr-diff-view');
+  diff.oldText = 'line one\nline two\nline three';
+  diff.newText = 'line one\nline TWO\nline three\nline four';
+  diff.addEventListener('lr-copy', (e) => console.log(e.detail.text));
+</script>
+```
+
+The package root also exports the pure `computeLineDiff(oldLines: string[], newLines: string[]):
+DiffOp[]` helper (plus the `DiffOp` type, `{ type: 'equal' | 'add' | 'remove'; text: string }`) — the
+same line-diff function this component's own `render()`/copy handler call, exposed standalone so a
+consumer can compute or unit-test the same alignment without instantiating the element at all.
+
+**Known gotchas:**
+- the alignment is a genuine O(n·m) longest-common-subsequence dynamic program over lines (split on
+  `\n`), not a naive "every removed line then every added line" — fine for a typical
+  tool-call/transcript-sized diff, but a very large pair of texts costs quadratic time/memory;
+  there's no line-count guard or chunking of its own.
+- `oldText`/`newText` are recomputed into the diff on every render — this component keeps no separate
+  cached diff state, so binding either property to something that changes on every keystroke
+  recomputes the whole alignment each time.
+
+---

package/llms/components/lr-divider.md

@@ -0,0 +1,28 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-divider`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/divider/divider.js';` (registers the tag; side-effect import)
+- **Class** `LyraDivider`, also available unregistered from `@aceshooting/lyra-ui/components/utility/divider/divider.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-divider`
+
+A semantic separator: renders `<hr part="base" role="separator" aria-orientation="…">`.
+
+**Properties:** `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected).
+
+**Events:** none. **Slots:** none. **CSS parts:** `base`.
+
+**Themeable custom properties:** shared tokens only — `--lr-color-border` (rule color),
+`--lr-border-width-thin` (thickness).
+
+The host is `display: block` when horizontal and `display: inline-block; block-size: 100%` when
+vertical, so a vertical divider fills its flex/grid row's height with no extra CSS — but it needs a
+parent that actually has a resolved height.
+
+---

package/llms/components/lr-dock-panel.md

@@ -0,0 +1,110 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-dock-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/dock-panel/dock-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraDockPanel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/dock-panel/dock-panel.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-dock-panel`
+
+A single panel docked to one edge of whatever contains it, resizable by dragging its inner edge.
+First-party invention (no Web Awesome equivalent). Unlike `lr-split` (which owns and lays out N
+sibling panels, and requires restructuring a layout so every panel becomes its direct child), this is
+one self-contained element you drop next to your existing content — typically as an absolutely-
+positioned child of a `position: relative` parent, or as a flex item alongside a main-content sibling.
+It deliberately imposes no `position`/`inset` of its own: it only manages its own size along the
+resize axis (`inline-size` for `start`/`end`, `block-size` for `top`/`bottom`) and fills 100% of the
+cross axis, leaving where it sits in the page entirely up to the consumer's own layout. `lr-split`
+stays the right primitive for the multi-sibling-panel case; this is the primitive for the single-edge-
+docked case.
+
+**Properties:**
+- `edge: 'start' | 'end' | 'top' | 'bottom' = 'end'` (reflected) — which edge of the panel's own
+  container it's docked to. `start`/`end` are logical-inline (mirror left/right depending on writing
+  direction); `top`/`bottom` are block-direction and unaffected by RTL.
+- `size: string = '280px'` — the current docked size along the resize axis, as a CSS length.
+- `minSize: string = '160px'` (attribute `min-size`) — minimum resize bound, as a CSS length.
+- `maxSize: string = ''` (attribute `max-size`) — maximum resize bound. Empty means "no explicit
+  cap": the live extent of the containing element is used instead (falling back to the viewport if
+  there's no parent, e.g. not yet connected), so the panel still can't be dragged wider/taller than
+  its container.
+- `collapsible: boolean = false` (reflected)
+- `collapsed: boolean = false` (reflected)
+- `resizable: boolean = true` (reflected) — when `false`, no drag handle renders at all and the panel
+  is a fixed size. (Assign `false` via a **property** binding, e.g. `.resizable=${false}` — a
+  `?resizable=${false}` boolean-attribute binding cannot override a `true` default; see AGENTS.md.)
+
+**Exported helper:** `parseLengthPx(length: string, containerPx: number, fontSizeEl: Element =
+document.documentElement): number | undefined` — resolves an arbitrary CSS length (`px`, `rem`, `em`,
+`vw`, `vh`, `%`, or a bare/unitless number treated as `px`) to a live pixel value without a DOM-probe
+measurement, since `min-size`/`max-size` are pure constraints that are never themselves rendered
+anywhere. `rem` resolves against the document root's font size; `em` resolves against `fontSizeEl`'s
+own computed font size; `%` resolves against `containerPx`. Returns `undefined` for an
+empty/unparseable string. Used internally to resolve `min-size`/`max-size`; the panel's *current* size
+is instead always read back live from `getBoundingClientRect()`, which handles any unit for free.
+
+**Events:**
+- `lr-resize` — `detail: { size }` (a `px` CSS length string), fired on every drag step, drag
+  release, and keyboard step.
+- `lr-collapse-change` — `detail: { collapsed }`, fired whenever the collapse toggle flips
+  `collapsed`.
+
+**Slots:** default — the panel's own content.
+
+**CSS parts:** `base` (the panel root), `content` (wraps the default slot; hidden while `collapsed`),
+`handle` (the draggable resize edge; only rendered when `resizable` and not `collapsed`),
+`collapse-toggle` (only rendered when `collapsible`)
+
+**Themeable custom properties:** `--lr-dock-panel-collapsed-size` (default
+`var(--lr-icon-button-size)`) — the persistent "rail" width/height the panel holds at while
+`collapsed`, rather than collapsing to zero (a zero-size collapsed panel would have nowhere to host
+the re-expand toggle); component-specific since collapse never zeroes the box. Plus shared tokens
+`--lr-color-surface`, `--lr-color-border`, `--lr-color-brand`, `--lr-color-brand-quiet`,
+`--lr-color-text`, `--lr-radius`, `--lr-space-xs`, `--lr-focus-ring-width/-color/-offset`,
+`--lr-transition-fast`, `--lr-icon-button-size`.
+
+**Optional peer deps:** none.
+
+```html
+<div style="position: relative; block-size: 100vh;">
+  <lr-dock-panel
+    edge="end"
+    size="320px"
+    min-size="200px"
+    max-size="480px"
+    collapsible
+    @lr-resize=${(e) => console.log(e.detail.size)}
+    @lr-collapse-change=${(e) => console.log(e.detail.collapsed)}
+  >
+    <div>Sidebar content — a chat thread list, an inspector, anything.</div>
+  </lr-dock-panel>
+</div>
+```
+
+Pointer-drag-resize mirrors `lr-split`'s pointer-capture technique (`pointerdown` captures the
+pointer on the handle; `pointermove` computes a new size; `pointerup`/`pointercancel`/
+`lostpointercapture` all release it, since a drag can end without a clean `pointerup`) but reasons in
+raw pixels throughout rather than percent. Every resize — drag step, drag release, or a keyboard step
+(<kbd>ArrowLeft</kbd>/<kbd>ArrowRight</kbd> for the inline axis, <kbd>ArrowUp</kbd>/<kbd>ArrowDown</kbd>
+for the block axis, 16px per step) — always commits `size` as a rounded `px` string regardless of
+what unit `size`/`min-size`/`max-size` were originally expressed in.
+
+**Known gotchas:**
+- `collapsed` doesn't zero the panel's box — it shrinks to the persistent rail size
+  (`--lr-dock-panel-collapsed-size`). `size` itself is left untouched while collapsed, so
+  re-expanding restores exactly what it was.
+- `handle` only renders while `resizable && !collapsed`; `collapse-toggle` only renders while
+  `collapsible` — a panel with both `false` renders neither control, just fixed-size slotted content.
+  `resizable` and `collapsed` interact: dragging is disabled whenever `collapsed` is `true`, even if
+  `resizable` is also `true`.
+- The collapse-toggle's chevron rotates to point toward the panel's pinned edge when expanded (the
+  direction clicking it will shrink toward) and away from it when collapsed — this is folded through
+  both `edge` and, for `start`/`end`, current RTL-ness, so the same markup visually flips correctly
+  under `dir="rtl"` with no extra author work.
+
+---

package/llms/components/lr-document-compare.md

@@ -0,0 +1,22 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-document-compare`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/document-compare/document-compare.js';` (registers the tag; side-effect import)
+- **Class** `LyraDocumentCompare`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/document-compare/document-compare.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `shiki` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-document-compare`
+
+Comparison surface for two document versions, using `lr-diff-view` for textual diffs and
+`lr-document-preview` for side-by-side rendered content.
+
+**Properties:** `oldVersion`, `newVersion`, `view`, `diffLayout`, `language`, `languages`, `anchor`,
+`copyable`, `syncScroll`. **Events:** `lr-copy`, `lr-download`, `lr-highlight-activate`,
+`lr-render-error`. **CSS parts:** `base`, `diff`, `panes`, `pane-old`, `pane-new`, `pane-header`,
+`pane-empty`. **Themeable custom properties:** `--lr-document-compare-pane-max-height` (default
+`var(--lr-size-24rem)`) — maximum block size of a `side-by-side` pane before it scrolls internally.

package/llms/components/lr-document-library.md

@@ -0,0 +1,21 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-document-library`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/document-library/document-library.js';` (registers the tag; side-effect import)
+- **Class** `LyraDocumentLibrary`, also available unregistered from `@aceshooting/lyra-ui/components/data/document-library/document-library.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-document-library`
+
+Controlled searchable and filterable document inventory with versions, tags, owners, freshness,
+sorting, and bulk selection.
+
+**Properties:** `documents`, `filter`, `label`, `loading`, `selectedIds`, `sortKey`, `sortDirection`,
+`tagFilter`. **Events:** `lr-filter-change`, `lr-open`, `lr-selection-change`, `lr-sort`. **CSS
+parts:** `base`, `toolbar`, `search`, `tag-filter`, `selection-bar`, `selection-count`,
+`clear-selection`, `table`, `row`, `cell`, `header-cell`, `document-name`.

package/llms/components/lr-document-preview.md

@@ -0,0 +1,179 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-document-preview`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/document-preview/document-preview.js';` (registers the tag; side-effect import)
+- **Class** `LyraDocumentPreview`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/document-preview/document-preview.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-document-preview`
+
+A format-dispatching viewer for one document/attachment, plus the visual state machine for an async
+server-side conversion a host app runs in front of it. First-party invention (no Web Awesome
+equivalent).
+
+Format dispatch is intentionally minimal: only `text/*`/`application/json` (a plain, scrollable
+`<pre>` — no syntax highlighting; compose `<lr-code-block>` yourself via the `unsupported` slot for
+that) and `image/*` (a contained `<img>`) render inline. Everything else — PDF, office documents,
+video, audio, or any unrecognized MIME type — falls back to a generic "can't preview this" state: a
+file glyph, a short message, and (when `src` is set) a native `<a download>` link. This is a
+deliberate ceiling, not a gap: the component ships a dispatch *shell*, not a format registry. The
+`unsupported` slot is the escape hatch for every format left out of the built-in three.
+
+`status="converting"` is a second, independent axis from format dispatch. This component doesn't know
+your backend's conversion API shape and owns none of the actual polling/fetch — a host converting a
+non-natively-previewable format server-side (e.g. `.docx` → `.pdf`) polls its own backend and updates
+`status`/`progress`/`src` here as that proceeds; this component only *visualizes* that state (an
+indeterminate spinner, or a determinate one once `progress` is supplied). The one piece of async work
+this component *does* own is fetching a `text/*`/`application/json` `src` itself — there's no other
+way to get a `<pre>`'s text content from a URL — gated behind a generation-counter guard
+(`lr-tool-result-view`'s `resolve()` uses the identical pattern) so a `src` reassigned mid-fetch
+can't have a stale response clobber a newer one.
+
+Every `src` is validated (via `internal/safe-url.ts`) against a scheme allowlist specific to the DOM/
+API sink it's about to reach: `fetch(src)` (text preview) and an `<img src>` (image preview) both
+allow relative URLs plus `http:`, `https:`, `blob:`, and `data:`; the download `<a href>` deliberately
+excludes `data:` (following a `data:text/html` URL can create an active document, unlike using it as
+inert media/fetch data). A `src` that fails its sink's check never reaches `fetch()`/`<img>`/the
+anchor: the text preview renders `[part="error"]` with `"Document URL is not allowed."`, the image
+preview silently falls back to the download fallback **directly** — not the generic
+download-or-`unsupported`-slot one, so `<slot name="unsupported">` content is *not* consulted on the
+image path — and the generic fallback simply omits `[part="download-link"]` entirely.
+
+**Properties:**
+- `src: string = ''` — URL to fetch (for `text`/`application/json`) or display (`image`, or as the
+  generic fallback's download `href`). Optional — gracefully absent while, e.g., a conversion is
+  still in progress. Validated per-sink before use — see the URL-safety note above; an unsafe/
+  malformed value is treated as if `src` were unusable for that sink, never passed to `fetch()`/
+  `<img>`/the anchor.
+- `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch (see above).
+- `filename: string = ''` — shown in the header and used as the download link's suggested filename.
+- `alt?: string` — image description. When omitted, the filename/localized image-preview fallback
+  is used; an explicit empty string keeps a decorative preview's `alt=""` intact.
+- `status: 'idle' | 'converting' | 'ready' | 'error' = 'idle'` (reflected) — host-owned lifecycle
+  state. `"converting"` shows the spinner regardless of `mimeType`/`src`; `"error"` shows
+  `errorMessage` regardless of either. `"idle"`/`"ready"` both resume normal format dispatch — a host
+  with no conversion step never has to explicitly set `"ready"`.
+- `progress?: number` (type `Number`) — 0-100. Only consulted while `status="converting"`. Unset (the
+  default) renders an indeterminate spinner instead of a determinate progress bar.
+- `errorMessage: string = ''` (attribute `error-message`) — shown via `[part="error"]` while
+  `status="error"`.
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"24rem"`); once set,
+  `[part="body"]` scrolls internally past this height instead of growing the page — same contract as
+  `lr-json-viewer`'s identically-named prop.
+- `zoomable: boolean = false` (reflected) — wraps the rendered image (image format only) in an
+  internal `<lr-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
+  inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome
+  viewport; an inspection surface opts in.
+- `highlights: LyraHighlight[] = []` (attribute: false) — display-only `region` highlights painted
+  over the image-format preview; ignored for the `text`/`generic` formats.
+- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
+  entry, if any, currently treated as active (`data-active` on its `region-highlight`).
+- `anchorKinds` is a readonly `['region']` (this viewer's supported `LyraAnchor.kind` values for the
+  shared anchor-target contract).
+
+**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor`
+matched back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing
+matches, the anchor isn't `region`, or the format isn't currently `image`.
+
+**Events:**
+- `lr-download` — `detail: { src, filename }` — fired when the generic-download fallback's link is
+  activated. The browser download itself needs no JS (a plain `<a download>` handles it); this is
+  purely for a host that wants to observe/log the download.
+- `lr-render-error` — `detail: { error }` — fired when this component's own `text/*`/
+  `application/json` `fetch(src)` fails (network error or non-2xx response). Distinct from
+  `status="error"`, which is entirely host-driven.
+- `lr-highlight-activate` — `detail: { id }` — a region highlight was clicked or activated via
+  Enter/Space (image format only).
+
+**Slots:** `unsupported` — escape hatch: when populated, its content renders *instead of* the generic
+download fallback for any `mime-type` this component doesn't natively support. Ignored while
+`mime-type` resolves to `text`/`image` dispatch, or while `status` is `"converting"`/`"error"`.
+
+**CSS parts:** `base`, `header` (hidden entirely when `filename` is unset), `filename`, `body`,
+`spinner` (indeterminate `role="status"`, or `role="progressbar"` once numeric progress is known —
+used both for `status="converting"` and this component's own in-flight text fetch), `error`
+(`role="alert"` — used both for `status="error"` and a failed text fetch), `download-link` (only
+rendered when `src` is set *and* passes the link-safe scheme allowlist — see the URL-safety note
+above; excludes `data:` even though the other two sinks allow it), `highlight-layer` (wrapper around
+every rendered region highlight, image format only), `region-highlight` (one region highlight,
+`data-tone`, `data-active`; image format only), `frame-viewport`/`frame-content`/`frame-controls`/
+`frame-zoom-in`/`frame-zoom-out`/`frame-reset` (forwarded from the internal `<lr-zoomable-frame>`
+while `zoomable`; image format only)
+
+**Themeable custom properties:** `--lr-document-preview-max-height` (default `none`) — the
+consumer-tunable scroll cap on `[part="body"]`, set from `max-height`; `none` means the preview grows
+with its content until a caller opts in. `--lr-document-preview-font` (default `ui-monospace,
+SFMono-Regular, Menlo, Consolas, monospace`) and `--lr-document-preview-spin-duration` (default
+`0.8s`, stopped under reduced motion). `--lr-document-preview-progress` (default `0`) — a unitless
+0–100 number the determinate spinner's `conic-gradient` fill reads; written inline on the ring by
+the component itself from the clamped `progress` property, so overriding it only makes sense to
+repaint the fraction. Plus shared tokens
+`--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
+`--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
+`--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.
+
+**Optional peer deps:** none directly — the `unsupported` slot is commonly used to compose
+`<lr-code-block>` (which has its own optional `shiki` peer dependency; see that component's own
+entry) or a third-party PDF/office-doc viewer, but neither is a dependency of this component itself.
+
+```html
+<lr-document-preview
+  filename="board-notes.txt"
+  mime-type="text/plain"
+  src="/files/board-notes.txt"
+  max-height="24rem"
+  @lr-render-error=${(e) => console.error(e.detail.error)}
+></lr-document-preview>
+
+<!-- A host driving its own server-side conversion -->
+<lr-document-preview filename="deck.pptx" status="converting" progress="42"></lr-document-preview>
+
+<!-- Escape hatch for an unsupported format -->
+<lr-document-preview filename="deck.pptx" mime-type="application/vnd.ms-powerpoint" src="/files/deck.pptx">
+  <lr-code-block slot="unsupported" language="text">Open in PowerPoint to preview.</lr-code-block>
+</lr-document-preview>
+```
+
+Accessibility: the `"converting"` state without numeric `progress` is a `role="status"` region
+wrapping a visually-hidden "Converting document…" string — a *plain* static region, not routed
+through `<lr-live-region>`/`Announcer`, since (like `<lr-typing-indicator>`) it only ever has one
+thing to announce (entering the state), not a rapidly-repeating stream. Once real `progress` is
+available, the region becomes a standard `role="progressbar"` instead, self-describing via
+`aria-valuenow` with no extra live-region wiring. `status="error"` renders `[part="error"]` as
+`role="alert"` — a one-shot assertive notice, without needing the announcer machinery either.
+
+**Known gotchas:**
+- `status="converting"`/`status="error"` always win over format dispatch, regardless of
+  `mimeType`/`src` — a `text`/`image` source is not shown until `status` returns to `"idle"`/`"ready"`.
+- The component's own text/JSON `fetch(src)` is a *different* async operation from the host-driven
+  `status="converting"` conversion. A failed fetch fires `lr-render-error` and renders
+  `[part="error"]` on its own; it never sets `status="error"` itself.
+- changing `src` aborts the superseded text fetch as well as ignoring any stale completion; removing
+  the component aborts its active request.
+- `progress` is only ever consulted for the host-driven `"converting"` state — this component's own
+  in-flight text fetch always renders the indeterminate spinner, with no numeric-progress path.
+- the text/JSON fetch is capped at 25 MB, enforced while streaming so it holds even when the server
+  omits `Content-Length`; going over renders `[part="error"]` with the localized
+  `documentPreviewResourceTooLarge` message. The cap is not overridable per component. The `image`
+  preview is unaffected — it hands `src` to an `<img>` rather than reading it.
+- The `unsupported` slot's initial presence is detected once, before the first render, by scanning
+  light-DOM children directly (not the slot's `assignedElements()`); every later slot-content change
+  is instead picked up via the slot's own `slotchange` listener. Both paths keep detection correct,
+  just via two different mechanisms depending on timing.
+- `download-link` (and thus `lr-download`) only renders/fires when `src` is set — a generic-fallback
+  state with no `src` shows only the file glyph and message, with no download affordance at all.
+- `download-link` also never renders for a `data:` URL, even though `data:` is accepted for text/image
+  sinks — a `src="data:..."` document renders/fetches fine but falls back to no download affordance
+  in the generic state.
+- A `src` that fails its sink's URL-safety check does **not** raise `lr-render-error` — that event is
+  reserved for a `fetch()` that was actually attempted and failed at the network layer; an unsafe/
+  malformed `src` is silently treated as unusable instead (a rendered `[part="error"]` message for
+  text, a silent fallback for image/download — and on the image path that fallback is the download
+  fallback directly, so an `unsupported` slot the host supplied is bypassed).
+
+---

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

@@ -0,0 +1,84 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-document-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDocumentViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/document-viewer/document-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-document-viewer`
+
+A dialog-hosted, format-dispatching full viewer for one document or attachment. It uses a pluggable
+renderer registry and falls back to `<lr-document-preview>` when no renderer matches the file's MIME
+type. First-party invention.
+
+**Properties:**
+- `open: boolean = false` (reflected) — opens or closes the viewer dialog.
+- `name: string = ''` — display name passed to the renderer and used as the dialog heading.
+- `mimeType: string = ''` (attribute `mime-type`) — MIME type used for exact renderer dispatch.
+- `src: string = ''` — source URL passed to the selected renderer or the fallback preview.
+- `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry override;
+  the module-level registry is used when unset.
+- `alt: string = ''` — media alt text forwarded to the resolved renderer, for image-like renderers.
+- `anchor: LyraAnchor | string | null = null` (attribute: false) — declarative scroll-to-anchor
+  target forwarded to the resolved renderer; a string is a highlight id in `highlights`.
+  `hasChanged: () => true`, so re-assigning the same value (e.g. re-clicking the same citation
+  badge) still re-fires.
+- `highlights: LyraHighlight[] = []` (attribute: false) — highlights forwarded to the resolved
+  renderer.
+
+**Events:**
+- `lr-close` — `detail: DocumentViewerCloseReason`, the nested dialog's dismissal reason. The
+  event is emitted after the viewer sets `open` to `false`.
+- `lr-download` — `detail: { src, filename }`, emitted when the native safe download action is
+  activated. The browser download itself is handled by the link.
+- `lr-anchor-result` — `detail: { found }`. Emitted by this shell as `{ found: false }` once per
+  applied `anchor` when the resolved renderer can't honor it (it declares no `capabilities.anchors`,
+  or none matching the anchor's `kind`), when the lazy renderer failed to load, or when the file fell
+  back to `<lr-document-preview>`. A capable renderer instead emits its own `lr-anchor-result` from
+  its embedded `DocumentAnchorTarget` mixin, which composes up through this element unchanged — the
+  shell stays silent in that case, so the event fires exactly once either way. A string `anchor`
+  (a highlight id) counts as supported by any renderer declaring at least one anchor kind.
+
+**CSS parts:** `body` — wrapper around the active renderer, loading/error state, or fallback preview;
+`download-link` — the native download action, rendered when `src` passes Lyra's safe-link policy.
+
+**Themeable custom properties:** `--lr-document-viewer-max-height` (default `70vh`) — maximum block
+size of `[part="body"]` before the dialog body scrolls internally.
+
+**Renderer registry exports:**
+- `DocumentFile` — `{ name: string; mimeType: string; src: string }`, the value passed to renderers.
+- `DocumentRendererDefinition` — optional `render(file)`, `matches(file)`, and lazy `load()` hooks.
+- `DocumentRendererRegistry` — `Map<string, DocumentRendererDefinition>`.
+- `registerDocumentRenderer(key, definition)` — adds or replaces a default-registry entry.
+- `findDocumentRenderer(file, registry?)` — checks an exact MIME-type key, then the first matching
+  `matches()` entry in registration order.
+- `loadDocumentRenderer(definition)` — resolves and identity-caches a lazy definition; rejected loads
+  are retried on the next call.
+
+```html
+<lr-document-viewer
+  open
+  name="report.pdf"
+  mime-type="application/pdf"
+  src="/files/report.pdf"
+></lr-document-viewer>
+```
+
+Register a renderer once during application setup. The definition may load a heavy optional viewer
+only when a matching document is opened:
+
+```ts
+import { registerDocumentRenderer } from '@aceshooting/lyra-ui';
+
+registerDocumentRenderer('application/x-example', {
+  render: (file) => `Preview: ${file.name}`,
+});
+```
+
+When no renderer matches, the viewer renders `<lr-document-preview>`, which handles text and images
+inline and provides a safe generic fallback for other formats.

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

@@ -0,0 +1,63 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-docx-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDocxViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify`, `mammoth` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-docx-viewer`
+
+Fetches a `.docx` Word document as an `ArrayBuffer`, converts it to semantic HTML with the optional
+`mammoth` peer, sanitizes that HTML through the optional `dompurify` peer, and renders the result.
+Mammoth preserves document structure such as headings, paragraphs, lists, tables, and images; it is
+not intended to reproduce pixel-exact Word page layout. There is no unsanitized rendering escape
+hatch: if `dompurify` is unavailable, rendering is blocked even when Mammoth converted successfully.
+
+Every rendered heading's slug (the same GitHub-slugger-style algorithm `<lr-markdown>` uses) is
+stamped as its `id` and cached into `getHeadingTree()`'s document-ordered outline. Adopts
+`DocumentAnchorTarget`: `fragment` anchors resolve against that outline, `text-quote` anchors via
+the shared quote-scoping helpers; `highlights` re-resolve by quote after every render.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
+the scrollable document body. `anchorKinds` is a readonly `['fragment', 'text-quote']` (this
+viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `getHeadingTree()` returns the document-ordered outline as `DocxHeadingItem[]` (`{ id,
+label, level }`), cached on every successful load. `search(query)` resolves the match count via a
+case-insensitive substring search over the rendered content's text (empty/whitespace query behaves
+like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
+(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
+painted marks.
+
+**Events:** `lr-render-error` with `detail.error` when fetching, conversion, sanitization, or a
+non-fatal Mammoth conversion message occurs. `lr-search-change` (`detail: { query, matchCount,
+activeIndex }`) — from `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+`lr-highlight-activate` (`detail: { id }`) — a painted `text-quote` highlight was clicked.
+`lr-text-select` (`detail: { text, anchor, rects }`) — fired on selection end inside the rendered
+content. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call.
+
+**CSS parts:** `base`, `body`, `content`, `spinner`, `error`, `highlight` (a painted `text-quote`
+highlight), `search-match` (a painted in-document search match), and `search-match-active` (the
+currently active search match, also carries `search-match`).
+
+**Themeable custom properties:** `--lr-docx-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+
+**Optional peer dependencies:** install `mammoth` and `dompurify` with `pnpm add mammoth dompurify`.
+The component registers an eager `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+renderer with `<lr-document-viewer>` (a plain `render`, no `load()` hook — importing this module
+defines `<lr-docx-viewer>` immediately; only `mammoth`/`dompurify` themselves are loaded on demand)
+and matches `.docx` filenames when the MIME type is generic.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the document.
+
+```html
+<lr-docx-viewer src="/files/report.docx" name="report.docx" max-height="32rem"></lr-docx-viewer>
+```