@aceshooting/lyra-ui 7.5.0 → 7.7.0

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

@@ -22,8 +22,9 @@ the reading region's accessible name. `location: string = ''` (not reflected —
 a CFI or spine href identifying the current reading position: set before the book finishes
 loading it's recorded and applied once ready, set after it applies immediately, and epub.js's own
 `relocated` event keeps it in sync with user navigation without re-triggering its own `display()`
-call. `anchorKinds` is a readonly `['cfi', 'text-quote']` (this viewer's supported `LyraAnchor.kind`
-values for the shared anchor-target contract).
+call. A controlled `location` assignment made synchronously inside `lr-location-change` wins over
+the peer-reported CFI and is displayed. `anchorKinds` is a readonly `['cfi', 'text-quote']` (this
+viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
 
 **Methods:** `getToc()` resolves the EPUB's own navigation document (`book.navigation.toc`,
 populated once `book.ready` resolves) flattened into document-ordered `EbookTocItem[]` (`{ id,
@@ -31,16 +32,20 @@ label, href, level }`, `level` starting at 1 for a top-level entry, `id` falling
 when a navigation entry has none), `[]` before a book has loaded. `search(query)` resolves the
 match count across every spine section, in document order, via epub.js's own `item.load()`/
 `item.find()`/`item.unload()` (empty/whitespace query behaves like `clearSearch()`; a newer
-`search()` call or a `src` change aborts an in-flight scan); `searchNext()`/`searchPrevious()`
+`search()` call or a `src` change aborts an in-flight scan; peer output is capped at 10,000
+matches); `searchNext()`/`searchPrevious()`
 advance/step back through matches (wrapping, resolving `false` when there are none); `clearSearch()`
 clears the query, matches, and painted search annotation.
 
 **Events:** `lr-render-error` with `detail.error` when fetching, opening, or rendering fails;
 `lr-location-change` (`detail: { cfi, href }`) fired from epub.js's own `relocated` event;
 `lr-search-change` (`detail: { query, matchCount, activeIndex }`) from `search()`/`searchNext()`/
-`searchPrevious()`/`clearSearch()`.
+`searchPrevious()`/`clearSearch()`; `lr-anchor-result` (`detail: { found }`) after an anchor is
+applied; `lr-highlight-activate` (`detail: { id }`) when a painted CFI highlight is clicked; and
+`lr-text-select` (`detail: { text, anchor, rects }`) after selection inside a chapter iframe.
 
-**CSS parts:** `base`, `toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
+**CSS parts:** `base` (explicit `aria-busy="true"|"false"`; loading text owns `role="status"`),
+`toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
 `mount`, `error`, and `announcer` (the visually-hidden `role="status"` region search results
 announce through).
 
@@ -50,7 +55,8 @@ unambiguous beside other previous/next controls and are overridable through `.st
 
 **Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
 matches `application/epub+zip` and `.epub` filenames, declaring `{ anchors: ['cfi', 'text-quote'],
-search: true, textSelect: true }` capabilities.
+search: true, textSelect: true }` capabilities and forwarding `anchor`/`highlights` to the mounted
+viewer. The peer loader requires the callable EPUB factory; malformed module shapes fail closed.
 
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the ebook.
@@ -63,3 +69,7 @@ this component's own shadow DOM — `lr-text-select` mirrors epub.js's own `sele
 same reason. `highlights` (kind `cfi`) paint via `rendition.annotations.highlight()` and are
 re-applied whenever the rendition is recreated (a `src` change, or a reconnect remount), since
 epub.js doesn't persist annotations across a fresh `renderTo()`.
+
+Rejected or synchronous failures from display, previous/next navigation, search annotation, or
+anchor application enter the localized error state and emit `lr-render-error`. Anchor failures
+emit one `{ found: false }`, and superseded async anchor/search work cannot mutate the current book.

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

@@ -25,8 +25,9 @@ downloading, or object-URL'ing them is the host's job (e.g.
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the message.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `foldQuotes:
-boolean = false` (attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings; invalid CSS
+`max-height` values, declaration breaks, and `url()` are ignored. `foldQuotes: boolean = false`
+(attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
 localized show/hide toggle. `false` (the default) preserves the full body rendering. A host
 `aria-label` takes precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
 `anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract.

package/llms/components/lr-embedding-explorer.md

