@aceshooting/lyra-ui 29.0.2 → 29.1.0

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 2 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 8 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`
 
 ---
@@ -19,6 +19,44 @@
 A file-explorer preset over `<lr-tree>` + `<lr-file-icon>`: path-keyed nodes with
 git-status/diff-count badges, lazy directory loading, and select/open events.
 
+**Provider hierarchy:** `treeSource: FileTreeSource | undefined` (attribute: false)
+uses `LyraHierarchySource<FileTreeNode, LyraHierarchyQuery>` from
+`@aceshooting/lyra-ui/data-sources.js`. A defined source takes precedence over `nodes`, preserving
+its identity; invalid defined input shows a localized source error. Setting `undefined` restores
+the current legacy `nodes` input. Reassign even the same source, or call a keyless
+`requestUpdate()`, after revision/provider-state changes. Locale, reconnect and adoption refresh
+the source; unrelated named display updates do not.
+
+The provider projects the complete visible preorder using the same `project` actions, fixed empty
+query and required direct key lookup described for `lr-tree` above. `total` includes collapsed
+nodes and `rows.count` counts all visible logical rows. Those counts can describe a million-node
+host hierarchy while at most 301 rows mount and at most 401 rows are retained (four 100-row pages
+and one focused row). Each range read requests at most 100 rows, with at most two physically
+pending reads. No full path/ancestor index or nested subtree copy is built. The provider owns
+storage, global uniqueness, selection/expansion snapshots and cancellation; source replacement
+and obsolete replies cannot commit old rows or focus.
+
+Global row keys must exactly equal `value.path`: nonblank strings of at most 65,536 UTF-16 units,
+preserved verbatim without filesystem resolution. Paths are identities, not permission to read or
+open a file; the host authorizes any resulting operation. Displayed `name`/`mimeType` use at most
+65,536 aggregate text units per row; oversized or accessor-backed fields fail visibly. Source
+events contain only bounded frozen displayed metadata, with no `children`. The provider's
+`childCount` identifies branches even when `kind` is omitted; branches never emit file-open.
+Nested `value.children` is ignored. Logical depth, sibling positions, bounded keyboard navigation,
+localized loading/empty/error states and retry follow the source tree contract above. The legacy
+snapshot limits below remain separate from this route; `maxNodes` does not raise its source window.
+
+**Controlled source selection:** an accepted user selection updates `selectedPath` and emits
+`lr-file-select`. Activating an already-selected leaf file also emits `lr-file-open`, provided the
+same source/projection is still current after the selection listener returns. The provider owns
+the authoritative selected flags. External `selectedPath` changes submit an item selection after
+the initial projection, without synthetic user events or moving focus; clearing it deselects the
+previously controlled key. The default `null` does not request a global clear. A current valid path
+is reconciled again after source replacement, rebind or refresh. Invalid empty/blank/oversized
+controlled paths are not forwarded. This adapter has no source search/copy controls.
+
+With `treeSource` undefined, the following snapshot and lazy-directory route applies.
+
 An unreadable optional field rejects only that file record; it cannot reserve the path against a
 later valid occurrence. Valid siblings retain their source order within the existing depth and
 inspected-position budgets.
@@ -26,7 +64,10 @@ inspected-position budgets.
 **Properties:** `nodes: readonly FileTreeNode[] = []` (attribute: false; clone-owned/frozen,
 cycle-safe snapshot omitting empty/blank paths and retaining the first successfully admitted occurrence of each path, bounded to
 the first 10,000 inspected source positions across 64 descendant levels; reassign after changes;
-rebinding the same array is a no-op). The composed `<lr-tree>` holds at most 1,000 rows: when the
+rebinding the same array is a no-op). `maxNodes: number = 1000` (attribute `max-nodes`) sets the
+composed tree's row budget, normalized to `1..10000`; unset or non-finite values restore 1,000.
+The source budget remains 10,000 inspected positions. The composed `<lr-tree>` holds at most
+`maxNodes` rows: when the
 whole listing is larger, each collapsed directory is projected as a single lazy row whose children
 load from the snapshot when it expands, so every top-level entry stays reachable;
 `selectedPath: string | null = null` (attribute `selected-path`), and `label?: string` — an
@@ -35,12 +76,14 @@ back to the localized default while an explicitly empty string renders as an emp
 `additions`/`deletions` are normalized once to finite nonnegative integers before localized visible
 and accessible diff summaries. A host `aria-label` wins by presence when naming the internal tree,
 including an explicit empty string; removing it restores `label` or the localized fallback.
+Derived rows are reused until their data, locale or limit changes; selecting a different path
+updates only the affected ancestor paths. An explicit `requestUpdate()` refreshes derived content.
 
 **Read-only getters:** `dataTruncated: boolean` — `true` when normalization omitted a malformed,
 duplicate, cyclic, over-depth or over-budget entry, or when the directories currently expanded hold
-more rows than the composed tree's 1,000-row budget.
+more rows than the composed tree's configured row budget.
 When source normalization reaches its 10,000-node cap, the host shows a localized `limit` part;
-the composed tree shows its own 1,000-item notice when its valid-node cap is reached.
+the composed tree shows its own notice when its configured valid-node cap is reached.
 
 **Lazy directories:** a directory with `hasChildren: true` and no `children` uses `<lr-tree>`'s own
 lazy lifecycle: expanding it shows the row's busy spinner (`aria-busy`), emits `lr-load-children`
@@ -49,13 +92,24 @@ children; an empty result ends the busy state without expanding. No placeholder
 
 **Methods:** `setChildren(path, children)` supplies a lazily-loaded directory's children.
 `revealPath(path)` expands every ancestor directory and scrolls the target row into view, resolving
-`true` once found. `expandAll()` and `collapseAll()` forward to the underlying `<lr-tree>`.
+`true` once found in legacy mode. In source mode it delegates to
+`revealSourceKey(key: string): Promise<boolean>`, which requests a provider reveal and focuses its
+current visible row; missing/invalid/obsolete requests resolve `false`. The provider must return a
+valid `focusIndex` for successful reveal. `expandAll()` and `collapseAll()` forward to the underlying
+`<lr-tree>` only in legacy mode and are no-ops in source mode. `setChildren()` updates the legacy
+`nodes` input; it does not mutate the provider. Source branch toggles use `project(toggle)` rather
+than `lr-load-children`.
 
 **Events:** `lr-file-select` (frozen readonly `detail: { filePath, node }`, a row was activated),
 `lr-file-open` (frozen readonly `detail: { filePath, node }`, Enter/click on an already-selected file
 row), and `lr-load-children` (frozen readonly `detail: { filePath }`, a lazy unloaded directory
-expanded). The composed tree's own `lr-expand`, `lr-collapse`, `lr-after-*`, `lr-lazy-*` and
+expanded, legacy mode only). Source select/open keep the same `{ filePath, node }` shape, with
+`node` limited to the displayed record rather than a complete subtree. The composed tree's own
+`lr-expand`, `lr-collapse`, `lr-after-*`, `lr-lazy-*` and
 `lr-selection-change` events stay inside the component.
 
 **CSS parts:** `base` — the root wrapper; `limit` — localized notice when the source listing
 exceeds its 10,000-item snapshot.
+Source mode retains `base` and adds `tree` on the semantic root, plus `source-list`, `source-row`,
+`source-toggle` (branch and retry buttons), `source-label`, `source-status`, and `source-error`.
+The root owns the accessible name/busy state, and each flat source row owns logical treeitem ARIA.

package/llms/components/lr-flag.md

@@ -52,6 +52,9 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
 
 Exported authoring types are `LyraFlagShape`, `LyraFlagFidelity`, and `LyraFlagUrlResolver`.
 
+Concurrent flags resolving the same country and fidelity share pending resolver work within the
+current resolver generation. Settled or failed requests do not prevent later retries.
+
 **Events:** none.
 
 **Slots:** `fallback` — rendered in place of the flag when `country`/`language` cannot resolve to a
@@ -107,8 +110,8 @@ exported:
 itself (`'fr'` → `français`, `'pt-BR'` → `português (Brasil)`). That is what a language switcher
 should list, so a reader who understands none of the current UI language can still find their own.
 It derives from `Intl.DisplayNames`, so no name table ships with the library and results follow the
-browser's own ICU data; the underlying instance comes from a shared memoized cache, since a picker
-does one lookup per offered locale on every render pass. A tag with no display name resolves to the
+browser's own ICU data. The underlying formatter and resolved native names are cached, so repeated
+catalog renders reuse prior results. A tag with no display name resolves to the
 tag itself, and so does a structurally invalid one — `Intl.DisplayNames` throws a `RangeError` on
 those rather than falling back, and a language picker should degrade to showing the raw tag rather
 than tearing down the render. Pair it with `languageToCountry()` for the flag half of the same row.

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 29 parts, 17 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 36 parts, 17 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`
 
 ---
