@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-input.md

@@ -0,0 +1,82 @@
+<!-- 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()`.
+
+**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.
+
+**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,98 @@
+<!-- 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 `ui-monospace, SFMono-Regular, Menlo,
+Consolas, monospace` — component-specific since no shared monospace token exists), 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.
+
+---

package/llms/components/lr-known-date.md

@@ -0,0 +1,84 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-known-date`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/known-date/known-date.js';` (registers the tag; side-effect import)
+- **Class** `LyraKnownDate`, also available unregistered from `@aceshooting/lyra-ui/components/utility/known-date/known-date.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-known-date`
+
+A form-associated control for a date the user already knows (a birthdate, a passport expiry),
+collected as three plain day/month/year number fields in the locale's natural order rather than a
+calendar popup. Uses the shared `FormAssociated` mixin; the submitted value is always canonical ISO
+8601 (`YYYY-MM-DD`), or `''` while any field is blank or the combination isn't a real calendar date.
+
+**Properties:**
+- `value: string` — canonical `YYYY-MM-DD` or `''`. Assignment goes through a strict-ISO gate:
+  a non-zero-padded (`"2007-3-27"`) or calendar-invalid (`"2007-02-30"`) literal sanitizes to `''`
+  and clears all three fields. Programmatic assignment never emits `input`/`change`
+- `valueAsDate: Date | null` — the same value as a local-midnight `Date`; settable (assigning
+  `null` clears)
+- `min: string = ''`, `max: string = ''` — inclusive `YYYY-MM-DD` bounds, surfaced as
+  `rangeUnderflow`/`rangeOverflow`
+- `readonly: boolean = false` (reflected) — also suspends all validity flags
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`)
+- `locale: string = ''` — BCP-47 override for field order and per-field label sampling only
+  (redeclared non-reflecting over the base `locale`, like `lr-date-input`)
+- `autocomplete: string = ''` — the special value `'bday'` expands to
+  `bday-day`/`bday-month`/`bday-year` across the three fields; any other non-empty value is
+  forwarded verbatim to all three
+- `dayLabel: string = 'Day'` (`day-label`), `monthLabel: string = 'Month'` (`month-label`),
+  `yearLabel: string = 'Year'` (`year-label`) — visible **and** accessible per-field labels; each
+  routes through `localize()` only while left at its literal default
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — applied to `[part="fieldset"]`,
+  which owns the group role, overriding the `<legend>`-derived name
+
+**Methods:** `focus(options?)` focuses the first field in locale order; `blur()` blurs whichever
+field currently has focus.
+
+**Events:** `input` (every keystroke), `change` (a field blur where the composite value newly
+transitioned), plus re-dispatched bubbling/composed `focus` and `blur` (`blur` fires once when focus
+leaves all three fields, not per field-to-field Tab). `input`/`change` detail is
+`{ value, day, month, year, field }` — `value` is the canonical ISO date or `''`, `day`/`month`/`year`
+are the live raw typed text, and `field` is `'day' | 'month' | 'year'`, whichever was last edited.
+
+**Slots:** `label`, `hint`, `error` (each rendered alongside its matching property).
+
+**CSS parts:** `form-control` (outer wrapper), `fieldset` (the `<fieldset>` grouping the fields —
+carries `aria-label` when `accessibleLabel` is set), `legend` (the `<legend>`; hidden when there is
+no label, and grows a `*` suffix while `required`), `fields` (the flex row), `field` (one field
+block, repeated three times, `data-field="day"|"month"|"year"`), `field-input` (the native
+`<input type="text" inputmode="numeric">` inside it, same `data-field` marker), `field-label` (the
+small per-field text label), `hint`, `error` (`role="alert"`).
+
+**Themeable custom properties:** `--lr-known-date-field-padding-block`,
+`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size` (all three rewritten by
+each `:host([size])` rule; `m` defaults `--lr-space-s`/`--lr-space-s`/`--lr-font-size-md-sm`),
+`--lr-known-date-field-gap` (default `--lr-space-s` — gap between the three field blocks),
+`--lr-known-date-day-field-width` / `--lr-known-date-month-field-width` (default `--lr-size-3-5em`)
+and `--lr-known-date-year-field-width` (default `--lr-size-5em`) — the per-field input widths, not
+size-scaled.
+
+**Known gotchas:**
+- Field *order* is derived from the locale by formatting a probe date (Jan 2 2026) with
+  `Intl.DateTimeFormat` and reading back the part order — not from `Date.parse()`'s mm/dd/yyyy bias.
+  It falls back to `month, day, year` only when that sampling fails.
+- Auto-advance (typing a field's last digit moves to the next) and backspace-into-the-previous-field
+  are this library's own additions, not Web Awesome parity. Auto-advance is purely digit-count
+  based, never value based.
+- Each `<input>` shows exactly what was typed and is never reformatted or reverted; only the
+  composite `value` is zero-padded.
+- Non-digit keystrokes are rejected before reaching field state — locale-specific numerals
+  (e.g. Arabic-Indic digits) are not accepted as input.
+- ArrowLeft/ArrowRight cross fields at a field's text boundary, and the *physical* key meaning
+  "next field" flips under an inherited `dir="rtl"`; the locale-derived field order itself does not.
+- A blank composite is `valueMissing` only when **all three** fields are blank; a partially typed
+  required date reports `badInput` instead.
+- The host carries a `:state(blank)` custom state whenever `value === ''`, and `data-invalid` only
+  once touched (first blur out of the whole control) and actually invalid.

package/llms/components/lr-lightbox.md

@@ -0,0 +1,79 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-lightbox`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/lightbox/lightbox.js';` (registers the tag; side-effect import)
+- **Class** `LyraLightbox`, also available unregistered from `@aceshooting/lyra-ui/components/media/lightbox/lightbox.class.js`
+- **Family** `components/media/` — 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-lightbox`
+
+A modal, full-screen image viewer with prev/next navigation, captions, and pan/zoom delegated to one
+stable embedded `<lr-zoomable-frame>`. It renders its own dialog panel (not a nested `<lr-dialog>`)
+but shares the same overlay infrastructure as `<lr-dialog>`/`<lr-command-palette>` — stacking, focus
+trap, Escape/backdrop dismissal, scroll lock, and focus return.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this or call `close()`; there is no `show()`/`hide()`.
+- `images: LyraLightboxImage[] = []` (attribute: false) — `LyraLightboxImage { src: string; alt?:
+  string; caption?: string }`. `src` is passed to the embedded frame, which runs it through
+  `safeMediaSrc()`. `alt`/`caption` are caller data, never localized.
+- `index: number = 0` (reflected) — clamped defensively for rendering and silently re-synced (no
+  event) when `images` shrinks.
+- `loop: boolean = false` (reflected) — wraps prev/next past the ends.
+- `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — opts out of backdrop dismissal.
+- `showCounter: boolean = true` (attribute `show-counter`) — shows `[part="counter"]` and its
+  live-region announcement.
+- `minZoom: number = 0.5`, `maxZoom: number = 4`, `zoomStep: number = 0.25` (attributes `min-zoom`/
+  `max-zoom`/`zoom-step`) — pure pass-throughs to the embedded `<lr-zoomable-frame>`, which does the
+  normalizing.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — the panel's accessible name,
+  overriding the localized `lightboxLabel`.
+
+**Methods:** `next()`, `previous()`, `goTo(index)`, `close(reason?)` — `reason` defaults to `'api'`
+and is forwarded as the close event's detail.
+
+**Events:** `lr-lightbox-close` (`detail: LyraLightboxCloseReason = 'escape' | 'backdrop' |
+'close-button' | 'api' | 'unmount' | (string & {})`; **cancelable** — `preventDefault()` blocks
+closing on every path, including a consumer's own `close()` call. Also fires with `'unmount'` when
+the element is removed from the DOM while still open); `lr-index-change` (`detail: { index }`, fired
+only for internally-driven navigation — a button, a keyboard shortcut, or `next()`/`previous()`/
+`goTo()`; **not** when a consumer sets `index`/`images` directly); `lr-zoom-change` (`detail: {
+zoom }`) is not emitted by the lightbox itself — it bubbles up composed from the embedded frame.
+
+**Slots:** `actions` — extra toolbar buttons (download/share/delete), rendered in `[part="toolbar"]`
+between the counter and the close button.
+
+**CSS parts:** `backdrop`, `panel` (`role="dialog"` + `aria-modal="true"` while open; fills the
+padded safe area rather than shrink-wrapping), `toolbar`, `counter` (visible localized "Image N of
+Total"), `live-region` (visually-hidden `role="status"` that announces position on *every* `index`
+change, including consumer-driven ones), `actions` (wrapper, `hidden` when nothing is slotted),
+`close-button` (always rendered — unlike `<lr-dialog>`'s opt-in `closable`), `stage`, `frame` (the
+embedded `<lr-zoomable-frame>`; its internal parts are not re-exported), `previous-button`,
+`previous-glyph`, `next-button`, `next-glyph`, `caption` (only when the current image has one; its
+`id` is the panel's `aria-describedby` target).
+
+**Themeable custom properties:** `--lr-lightbox-overlay-color` (default
+`var(--lr-color-overlay-strong)` — the backdrop scrim), `--lr-lightbox-control-bg` (default
+`var(--lr-color-neutral)`) and `--lr-lightbox-control-color` (default `var(--lr-color-on-neutral)`)
+— background/foreground for the counter, caption, and every floating/toolbar icon button; these use
+the solid neutral token rather than `--lr-color-surface` because the controls float over arbitrary
+photo content.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- keyboard navigation is RTL-aware and bound on `[part="panel"]`, so it also sees keydowns bubbling
+  out of the embedded frame's shadow tree: Arrow forward/back (mirrored under `rtl`), `Home`, `End`.
+  It never collides with the frame's own `+`/`-`/`0` zoom shortcuts.
+- initial focus deliberately goes to `close-button`, not the first tabbable element — a slotted
+  `actions` button placed before it does not steal focus.
+- zoom/pan reset on navigation is imperative (`resetView()` from `updated()`), not a binding; the
+  frame element is reused across navigations rather than recreated, so a keyboard user who tabbed
+  into the viewport keeps focus.
+- scope for v1: no per-image slotted content (data-driven via `images` only), no dot indicators, no
+  open/close transition, no click-image-to-navigate, no touch-swipe.