@@ -19,7 +19,8 @@ the component only normalizes them into SVG, colors optional clusters, and emits
 **Properties:** `points: EmbeddingPoint[] = []` (attribute: false), where each point is `{ id, x,
 y, label?, sourceId?, cluster? }`; `selectedId: string = ''`; `height: string = '360px'`;
 `accessibleLabel: string | null = null` (attribute `aria-label`). Non-finite coordinates are
-omitted.
+omitted. Pointer and programmatic focus synchronize the single roving tab stop, and every point
+keeps at least a 24×24 CSS px pointer target at narrow allocations without enlarging its marker.
 
 **Events:** `lr-point-select` (`{ point }`), activated by click or Enter/Space.
 

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

@@ -15,7 +15,8 @@
 
 A masked key/value list for environment variables and secrets, with per-row reveal and copy.
 Masking is presentational, not a security boundary: the real value sits in a DOM property
-regardless of mask state.
+regardless of mask state. Names, revealed values, and localized action text wrap within narrow
+allocations; the name track uses at most 40% of the available inline size.
 
 **Properties:** `entries: EnvEntry[] = []` (attribute: false), `revealable: boolean = true`
 (reflected), `copyable: boolean = true` (reflected), and `label: string = ''`.

package/llms/components/lr-eval-result.md

@@ -17,6 +17,8 @@ Rubric scoring and human-review surface for comparing the runs of one evaluation
 
 Composes `lr-table` (the comparison table), `lr-rubric-form` (the review surface), and
 `lr-diff-view` (baseline↔selected output diff) rather than re-deriving any of their behavior.
+The table's accessible name is the localized evaluation-runs label by default; a host
+`aria-label` on `<lr-eval-result>` overrides it.
 
 **Properties:**
 - `runs: EvalRunResult[] = []` (attribute: false) — `EvalRunResult { id: string; label: string;

package/llms/components/lr-export-button.md

@@ -87,7 +87,7 @@ Package-level CSV utilities (used internally, also exported for standalone use
 escapeCsvField, buildCsv, downloadBlob } from
 '@aceshooting/lyra-ui/components/utility/export-button/csv.js'`):
 ```ts
-escapeCsvField(value: unknown): string   // quotes/escapes; neutralizes formula-injection (=,+,@,tab,CR) with a leading apostrophe — a bare leading '-' is deliberately left alone (OWASP guidance: it's not itself formula syntax, and guarding it would mangle ordinary negative numbers)
+escapeCsvField(value: unknown): string   // quotes/escapes; neutralizes leading ASCII/fullwidth =,+,-,@ and tab/CR/LF formula prefixes with an apostrophe
 buildCsv(rows: Record<string, unknown>[], columns: CsvColumn[]): string  // CRLF-joined, header row included
 downloadBlob(content: string, filename: string, mime: string): void      // triggers a browser download
 ```
@@ -99,6 +99,10 @@ downloadBlob(content: string, filename: string, mime: string): void      // trig
   for that handler, not automatic filename handling.
 - CSV formula-injection guarding and the deferred (5s) `URL.revokeObjectURL` (works around Safari
   cancelling in-flight downloads on immediate revoke) are genuine, safe-to-rely-on strengths.
+- `open` is valid only when `formats` contains more than one choice. An invalid open request is
+  normalized closed without a false `lr-show`/`lr-hide` pair; shrinking an open menu to one format,
+  or becoming `disabled`/`loading`, closes it and repairs focus. JSON projection safely preserves
+  an own enumerable column literally named `__proto__`.
 - the multi-format menu (`role="menu"`) supports full arrow-key navigation — ArrowUp/ArrowDown move
   between items (opening the menu and seeding the right one focused, if it was closed), Home/End
   jump to the first/last item once open, Escape closes it and returns focus to the trigger button,

package/llms/components/lr-file-icon.md

@@ -20,7 +20,9 @@ type wins; filename extension fallback is used only for an empty or `application
 MIME type. Unknown values return a generic file result.
 
 **Properties:** `mimeType` (attribute `mime-type`), `name`, `size` (bytes; `0` renders no size),
-`label`, `decorative`, and `variant: 'icon' | 'label'`.
+`label`, `decorative`, and `variant: 'icon' | 'label'`. A host `aria-label` wins over the computed
+localized file-type/size name. `decorative` changes the semantic owner to presentation and renders
+`aria-hidden="true"` explicitly.
 
 **CSS parts:** `base`, `icon`, `label`, and `size`.
 

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

@@ -61,10 +61,14 @@ file can be selected at a time.'`), and — for `'directory'` — the pre-existi
 itself. The region is cleared (and unrendered) as soon as a subsequent selection rejects nothing.
 
 **Slots:** default slot — custom dropzone content, overrides the `label` attribute text when