@@ -18,13 +18,26 @@
 
 A pannable/zoomable DAG workflow canvas: positions HTML node cards, draws SVG edges between their
 handles, runs a shared layered auto-layout for unpositioned nodes, and owns all selection/drag/
-connect interaction. It is readonly by default; opt into editor gestures with `nodes-draggable`,
+connect interaction. Editor gestures are opt-in with `nodes-draggable`,
 `connectable`, and `droppable`. The component snapshots model inputs instead of retaining mutable
 caller aliases, and reports edit intent for the host to apply.
 
-Input/output handle IDs are reserved only after their complete handle record is admitted; unreadable
+With `graphSource` unset, node cards and edges outside the visible viewport are culled. Active and selected nodes, active
+and selected edge endpoints, connection targets and their incident edges remain available.
+Keyboard navigation retains the complete model order and pans to reveal its destination. Panning
+queries retained geometry indexes; companion snapshots contain the complete admitted model.
+Viewport culling preserves existing collection-admission limits and controlled model semantics.
+Without a measurable viewport, including during SSR, the complete model is rendered.
+
+For legacy array inputs, input/output handle IDs are reserved only after their complete handle record is admitted; unreadable
 optional labels cannot suppress a later valid handle with the same ID.
 
+Legacy node metadata uses a shared 50,000-position inspection budget per node assignment, at most
+10,000 own keys per record and 16 descendant levels. Cloned JSON references and cycles are shared
+across node data roots and frozen; non-plain leaves remain opaque. The `input-limit` part reports
+node/edge or metadata admission loss separately from `layout-limit`. JavaScript key enumeration
+itself can still scale with an individual object's key count.
+
 Anchored Lyra overlays in a node's slotted content (a node menu, a tooltip) resolve the `fixed`
 strategy by default, because a node is translated inside a scaled, clipped world where an
 `absolute` overlay could never extend past the canvas; a trapped `fixed` overlay opens in the
