@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-ingestion-queue.md

@@ -0,0 +1,68 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-ingestion-queue`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.js';` (registers the tag; side-effect import)
+- **Class** `LyraIngestionQueue`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.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-ingestion-queue`
+
+Controlled list of documents moving through an ingestion pipeline: stage badge, progress, chunk/
+embedding counts, retry attempts, errors, and retry/cancel requests. Never ingests anything itself.
+
+**Properties:**
+- `items: IngestionQueueItem[] = []` (attribute: false) — `IngestionQueueItem { id: string;
+  document: DocumentRef; stage: IngestionStage; progress?: number; chunkCount?: number;
+  embeddedChunkCount?: number; attempts?: number; error?: string }` (exported here). `document` is
+  **`DocumentRef` from `@aceshooting/lyra-ui/ai`** (`{ id, name, mimeType?, uri?, version? }`), not a
+  divergent name/mimeType pair, so a caller can reuse the same list a `DocumentRef`-typed
+  knowledge-base view already holds. `IngestionStage = 'queued' | 'uploading' | 'extracting' |
+  'chunking' | 'embedding' | 'indexing' | 'done' | 'failed' | 'cancelled'` — the first six are
+  in-flight (in pipeline order), the last three terminal. `progress` is 0–100 *within the current
+  stage* (omitted/non-finite renders an indeterminate indicator, and it is only meaningful during an
+  active non-`'queued'` stage). `embeddedChunkCount` renders only alongside a defined `chunkCount`.
+  `error` renders only while `stage === 'failed'`. Controlled — pass a new array to update
+- `label: string = ''` — accessible name for the region; defaults to the localized
+  `ingestionQueueLabel`
+- `virtualizeThreshold: number = 100` (attribute `virtualize-threshold`) — item count above which the
+  list renders through an internal `lr-virtual-list`
+
+**Events:**
+- `lr-retry` (`detail: IngestionRetryEventDetail` = `RetryEventDetail & { itemId: string }` =
+  `{ attempt: number; messageId?: string; itemId: string }`) — `attempt` is the attempt about to be
+  made, `(item.attempts ?? 0) + 1`. Only offered on `'failed'` rows.
+- `lr-cancel` (`detail: IngestionCancelEventDetail` = `CancelEventDetail & { itemId: string }` =
+  `{ reason?: string; itemId: string }`) — this component never supplies `reason` itself. Only
+  offered on non-terminal rows (`'queued'` plus the five active stages).
+
+Both `RetryEventDetail` and `CancelEventDetail` come from `@aceshooting/lyra-ui/ai`.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `list`, `item`, `item-header`, `item-name`, `item-meta`, `item-stage` (the
+per-item stage label), `item-progress`,
+`item-chunk-count`, `item-embedding-status` (the "N of M chunks embedded" text, only once both
+`chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`),
+`item-error` (only for `stage="failed"` with `error` set), `item-actions`, `retry-button`,
+`cancel-button`, `empty`.
+
+In virtualized mode (at or above `virtualizeThreshold`) the rows live in the internal
+`lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,
+`item-meta`, `item-error`, `item-actions`, `retry-button` and `cancel-button` are forwarded out
+through `exportparts`, so `lr-ingestion-queue::part(item)` and the rest keep working from a consumer
+stylesheet. `item-stage`, `item-chunk-count`, `item-embedding-status` and `item-attempts` are not
+forwarded, so those four are only reachable through `::part()` while the queue is below the
+threshold.
+
+**Themeable custom properties:** `--lr-ingestion-queue-max-height` (default `none`) — non-virtualized
+mode only: caps how tall the list grows before it scrolls internally. No effect once virtualized —
+retheme the internal list via `lr-virtual-list { --lr-virtual-list-height: … }` instead.
+
+**Optional peer deps:** none.
+
+---

package/llms/components/lr-input.md