-provided. The accessible name always comes from `label` regardless, so icon-only slot content still
-announces correctly.
-
-**CSS parts:** `base`, `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
+provided. The semantic button's accessible name comes from `accessibleLabel`/host `aria-label`,
+then `label`, so icon-only slot content still announces correctly. Slotted content is a sibling of
+the button rather than nested inside it: links, buttons, inputs, and other interactive slotted
+controls keep their own activation and do not also open the picker; clicking non-interactive custom
+content still activates the dropzone.
+
+**CSS parts:** `base` (the native dropzone button, visually behind but semantically beside the
+slotted content), `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
 element carrying the drag accept/reject announcement and the aggregate accepted/rejected count),
 `rejection` (a **visible** `role="alert"` region, rendered only while a rejection exists, listing
 each currently-rejected file next to a per-reason message — in addition to, never in place of, the

package/llms/components/lr-filter-bar.md

@@ -57,3 +57,48 @@ value means no debounce at all: every keystroke commits immediately. A pending d
 **cancelled outright** by `reset()`, by removing that filter's chip, and on disconnect — a stale
 keystroke can never overwrite a reset or fire after teardown. `debounce` is ignored for every other
 `type`, whose commits are discrete choices with nothing to debounce.
+
+### Custom controls
+
+Use `type: 'custom'` when an existing Lyra control does not fit the built-in filter types. Provide a
+`custom` object with a `render(context)` function and an `adapter`. The renderer owns the control's
+markup and should bind the context's `value`, `disabled`, `required`, and `errorText` as appropriate;
+`context.onValueChange` (or its `onInput`/`onChange` aliases) reads the event through
+`adapter.valueFromEvent` and commits it to the filter bar. `context.setValue(value)` is available for
+controls that expose a value without an event payload, and `context.onFocusout` marks the filter
+touched for required validation.
+
+The adapter's optional `emptyValue` is used when the active chip is removed, and its optional
+`formatValue` controls the chip's display text. Custom values may be strings, string arrays,
+booleans, or `undefined`, so controls such as `lr-time-range`, `lr-checkbox`, and an async-backed
+`lr-combobox` can participate in the same controlled `value`, active-chip, reset, disabled, and
+validation contract:
+
+```ts
+const filters: FilterBarFilterDefinition[] = [
+  {
+    id: 'archived',
+    label: 'Include archived',
+    type: 'custom',
+    custom: {
+      adapter: {
+        valueFromEvent: (event) =>
+          (event as CustomEvent<{ checked: boolean }>).detail.checked,
+        emptyValue: false,
+        formatValue: (value) => value === true ? 'Enabled' : 'Disabled',
+      },
+      render: (context) => html`
+        <lr-checkbox
+          ?checked=${context.value === true}
+          ?disabled=${context.disabled}
+          @lr-change=${context.onValueChange}
+          @focusout=${context.onFocusout}
+        >${context.label}</lr-checkbox>
+      `,
+    },
+  },
+];
+```
+
+The custom renderer returns a Lit `TemplateResult`; the filter bar places it in its
+`filter-control` part and re-renders it whenever the controlled value or validation state changes.

package/llms/components/lr-flow-minimap.md

@@ -6,7 +6,7 @@
 - **Class** `LyraFlowMinimap`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-minimap/flow-minimap.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 6 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -33,7 +33,13 @@ disagree.
 draggable, focusable view rectangle).
 
 **Themeable custom properties:** `--lr-flow-minimap-inline-size` (default `12rem`),
-`--lr-flow-minimap-block-size` (default `8rem`).
+`--lr-flow-minimap-block-size` (default `8rem`), `--lr-flow-minimap-node-color` for a node without
+an execution status, and `--lr-flow-minimap-node-{pending|running|success|error|denied}-color` for
+each status-specific rectangle. The status hooks default to the shared border-strong, brand,
+success, danger, and warning colors respectively. Their expanded names are
+`--lr-flow-minimap-node-pending-color`, `--lr-flow-minimap-node-running-color`,
+`--lr-flow-minimap-node-success-color`, `--lr-flow-minimap-node-error-color`, and
+`--lr-flow-minimap-node-denied-color`.
 
 **Optional peer deps:** none.
 

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

