@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-model-select.md

@@ -0,0 +1,169 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-model-select`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/model-select/model-select.js';` (registers the tag; side-effect import)
+- **Class** `LyraModelSelect`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/model-select/model-select.class.js`
+- **Family** `components/conversation/` — 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-model-select`
+
+A provider/model picker that renders as a closed dropdown when a fixed `catalog` is available, or as a
+filterable free-text combobox when it isn't (or when `allow-custom` explicitly permits typing something
+outside the catalog). Form-associated (hand-rolled internals via `attachInternals()` directly, not the
+shared `FormAssociated` mixin — same reasoning as `lr-combobox`/`lr-select`: see the shared-foundation
+notes). Built on the same trigger-button/`aria-activedescendant` listbox technique `<lr-select>` uses
+and the filter-as-you-type suggestion-popup technique `<lr-combobox>` uses, without composing either
+element. First-party invention (no Web Awesome equivalent).
+Session-history/autofill restoration synchronously restores the model id and form entry without
+emitting `lr-change`.
+
+**Exported types:**
+- `LyraModelCatalogEntry { id: string; label: string }` — one catalog row.
+- `LyraModelCatalog = string[] | LyraModelCatalogEntry[]` — either every entry is a plain string (used
+  as both id and label) or every entry is a full `{ id, label }` row; the two shapes are not meant to be
+  mixed within one array.
+
+**Properties:**
+- `provider: string = ''` — informational only (e.g. `'ollama'`); rendered as a small leading badge.
+- `catalog?: LyraModelCatalog` (attribute: false) — the full model list. Omit (or leave empty) to fall
+  back to plain free-text entry.
+- `allowCustom: boolean = false` (attribute `allow-custom`, reflected) — let the user type/commit a
+  value that isn't in `catalog`, even when `catalog` is non-empty.
+- `label: string = ''` — optional visible title above the control, mirroring `<lr-select>`'s own
+  `label` exactly: rendered via a `[part="form-control-label"]` `<label>` paired with the control's
+  id, and once non-empty it takes over as the accessible-name source (an `aria-label` override is
+  then only consulted as the fallback). Empty (the default) keeps the original
+  `aria-label || placeholder || 'Model'` accessible-name chain untouched.
+- `hint: string = ''` — hint text below the field. Unset (the default): no hint chrome renders.
+- `errorText: string = ''` (attribute `error-text`) — error text below the field (overridden by
+  slotted `error` content). Unset (the default): no error chrome renders.
+- `placeholder: string = ''`
+- `spellcheck: boolean = true` — forwarded to the free-text mode's native `<input>`; no effect in
+  closed-dropdown mode (no native text input there). `spellcheck="false"` is parsed as `false` (a
+  custom converter, not Lit's presence-based `type: Boolean`, so the literal attribute string is
+  honored — matches `<lr-textarea>`/`<lr-date-input>`).
+- `autocapitalize: string = ''` — forwarded to the free-text mode's native `<input>`; empty omits
+  the attribute.
+- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the free-text mode's native
+  `<input>`'s own `autocorrect` (Safari/WebKit-specific); empty omits the attribute. Named
+  `autoCorrect` in JS purely to dodge a `lib.dom.d.ts` typing collision — the wire attribute is
+  still plain `autocorrect`.
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the free-text input;
+  they have no effect in closed-dropdown mode
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the free-text mode's native `<input>`.
+- `name: string = ''` (reflected)
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `open: boolean = false` (reflected)
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — visual size; same `xs`–`xl` scale as
+  `<lr-select>`'s own `size`, scaling `[part="trigger"]`/`[part="combobox"]`'s padding/min-height/
+  font-size and `[part="expand-icon"]`'s box size (see the themeable custom properties below).
+- `value: string` — getter/setter (hand-rolled, not the `FormAssociated` mixin); the current model id,
+  `''` when nothing is selected. Writing it calls `internals.setFormValue()` synchronously. A named,
+  untouched model-select contributes `''` to `FormData` instead of omitting its key.
+
+**Methods:** `click()` (override) — forwards to whichever internal control the active mode renders,
+since `HTMLElement.prototype.click()` is otherwise a no-op on a custom element with no native click
+semantics of its own (mirrors `<lr-button>`'s identical host `click()` forwarding, so a generic
+form-automation helper or another component calling `.click()` on the host actually opens the picker
+instead of silently doing nothing). Closed-dropdown mode forwards a real `.click()` to the trigger
+`<button>`, whose own `@click` handler opens it. Free-text mode instead calls `.focus()` on the
+combobox `<input>`: unlike a genuine pointer click, `HTMLElement.click()` never moves focus (that's a
+`mousedown` side effect the browser applies only to real pointer interaction), and this mode's open
+behavior is wired to the input's `focus` event (`onInputFocus`), not a `click` handler on the input
+itself.
+
+**Mode switching:** `closedMode` (private) is `true` whenever `normalizedCatalog.length > 0 &&
+!allowCustom` — a non-empty `catalog` with `allowCustom` left `false` renders the closed dropdown
+trigger-button UI (`[part="trigger"]`, `role="combobox"` on a `<button>`, no typing). Any other
+combination (`catalog` empty/unset, or `allowCustom` true) renders the free-text `<input>` UI
+(`[part="combobox"]`/`[part="combobox-input"]`) with live substring filtering against the catalog (id or
+label, case-insensitive). The mode is re-evaluated on every render, so toggling `allowCustom` or clearing
+`catalog` at runtime switches modes live, repositioning the shared `[part="listbox"]` popover against
+whichever element is the active anchor.
+
+A `value` that isn't present in `catalog` (e.g. a model id saved from a provider whose live catalog has
+since changed) is never silently dropped: it's appended to the rendered option list as a synthetic,
+visually-distinct row (dashed border, italic label, "not in catalog" badge) computed fresh from
+`catalog` + `value` on every access, without ever mutating the `catalog` property itself.
+
+**Events:**
+- `lr-change` (`detail: { value: string; inCatalog: boolean }` — fired when a value is selected
+  from the listbox or committed in free-text mode; `inCatalog` reflects whether that value was
+  actually present in `normalizedCatalog`, so a consumer can flag a freshly-typed custom value
+  distinctly from a real catalog pick)
+- `blur` (no detail) — re-dispatched from the free-text mode's internal `<input>`'s own `blur`,
+  bubbling and composed unlike the native event. Closed-dropdown mode's trigger `<button>` has no
+  equivalent re-dispatch, matching `<lr-select>`'s own trigger.
+- `focus` (no detail) — re-dispatched from the free-text mode's internal `<input>`'s own `focus`,
+  for the same reason as `blur`.
+
+**Slots:** `hint` (custom hint content), `error` (custom error content).
+
+**CSS parts:** `form-control-label` (the `<label>` element — only rendered, and only contributes to
+the accessible name, once `label` is non-empty), `trigger` (closed-dropdown mode's
+`<button role="combobox">`, also its positioning anchor), `combobox` (free-text mode's input
+container, also its positioning anchor), `combobox-input` (the free-text `<input>`),
+`provider-badge` (the optional leading `provider` label), `listbox` (the options popover, shared by
+both modes), `option`, `option-label`, `option-badge` (the "not in catalog" badge on a synthetic
+stale-value row), `expand-icon` (the dropdown chevron, present in both modes), `hint` (the hint
+message), `error` (the error message)
+
+**Themeable custom properties:** `--lr-model-select-trigger-padding` (default `var(--lr-space-xs)
+var(--lr-space-s)`) — `[part="trigger"]`/`[part="combobox"]`'s padding shorthand.
+`--lr-model-select-trigger-min-height` (default `var(--lr-size-2-5rem)`) — their block-size floor.
+`--lr-model-select-font-size` (default `var(--lr-font-size-md)`) — their font size.
+`--lr-model-select-expand-size` (default `var(--lr-size-1-75rem)`) — `[part="expand-icon"]`'s
+decorative box size (clamped against `--lr-icon-button-size` via `min()`). All four are declared on
+`:host` at these `size="m"` (the default) values and re-declared inside each
+`:host([size="xs"|"s"|"l"|"xl"])` block at that tier's own value — same xs–xl scale `<lr-select>`
+uses — so `size` is the primary lever; override the cssprop directly only to retune a single tier or
+step outside the scale entirely. `--lr-model-select-option-active-bg` (default
+`var(--lr-color-brand-quiet)`) — background of a hovered or keyboard-active `[part="option"]` row;
+declared as a `var()` fallback at the point of use, not on `:host`, so it isn't tied to `size`. Plus
+shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`,
+`--lr-radius`, `--lr-shadow`, `--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`,
+`--lr-transition-fast`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-model-select
+  provider="openai"
+  .catalog=${[
+    { id: 'gpt-4o', label: 'GPT-4o' },
+    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
+  ]}
+  value="gpt-4o"
+  placeholder="Choose a model…"
+  @lr-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
+></lr-model-select>
+
+<!-- No fixed catalog yet: falls back to free-text entry -->
+<lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
+```
+
+**Known gotchas:**
+- `catalog` must be homogeneous — an array of plain strings, or an array of `{ id, label }` objects, not
+  a mix; `LyraModelCatalog` is a union of two array *types*, not an array of a union item type.
+- The synthetic "not in catalog" row only ever appears when `catalog` is non-empty and `value` isn't one
+  of its ids — with no `catalog` at all, there's no catalog list to diff `value` against, so no badge.
+- `value`/form-association here is hand-rolled via `attachInternals()` directly, not the shared
+  `FormAssociated` mixin — mirrors `lr-combobox`/`lr-select`'s identical divergence.
+- `aria-invalid`/`data-invalid` only reflect once the control has been blurred (touched) at least once,
+  matching `lr-select`'s identical pattern — validity styling never flashes on first render.
+- In free-text mode, the input's displayed text is `query` only while `open`; while closed it shows the
+  committed value's label — so setting `.value` programmatically doesn't require also touching the live
+  typed text.
+- `hint`/`errorText` mirror `<lr-select>`'s identical chrome, including the `aria-describedby` wiring
+  to the rendered `hint`/`error` ids — set on whichever element (`trigger` or `combobox-input`) owns
+  `role="combobox"` for the active mode.
+
+---