@@ -53,6 +66,121 @@ import type {
 } from "@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js";
 ```
 
+**Complete workflow source:** `graphSource: FlowCanvasSource | undefined`
+(attribute: false) takes precedence over `nodes`/`edges`. Only `undefined` restores the latest
+legacy inputs; invalid defined providers fail visibly without falling back to those arrays.
+Provider identity/revision is caller-owned; the canvas admits bounded records and scenes.
+
+```ts
+import "@aceshooting/lyra-ui/components/lr-flow-canvas.js";
+import type { FlowCanvasSource } from
+  "@aceshooting/lyra-ui/components/data/flow-canvas/flow-canvas.class.js";
+import type { FlowNode, FlowEdge, FlowStructureSnapshot } from
+  "@aceshooting/lyra-ui/components/data/flow-canvas/flow-types.js";
+import type { LyraGraphSource, LyraGraphSourceQuery, LyraGraphSourceSummary,
+  LyraGraphOverview, LyraSourceBounds } from
+  "@aceshooting/lyra-ui/data-sources.js";
+```
+
+`FlowCanvasSource = LyraGraphSource<FlowNode, FlowEdge>`; the exact generic protocols are in
+[shared source contracts](../shared/events-and-types.md). It provides `revision`, `records`,
+`scene(request)` and optional `overview(request)`. Source and records revisions must agree and
+be a nonempty string or finite number. `records` supplies `query`, `lookup` and `locate` for the
+complete logical workflow, separately from the bounded positioned scene.
+
+**Global record navigation:** `sourcePage: number = 0` (`source-page`) is zero-based;
+`sourcePageSize: number = 100` (`source-page-size`) normalizes to 1–500. Readonly
+`sourceTotal: number | null` is the accepted current record-query total, or null while unavailable
+or without a source. Size/query changes reset page zero; an out-of-range page receives at most
+one corrective last-page request and publishes the accepted corrected page. The navigator offers
+nodes or edges, full-source search, incident-edge scope with in/out/both direction, endpoint
+links, page entry/previous/next and global Home/End/Up/Down record navigation.
+
+The navigator sends `LyraGraphSourceQuery`, initially
+`{ kind: 'nodes', search: '', centerKey: null, direction: 'both', nodeTypes: [] }`.
+Search is bounded to 65,536 UTF-16 units; these controls query the whole source rather than
+filtering a loaded scene/page. `records.query({ revision, locale, signal, page, pageSize, query })`
+returns `{ rows, total, summary: { nodes, edges } }`. Each row is `{ key, order, value }`, where
+`value` is `{ kind: 'node', value: FlowNode }` or `{ kind: 'edge', value: FlowEdge }` and its key is
+exactly `node:<id>` or `edge:<id>` with a nonblank original ID. Safe nonnegative canonical `order`
+and keys are unique within a page; rows exactly fill the requested in-bounds page. The required
+summary gives complete global node/edge counts; unfiltered total equals the matching summary
+count, filtered/incident total cannot exceed it, and accepted scenes must agree with those counts.
+Totals and summary counts are safe nonnegative integers.
+Groups/tags are not accepted on this route. Invalid/duplicate/oversized responses fail atomically,
+without local filtering, sorting or silent trimming. Record pages copy only bounded display fields
+and edge endpoints; they do not materialize complete node metadata.
+
+`revealSourceKey(key: string): Promise<boolean>` accepts canonical `node:<id>`/`edge:<id>`, clears
+search/incident scope for that kind, uses global `locate`, loads the matching page and attempts to
+focus its navigator row. It resolves false for unset/invalid/missing, failed or superseded work. This is
+separate from synchronous `focusNode(id, options)`, which moves camera/focus only for a node
+already known in the current scene and does not fetch globally. Reveal does not promise a camera
+move or a new scene. Reveal, controlled paging/selection and rebind emit no activation or selection
+event; actual row activation retains `lr-node-activate`/`lr-edge-activate` and selection payloads
+with original IDs. Scene absence does not prove global record absence.
+
+**Bounded scene and source geometry:** `scene` receives viewport bounds, at most 32 selected/focus
+reservation keys, `nodeLimit: 500` and `edgeLimit: 1000`. It returns at most those exact node/edge
+entries, global `total`, explicit `coverage: 'complete' | 'neighborhood' | 'aggregate'` and non-null
+`worldBounds`. Requests include revision/locale/signal, `mode: 'viewport'`, `centerKey: null`,
+`bounds` and `includeKeys`. Nodes require finite explicit entry positions inside authoritative world
+bounds; an optional value position must agree. Position/world rectangle endpoints stay within ±1,000,000,
+with nonnegative world dimensions and finite endpoints. Scene edge keys/endpoints must match
+value IDs and resolve to nodes in that scene. Missing positions never trigger local auto-layout.
+The same revision must keep world bounds and global totals consistent. `source-coverage` reports
+shown versus global counts, rather than suggesting every record is drawn.
+
+Source scenes preserve FlowNode type, accessible label, disabled state, input/output handles and
+data, plus FlowEdge handles, label and tone. They read own data descriptors; accessors reject.
+`data` accepts plain records/arrays of strings, finite numbers, booleans and null, with shared
+references/cycles preserved in detached frozen copies. Opaque leaves such as functions or Dates
+reject. Each container/handle collection allows at most 10,000 entries, descendant container depth
+is at most 16, and metadata/handle inspection shares a 50,000-field scene budget. Each admitted
+text/key is at most 65,536 UTF-16 units, with a 2,000,000-unit cumulative text ceiling per scene
+or record-page response. Overflow fails the complete response without clipping. JavaScript's
+eager own-key enumeration can still allocate/work in proportion to one input object's key count
+before that object's entry limit is rejected; these bounds do not make provider work constant.
+
+Provider-derived retained data covers the current record page (at most 500 rows), current scene
+(at most 500 nodes/1,000 edges) and bounded geometry/overview. Controlled selection keeps its existing first-10,000
+candidate-ID bound and preserves offscene IDs instead of pruning them by scene membership;
+scene reservations are at most 32 keys. This route does not materialize the full provider workflow
+or cache historic pages.
+Page/locate work, scene and overview each keep their fixed request lanes, with one physical call
+per lane and only the latest queued intent. Ignored aborts keep physical permits until settlement;
+providers should settle promptly. Paging does not reset the camera or refetch an unchanged scene;
+pan/zoom/resize changes the viewport scene without restarting the record query. Accepted overview
+is reused across viewport changes.
+
+Source mode disables model editing: drag/nudge/connect/drop/delete and full-array layout/model
+mutations, including gestures started before the source was assigned. It does not force public
+`readonly`; pan/zoom/navigation and minimap controls remain usable when unlocked. Public
+`readonly` still locks viewport interaction and makes viewport-mutating methods inert. Source
+mode emits no model-edit/layout event presenting a bounded scene as the complete workflow.
+`fit()` frames accepted global world bounds; legacy `fit()` frames admitted node geometry.
+
+Companion snapshots add optional
+`source: Readonly<{ coverage: 'complete' | 'neighborhood' | 'aggregate'; total: LyraGraphSourceSummary;
+worldBounds: LyraSourceBounds; overview: LyraGraphOverview | null }>` when accepted source bounds
+are available. Their node/edge arrays remain bounded exact scene geometry. `locked` still means
+public `readonly`. Optional `overview({ revision, locale, signal, limit: 1024 })` must describe
+those exact world bounds with at most 1,024 finite contained nonoverlapping bins whose counts sum
+to the global node total. Null/unavailable/rejected overview is distinct from accepted empty
+bins; the minimap never invents a global overview from scene nodes. The frozen accepted overview
+identity is shared across viewport notifications.
+
+Reassign even the same source or call a keyless `requestUpdate()` after revision/state changes.
+Named local presentation paints reuse accepted provider data unless source revision/effective
+locale changed. Replacement, unset, disconnect and adoption revoke old provider callbacks, gestures
+and effects; superseding query/reveal revokes obsolete record controls. Reconnect captures current
+input. Source navigator/status parts are `source-navigator`, `source-controls`, `source-status`, `source-coverage`,
+`source-records` and `source-record`. Loading, successful empty, missing record, record failure
+and scene failure remain distinct localized states with current guarded retry controls.
+
+The following array admission, legacy auto-layout and complete-model snapshot rules apply with
+`graphSource` unset; source behavior is described above.
+
 **Properties:**
 
 - `nodes: readonly FlowNode[] = []` (attribute: false) — each record has readonly `id`, optional
@@ -85,13 +213,13 @@ import type {
 - `readonly: boolean = false` (reflected) — freezes pan/zoom/drag/connect without touching the other
   gesture flags. Enabling it during a pan, node drag, pointer/keyboard connection, or palette drop
   cancels the active preview, rolls pan/node geometry back, clears transient state, and retires the
-  window pointer listeners so a later release cannot commit. The one-shot initial framing still
-  applies to a `readonly` canvas, and waits until the canvas has a rendered size (a hidden tab or
+  window pointer listeners so a later release cannot commit. The legacy one-shot initial framing
+  still applies to a `readonly` canvas, and waits until the canvas has a rendered size (a hidden tab or
   closed dialog is framed when it is first shown).
 - `selectedNodeIds: readonly string[] = []`, `selectedEdgeIds: readonly string[] = []` (attribute:
   false) — seed or replace selection. Each assignment snapshots at most the first 10,000 ids,
-  omits blank/later duplicates first-wins, and prunes identities absent from the current canonical
-  node/edge model. Reassign after changes. Activation and clear-selection gestures update frozen
+  omits blank/later duplicates first-wins, and, with `graphSource` unset, prunes identities absent
+  from the current canonical node/edge model. Reassign after changes. Activation and clear-selection gestures update frozen
   arrays before emitting `lr-selection-change`; model shrinkage prunes stale ids without claiming
   a user selection gesture occurred.
 - `minZoom: number = 0.25` (attribute `min-zoom`), `maxZoom: number = 2` (attribute `max-zoom`)
@@ -109,21 +237,25 @@ import type {
 - `viewport` (readonly getter) — a frozen `{ x, y, zoom }` snapshot
 
 **Methods:** `setViewport({ x, y, zoom })`, `zoomIn()`, `zoomOut()`, `resetZoom()`,
-`fit(options?: { padding?: number })` (frames every node), `focusNode(id, options?: { zoom? })`
-(pans/zooms to one node and moves roving focus onto it), `toContentPoint(clientX, clientY)` (maps a
+`fit(options?: { padding?: number })` (frames legacy admitted nodes or source global world bounds),
+`focusNode(id, options?: { zoom? })` (pans/zooms to one currently known node and moves roving focus
+onto it), `toContentPoint(clientX, clientY)` (maps a
 pointer position to content coordinates, RTL-aware), `registerCompanion(cb: (snapshot:
 FlowStructureSnapshot) => void): () => void` — the subscription `lr-flow-minimap` uses to read
 live node/edge/viewport geometry without this canvas ever importing the minimap.
+`revealSourceKey(key: string): Promise<boolean>` provides the global record navigation described above.
 All viewport-mutating methods, including `focusNode()`, are inert while `readonly`; coordinate mapping
 and companion subscription remain available because neither mutates viewport or edit state.
 Each companion observer receives its own deeply frozen `FlowStructureSnapshot`: readonly node and
 edge geometry/status arrays (shared between observers and reused, by identity, across
 viewport-only frames until the structure changes), viewport `{ x, y, zoom, width, height, minZoom, maxZoom }`, and the
 effective `readonly` state (as the snapshot's `locked` key), `orientation`, `layerGap`, and `nodeGap`. Zoom bounds are finite, positive, and
-sorted even when public inputs are invalid or reversed.
+sorted even when public inputs are invalid or reversed. Source snapshots additionally carry the
+accepted `source` descriptor above; their scene arrays do not imply full-source coverage.
 
-**Events:** `lr-node-activate` (`detail: { nodeId }`), `lr-edge-activate` (`detail: { edgeId, source, target
-}`), `lr-selection-change` (`detail: { selectedNodeIds, selectedEdgeIds }`), `lr-node-move` (`detail: { nodeId,
+**Events:** `lr-node-activate` (`detail: { nodeId }`), `lr-edge-activate` (`detail: { edgeId,
+sourceNodeId, targetNodeId, source, target }`, both endpoint-name pairs are supplied),
+`lr-selection-change` (`detail: { selectedNodeIds, selectedEdgeIds }`), `lr-node-move` (`detail: { nodeId,
 position, previous }`), `lr-connect` (`detail: { source, target, sourceHandle, targetHandle }`),
 `lr-node-add` (`detail: { type, position }`, from a palette drop), `lr-selection-delete`
 (`detail: { nodeIds, edgeIds }`), `lr-viewport-change` (`detail: { x, y, zoom }`),
@@ -131,7 +263,7 @@ position, previous }`), `lr-connect` (`detail: { source, target, sourceHandle, t
 previously unpositioned nodes). Every detail and nested coordinate/array is readonly and frozen.
 
 **Slots:** default (consumer-authored cards matched by `node-id` and assigned to generated
-`node-{id}` slots), `top-start`, `top-end`, `bottom-start`, `bottom-end`. Each node always has a
+`node-{id}` slots), `top-start`, `top-end`, `bottom-start`, `bottom-end`. Each rendered node has a
 declarative shadow-DOM fallback card, so SSR and hydration do not depend on imperative light-DOM
 card creation. An authored card replaces only its matching fallback; unmatched cards are unslotted
 with a warning. Opposite-side companion slots share wrapping rails in narrow allocations.