@@ -6,7 +6,7 @@
 - **Class** `LyraFlowNode`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-node/flow-node.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 12 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 12 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -56,7 +56,13 @@ hijacking the library-wide `--lr-color-brand` token and repainting everything el
 `status="running"`, independent of `--lr-flow-node-selected-border` so a consumer can retint just one
 of the two states without the other following along — and `--lr-flow-node-running-glow` (default
 `var(--lr-color-brand-quiet)`) — the box-shadow color of the running-state ring around the card, and
-the pulse keyframes' peak color.
+the pulse keyframes' peak color. The status dot has independent
+`--lr-flow-node-status-{pending|running|success|error|denied}-color` hooks, defaulting respectively
+to the shared border-strong, brand, success, danger, and warning tokens;
+`--lr-flow-node-status-color` controls the no-status fallback. The expanded status names are
+`--lr-flow-node-status-pending-color`, `--lr-flow-node-status-running-color`,
+`--lr-flow-node-status-success-color`, `--lr-flow-node-status-error-color`, and
+`--lr-flow-node-status-denied-color`.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-flow-run-overlay.md

@@ -6,7 +6,7 @@
 - **Class** `LyraFlowRunOverlay`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-run-overlay/flow-run-overlay.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 4 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 4 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -15,7 +15,8 @@
 
 Execution-state presentation for a `lr-flow-canvas`: pushes a `FlowRunDecorations` map into the
 resolved canvas (the canvas itself renders the node/edge paint) and renders a compact run-summary
-strip. Does not execute, poll, or time anything — pure pushed state; `durationMs` is host-computed.
+strip. Summary/count text and slotted host chrome wrap within narrow allocations. Does not execute,
+poll, or time anything — pure pushed state; `durationMs` is host-computed.
 
 **Properties:**
 - `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
@@ -37,7 +38,13 @@ badge).
 **CSS parts:** `base`, `summary` (the "{done} of {total} steps complete" line), `count` (one per
 status present, text + tone dot, never color-only), `live-region` (step-transition announcement).
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** `--lr-flow-run-overlay-status-color` controls a count dot without
+an execution status. `--lr-flow-run-overlay-status-{pending|running|success|error|denied}-color`
+independently retints each status count, defaulting respectively to the shared border-strong,
+brand, success, danger, and warning tokens. Their expanded names are
+`--lr-flow-run-overlay-status-pending-color`, `--lr-flow-run-overlay-status-running-color`,
+`--lr-flow-run-overlay-status-success-color`, `--lr-flow-run-overlay-status-error-color`, and
+`--lr-flow-run-overlay-status-denied-color`.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-format-bytes.md

@@ -26,7 +26,8 @@ name is localized too. Text-only host — no CSS parts, events, or own tokens; l
 
 The unit ladder is fixed at `byte`, `kilobyte`, `megabyte`, `gigabyte`, `terabyte`, `petabyte` and
 saturates at the top; the index is `floor(log|value| / log(unitStep))`, and `0` always formats as
-bytes. `unitStep` is normalized to a finite number `> 1` (a step of exactly `1` would divide by
+bytes. Magnitudes below one byte, including negative values, stay in the `byte` unit rather than
+forming a negative unit index. `unitStep` is normalized to a finite number `> 1` (a step of exactly `1` would divide by
 `log(1) === 0`) falling back to `1024`; `decimals` is clamped to `[0, 10]` — an out-of-range value
 would otherwise throw a `RangeError` from `maximumFractionDigits`. Note that `unitStep: 1024` still
 prints the SI-named `kB`/`MB` units, not `KiB`/`MiB` — `Intl` has no binary unit names.

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

@@ -24,6 +24,9 @@ empty, which means "the runtime's default locale". Every `Intl` instance is pull
 memoized `internal/intl-cache.ts` (one instance per locale + options pair, LRU-capped), so these are
 cheap to use per row in a large table or feed.
 
+Malformed runtime options fall back to a safe option set without discarding an otherwise-valid
+effective locale. Only a malformed locale itself falls back to the runtime default.
+
 **Properties:**
 - `value: number = 0`
 - `currency: string = ''` — an ISO 4217 code (`'EUR'`, `'JPY'`). Non-empty switches the formatter to

package/llms/components/lr-gauge.md

@@ -48,6 +48,10 @@ Dependency-free SVG radial, full-circle ring, or linear meter (no charting libra
 ```
 
 **Known gotchas:**