package/llms/components/lr-model-settings-panel.md

@@ -0,0 +1,99 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-model-settings-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/model-settings-panel/model-settings-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraModelSettingsPanel`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/model-settings-panel/model-settings-panel.class.js`
+- **Family** `components/conversation/` — 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-model-settings-panel`
+
+A fixed composition of `<lr-model-select>` and `<lr-slider>` into one agent-configuration card:
+pick a provider's model, then tune its sampling temperature. First-party invention (no Web Awesome
+equivalent). Not a generic layout shell — it exists so a consumer doesn't have to re-wire the same
+two child `lr-change` events into one combined settings object by hand every time this pairing
+comes up.
+
+Every prop here is a plain pass-through to (or mirror of) the matching child control's own prop of
+the same/similar name — see `lr-model-select` and `lr-slider` themselves for the exact semantics
+of `catalog`/`allowCustom` and `temperatureMin`/`temperatureMax`/`temperatureStep`.
+
+**Properties:**
+- `provider: string = ''` — informational provider badge, passed straight through to the internal
+  `lr-model-select`.
+- `catalog?: LyraModelCatalog` (attribute: false, JS-only) — `string[] | { id: string; label: string
+  }[]` (every entry must be one shape or the other, never mixed); passed straight through to the
+  internal `lr-model-select`.
+- `modelValue: string = ''` (attribute `model-value`) — the current model id.
+- `allowCustom: boolean = false` (attribute `allow-custom`) — lets the model control accept a value
+  outside `catalog`; passed straight through.
+- `temperature: number = 1` — the current sampling temperature. `1` is the midpoint of the default
+  `[0, 2]` range and matches both OpenAI's and Anthropic's own provider default; reassign it yourself
+  if your provider differs.
+- `temperatureMin: number = 0` (attribute `temperature-min`)
+- `temperatureMax: number = 2` (attribute `temperature-max`)
+- `temperatureStep: number = 0.1` (attribute `temperature-step`)
+- `layout: 'vertical' | 'compact' = 'vertical'` (reflected) — `vertical` stacks full-width rows with
+  visible labels; `compact` runs the same two rows side by side with a smaller, uppercase temperature
+  caption, for toolbars/sidebars where the vertical layout's height doesn't fit.
+- `disabled: boolean = false` (reflected) — disables the panel as a unit by forwarding to *both*
+  internal `lr-model-select` and `lr-slider`; a wrapping `<fieldset disabled>` alone would not
+  reach either, since a form-associated control's own `disabled` IDL property/attribute is never
+  mutated by fieldset cascading.
+
+**Events:** `lr-change` — `detail: { modelValue: string; inCatalog: boolean; temperature: number }`.
+Fires whenever *either* child control's own `lr-change` fires, and always carries the full current
+settings snapshot, not just whichever field actually changed. `inCatalog` is recomputed fresh from
+`catalog`/`modelValue` on every emission (mirroring `lr-model-select`'s own `effectiveEntries` logic)
+rather than cached from the last child event, so it's still correct even when `modelValue` was just
+assigned directly instead of via the child's own event.
+
+**Slots:** none — this is a fixed two-control composition, not a generic layout shell.
+
+**CSS parts:** `base`, `model-row`, `temperature-row`, `temperature-label`, `temperature-value`
+
+**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+`--lr-space-l/-m/-s/-xs`, `--lr-color-border`, `--lr-radius`, `--lr-color-surface`,
+`--lr-color-text`, `--lr-color-text-quiet`.
+
+**Optional peer deps:** none — it composes the library's own `<lr-model-select>` and `<lr-slider>`
+internally (both imported unconditionally as side effects, not optional).
+
+```html
+<lr-model-settings-panel
+  provider="OpenAI"
+  .catalog=${['gpt-4o', 'gpt-4o-mini', 'gpt-4.1']}
+  model-value="gpt-4o"
+  temperature="0.7"
+  @lr-change=${(e) => console.log(e.detail)}
+></lr-model-settings-panel>
+
+<lr-model-settings-panel layout="compact" .catalog=${catalog}></lr-model-settings-panel>
+```
+
+The internal `lr-slider` renders with its own value readout suppressed (`.showValue=${false}`);
+the current temperature is instead shown via this component's own `[part="temperature-value"]` span,
+which interpolates `temperature` verbatim with no `toFixed`/formatting applied — a value like `0.1`
+shows as `0.1`, and any floating-point noise a slider drag produces would render digit-for-digit. The
+panel's own `temperature` property mirrors the nested slider's *live* value on every one of its
+`lr-input` events (drag/key-repeat), not just its committed `lr-change` — so `temperature` (and
+the visible readout) tick continuously during a drag, but the panel's own `lr-change` event only
+fires once the slider's own `lr-change` commits (pointerup/keyup) or the model changes; reading
+`.temperature` mid-drag will already reflect the live position even though no `lr-change` has fired
+yet for it.
+
+**Known gotchas:**
+- `catalog` is JS-only (`attribute: false`) — set it via a property binding (`.catalog=`), never as
+  an HTML attribute, same requirement as the underlying `lr-model-select`.
+- `layout="compact"` removes the host's own `max-inline-size` cap (`28rem` in `vertical` layout)
+  entirely, so a compact panel can grow as wide as its container/flex context allows.
+- The nested `lr-model-select`'s own `max-inline-size` (sized for a standalone dropdown) is
+  overridden to `100%`/`none` inside `[part="model-row"]` so it fills the card's full width — a
+  detail only worth knowing if you're targeting `lr-model-select` internals with your own CSS
+  through this component.
+
+---

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

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-mutation-observer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/mutation-observer/mutation-observer.js';` (registers the tag; side-effect import)
+- **Class** `LyraMutationObserver`, also available unregistered from `@aceshooting/lyra-ui/components/utility/mutation-observer/mutation-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-mutation-observer`
+
+Lifecycle-managed wrapper around the native `MutationObserver`. All element children in the default
+slot are observed and their mutation records are emitted as a composed event; the wrapper itself
+adds no layout.
+
+**Properties:** `disabled: boolean = false` (reflected), `childList: boolean = true` (attribute
+`child-list`), `observeAttributes: boolean = false` (attribute `attributes`), `characterData: boolean = false` (attribute
+`character-data`), `subtree: boolean = true`, and `attributeFilter: string[] = []`.
+
+**Events:** `lr-mutation` with `{ records: MutationRecord[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---

package/llms/components/lr-neighbor-list.md

@@ -0,0 +1,62 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-neighbor-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/neighbor-list/neighbor-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraNeighborList`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/neighbor-list/neighbor-list.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-neighbor-list`
+
+One entity's relationship rows: relation, direction, neighbor, with per-row navigate and
+expand-in-graph affordances. Never computes neighbors itself (the host derives rows from its own
+graph data) and never mutates a graph.
+
+**Properties:**
+- `rows: LyraNeighborRow[] = []` (attribute: false) — `LyraNeighborRow { relation: string; direction:
+  'in' | 'out' | 'both'; node: LyraEntity }`
+- `groupByRelation: boolean = false` (attribute `group-by-relation`) — inserts a `group-header` row per
+  distinct `relation`
+- `expandable: boolean = false` — renders a per-row expand-in-graph icon button
+- `virtualizeAt: number = 100` (attribute `virtualize-at`) — row count above which the list virtualizes
+- `label: string = ''`
+
+**Events:** `lr-entity-activate` (`detail: { id }`, a row's node button was activated),
+`lr-node-expand` (`detail: { id }`, a row's expand button was activated — deliberately the same
+name and detail shape as `lr-graph`'s own event, so one host handler serves both).
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`; above
+`virtualizeAt` this is the internal virtual-list's own group label, re-exported under the same
+name), `row` (`role="listitem"`; above `virtualizeAt` this is the internal virtual-list's own row
+wrapper, re-exported under the same name), `direction` (`aria-hidden` glyph), `relation`,
+`node-label`, `node-meta` (secondary type/degree text, when present), `expand-button` (only when
+`expandable`), `empty` (shown when `rows` is empty). Every part presents identically either side of
+`virtualizeAt`.
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-neighbor-list expandable group-by-relation></lr-neighbor-list>
+<script>
+  document.querySelector('lr-neighbor-list').rows = [
+    { relation: 'works_for', direction: 'out', node: { id: 'e2', label: 'Analytical Engine Co.' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- `lr-node-expand`'s detail shape is intentionally identical to `lr-graph`'s own event of the
+  same name, so a single listener wired to both handles "expand this node's neighborhood" uniformly.
+- A row is exactly one `[part="row"]` element in both rendering paths. Above `virtualizeAt` that
+  element is the internal virtual-list's own row wrapper (the component renders only the row's
+  content into it), so a `::part(row)` rule applies once, not twice.
+
+---

package/llms/components/lr-node-palette.md

@@ -0,0 +1,69 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-node-palette`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/node-palette/node-palette.js';` (registers the tag; side-effect import)
+- **Class** `LyraNodePalette`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/node-palette/node-palette.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-node-palette`
+
+The searchable, categorized node library for workflow editors: drag an item onto a canvas, or place
+it by keyboard. Never creates nodes or touches a canvas's data itself — the drop/place handshake ends
+at `lr-node-add`/`lr-palette-place`; the host mutates `nodes`. Fully decoupled from
+`lr-flow-canvas` (no `for` resolution, unlike the other three companions) — it only needs to agree
+with a `droppable` canvas on the `FLOW_PALETTE_MIME_TYPE` drag payload shape.
+
+**Properties:**
+- `items: PaletteItem[] = []` (attribute: false) — `PaletteItem { type: string; label: string;
+  description?: string; category?: string; keywords?: string[]; icon?: unknown; disabled?: boolean }`;
+  `type` is the `FlowNode.type` a placement/drop creates, `category` groups items under
+  first-appearance-ordered headings, `disabled` renders an item visible but not draggable/placeable
+- `label: string = ''` — accessible name for the search field/listbox
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the listbox's
+  computed accessible name; wins over `label` and the localized default, and attribute-reflects
+  from a host-level `aria-label`
+
+**Events:** `lr-palette-place` (`detail: { type }`, a pointer click or Enter/Space — the
+click/keyboard alternative to dragging), `lr-select` (`detail: { item }`, emitted alongside
+`lr-palette-place` on both gestures, carrying the full item), `focus`/`blur` (no detail —
+re-dispatched from the internal search field's own `focus`/`blur`, bubbling and composed unlike
+the native events, since neither bubbles nor crosses the shadow boundary on its own).
+
+**Slots:** `header` (content above the search field, e.g. a heading or tabs), `footer` (content
+below the list).
+
+**CSS parts:** `base`, `search`, `list` (the listbox), `group-header`, `item`, `item-icon`,
+`item-label`, `item-description`, `empty` (no-results message), `live-region` (result-count
+announcement).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-node-palette id="palette"></lr-node-palette>
+<lr-flow-canvas id="canvas" droppable style="height:480px"></lr-flow-canvas>
+<script>
+  document.getElementById('palette').items = [
+    { type: 'http-request', label: 'HTTP Request', category: 'Actions' },
+    { type: 'transform', label: 'Transform', category: 'Actions' },
+  ];
+  document.getElementById('canvas').addEventListener('lr-node-add', (e) => {
+    console.log('drop payload type:', e.detail.type, e.detail.position);
+  });
+</script>
+```
+
+**Known gotchas:**
+- A drag from this palette carries `FLOW_PALETTE_MIME_TYPE` as its `DataTransfer` type — only a
+  `droppable` `lr-flow-canvas` (or a host reimplementing the same MIME type) accepts it.
+- Clicking or activating an item by keyboard fires `lr-palette-place`/`lr-select` immediately, no
+  drag required — the host decides where the new node lands (there's no pointer position to derive
+  one from on a keyboard placement).
+
+---

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

@@ -0,0 +1,80 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-notebook-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/notebook-viewer/notebook-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraNotebookViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/notebook-viewer/notebook-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-notebook-viewer`
+
+Read-only Jupyter notebook (nbformat 4.x) renderer, composing existing components per cell.
+Execution is a hard non-goal. Markdown cells render through `lr-markdown`, code cells through
+`lr-code-block` (using the notebook's kernel language for syntax highlighting), and raw cells as
+plain preformatted text. A code cell's `execute_result`/`display_data` outputs prefer, in order,
+`image/png`, `image/jpeg`, `image/svg+xml` (sanitized), `text/html` (sanitized), `application/json`
+(via `lr-json-viewer`), then `text/plain`. Stream/error outputs render as plain preformatted text
+(tinted `danger` for stderr/tracebacks). Sanitizing raw HTML/SVG output markup lazy-loads the
+optional peer `dompurify`; without it, the output renders a localized notice instead of raw markup.
+Cells are virtualized through `lr-virtual-list`. `node-path` anchors resolve `path[0]` as a cell
+index; `fragment` anchors resolve a cell's own `id`. No execution, no kernels, no editing, no
+ipywidgets.
+
+**Properties:** `src: string = ''` — URL to fetch and parse as a notebook; ignored once `notebook` is
+set. `notebook?: object | string` (property only) — an already-parsed notebook document, or its raw
+JSON text; wins over `src` and is parsed (and validated) synchronously. `name: string = ''` —
+accessible label, and matched against a `fragment` anchor's cell id. `outputCollapseLines: number =
+40` (attribute `output-collapse-lines`) — a plain-text output longer than this many lines renders
+collapsed behind a toggle; `0` disables collapsing. `maxHeight: string = ''` (attribute
+`max-height`) — once set, the notebook scrolls internally past this height. `anchorKinds` is a
+readonly `['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for the
+shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
+matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
+`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and flashing the
+target cell; `clearSearch()` clears the query and matches.
+
+**Events:** `lr-load` — `detail: { cellCount, language }`, fired once a notebook has been parsed
+and validated (`language` from `metadata.language_info.name`/`kernelspec.language`, else `''`).
+`lr-highlight-activate` — `detail: { id }`. `lr-search-change` — `detail: { query, matchCount,
+activeIndex }`. `lr-render-error` — `detail: { error }`, fetching, parsing, or validating the
+notebook failed.
+
+**CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
+`data-active`), `cell-active` (added alongside `cell` on the cell an anchor currently targets),
+`cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`, `output`
+(`data-output-type`, `data-stream`), `output-error` (added alongside `output` on a stderr stream or
+an error output), `error-output-label` (the label introducing an error output's traceback),
+`output-toggle`, `error`, `spinner`.
+
+Every cell-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
+forwarded back out through `exportparts`, so `lr-notebook-viewer::part(cell)` and friends work from
+a consumer stylesheet. The three state variants are separate part *names* rather than attribute
+selectors, because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(cell)[data-active]` is invalid CSS, so use `::part(cell-active)`. The `data-*` attributes
+remain on the elements for scripting.
+
+**Themeable custom properties:** `--lr-notebook-viewer-max-height` (default `none`).
+
+`--lr-notebook-viewer-active-bg` (default `var(--lr-color-brand-quiet)`) is the background of the
+cell currently targeted by an anchor — the `cell-active` part. 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.
+
+**Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
+`shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
+`text/plain`).
+
+```html
+<lr-notebook-viewer .notebook=${result} max-height="30rem"
+  @lr-load=${(e) => console.log(e.detail.cellCount, 'cells')}
+></lr-notebook-viewer>
+```
+
+A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
+localized error and fires `lr-render-error` instead of the notebook.

package/llms/components/lr-number-input.md

@@ -0,0 +1,45 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-number-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/input/number-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraNumberInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/input/number-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-number-input`
+
+A migration-friendly numeric alias of `lr-input` — a subclass whose constructor and
+`connectedCallback()` both set `type = 'number'`. It adds no API of its own; everything below is
+`lr-input`'s surface, unchanged.
+
+**Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
+(`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
+`autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), `enterKeyHint` (`enterkeyhint`), and
+`min`/`max`/`step` (the native numeric constraint validation). `clearable` and `passwordVisible`
+(`password-visible`) are inherited but inert — see gotchas.
+
+**Events:** `input`/`change` (native-style, composed), `lr-input`/`lr-change`
+(`detail: { value }`), `focus`/`blur` (re-dispatched bubbling + composed from the internal native
+input), and `lr-clear` (inherited, never fired here).
+
+**Slots:** `label`, `hint`, `error`, `start`, `end`.
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start`, `end`,
+`hint`, `error`, plus the inherited `clear-button` and `password-toggle`, neither of which this
+alias ever renders.
+
+**Themeable custom properties:** inherited from `lr-input`, identical in meaning —
+`--lr-input-control-min-height`, `--lr-input-control-height`, `--lr-input-padding-block`,
+`--lr-input-padding-inline` and `--lr-input-font-size` (all but `--lr-input-control-height` swap
+per `size`; that one stays undeclared until you pin an exact row height).
+
+**Known gotchas:**
+- `clearable`/`clear-button`/`lr-clear` are inert: the clear action only renders for
+  `type="text"`/`"search"`. `password-visible`/`password-toggle` are likewise inert, since the
+  toggle only renders for `type="password"`.
+- `type` is re-forced to `number` on every connect, but a later `el.type = 'text'` on a connected
+  element is not reverted — use `lr-input` when the type has to change.