@@ -141,13 +273,19 @@ with a warning. Opposite-side companion slots share wrapping rails in narrow all
 (a dangling-edge stub line), `connection-line` (in-progress connect gesture), `node`, `empty`,
 `node-control` (the native per-node roving/activation control), `live-region`, `edge-list` (a
 visually hidden list only for dangling/unrenderable edges), `layout-limit` (a visible notice whose
-announcement uses the shared light-DOM polite sink), `overlay-rail`, and the
+announcement uses the shared light-DOM polite sink), `input-limit` (node/edge or metadata
+admission notice), `overlay-rail`, and the
 fallback-card parts `node-card`, `node-card-base`, `node-card-surface`, `node-card-header`,
 `node-card-heading`, `node-card-status`, `node-card-progress`, `node-card-body`, `node-card-toolbar`,
 `node-card-handle`, `node-card-handle-input`, and `node-card-handle-output`. A node whose `type`
 normalizes to a safe part token also exposes `node-type-{value}`. A selected node wrapper carries
 `data-selected`; its hidden `node-control` exposes the state as `aria-pressed`.
 
+With `graphSource` set, additional CSS parts are `source-navigator` (complete-source record navigation), `source-controls`
+(query and page controls), `source-records` (the bounded current page), `source-record` (one record
+with incident-edge or endpoint actions), `source-status` (record/scene loading, failure and count
+text), and `source-coverage` (accepted scene coverage relative to complete node/edge totals).
+
 `live-region` is a visually hidden, `aria-hidden` mirror of the latest item/gesture message. The
 actual messages are flushed to the document's shared light-DOM polite sink; mount is silent, and
 identical repeated messages are appended as separate announcements.

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 7 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 9 parts, 10 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`
 
 ---
@@ -22,6 +22,32 @@ rectangle, for orientation and fast navigation on canvases larger than the scree
 geometry always comes from the canvas's `registerCompanion()` snapshots, so the two can never
 disagree.
 
+For legacy snapshots, the minimap retains every admitted node. Its node overview and moving viewport use
+separate SVG layers, so panning keeps the overview tree unchanged. Existing `node`, `viewport`
+and `viewport-hit-area` parts remain available.
+
+**Source companion:** when `FlowStructureSnapshot.source` is present, the minimap frames its
+accepted global `worldBounds`, including negative origins and positive fractional extents; it
+never infers source extent from the bounded scene-node array. Every positive axis keeps its exact
+source dimension without legacy padding or a one-unit minimum. Only an exactly zero-width or
+zero-height axis receives a centered one-unit SVG display extent; source coordinates are unchanged.
+
+Only accepted `source.overview.bins` render, under `aggregate-bin`, at most 1,024 rectangles.
+They describe the complete node population within the authoritative world bounds; scene-node
+rectangles are not painted as a substitute global overview. The canvas owns overview validation
+and freezing, and the minimap adds no provider query or second normalization. A missing/rejected
+`overview: null` shows localized `source-unavailable` (default “Workflow overview unavailable”)
+while world framing and unlocked viewport controls remain usable. Accepted empty bins are a
+successful empty overview and do not show the unavailable state.
+
+The immutable overview layer is reused by identity across viewport-only snapshots. Map clicks,
+viewport drag, wheel zoom and physical arrow keys use the same exact source-world inverse
+mapping, including RTL and zero-axis display fallback. A change in world coordinate values
+cancels an active drag; cloned equal bounds do not. Old subscriptions/detached controls cannot
+move a later canvas binding. `locked` continues to reflect public canvas `readonly`; the source
+editing gate alone does not disable minimap navigation. Removing the provider restores the
+legacy node-geometry overview.
+
 **Properties:**
 
 - `for: string = ''` — id of the target `lr-flow-canvas`; when empty, the nearest ancestor canvas
@@ -39,7 +65,9 @@ disagree.
 **Slots:** none.
 
 **CSS parts:** `base` (the root wrapper; drops its border, background and corner radius under
-`frame="plain"`), `map` (the scaled SVG), `node` (one rect per node), `viewport` (the
+`frame="plain"`), `map` (the scaled SVG), `node` (one rect per legacy node),
+`aggregate-bin` (one accepted source overview rectangle), `source-unavailable` (missing source
+overview message), `viewport` (the
 exact visible view rectangle), `viewport-hit-area` (the transparent draggable/focusable target),
 `instructions` (visually hidden keyboard help), and `live-region` (the `aria-hidden` mirror of the
 latest viewport-change text).
@@ -67,8 +95,8 @@ viewport-to-content ratio. The token inherits from ancestors; set it to `0` to o
 **Known gotchas:**
 
 - Never resolves `nodes`/`edges` on its own — it subscribes to `registerCompanion()` and repaints
-  from whatever snapshot the canvas last pushed, so it can only ever show what the canvas itself
-  currently renders.
+  from the complete admitted legacy geometry or the accepted source overview/world bounds the
+  canvas last pushed. Source scenes remain bounded and never substitute for a global overview.
 - A readonly canvas snapshot makes the hit area unfocusable and inert: no pointer, click, wheel, or keyboard
   shortcut can mutate the canvas.
 - Dragging the viewport rectangle calls the canvas's `setViewport()` directly; there's no separate

package/llms/components/lr-funnel.md

@@ -21,6 +21,12 @@ bar whose length is that stage's share of the **first** stage, read top-to-botto
 drop-off. It sits beside `lr-gauge` and `lr-heatmap` as an analytics primitive rather than a general
 chart type.
 
+Supply `stages` and `comparison` as aggregate counts or measures computed across their complete
+cohorts. A few stages can summarize one million underlying observations when each value includes
+every applicable cohort member. The host or server performs the raw-event aggregation; the
+component receives stage totals, and each comparison cohort normalizes to its own first stage.
+The 500-stage rendering ceiling bounds stage cardinality independently of the observation count.
+
 When a positive finite stage value divided by a positive finite baseline overflows to `Infinity`,
 the main or comparison data fill clamps to 100%. Nonfinite input normalization, nonpositive-baseline
 behavior, percentage and drop-off text, and overflow border styling keep their existing rules.
@@ -32,6 +38,14 @@ Reach for `lr-bar-chart`/`lr-lite-chart` when you actually want a value axis and
 The whole chart is plain HTML — stage names, absolute values, shares and drop-off percentages are
 real text inside an `<ol>`, so there is no sighted-only drawing needing a separate transcript. The
 list carries the accessible name; a host `aria-label` overrides `label`.
+Stage and comparison projections reuse their input identities. Reassign after changes, or call
+`requestUpdate()` after mutating the current arrays. The component resolves at most the first 501
+valid stages to detect overflow and renders at most 500.
+Validation inspects at most 10,000 source positions per chunk and continues through malformed
+entries until it reaches that valid-stage boundary or the end. The last completed chart stays
+visible with `aria-busy` while a replacement is inspected. Keep pending source arrays and records
+unchanged, or reassign/explicitly refresh to restart inspection. Replacement and disconnect cancel
+unfinished work; reconnect derives the current input again.
 
 **Properties:**
 

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

@@ -23,18 +23,34 @@ The root and viewers family barrels still expose the same distinct `LyraGeojsonV
 for compatibility; importing it does not register the removed tag. Prefer the canonical class.
 The document registry renders `lr-geojson-viewer` for `application/geo+json` and `.geojson` filenames.
 
-Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
-`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
-rendering; anything else renders the localized `geojsonViewInvalid` error. On success, it walks every
+Responses are limited to 4 MiB (4,194,304 bytes) before `JSON.parse`. The parsed JSON must be a
+`Feature`/`FeatureCollection`/bare geometry (one of `Point`,
+`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`);
+anything else renders the localized `geojsonViewInvalid` error. On success, it walks every
 value and object key first, rejecting more than 50,000 graph units, nesting beyond 64 levels, more
-than 2 Mi UTF-16 units of aggregate keys/string values, or more than 4 Mi UTF-16 units of formatted
-metadata before serialization or peer handoff. It then walks every coordinate under a separate
+than 2 Mi UTF-16 units of aggregate keys/string values, or more than 4,194,304 UTF-16 units of
+formatted metadata. A size preflight rejects oversized pretty metadata before full serialization
+or peer handoff. It then walks every coordinate under a separate
 10,000-position ceiling to compute a bounding box, seeds `center`/`zoom` from it as a placeholder, and
 frames the data with `<lr-map>.fitBounds()` (size-aware, padded, antimeridian-safe, no animation) once
 the map exists, then hands the parsed value to
-`<lr-map>` as a single `dataLayers` entry (`sourceId: 'lr-geojson'`). When the optional
+`<lr-map>` as a single `dataLayers` entry (`sourceId: 'lr-geojson'`). The nested map explicitly uses
+`engine="maplibre"`, preserving this viewer's native `maplibre-gl` peer contract independently of
+`lr-map`'s modular default. There is no viewer engine-selection property. When the optional
 `maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lr-json-viewer