+- SVG text cannot wrap. When a caller-supplied visible `label` or `valueLabel` exceeds the
+  single-line capacity, the component applies SVG `textLength` fitting so the complete string stays
+  inside the fixed radial/ring viewBox or its half of the linear viewBox; the host's accessible
+  label and `aria-valuetext` retain the original text.
 - setting `valueLabel` (e.g. `"72°F"`) now also sets `aria-valuetext` on the host (in addition to
   changing the visible SVG text), so a screen reader announces your formatted string instead of the
   raw `aria-valuenow` number; the SVG `<text part="value">`/`<text part="label">` elements are

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

@@ -6,7 +6,7 @@
 - **Class** `LyraGeojsonView`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `maplibre-gl` — see `llms/peers.md`
-- **Themeable via** 5 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -27,17 +27,24 @@ approximation weighting latitude span ~2x, with 40% padding), then hands the par
 `maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lr-json-viewer
 collapsed-depth="2">` of the raw value instead of the map.
 
+The root owns the named `region` landmark while loading, in fallback/error/idle states, and while a
+lazy map initializes. After `lr-map-load`, landmark ownership transfers to the map canvas so there
+is exactly one named region. Serialized metadata is locally inline-scrollable, preventing long
+unbroken values from widening a 320px allocation.
+
 **Properties:** `src: string = ''` — URL to fetch and parse. `name: string = ''` — accessible label,
 used as `<lr-map>`'s `label` and the root's `aria-label` (falling back to the localized
 `geojsonViewLabel` when unset). A host `aria-label` takes precedence over `name`. The shared
 text-viewer contract adds `highlights`, `activeHighlightId`, `anchor`, and
 `anchorKinds` (`['text-quote', 'fragment']`), plus `search()`, `searchNext()`, `searchPrevious()`,
-`clearSearch()`, and `scrollToAnchor()` for rendered feature metadata and status text.
+`clearSearch()`, and `scrollToAnchor()` for the ordinary-DOM serialized feature metadata and status
+text, independent of whether the optional map peer is available.
 
 **Events:** `lr-render-error` — `detail: { error }` — fetch, parse, or shape-validation failure.
 
 **CSS parts:** `base` (the root container), `status` (the feature-count status line, `role="status"`,
-shown only in the `<lr-map>` path), `missing-library` (the missing-`maplibre-gl` callout shown
+shown only in the `<lr-map>` path), `metadata` (selectable/searchable serialized GeoJSON `<pre>`,
+rendered in both map and fallback paths), `missing-library` (the missing-`maplibre-gl` callout shown
 alongside the `lr-json-viewer` fallback), `error` (the error region, `role="alert"`), `spinner`
 (the loading status region).
 

package/llms/components/lr-graph-legend.md

@@ -6,7 +6,7 @@
 - **Class** `LyraGraphLegend`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/graph-legend/graph-legend.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 6 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -21,7 +21,8 @@ same event-decoupled contract every sibling in this family follows.
 **Properties:**
 - `types: LyraGraphLegendType[] = []` (attribute: false) — `{ id: string; label: string; color?:
   string; shape?: 'circle' | 'square' | 'diamond' }`, the exact `lr-graph.nodeTypes` entry shape
-  (declared locally, not imported, so this stays a zero-dependency component)
+  (declared locally, not imported, so this stays a zero-dependency component). A color is used only
+  when valid for CSS `color`; declaration breaks and `url()` fall back to the categorical palette
 - `counts?: Record<string, number>` (attribute: false) — optional per-type count shown alongside the
   label
 - `hiddenTypes: string[] = []` (attribute: false) — controlled; the host assigns this back from
@@ -41,7 +42,8 @@ after each toggle).
 **Themeable custom properties:** `--lr-graph-legend-hidden-color` (default
 `var(--lr-color-text-quiet)`) — text color of a filtered-out (hidden) row's `label`/`count`,
 independent of the shared quiet-text token so a host can retint "hidden" rows without repainting
-every other quiet-text surface. Also reads `--lr-graph-cat-1` through `-8`
+every other quiet-text surface; `--lr-graph-legend-hidden-swatch-opacity` (default `0.5`) controls
+only that row's decorative swatch opacity. Also reads `--lr-graph-cat-1` through `-8`
 (the same computed-style fallback palette `lr-graph`/`lr-word-cloud` use) plus shared tokens.
 
 **Optional peer deps:** none.

package/llms/components/lr-graph.md

