@aceshooting/lyra-ui 5.0.0 → 5.2.0

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,187 @@
+<!-- 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. `--lr-document-preview-active-border` (default
+`var(--lr-color-warning, var(--lr-color-brand))`) — the border color of the `[part='region-highlight']`
+matching `activeHighlightId` (image format only), deliberately distinct from the resting highlight
+border so the active region can be recolored without touching the rest. Like the library's other
+state hooks it is an inline `var()` fallback at the point of use rather than a `:host` declaration,
+so it can be set on the element or on any ancestor — `::part(region-highlight)[data-active]` is
+invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which previously left
+re-pointing the shared `--lr-color-warning`/`--lr-color-brand` tokens as the only lever, repainting
+every other element that read them. 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>
+```

package/llms/components/lr-doughnut-chart.md

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-doughnut-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/doughnut-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraDoughnutChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/doughnut-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — see `llms/components/lr-chart.md`).
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

package/llms/components/lr-drawer.md

@@ -0,0 +1,48 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-drawer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/drawer/drawer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDrawer`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/drawer/drawer.class.js`
+- **Family** `components/overlays/` — 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-drawer`
+
+A modal panel anchored to one edge of the viewport. It inherits the dialog overlay contract:
+focus trapping, Escape and optional backdrop dismissal, document scroll locking, overlay stacking,
+accessible naming, and the cancelable `lr-dialog-close` event.
+
+**Properties:**
+- `open: boolean = false` (attribute `open`, reflected) — controls visibility
+- `placement: 'start'|'end'|'top'|'bottom' = 'start'` (attribute `placement`, reflected)
+- `heading?: string`, `label: string`, `closable: boolean`, and `noLightDismiss: boolean` — inherited
+  dialog naming and dismissal options. A plain `aria-label` attribute on the host is honored too,
+  with the same priority-over-everything semantics documented under `lr-dialog` below
+
+**Events:** `lr-dialog-close` (`detail: DialogCloseReason`) — inherited unchanged from `lr-dialog`.
+
+**Slots:** default (drawer body), `footer` — inherited from `lr-dialog`.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `heading`, `close-button`, `label`, `body`, `footer`.
+
+**Themeable custom properties:** `--lr-drawer-width` (default `--lr-size-24rem`; used by
+`placement="start"|"end"`, capped at `100%`), `--lr-drawer-height` (default `--lr-size-24rem`;
+used by `placement="top"|"bottom"`), `--lr-drawer-enter-x` / `--lr-drawer-enter-y` (the panel's
+entrance-animation translate offset — `-x` for start/end, `-y` for top/bottom; both default to
+`±--lr-size-1rem` and are set per `placement`, with `-x` explicitly flipped under `:dir(rtl)` since
+`translateX` is physical. Override to lengthen/shorten the slide-in; the animation is dropped
+entirely under `prefers-reduced-motion: reduce`). It also inherits `<lr-dialog>`'s own tokens —
+`--lr-dialog-overlay-color`, `--lr-dialog-width` and `--lr-dialog-max-width` — since `LyraDrawer`
+extends `LyraDialog`; the drawer's own width tokens take precedence for its panel.
+
+```html
+<lr-drawer open placement="end" heading="Filters" closable>
+  <lr-checkbox label="Only active"></lr-checkbox>
+</lr-drawer>
+```
+
+---

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

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-drilldown-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraDrilldownPanel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-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-drilldown-panel`
+
+Controlled navigation shell from a chart or table datum to related evidence, documents, entities,
+or agent runs. It renders a breadcrumb path and delegates category content to existing primitives.
+
+**Properties:** `path: DrilldownNode[] = []` and `types: NodeTypeStyle[] = []` (both attribute:
+false), `accessibleLabel: string | null = null` (attribute `aria-label` — names the nested
+`lr-tabs`; unset renders no `aria-label` at all, matching `lr-tabs`' own default),
+`communityLabel: string = ''` (attribute `community-label`), `showFocusButton: boolean = true`
+(attribute `show-focus-button`). **Events:**
+`lr-drilldown-navigate` (`detail: { id, index }`). **Slots:** `runs`. **CSS parts:** `base`,
+`breadcrumb`, `breadcrumb-item`, `breadcrumb-button`, `tabs`, `category`, `content`, `evidence-item`,
+`document-item`, `entity-item`, `empty`.