-expand-depth="2">` of the raw value instead of the map.
+expand-depth="2">` of the raw value instead of the map. The JSON-viewer fallback is registered
+lazily only when the map peer is unavailable. Loaded documents survive disconnect/reconnect while
+`src` is unchanged; changing `src` reloads the document.
+
+**Large spatial datasets:** `src` remains a bounded GeoJSON document preview; it accepts neither a
+tile manifest nor a catalog provider. For a million-record spatial source, keep records, indexing,
+global counts and identity lookup in a host-owned service and compose a separate
+[`lr-map`](./lr-map.md) with a tiled vector style through `mapStyle`. Query style-owned rendered
+features through that map's public `map` getter, then fetch a bounded selected-feature overlay or a
+deliberately sized GeoJSON preview document. Keep the full source total and preview scope visible
+in the host interface. The preview's feature count describes only the admitted file, and its
+metadata search does not traverse the full spatial service. This composition preserves all file,
+geometry and text guards above.
 
 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
@@ -97,9 +113,10 @@ The canonical tag is registered by importing `components/lr-geojson-viewer.js` (
 `components/viewers/geojson-view/geojson-viewer.js`). The former `components/lr-geojson-view.js`,
 `components/viewers/geojson-view/geojson-view.js` and `geojson-view.class.js` routes were removed
 in 23.0.0. Applications using them to register the viewer must use the canonical tag-shaped route.