@@ -38,8 +38,9 @@ A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
   boolean; color?: string; dash?: number[] }` (source/target are node ids). `directed` adds an
   arrowhead; `color` and `dash` style the individual stroke; `label` provides a spoken-name and SVG
   tooltip fallback but is not rendered as visible edge text; `accessibleLabel` and `description`
-  can override the spoken name and tooltip independently. A link whose `source` id doesn't resolve
-  to a real node is still dropped entirely
+  can override the spoken name and tooltip independently. `width` is normalized before reaching
+  SVG, canvas paint, or canvas picking: negative values clamp to `0`, while a non-finite or unset
+  value uses `1.5`. A link whose `source` id doesn't resolve to a real node is still dropped entirely
   (there's no position to draw a stub from). A link whose `target` id doesn't resolve instead renders
   as a short, dashed, non-interactive stub off `source`'s own position
   (`[part='link'][data-dangling]`, `aria-hidden="true"`) rather than being silently dropped — e.g. for
@@ -82,7 +83,9 @@ A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
   `::part(node)`/`::part(link)` styling (pixels, not elements — theme via cssprops instead), no
   native SVG `<title>` tooltip (replaced by `part="tooltip"`), and a drawn focus ring instead of a
   CSS one. Keyboard roving/announcements are preserved through an offscreen `part="cursor-item"`
-  button per node/link/hull.
+  button per node/link/hull. In both renderers, node, link, and community-hull picking keeps at
+  least 24 CSS px of screen-space geometry as the viewport zoom changes; this enlarges interaction
+  only, not the visible marks.
 
 **Methods:** `focusNode(id, options?: { zoom? })` and `fit(options?: { padding?: number })` control the
 camera; `getNodePosition(id)` returns the current `{ x, y }` in graph-local drawing coordinates, or
@@ -95,7 +98,9 @@ id? }`; the optional `id` is the stable `GraphLink.id` supplied by the caller),
 `lr-link-enter`/`lr-link-leave` (`detail: { source, target, id? }`, same hover contract),
 `lr-node-expand` (`detail: { id }`, a node was double-activated — native `dblclick`, or two
 Enter/Space activations within 500ms — regardless of `GraphNode.expandable`), `lr-community-click`
-(`detail: { id }`, a hull was activated)
+(`detail: { id }`, a hull was activated), `lr-selection-change`
+(`detail: { nodeIds, linkIds }`, a controlled selection intent), and `lr-viewport-change`
+(`detail: { k, x, y }`, a frame-coalesced camera/layout signal)
 
 **Slots:** none.
 