@@ -0,0 +1,117 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/input/input.js';` (registers the tag; side-effect import)
+- **Class** `LyraInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/input/input.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-input`
+
+A single-line plain-text input primitive, the `lr-*` equivalent of a plain `wa-input`,
+form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the same opt-in
+`label`/`hint`/`errorText` form-control chrome as `lr-textarea`/`lr-select`, and the same
+`size` scale as `lr-select`/`lr-combobox`.
+
+**Properties:**
+- `type: 'text' | 'password' | 'email' | 'number' | 'time' | 'search' = 'text'`
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
+- `value: string = ''` (from `FormAssociated`)
+- `placeholder: string = ''`
+- `clearable: boolean = false` (reflected) — shows a localized clear action while a `text` or
+  `search` input has a value; clearing preserves input focus
+- `readonly: boolean = false` (reflected) — forwarded to the native input and disables clearing
+- `label: string = ''`
+- `hint: string = ''`
+- `errorText: string = ''` (attribute `error-text`)
+- `accessibleLabel: string | null = null` (attribute `aria-label`)
+- `autocomplete: string = ''`
+- `spellcheck: boolean = true` — forwarded to the native input, including `spellcheck="false"`
+- `autocapitalize: string = ''` / `autoCorrect: string = ''` (attribute `autocorrect`)
+- `inputMode: string = ''` (attribute `inputmode`) / `enterKeyHint: string = ''` (attribute
+  `enterkeyhint`) — these four are forwarded verbatim to the native input; an empty string omits
+  the attribute entirely
+- `min?: number` / `max?: number` (attributes `min`/`max`) / `step?: number | 'any'` (attribute
+  `step`, accepts the native `'any'` value alongside a number) — forwarded verbatim to the native
+  input and validated by it. Intended for `type="number"`; `step` is equally meaningful on
+  `type="time"`. On `lr-input` itself the `min`/`max` *attributes* are number-converted, so a
+  non-numeric bound only survives a direct property assignment; the declared type also admits a
+  string so a subclass can narrow the attribute parsing to its own native type's literal form —
+  `lr-time-input` does exactly that. Inert for the other types
+- `passwordVisible: boolean = false` (attribute `password-visible` — `type="password"` only)
+- `name`/`disabled`/`required` (from `FormAssociated`)
+
+**Getters/methods:** `input: HTMLInputElement | null` (the internal native `<input>`, for direct DOM
+access), `focus(options?: FocusOptions)`, `blur()`, `select()`. Also forwards the full native
+selection/editing surface, mirroring `lr-textarea`'s identical passthrough: `selectionStart: number
+| null` and `selectionEnd: number | null` (readable/writable; `null` both before the internal input
+has rendered and whenever `type` doesn't support selection — only `text`/`search`/`password` do,
+matching the native `<input>`'s own contract), `setSelectionRange(start, end, direction?)`
+(no-op before render, otherwise throws the same native `InvalidStateError` a native `<input>` would
+for an unsupported `type`), and `setRangeText(replacement, start?, end?, selectMode?)` (no-op
+before render; syncs `value` afterward without emitting a user event).
+
+**Events:** native-style composed `input` and `change`, plus `lr-input` (`detail: { value }`,
+fired on every user-driven edit) and `lr-change` (`detail: { value }`, fired on the native
+`change` timing), `blur`/`focus` (re-dispatched bubbling + composed from the internal native input's
+own `blur`/`focus`), and `lr-clear` (no detail, fired after the clear action's `input`/`lr-input`/
+`change`/`lr-change` sequence).
+
+**Slots:** `label`, `hint`, `error`, `start` (adornment before the input), `end` (adornment after the
+input and built-in actions).
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `password-toggle`
+(present only when `type="password"`), `start`, `end`, `clear-button` (non-empty clearable
+`text`/`search` inputs only), `hint`, `error`.
+
+**Themeable custom properties:** `--lr-input-padding-block`, `--lr-input-padding-inline`,
+`--lr-input-font-size`, `--lr-input-control-min-height` — all four auto-swapped per `size`
+(`2xs`…`xl`), the same pattern
+`lr-select`'s `--lr-select-trigger-padding`/`--lr-select-font-size` use.
+`--lr-input-control-height` pins an **exact** outer control-row height (both floors and caps it) —
+for example to pixel-match an `<lr-select>` or `<lr-combobox>` in the same toolbar row. It is
+undeclared by default, leaving `--lr-input-control-min-height` as a floor only and the row free to
+grow.
+
+### Exact-height hatches — the one rule that applies to all of them
+
+Several controls expose the same pair: a per-`size` `*-min-height` **floor**, and an exact
+`*-height` **cap**. The family is `--lr-input-control-height`, `--lr-select-trigger-height`,
+`--lr-combobox-trigger-height`, `--lr-date-input-control-height`, `--lr-button-height`,
+`--lr-known-date-field-height`, and `--lr-chip-height`. Every one of them behaves identically:
+
+- **Each is undeclared by default.** The component reads it only through two `var()` fallbacks —
+  `min-block-size: var(--lr-x-height, var(--lr-x-min-height))` and
+  `block-size: var(--lr-x-height, auto)` — so leaving it unset is what makes the per-tier floor
+  and the content-driven height work at all.
+- **Setting one to `auto` is not the same as leaving it unset.** `auto` is a perfectly valid
+  *declared* value, and a declared value wins over the `var()` fallback arm — so `auto` silently
+  turns the per-tier `*-min-height` floor into dead code, and nothing anywhere reports it. To
+  return a control to default behavior, **remove** the declaration; never neutralize it with
+  `auto`.
+- Because the component itself never declares them, each can be set inline on the element, from an
+  ancestor, or from an outer-tree rule (`lr-input { --lr-input-control-height: 44px }`) — no
+  `::part()` rule needed.
+- **A dead declaration is invisible in source.** There is no way to tell a live `--lr-*`
+  declaration from a shadowed or defeated one without rendering: a test asserting on stylesheet
+  text passes either way. Assert the rendered `min-block-size`/`block-size` via
+  `getComputedStyle` on the real element instead of reading the custom property back.
+
+**Optional peer deps:** none.
+
+```html
+<lr-input type="password" label="Password"></lr-input>
+<lr-input type="email" label="Email" required></lr-input>
+<lr-input size="s" placeholder="Compact"></lr-input>
+<lr-input type="search" clearable value="workflow" aria-label="Search"><span slot="start">⌕</span></lr-input>
+```
+
+**Known gotchas:**
+- `type="email"`/`type="number"` delegate constraint validation to the internal native `<input>`'s
+  own browser-computed `validity` (format/range/step), bridged into this element's own
+  `ElementInternals` — not a second hand-rolled regex check.
+- `type="password"` always renders the `password-toggle` button; there is no separate opt-out.

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

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-intersection-observer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/intersection-observer/intersection-observer.js';` (registers the tag; side-effect import)
+- **Class** `LyraIntersectionObserver`, also available unregistered from `@aceshooting/lyra-ui/components/utility/intersection-observer/intersection-observer.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-intersection-observer`
+
+Lifecycle-managed wrapper around the native `IntersectionObserver`. It observes all element children
+in the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected), `rootMargin: string = '0px'` (attribute
+`root-margin`), `threshold: number | number[] = 0`, and `root: Element | null = null`.
+
+**Events:** `lr-intersection` with `{ entries: IntersectionObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---

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

@@ -0,0 +1,101 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-json-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraJsonViewer`, also available unregistered from `@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.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-json-viewer`
+
+A collapsible, copyable tree view for an arbitrary JSON-serializable value (object, array, string,
+number, boolean, null, or `undefined`). Serves as a fallback renderer wherever a raw payload needs
+inspecting without a bespoke view. Expand/collapse state is keyed by structural path (not object
+identity), so it survives a `data` reassignment that keeps the same shape — e.g. a streaming result
+being patched in place. A container value that self-references (directly or through a longer cycle)
+renders as a leaf `Circular reference` marker (`data-type="circular"`) instead of recursing — no
+stack overflow on cyclic `data`.
+
+**Properties:**
+- `data: unknown` (attribute `false` — property-only, not settable via an HTML attribute)
+- `collapsedDepth?: number` (attribute `collapsed-depth`) — nodes at or beyond this nesting depth
+  (root = `0`) start collapsed; omitted/`undefined` means nothing auto-collapses
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
+  viewer scrolls internally past this height instead of growing the page
+- `copyable: boolean = false` (reflected) — shows copy-to-clipboard affordances: one for the whole
+  value, plus one per node
+- `search: string = ''` — case-insensitive substring match against keys/values; matches are
+  highlighted and their ancestors auto-expanded
+
+**Methods:** `runSearch(query)` sets the declarative `search` property and awaits the recompute,
+resolving the match count — named distinctly from `search` because a class member can't share a name
+with a reactive property. `searchNext()`/`searchPrevious()` advance/step back a match cursor
+(wrapping) and scroll the active match into view, resolving `false` when there are no matches.
+`clearSearch()` resets `search` to `''`, clearing all matches and the cursor.
+
+**Events:** `lr-copy` (`detail: { text: string }`) — fired by the top-level copy button or a
+per-node one. Fires even when `navigator.clipboard` is unavailable or the write silently failed
+(a rejected `writeText()` is swallowed), so a consumer can still observe copy *intent* — the event
+is not a confirmation that the OS clipboard was actually reached. Copying a circular `data` value
+serializes safely, substituting the same `Circular reference` marker the tree view renders, instead
+of throwing. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — fired whenever the
+search query, match count, or active-match cursor changes, from `runSearch()`/`searchNext()`/
+`searchPrevious()`/`clearSearch()`, or a direct `search`/`data` property write.
+
+**Slots:** none — the tree is rendered entirely from `data`.
+
+**CSS parts:** `base` (root scroll container, respects `max-height`), `toolbar` (wrapper around the
+top-level copy button, only rendered when `copyable`), `tree` (wrapper around the rendered node
+tree), `key` (an object property key or array index label, `data-match` while it matches `search`,
+`data-active` while it is the current `searchNext()`/`searchPrevious()` cursor position),
+`value` (a primitive value's text — carries `data-type` of
+`string`/`number`/`boolean`/`null`/`undefined`/`circular` for per-type coloring, `data-match`
+while it matches `search`, and `data-active` while it is the current cursor position), `bracket` (a
+`{`, `}`, `[`, or `]` delimiter), `toggle` (a container node's expand/collapse button; hidden but
+present for row alignment on leaf/empty nodes),
+`copy-button` (a copy-to-clipboard button — the top-level one in `toolbar` (aria-label "Copy JSON to
+clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age"); only rendered when
+`copyable`)
+
+**Themeable custom properties:** `--lr-json-viewer-max-height` (default `none` — grows with content
+until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono)`),
+`--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
+box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
+shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
+without repainting every other warning-toned surface that reads the same shared token. Plus shared
+tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
+`--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
+`--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```ts
+import { html } from 'lit';
+import '@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.js';
+
+html`<lr-json-viewer .data=${apiResponse} copyable max-height="24rem" search=${query}></lr-json-viewer>`;
+```
+
+```html
+<lr-json-viewer copyable max-height="24rem"></lr-json-viewer>
+<script type="module">
+  document.querySelector('lr-json-viewer').data = { hello: 'world', items: [1, 2, 3] };
+</script>
+```
+
+**Known gotchas:**
+- `data` is property-only (`attribute: false`) — it must be set via `.data = ...` or a lit-html `.data=${...}`
+  binding, never as a plain HTML attribute.
+- Search highlighting auto-expands only the *ancestors* of a match, not the whole tree — a
+  non-matching sibling subtree elsewhere stays collapsed (or expanded) exactly as it already was.
+- An explicit per-node expand/collapse (from clicking a node's `toggle` button) permanently overrides
+  both `collapsedDepth` and any search-driven auto-expand for that path, until `data` is reassigned
+  with a different shape.
+- Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
+  row's expand/collapse state.
+
+---

package/llms/components/lr-kbd.md

@@ -0,0 +1,74 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-kbd`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/kbd/kbd.js';` (registers the tag; side-effect import)
+- **Class** `LyraKbd`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/kbd/kbd.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-kbd`
+
+A small chip representing a keyboard shortcut, rendering the platform-appropriate glyph for
+cross-platform modifier keys (⌘ on macOS, "Ctrl" elsewhere) from a single platform-neutral `keys`
+string. First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `keys: string = ''` — a `+`-separated sequence of tokens, e.g. `"mod+k"` or `"mod+shift+p"`.
+  Recognized modifier tokens: `mod` (platform-neutral primary modifier — ⌘/"Command" on macOS,
+  "Ctrl"/"Control" elsewhere), `alt` (⌥/"Option" on macOS, "Alt" elsewhere), `shift` (⇧/"Shift"
+  always), `ctrl`/`control` (always the literal Control key, distinct from `mod`, for a shortcut
+  that's specifically Ctrl even on macOS). Anything else falls through to a small built-in map of
+  friendly labels (`enter` → `↵`/"Enter", `esc`/`escape` → "Esc"/"Escape", `tab`, `space`,
+  `backspace` → `⌫`/"Backspace", `delete` → "Del"/"Delete", `home`, `end`, `pageup` → "PgUp"/"Page
+  Up", `pagedown` → "PgDn"/"Page Down", the four `arrowup`/`arrowdown`/`arrowleft`/`arrowright` →
+  arrow glyphs, `plus`/`minus` → literal "+"/"−" as an escape hatch since `+` is the token
+  delimiter and can't appear as a literal token itself), or, failing that, renders as typed
+  (single letters/digits upper-cased).
+
+**Exported types/functions (also directly usable standalone):** `KbdKeyLabel { visual: string;
+word: string }` — one resolved token's rendered glyph and spelled-out word.
+`shortcutTokenLabel(rawToken: string, isMac: boolean): KbdKeyLabel` — resolves a single token,
+parameterized on `isMac` so both platform branches are unit-testable without spoofing `navigator`.
+`parseShortcut(keys: string, isMac: boolean): KbdKeyLabel[]` — splits and resolves a full `keys`
+string.
+
+**Events:** none — purely presentational.
+
+**Slots:** default — an escape hatch for fully custom key-cap content (e.g. an icon instead of a
+text glyph). When it has any real (non-whitespace) content, it replaces the `keys`-driven rendering
+entirely and this component stops *computing* its own `aria-label` from `keys`, leaving the slotted
+content to carry its own accessible name — a host-supplied `aria-label` attribute is still forwarded
+onto the rendered chip in either mode, custom content included.
+
+**CSS parts:** `base` (the chip root), `key` (one per rendered token).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-surface`/
+`-border`/`-text`/`-text-quiet`, `--lr-radius`, `--lr-font`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-kbd keys="mod+k"></lr-kbd>
+<lr-kbd keys="mod+shift+p"></lr-kbd>
+<lr-kbd keys="esc"></lr-kbd>
+```
+
+Platform detection (`IS_MAC`, computed once at module scope, not per-instance/per-render, since a
+page's platform never changes mid-session) prefers `navigator.userAgentData` (Client Hints, so far
+Chromium-only) when available, falling back through `navigator.platform` (long-deprecated) and
+finally a `navigator.userAgent` substring check — all three are deprecated/non-standard to varying
+degrees but remain, in combination, the practical cross-browser way to answer "is this macOS" today.
+The rendered chip carries `role="img"` with a single spelled-out `aria-label` (e.g. "Command+K")
+rather than exposing each glyph/`+`-separator as separate accessible-tree text, since the individual
+pieces aren't real words and would read worse piecemeal than as one label — glyphs like ⌘/⇧/⌥ are
+not reliably announced by every screen reader/platform combination, which is exactly why the
+spelled-out word form exists at all. An empty `keys` with no explicit `aria-label` override and no
+slotted content renders nothing visible and is marked `aria-hidden="true"` (no `role="img"`) instead
+of exposing a nameless image element — `role`/`aria-hidden` are both derived from the same
+computed-label value so the two can never disagree.
+
+---

package/llms/components/lr-knowledge-base.md

@@ -0,0 +1,64 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-knowledge-base`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/knowledge-base/knowledge-base.js';` (registers the tag; side-effect import)
+- **Class** `LyraKnowledgeBase`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/knowledge-base/knowledge-base.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-knowledge-base`
+
+Controlled source list for a retrieval knowledge base: sync status, indexing health, permissions, and
+per-row create/sync/pause/delete requests. Composes `lr-table`, `lr-badge`, `lr-stat`, and a per-row
+`lr-menu`. Never syncs or indexes anything itself.
+
+**Properties:**
+- `sources: KnowledgeSource[] = []` (attribute: false) — `KnowledgeSource { id: string; name: string;
+  type?: string; syncStatus: KnowledgeSourceSyncStatus; indexingHealth?: KnowledgeSourceIndexingHealth;
+  permission?: KnowledgeSourcePermission; documentCount?: number; lastSyncedAt?: Date | string;
+  errorMessage?: string }` (all four types exported here), where
+  `KnowledgeSourceSyncStatus = 'idle' | 'syncing' | 'paused' | 'synced' | 'error'`,
+  `KnowledgeSourceIndexingHealth = 'healthy' | 'degraded' | 'failed' | 'unknown'` (absent is treated
+  as `'unknown'`), and `KnowledgeSourcePermission = 'owner' | 'editor' | 'viewer' | 'restricted'`.
+  `type` is a free-form connector kind (`'drive'`, `'notion'`, `'upload'`, `'url'`, …) rendered
+  as-is. `lastSyncedAt` follows this library's `Date | string` timestamp convention (epoch ms Date or
+  ISO-8601); absent/unparseable renders "never synced". `errorMessage` shows only while
+  `syncStatus === 'error'`. `id`/`name` follow `DocumentRef`'s spirit, but a source is a *connector
+  feeding* documents, not a document, so the rest of the fields are its own
+- `label: string = ''` — heading text and the table's accessible name; falls back to a localized default
+- `hideSummary: boolean = false` (attribute `hide-summary`, reflected) — hides the aggregate
+  total/synced/syncing/needs-attention row
+- `hideCreate: boolean = false` (attribute `hide-create`, reflected) — hides the "Add source"
+  affordance, e.g. for a read-only or permission-gated view
+
+**Events:** `lr-kb-create` (`detail: undefined` — nothing exists yet to reference), `lr-kb-sync`
+(`detail: { sourceId: string }`), `lr-kb-pause` (`detail: { sourceId: string }`), `lr-kb-delete`
+(`detail: { sourceId: string }`, no built-in confirmation, matching `lr-thread-list`'s
+`lr-thread-delete`).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `toolbar` (heading + "Add source" row), `heading` (the heading text),
+`create-button` (omitted while `hideCreate`), `summary` (omitted while `hideSummary` or `sources` is
+empty), `summary-stat`, `table`, `name-cell`, `source-name`, `source-type` (omitted when `type` is
+unset), `sync-cell`, `sync-badge`, `sync-timestamp`, `sync-error`, `health-cell`, `health-badge`,
+`document-count` (omitted when unset), `permission-badge` (omitted when `permission` is unset),
+`actions-menu`, `actions-trigger` (the kebab `<button>`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- `permission` is rendered informationally only — the per-row action menu is never gated by it.
+  Authorization enforcement is the host's concern.
+- "Sync now" is disabled only while `syncStatus === 'syncing'` (including on `'error'` rows, so
+  re-running a failed sync is one click); "Pause sync" is enabled only while `'syncing'`.
+- The inner `lr-table`'s own `lr-row-click` is deliberately stopped from propagating — this component
+  exposes no row-click/selection semantics, only the per-row action menu.
+
+---

package/llms/components/lr-knowledge-graph-explorer.md

@@ -0,0 +1,92 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-knowledge-graph-explorer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/knowledge-graph-explorer/knowledge-graph-explorer.js';` (registers the tag; side-effect import)
+- **Class** `LyraKnowledgeGraphExplorer`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/knowledge-graph-explorer/knowledge-graph-explorer.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** `d3-drag`, `d3-force`, `d3-selection`, `d3-zoom` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-knowledge-graph-explorer`
+
+Orchestration-level knowledge-graph surface: the `lr-graph` canvas plus entity search, type filters,
+neighborhood expansion, pinned nodes, path finding between pins, node selection, and a details
+overlay. Composes `lr-graph`, `lr-graph-legend`, `lr-entity-card`, `lr-neighbor-list`,
+`lr-path-strip`, and `lr-popover.showAt()`.
+
+**Properties:** (host-supplied data, rendered as given)
+- `nodes: GraphNode[] = []`, `links: GraphLink[] = []`, `nodeTypes: GraphNodeType[] = []`,
+  `communities: GraphCommunity[] = []` (all attribute: false) — exactly `lr-graph`'s own types,
+  forwarded verbatim; see the `lr-graph` section above for each shape
+- `entityDetails: Record<string, LyraKnowledgeGraphEntityDetails> = {}` (attribute: false) —
+  `LyraKnowledgeGraphEntityDetails = Pick<LyraEntity, 'description' | 'properties' | 'degree'>`, i.e.
+  `{ description?: string; properties?: Record<string, string | number>; degree?: number }`, keyed by
+  node id. Merged onto the matching `GraphNode` to build the entity shown in the details popover and
+  neighbor rows. A node with no entry still renders: `degree` falls back to a live count derived from
+  `links`, `description`/`properties` are omitted
+- `path: LyraPathElement[] = []` (attribute: false) — host-supplied path-finding *result*, rendered
+  via `lr-path-strip` (`{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string;
+  directed?: boolean; reverse?: boolean }`). Empty renders no strip
+
+(self-managed but presettable/observable — this component toggles its own copy on interaction, the
+same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature works with zero host wiring)
+- `hiddenTypes: string[] = []` (attribute: false) — forwarded to both `lr-graph.hiddenTypes` and
+  `lr-graph-legend.hiddenTypes`
+- `selectedNodeId: string | null = null` (attribute `selected-node-id`) — drives the details popover
+  and `lr-graph.selectedNodeIds`; `null` shows no selection and keeps the popover closed
+- `pinnedNodeIds: string[] = []` (attribute: false) — exactly two pinned nodes reveals the "Find
+  path" action
+
+(presentation)
+- `renderer: 'svg' | 'canvas' = 'svg'` — forwarded to `lr-graph.renderer`
+- `width: number = 800`, `height: number = 600`
+- `highlight: 'selection' | 'hover' | 'none' = 'selection'` — what drives the dimming forwarded to
+  `lr-graph`'s `dimmedNodeIds`/`dimmedLinkIds`, on top of the always-active search-match dimming:
+  `'selection'` dims by the selected node's immediate neighborhood; `'hover'` additionally dims by
+  the pointer-hovered node (falling back to selection while nothing is hovered); `'none'` forwards
+  empty arrays regardless of search/selection state, for a host driving dimming its own way
+- `label: string = ''` — accessible name for the root landmark; falls back to the localized
+  `graphExplorerLabel`
+
+**Events:**
+- `lr-path-request` (`detail: { sourceId: string; targetId: string }`) — the "Find path" action was
+  activated with exactly two nodes pinned. This component has no traversal algorithm; the host
+  computes/fetches the path and assigns it back through `path`.
+- `lr-pin-change` (`detail: { pinnedNodeIds: string[] }`) — the complete updated array. Already
+  self-applied before emitting, so reassigning back is optional.
+- Bubbling straight through from composed children, unmodified: `lr-node-click`
+  (`detail: { id, x, y }`), `lr-link-click` (`detail: { source, target, id? }`), `lr-community-click`
+  (`detail: { id }`), `lr-node-expand` (`detail: { id }`, from `lr-graph` and/or `lr-neighbor-list`),
+  `lr-relation-activate` (`detail: { relation, sourceId?, targetId? }`, from `lr-path-strip`).
+
+**Slots:** `details` — overrides the details popover's default content (an `lr-entity-card` with a
+nested `lr-neighbor-list` and a pin toggle). Receives no data; an overriding consumer reads the
+selected entity from `selectedNodeId`/`nodes` itself.
+
+**CSS parts:** `base` (`role="group"`), `toolbar`, `search` (the search `lr-input`), `legend` (the
+composed `lr-graph-legend`), `search-results` (only while the internal search query is non-empty),
+`search-result` (`role="listitem"` wrapping a `<button>`), `search-empty`, `pinned` (only while
+`pinnedNodeIds` is non-empty), `pinned-heading`, `graph` (the composed `lr-graph`), `path` (only
+while `path` is non-empty), `detail-popover`, `detail-card`.
+
+**Themeable custom properties:** shared tokens only; retheme the graph through `lr-graph`'s own
+tokens (see above).
+
+**Optional peer deps:** `lr-graph`'s `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` set, transitively.
+
+**Known gotchas:**
+- The search query is internal `@state`, not a public property.
+- `lr-graph.getNodePosition()` and `lr-node-click`'s `{ x, y }` are graph-*local* drawing
+  coordinates, never viewport pixels. For `renderer="svg"` this component resolves the real viewport
+  rect from `event.composedPath()`'s `[part="node"]` element; for `renderer="canvas"` (no per-node
+  DOM) it uses the click's `clientX`/`clientY`. While an svg-click popover stays open it re-anchors
+  on every `lr-viewport-change` from the graph — no `requestAnimationFrame` polling loop.
+- Selecting a node any *other* way (search result, neighbor row, path element, keyboard Enter/Space
+  on a graph node — which dispatches no native `click`) has no rect to read, so it calls
+  `lr-graph.focusNode(id)` and anchors at the graph element's own bounding-box center instead; no
+  continuous tracking applies on that path.
+
+---