-Remote
-resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
-message instead of the map. Lyra supports MapLibre v5 and v6; consumers must import its CSS.
+Remote resources are capped at 4 MiB (4,194,304 bytes) before JSON parsing; exceeding that bound
+surfaces the localized `documentPreviewResourceTooLarge` message instead of the map. Lyra supports
+native MapLibre v5 and v6; consumers must import its CSS and configure that peer before connecting
+the viewer. Installing only `@aceshooting/lyra-map` does not satisfy this viewer's native peer contract.
 MapLibre v5's standard build includes its worker, while v6 is ESM-only, requires WebGL2, and needs
 its module-worker URL configured for the bundler before this viewer constructs the nested map. See
 `llms/components/lr-map.md` for the Vite v6 example and the other bundler variants.

package/llms/components/lr-graph.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [retrieval](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/retrieval.md)
 - **Deprecations** none
 - **Optional peers** `d3-drag`, `d3-force`, `d3-selection`, `d3-zoom` — see `llms/peers.md`
-- **Themeable via** 28 parts, 17 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 33 parts, 17 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`
 
 ---
@@ -18,7 +18,35 @@
 
 A node-link diagram whose default 2D force layout uses `d3-force`. Set `view="3d"` for an
 orbitable perspective view of real x/y/z positions, or `view="list"` for a visible, paginated
-list of all graph items. The 3D and list views require no optional peer.
+list of all admitted graph items. The 3D and list views require no optional peer.
+
+**Complete graph provider:** `graphSource: GraphSource | undefined` (attribute: false)
+takes precedence over `nodes` and `edges`; an invalid defined source fails visibly. Setting
+`undefined` restores the current legacy arrays. `GraphSource` is
+`LyraGraphSource<LyraGraphNode, LyraGraphEdge & { readonly id: string }>`; see the
+[shared graph-source protocol](../shared/events-and-types.md). Record keys are `node:<id>` or
+`edge:<id>`, and source edges require explicit IDs. Reassign the source, even the same object,
+or call `requestUpdate()` to refresh. The global record navigator remains available beside a
+bounded diagram of at most 500 nodes and 1,000 edges, with up to 32 reserved active/focused keys.
+Provider totals describe the complete source; scene coverage is disclosed separately, and
+`fit()` frames only the current scene.
+
+`sourcePage: number = 0` (attribute `source-page`) is the zero-based global record page;
+`sourcePageSize: number = 100` (attribute `source-page-size`) normalizes to 1–500, and changing
+its effective size resets page zero. Readonly `sourceTotal: number | null` reports the exact
+active node/edge query total after a successful current response, or `0` for an empty composed
+filter; otherwise `null` without a current response.
+`revealSourceKey(key: string): Promise<boolean>` clears query filters, uses provider `locate`,
+and reveals and focuses a canonical row without selecting or activating it. It returns false
+when the source/key is invalid or absent, the target row cannot be found after paging, or work
+is superseded.
+
+Spatial rendering and layered layout load only when selected. After changing `view` to a spatial
+view or selecting `layout="layered"`, await `updateComplete` to include that module's loading;
+the existing asynchronous d3 data-readiness contract is unchanged. Node and edge snapshots retain
+the existing 10,000-entry and 50,000-nested-value safety ceilings, so richer records can reach the
+nested-value ceiling earlier. The visible limit notice reports retained and source counts. Narrow
+or aggregate data before binding when the complete graph exceeds admission.
 
 **Spatial view:** `view: LyraGraphView = '2d'` accepts `'2d' | '3d' | 'list'`. Invalid runtime
 values normalize to `'2d'`. The default retains the existing 2D SVG/canvas behavior and adds no
@@ -34,7 +62,7 @@ placement keyed by node id, with genuine z separation. Inputs are never moved or
 `renderer`, `layout`, `chargeStrength`, `edgeDistance` and `seed` have no effect: there is no force
 solver, settling animation, auto-rotation or inertia. Rendering uses original perspective math
 and a Canvas 2D raster surface, with near-plane clipping, depth-ordered node/edge segments and
-frontmost picking. Fixed edge subdivision approximates crossings; this is not a mesh renderer or
+frontmost picking. Adaptive edge subdivision approximates crossings; this is not a mesh renderer or
 a guarantee of perfect translucent intersections. Use modest graphs, typically low hundreds;
 the 2D canvas capacity claim below does not apply to 3D.
 
@@ -188,8 +216,8 @@ boolean; color?: string; dash?: number[] }` (source/target are node ids). `direc
 - `layout: 'force' | 'layered' = 'force'` — `'force'` runs the `d3-force` simulation described
   throughout this section, unchanged. `'layered'` swaps in a deterministic Sugiyama-lite layered
   layout instead (longest-path layering, barycenter crossing reduction, cycle-safe — back edges are
-  reversed only for layering, never mutating caller data): positions are computed synchronously
-  with no settle animation, sized from each node's own radius and spaced by `edgeDistance` (the
+  reversed only for layering, never mutating caller data): after the layout module loads, positions
+  are computed synchronously with no settle animation, sized from each node's own radius and spaced by `edgeDistance` (the
   layer gap) and a fixed 12px in-layer gap. Node drag is disabled in this mode (dragging would fight
   a computed layout) and `chargeStrength` becomes a documented no-op; pan/zoom, keyboard roving,
   `focusNode()`/`fit()`, hulls, edge labels, and `hiddenTypes` filtering all work identically to
@@ -210,6 +238,9 @@ boolean; color?: string; dash?: number[] }` (source/target are node ids). `direc
   only, not the visible marks. Every data-driven and token-derived canvas color is resolved through
   the live computed CSS cascade before painting, so CSS-wide keywords such as `inherit`/`unset`,
   custom-property references, and modern color functions reach Canvas as concrete colors.
+  Prefer this renderer for large admitted graphs. Visual painting is culled to the viewport, and
+  force simulation pauses while the graph is offscreen. SVG cursor movement retains the existing
+  item markup; it does not rebuild every node and link template.
 
 **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
@@ -248,6 +279,10 @@ the offscreen keyboard-roving items), `spatial-toolbar` (3D/list view and camera
 interaction surface), `spatial-instructions` (camera keyboard instructions), `spatial-list` (the
 visible paginated fallback), `spatial-list-item` (each activatable node, edge or community),
 `spatial-page-count` (localized total and page status), and `spatial-pagination` (page controls).
+Source-mode parts: `source-navigator` (global query, record list and pagination), `source-row`
+(a mounted record activation button), `source-row-active` (the navigator's roving tab stop),
+`source-status` (loading, unavailable-record or error text), and `source-coverage` (full-source
+totals and current diagram coverage).
 
 **Themeable custom properties:** `--lr-canvas-reserved-height` (default
 `var(--lr-size-24rem)`) sets the host block size and is shared with the optional pre-upgrade
@@ -278,8 +313,9 @@ behind a drawn `[part="link-label"]` (via `paint-order: stroke`).
 `--lr-graph-hull-fill` (default `var(--lr-color-brand)`) — community hull fill/stroke color
 (overridden inline per hull from `LyraGraphCommunity.color`).
 `--lr-graph-hull-opacity` (default `0.12`) — hull element opacity (composites fill+stroke as one).
-Under `renderer="canvas"` these five are read from computed style at paint time (there are no
-per-node elements to inherit them), so they must be set on or above the `<lr-graph>` host itself.
+Under `renderer="canvas"` these five are resolved from computed style and cached until relevant
+inputs change (there are no per-node elements to inherit them), so they must be set on or above
+the `<lr-graph>` host itself.
 The canvas repaints when inherited theme inputs change (including ancestor class/data attributes,
 adopted stylesheets, and media-query theme transitions); a host does not need to reassign `nodes`
 to make new token values visible.