@@ -131,8 +136,10 @@ Under `renderer="canvas"` these five are read from computed style at paint time
 per-node elements to inherit them), so they must be set on or above the `<lr-graph>` host itself.
 
 **Optional peer deps:** `d3-force`, `d3-drag`, `d3-zoom`, `d3-selection` (all four required
-together; lazy-`import()`ed once per page, `console.warn` once and renders empty if missing —
-install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
+together; lazy-`import()`ed once per page). Each loaded module is validated for the named callable
+capabilities the graph uses; a missing package or malformed module fails closed through the
+localized `part="error"` alert. Install with
+`pnpm add d3-force d3-drag d3-zoom d3-selection`.
 
 ```html
 <lr-graph style="display:block;height:500px"></lr-graph>
@@ -174,12 +181,11 @@ install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
   `<lr-skeleton>` sized to `width`/`height` with `aria-busy="true"`. If they fail to load (for
   example, because they are not installed), the graph fails closed with a localized
   `part="error"` / `role="alert"` message instead of leaving an empty SVG.
-- `GraphNode.color` is sanitized (rejects `;`/`{`/`}`) before being written into the
-  `--lr-node-fill` inline custom property, so an untrusted color string can't break out of that
-  CSS declaration.
-- `GraphLink.color` applies the same declaration-delimiter sanitization. `GraphLink.dash` is used
-  only when every entry is finite and non-negative; an empty or invalid array falls back to a solid
-  line rather than partially applying malformed SVG stroke data.
+- `GraphNode.color`, node-type colors, `GraphLink.color`, and community colors are accepted only
+  when the browser parses them as CSS `color`; declaration breaks and `url()` paint servers are
+  ignored in favor of the normal token/palette fallback. `GraphLink.dash` is used only when every
+  entry is finite and non-negative; an empty or invalid array falls back to a solid line rather
+  than partially applying malformed SVG stroke data.
 - a structural `nodes`/`links` change now carries over each already-settled node's position (and any
   in-progress drag) by id when rebuilding the simulation, instead of discarding every node's (x, y)
   and re-running the whole ~300-tick random-start settle from scratch — only genuinely new ids get a
@@ -188,6 +194,8 @@ install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
 - under `prefers-reduced-motion: reduce`, or whenever `seed` is set, the simulation converges
   synchronously (ticked in a loop down to `alphaMin` before first paint) instead of animating over
   ~300 rendered frames; user-initiated motion (dragging a node) is unaffected either way.
+- in canvas mode, `pointercancel`, lost pointer capture, and disconnect all release a live node's
+  force pin and reset the simulation target; a canceled drag never leaves the node pinned.
 - the `<svg part="svg">` now carries `role="group"` and an `aria-label` summarizing the node/link
   counts (e.g. "Node-link diagram with 5 nodes and 4 links"), and node `<text part="label">`s are
   `aria-hidden="true"` (their content is already covered by each node's own `aria-label`).

package/llms/components/lr-grounding-summary.md

@@ -43,7 +43,8 @@ and `lr-citation-badge` for each evidence entry.
 `@aceshooting/lyra-ui/ai` = `{ citation: Citation }`) — emitted when an evidence badge is activated.
 The inner `lr-citation-badge`'s own `lr-citation-activate` (`detail: { sourceId, index }`) still
 bubbles through unmodified; this richer event exists because a bare `sourceId`/`index` pair can't
-tell a host which exact evidence *span* to jump to.
+tell a host which exact evidence *span* to jump to. The composed `lr-claim-evidence` also surfaces
+`lr-claim-select` (`detail: { claim }`) unchanged when a claim is activated.
 
 **Slots:** none.
 

package/llms/components/lr-heatmap.md

@@ -132,16 +132,17 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   exact ramp steps instead of linearly interpolating between `--lr-heatmap-scale-lo`/`-hi`;
   governs both `mode`s and both `scale` values, discretizing whichever scale would otherwise
   interpolate continuously into `colorSteps.length` buckets instead. Unset (the default, or fewer
-  than 2 entries) keeps today's 2-endpoint interpolation exactly.
+  than 2 entries) keeps today's 2-endpoint interpolation exactly. Invalid colors use the canvas
+  fallback color and prevent the custom legend gradient from being assigned.
 - `legendStops?: HeatmapLegendStop[]` (attribute: false) — `HeatmapLegendStop { value: number;
   color?: string; label?: string }`: a discrete legend key rendered **instead of** the
   `--lr-heatmap-scale-lo`/`-hi` gradient bar and its `[part="legend-lo"]`/`[part="legend-hi"]`
   endpoint labels — one `[part="legend-stop"]` per entry, in array order, each a
   `[part="legend-swatch"]` filled with that entry's `color` plus a `[part="legend-stop-label"]`.
-  `color` is optional: omit it (or pass an empty string) for a **caption-only** stop, which renders
-  its `[part="legend-stop-label"]` alone with no `[part="legend-swatch"]` element in the DOM at all —
-  so a leading "0" or trailing "more" caption around a run of colored stops doesn't leave an empty
-  swatch box in the row.
+  `color` is optional: omit it, pass an empty string, or pass an invalid CSS color for a
+  **caption-only** stop, which renders its `[part="legend-stop-label"]` alone with no
+  `[part="legend-swatch"]` element in the DOM at all — so a leading "0" or trailing "more" caption
+  around a run of colored stops doesn't leave an empty swatch box in the row.
   A stop's label defaults to the component's own locale-aware numeric formatting of `value`, so an
   explicit `label` is only needed when the number isn't the right caption ("none", "≥ 90%"). Exists
   for the consumer who supplies `cellColor`: because that callback overrides a cell's color
@@ -228,6 +229,8 @@ same color as `--lr-heatmap-focus-ring-color`).
 ```
 
 **Known gotchas:**
+- The legend is a wrapping flex row. Long unbroken stop labels, the trailing `valueLabel`, and
+  annotation labels wrap within the host instead of forcing the heatmap wider than its allocation.
 - `legendStops` *replaces* the lo/hi gradient bar rather than adding to it: supplying it removes
   `[part="legend-lo"]`, `[part="legend-hi"]` and the bar from the DOM, so a stylesheet targeting
   those parts silently stops applying. It is also presentation-only — it never feeds back into the

package/llms/components/lr-highlight-layer.md

@@ -20,7 +20,8 @@ positioned ancestor.
 
 **Properties:** `items: HighlightLayerItem[] = []` (attribute: false), `activeId: string | null =
 null` (attribute `active-id`), and `interactive: boolean = true` (reflected) — gates click/keyboard
-activation.
+activation. A rectangle is eligible only when `x`/`y`/`width`/`height` are finite numbers and both
+dimensions are nonnegative; invalid rectangles are omitted from paint, focus, and activation.
 
 **Methods:** `flash(id)` briefly re-triggers the flash styling for an already-rendered rect (e.g. a
 re-click of the same source citation).

package/llms/components/lr-histogram.md

@@ -6,7 +6,7 @@
 - **Class** `LyraHistogram`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/histogram.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 7 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -35,16 +35,20 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
   (`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
   (`show-data-table`), `chartArea` (readonly).
 
-**Methods:** `resetZoom()`, `refreshTheme()` — both inherited.
+**Methods:** `resetZoom()`, `refreshTheme()` — both inherited; plus
+`appendData(_label, values, maxPoints?)`, which appends finite raw samples to `values` and
+optionally retains only the newest `maxPoints`. The label argument is ignored because bucket
+labels are regenerated from the rebinned sample range.
 
 **Events:** `lr-zoom`, `lr-point-click` — inherited; `lr-point-click`'s `index` is the bucket index
 and `label` the generated bucket range string (`"lo–hi"`, both bounds at one decimal place).
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
-`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
-dependency fails to load — inherited from `LyraChart`, unaffected by the binning logic).
+**CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-swatch`,
+`reset-zoom-button`, `description`, `data-table`, `center`, `error` (`role="alert"` message
+rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load —
+inherited from `LyraChart`, unaffected by the binning logic).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -70,5 +74,8 @@ their semantics, defaults, and gotchas.
   property write from requesting an unbounded bucket array.
 - non-finite samples in `values` are dropped before bucketing rather than corrupting bucket-index
   math; constant data (every sample equal) lands wholly in the **first** bucket, not the last.
+- `values`/`bins`/`label` changes join the inherited connected-and-visible redraw path. There is no
+  second post-update refresh, so a same-tick disconnect cannot recreate Chart.js on a detached
+  canvas and off-screen sample updates do not repaint it.
 
 ---

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

@@ -16,8 +16,9 @@
 Fetches an HTML document, sanitizes it with the optional `dompurify` peer, and renders the safe markup
 inside a bounded, scrollable body.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. A host
-`aria-label` takes precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings; invalid CSS
+`max-height` values, declaration breaks, and `url()` are ignored. A host `aria-label` takes
+precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
 `anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract.
 
 **Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and

package/llms/components/lr-icon.md

@@ -28,7 +28,9 @@ Dependency-free SVG path icon: no icon font, no sprite sheet, no network fetch.
 **Slots:** (default) — custom SVG geometry, rendered only when neither `path` nor a known `name`
 resolves. Slotted nodes are cloned into the component-owned `<svg>` (Chromium does not paint SVG
 geometry distributed through a slot that sits inside an SVG), so pass plain `<path>`/`<circle>`/
-`<g>` elements, not a whole `<svg>`.
+`<g>` elements, not a whole `<svg>`. Attribute and descendant mutations to assigned geometry are
+mirrored live while connected; observation stops on detach and a reconnect synchronizes the latest
+source tree.
 
 **CSS parts:** `svg`
 

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

@@ -40,6 +40,11 @@ zoom }`), `lr-rotation-change` (`detail: { rotation }`), `lr-fit-change` (`detai
 embedded `lr-zoomable-frame`), `image-wrapper`, `image`, `highlight-layer`, `highlight` (carries
 `data-tone`/`data-active`), `highlight-label`, `annotation-box`, and `error`.
 
+While `annotatable`, `image-wrapper` is a named `role="group"` with the localized annotation hint.
+Only `region` highlights whose `rect` contains finite numeric `x`/`y`/`width`/`height` and
+nonnegative dimensions are rendered; malformed rectangles are omitted rather than reaching inline
+styles or anchor hit testing.
+
 **Themeable custom properties:** `--lr-image-viewer-annotate-active-bg` (default
 `var(--lr-color-brand-quiet)`) and `--lr-image-viewer-annotate-active-border` (default
 `var(--lr-color-brand)`) — the background and border of `[part='annotate-toggle']` while annotation