@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/llms/components/lr-lite-chart.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 20 parts, 23 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 21 parts, 23 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`
 
 ---
@@ -42,6 +42,16 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
 
 **Properties:**
 - `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
+- `maxRecords: number = 1000` (attribute `max-records`) — rendered record budget, normalized to
+  2–1,000; invalid values or a removed attribute use the default. With `preparedData = null`, fit
+  layouts also sample to the measured allocation width; callbacks and events retain original
+  source category indexes, and scroll category widths follow the sampled categories. Prepared
+  input instead uses the global entry and table-cell admission limits described below.
+- `preparedData: LyraChartPreparedData | null = null` (property only) — a bounded whole-source
+  series or category summary. It takes precedence over `labels` and `datasets`; see the prepared
+  route below for original coordinates, activation identities and exact-point lookup. The shared
+  union also names `LyraSpatialChartSource`; lite rejects that kind visibly and has no spatial
+  density, ID-reveal or scatter/bubble route.
 - `labels: readonly string[] = []` (attribute: false)
 - `datasets: readonly LyraLiteChartSeries[] = []` (attribute: false) —
   `LyraLiteChartSeries { readonly label: string; readonly data: readonly (number|null)[];
@@ -65,7 +75,9 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
 - `withoutZeroBaseline: boolean = false` (attribute `without-zero-baseline`) — lets the value axis
   start at the data minimum instead of always including zero.
 - `stacked: boolean = false` — sums each category's bars into one segmented bar instead of grouping
-  them side by side; ignored for `type="line"`
+  them side by side; ignored for legacy `type="line"`. Prepared ordered series reject `stacked`
+  in either chart type because their source indexes are independent; prepared categories retain
+  category stacking.
 - `tickFormat?: (value: number) => string` (attribute: false) — formats a y-axis tick value for
   display (e.g. `(v) => \`$${v.toFixed(2)}\`` for currency, or a duration formatter for `"42s"`).
   Falls back to the built-in "nice numbers" formatter when unset. The returned string is painted
@@ -127,9 +139,9 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   negative values fall back to it, and a finite value is capped so the category run stays within
   1,000,000px.
 - `maxLabels?: number | 'auto'` (attribute `max-labels`) — decimates which category axis labels
-  actually render *text*: after the global record sampler runs, it selects from those retained
-  categories, always shows the first and last sampled label, and roughly evenly distributes the
-  rest between them. A number is authoritative up to the number of sampled categories. `'auto'`
+  actually render *text*: after legacy sampling or prepared-summary admission, it selects from
+  those retained categories, always shows the first and last retained label, and roughly evenly
+  distributes the rest between them. A number is authoritative up to the retained category count. `'auto'`
   re-selects after each resize from the resolved tick positions and the widest rendered caller
   label, using the same deterministic 7px-per-character estimate as label ellipsis. Whenever the
   first and last labels fit side by side, it keeps at least 10px of breathing room between every
@@ -142,8 +154,8 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   It therefore responds to either `layout` mode without DOM text measurement or browser-specific
   font metrics. Unset (the default) renders every label, unchanged. Each rendered category label
   is allocation-aware: narrow/long text is ellipsized before paint, with the complete caller label
-  retained as its accessible name. Independently, the global 1,000-record safety sampler may bound
-  both marks and labels for very large category×series input.
+  retained as its accessible name. With `preparedData = null`, the global 1,000-record safety
+  sampler may independently bound marks and labels for very large category×series input.
 - `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
   per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
   consumer can pixel-align this chart's bars with a sibling `<lr-heatmap>` calendar's week columns
@@ -164,8 +176,9 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   the label alone when unset; no-op while `withLegend` is `false`.
 - `axisLabelText?: (label: string, index: number) => string | null` (attribute: false) — a
   display-only override for one category-axis tick's text; returning `null` renders no tick there at
-  all. `labels` stays the single authoritative source for the generated accessible table's row
-  headers, the per-mark `<title>`/accessible name, the live announcement and CSV export, so blanking
+  all. Effective category labels (`labels` for legacy input, descriptor labels for prepared
+  categories) remain authoritative for table row headers, per-mark `<title>`/accessible names,
+  live announcements and CSV export, so blanking
   a tick never blanks the same category where a reader or a spreadsheet needs it. Complements
   `maxLabels` rather than replacing it: that even decimation is applied FIRST, so a category it
   already dropped never reaches this callback — use this one for ticks that must line up with an
@@ -226,7 +239,8 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   in the bounded rendered sample select matching bars and line points, which receive
   `data-selected` and explicit `aria-pressed="true"`; all other marks render `aria-pressed="false"`.
   For a multi-series chart, a selected source category selects the matching rendered mark in every
-  dataset. Empty is the default.
+  dataset. Empty is the default. For prepared input, these remain plotted indexes (including
+  separator offsets), not original source indexes; use `revealSourcePoint()` for source lookup.
   Style the built-in highlight through `--lr-lite-chart-selected-outline-color` and
   `--lr-lite-chart-selected-outline-width`. Note
   `::part(bar)[data-selected]` and `::part(point)[data-selected]` are **invalid CSS** — Shadow Parts
@@ -235,15 +249,64 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
 - `labels`, `datasets`, and `selectedIndices` are clone-owned, bounded, frozen snapshots. Mutating
   a previously assigned array or nested series data has no effect; create and reassign a new
   collection. `labels` keeps its first 10,000 entries; each series keeps its first 10,000 values,
-  fewer when more than four series share the 45,000-value bound (a development-mode warning reports
-  the trim), so a long series is shortened rather than dropped.
+  fewer when more than four series share the 45,000-value bound, so a long series is shortened
+  rather than dropped. A localized `limit` notice discloses input loss separately from the
+  `data-truncation` rendering notice.
 - `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
   small non-zero values; finite input is capped at 1,000,000px before derived SVG geometry is
   calculated. Authored floors can exceed the available plot height. Linear and logarithmic stacks
   push subsequent segments along their signed pixel cursor; zero values remain unfloored.
 - `appendData(label, values, maxPoints?)` — appends one aligned category and keeps a rolling window
   of the newest `maxPoints` categories, never more than the `datasets` bound above (also the
-  default)
+  default). The immutable window copy remains proportional to the retained window; existing
+  canonical points are not re-admitted. Hidden generated multi-series table formatting coalesces
+  append-only updates during idle, with a 250ms timeout. Visible tables, single-series data lists,
+  keyboard announcements and exports remain immediate. External data, formatter or locale changes
+  and explicit refreshes cancel deferred work. `appendData()` is inactive while `preparedData`
+  is supplied.
+
+**Prepared whole-source data:** use `prepareLyraSeriesData` or `prepareLyraCategoryData` from
+`@aceshooting/lyra-ui/utilities/data-preparation.js`, or supply a compatible bounded descriptor.
+Ordered series support `line` and `bar`; category aggregates support `bar`. The shared descriptor
+contract and validation limits are described under `lr-chart` above. Invalid, incompatible or
+over-budget input shows a localized visible message instead of reading legacy arrays or sampling
+again. `maxRecords` bounds entries across all series, and every line-gap separator costs an entry.
+Ordered-series admission additionally reserves two render entries for an isolating separator and
+one exact point. The 9,000 semantic-sample ceiling includes that one extra observation, and the
+1,000 rectangular-cell ceiling includes the reserved rows across all series. Category aggregates
+use the global entry/cell limits without an exact-point reservation.
+
+Each ordered series retains its own original x coordinates, source indexes and disconnected gaps;
+nonmonotonic x remains in source order. Full x domains drive horizontal positions; full y domains
+drive value geometry and the accessible min/max/trend summary, with the existing value-scale and
+zero-baseline settings. Categorical synchronization,
+`barX` and `barSlotWidth` are inactive for ordered series. Their accessible alternative uses a
+bounded list even with multiple series, naming each observation's original index and x/y values.
+Category input retains the category table/list behavior. The summary reports complete valid and
+invalid observation counts as well as the displayed count.
+
+The host owns the descriptor and reader closures. Reassign `preparedData` (including the same
+identity), or call unnamed `requestUpdate()`, after changing a descriptor or its revision.
+Presentation changes reuse the captured summary. Replacement, explicit refresh, disconnection and
+adoption cancel pending source work and prevent obsolete replies from replacing the current view.
+Setting `preparedData = null` restores the current legacy arrays. Reader closures may retain
+host-owned backing data; component admission does not release that storage.
+
+`revealSourcePoint(ref: LyraSeriesPointRef): Promise<boolean>` looks up an original series ID and
+source index. It may refine a bounded source-index neighborhood through an optional host
+`queryRange`; it never guesses an index from x or scans the full source. The component retains one
+bounded overview and one current refinement/overlay. Pending work exposes busy/loading state;
+invalid replies retain the completed view and show a localized failure. Revealing does not select
+or activate a point. There is no zoom API on this component.
+
+**Events:** Prepared activation additionally emits noncancelable `lr-source-point-select` with
+`LyraChartSourcePointSelectDetail { revision, seriesId, sourceIndex, point: { x, y } }`, or
+noncancelable `lr-source-category-select` with
+`LyraChartSourceCategorySelectDetail { revision, seriesId, categoryId, value, observationCount }`.
+These carry original source identity;
+the existing point/datum events retain plotted-index meaning. Actions on the displayed view stay
+bound to its committed revision while a replacement is pending; obsolete detached marks cannot
+act on the new model.
 
 **Events:** `lr-datum-activate` — canonical family activation with `kind: 'bar'|'point'`,
 `datasetIndex`, `index`, `label`, and `value`. `lr-point-activate` is emitted for the same pointer
@@ -253,10 +316,15 @@ rendered point in two-dimensional screen space; an exact distance tie retains th
 target received the click.
 
 **Methods:** `exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot or the current SVG
-markup. CSV rows cover the canonical record count — the maximum of `labels.length` and every
+markup. With `preparedData = null`, CSV rows cover the canonical record count — the maximum of `labels.length` and every
 `dataset.data.length` — and use empty cells for missing labels/values, so a longer or ragged series
 is never truncated or shifted. The method does not download a file; pair it with
-`lr-export-button` for download UX.
+`lr-export-button` for download UX. Prepared exports synchronously serialize the current bounded
+summary/refinement and start no source reads. Ordered-series CSV keeps the label-plus-series
+column schema: each observation gets a row labelled with its original index and localized x/y
+coordinates, a value in its own series column, and empty cells for other series. `skipZero` may
+hide a zero bar but does not omit that admitted value from CSV. SVG exports the current rendered
+view. Complete raw-source export remains host-owned.
 
 Axis titles retain their complete `xLabel`/`yLabel` values and accessible names. In the browser,
 visible titles fit their plot allocation using the rendered SVG font; long titles end with an
@@ -273,33 +341,30 @@ anchoring keeps working correctly under RTL without inverting which rendered cat
 keyword. Built-in mark summaries are complete localized templates and format values with
 `effectiveLocale`.
 
-**Performance:** `render()` recomputes the grid/marks on every update rather than memoizing against a
-content signature — `datasets`/`labels` can hold callbacks (`tickFormat`, `barX`) or arbitrary,
-possibly circular or BigInt-bearing application data that a fingerprint can't serialize safely, so a
-fresh, small SVG render is cheaper and more correct than a lossy cache. The shared sampling path
-keeps that render bounded to 1,000 category×series marks/keyboard records, retaining endpoints
-instead of materializing an unbounded hidden DOM or SVG tree. The sample is evenly spaced, not
-extreme-preserving, while the value axis still spans the complete data: a line can stop short of
-the axis maximum when the spike that set it falls between samples. Pre-aggregate (for example a
-minimum and maximum per bucket) when every spike must be drawn.
+**Performance:** focus movement patches the active marks without rebuilding the SVG. Derived table
+content reuses canonical input identity; arbitrary formatter callback results are not cached by a
+serialized content fingerprint. With `preparedData = null`, the shared sampling plan bounds marks, keyboard records and
+generated alternatives by `maxRecords`, retaining endpoints and bucket extrema within the available
+budget. Fit layouts also use allocation width. The value axis still spans admitted data; a finite
+sample cannot retain every extremum from arbitrarily many series, so pre-aggregate when every spike
+must be represented.
 
 **Slots:** `data-table` — optional consumer-provided complete, paginated, or virtualized accessible
 data alternative.
 
-**CSS parts:** `base`, `description`, `grid-line`, `axis-label`, `axis-title`,
+**CSS parts:** `base`, `description` (accessible summary and visible prepared loading/error text), `grid-line`, `axis-label`, `axis-title`,
 `sync-crosshair` (decorative synchronized category line), `sync-tooltip` (noninteractive positioned
 text tooltip while `syncGroup` is active), `bar` and `point` (each carries
 `data-selected` when its category index is in `selectedIndices`, with explicit pressed state on every
 mark), `line`, `legend`, `legend-item`, `legend-swatch`, `legend-text` (extra per-item text after
 the series label, rendered only when `legendText` is set), `live-region` (the current mark
 announcement for keyboard users), `data-list` (a visually hidden sampled list of plotted data
-points — single-series only), `data-table` (the generated/slotted alternative container),
+points — single-series legacy/category input or any prepared ordered series), `data-table` (the generated/slotted alternative container),
 `data-table-toggle` (the `dataTableToggle` disclosure button), `table`
-(the generated semantic category×series table rendered when there is more than one dataset), and
-`data-truncation` (the
-visible/announced sampling notice).
+(the generated semantic category×series table for multi-series legacy/category input), and
+`data-truncation` (the visible/announced sampling notice), and `limit` (the input-admission notice).
 
-**Screen-reader data alternative:** a single dataset renders the flat `data-list` (one `<li>` per
+**Screen-reader data alternative (legacy or prepared categories):** a single dataset renders the flat `data-list` (one `<li>` per
 plotted point, matching the roving-tabindex mark order). More than one dataset instead renders a
 `data-table` — a category-labelled `<caption>` (the shared localized `chartData` string), one
 `<th scope="col">` per series (plus a leading `chartCategory` corner header), and one
@@ -309,7 +374,7 @@ Finite table cells use `tableCellFormatter` when supplied and otherwise use the
 effective locale. A stacked multi-series bar chart with `tableTotals` adds a localized total
 column; null/non-finite inputs are skipped, while an all-missing category leaves the total cell
 blank instead of reporting a misleading zero. Built-in SVG marks, keyboard targets, and this data
-alternative share one endpoint-preserving sample of at most 1,000 category×series records. When
+alternative share the same endpoint/extremum sample bounded by `maxRecords`. When
 sampling occurs, a localized `data-truncation` notice is shown and announced; provide
 `slot="data-table"` for a complete paginated, virtualized, or application-owned alternative, which
 suppresses the generated sample; the notice then says only the plot is sampled.

package/llms/components/lr-locale-picker.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 17 parts, 25 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 18 parts, 25 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`
 
 ---
@@ -47,8 +47,10 @@ readonly LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string; cou
   the derived `localeNativeName(tag)` endonym only when it is non-blank; an explicitly blank (or
   whitespace-only) `label` is treated the same as an omitted one and still falls back to
   `localeNativeName(tag)`. Explicit catalogs are
-  capped, cloned and frozen at assignment; mutate a new array/entry and reassign it to update the
-  list. `country` (ISO 3166-1 alpha-2 or alpha-3) overrides a row's derived flag — e.g.
+  capped at the first 512 source entries, cloned and frozen at assignment; mutate a new array/entry
+  and reassign it to update the list. The localized `limit` part reports omitted input through
+  `localePickerInputLimit`. Closed listboxes contain no option rows after their exit transition;
+  the trigger still resolves the selected label. `country` (ISO 3166-1 alpha-2 or alpha-3) overrides a row's derived flag — e.g.
   showing Lebanon's flag for an `'ar'` row instead of the library's default Saudi Arabia mapping;
   only available on the `{tag,label,country}` object form, not the bare `string[]` form. Replacing
   the catalog while the listbox is open keeps keyboard navigation valid: an active row beyond the
@@ -191,7 +193,7 @@ priority until cleared.
 
 **Slots:** `label`, `hint`, `error`.
 
-**CSS parts:** `form-control`, `form-control-label`, `trigger`,
+**CSS parts:** `limit` (input-loss notice), `form-control`, `form-control-label`, `trigger`,
 `trigger-flag` (the trigger's leading `<lr-flag>` for the current value, present only while
 `withoutFlags` is off and `triggerDisplay` is not `label`), `trigger-label` (the current language,
 visually hidden in flag-only mode), `listbox`, `option`, `option-flag` (present only while `withoutFlags` is off),

package/llms/components/lr-map.md

@@ -23,6 +23,31 @@ plus a peer-neutral `map` getter for common imperative operations. Its runtime v
 underlying MapLibre map. The component observes its own map-container allocation and calls the
 peer's `resize()` when that allocation changes.
 
+**Large spatial sources:** a catalog of a million logical geospatial records can stay in a
+host-owned spatial service. Supply a hosted vector style URL, or a style object with vector tile
+sources and layers, through `mapStyle`; the selected peer requests and renders tiles for the
+viewport. The host owns durable records, spatial indexing, identity lookup, global bounds and
+total counts. Keep those totals beside the map: a rendered-feature query describes the current
+viewport, not the complete catalog. Tile density, zoom range and service response sizes remain
+application decisions. This route does not require a million-feature inline GeoJSON collection.
+
+Configure the selected engine's worker before constructing the map, as described below. For a
+custom tile protocol, register `addProtocol()` from that same engine package before assigning a
+style that uses its scheme (`@aceshooting/lyra-map` for the default, `maplibre-gl` for explicit
+`engine="maplibre"`). The host protocol handler supplies real tile bytes and owns its transport,
+authorization and cancellation. Remove registrations with `removeProtocol()` when no remaining
+map uses them. A protocol registration is peer setup, not an `lr-map` provider property.
+
+Use bounded `dataLayers` for changing selections or local overlays fetched by identity or spatial
+query. Only the first 100 descriptors are inspected, and `markers` inspects at most 2,000 entries;
+neither is a complete catalog browser. Stable unique feature IDs allow
+`updateSourceData(sourceId, diff)` to update an applied generated GeoJSON source without replacing
+the whole collection. Check its boolean result and retain the host's authoritative state; a later
+controlled `dataLayers` assignment replaces imperative changes. Opaque GeoJSON handoff and
+uncloned diffs avoid a Lyra deep copy, while the peer still parses, indexes, transfers and caches
+data. The tile cache belongs to the peer; bounded wrapper DOM does not establish a bound on worker
+heap or guarantee constant rendering cost as the source grows.
+
 Markers and popups use the physical top-left origin required by MapLibre's projected transforms in
 both LTR and RTL. Their text and surrounding controls retain logical direction-aware layout.
 
@@ -195,7 +220,9 @@ string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, strin
 - `markers: LyraMapMarker[] = []` (attribute: false) — `LyraMapMarker { id?: string; lngLat:
 [number, number]; color?: string; label?: string; unsafeHtml?: string }`; an explicit `id` is
   trimmed and must be nonempty, and the first successfully admitted marker for an explicit ID wins.
-  A malformed earlier row does not reserve that ID. Markers are reconciled
+  Only the first 2,000 authored entries are inspected; `markersTruncated` reports an omitted
+  suffix. Use clustered `dataLayers` for larger point collections. A malformed earlier row does
+  not reserve that ID. Markers are reconciled
   by that explicit ID (falling back
   to a `lng,lat` key, disambiguated by occurrence order for duplicate-coordinate id-less markers,
   when `id` is omitted) so an unchanged marker isn't torn down and recreated on every `markers`
@@ -206,12 +233,14 @@ string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, strin
   escaped) when the content is plain text. For marker/popup naming, visible text is extracted from
   trusted markup while `script`, `style`, `template`, `[hidden]`, and `aria-hidden="true"` subtrees
   are excluded; an explicitly supplied `label` remains the more predictable accessible name. A
-  marker whose `color` changes for a persisting `id`
+  marker whose authored `color` changes for a persisting `id`
   can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
   gotchas. Entries with non-finite coordinates, latitude outside `[-90, 90]`, or a runtime
   non-string `label` are skipped without aborting valid siblings. `color` is used only when the
   browser accepts it as CSS `color`;
-  declaration breaks and `url()` paint servers fall back to MapLibre's default marker color.
+  declaration breaks and `url()` paint servers fall back to the default color. Without an authored
+  color, markers follow `--lr-color-brand` through CSS `currentColor`; rethemes preserve marker and
+  popup identity, including an open popup. Explicit authored color changes still reconstruct markers.
   Every retained marker is a named `role="button"` tab stop, including one without a popup. Click,
   Enter, and Space emit `lr-map-marker-activate`; Space suppresses its page-scroll default while
   preserving MapLibre's popup toggle. A popup-bearing marker additionally exposes
@@ -222,7 +251,8 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
 'danger' | 'neutral'; color?: string; strokeColor?: string; line?: LyraMapLineOptions;
 point?: LyraMapPointOptions; kind?: LyraMapDataLayerKind;
 heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId` is trimmed and must be nonempty; the first layer for a
-  `sourceId` that is successfully admitted wins; blank, malformed, and later duplicate records are
+  `sourceId` that is successfully admitted wins. Only the first 100 entries are inspected; blank,
+  malformed, and later duplicate records are
   ignored without reserving an identity for a valid later sibling. Each retained entry adds one
   GeoJSON source plus three geometry-filtered layers
   (fill, line, and circle, so a mixed `FeatureCollection` renders correctly), colored from the
@@ -253,6 +283,12 @@ heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId`
   The component snapshots the configuration it reads. It passes `choropleth.geojson` and
   `dataLayers[].geojson` through to MapLibre; assign a new `choropleth`, `dataLayers`, or `markers`
   value after changing configuration, because mutating an assigned value is not observed.
+  For an in-place change to pass-through GeoJSON, call `requestUpdate()` explicitly to refresh its
+  comparison snapshot. This refresh still applies when coalesced with a named presentation update.
+  Changed geometry or bounding boxes replace the peer source data. For comparable feature
+  collections, unchanged snapshots avoid a redundant write; eligible property-only changes keep
+  the incremental update path. A refreshed standalone feature or over-limit collection uses a
+  full replacement even when its data is unchanged.
 
   `cluster` and `kind` (both new in 12.0.0) opt one entry out of that three-layer geometry split.
   **Both are strictly additive: an entry that sets neither renders exactly what it rendered before,
@@ -436,8 +472,12 @@ features keep semantically unchanged geometry/bbox values, the component emits M
 incremental `updateData()` for property changes, additions, removals, and order changes. The exact
 next order is preserved: an unchanged prefix stays in place and only the invalidated suffix is
 removed and re-added. Lyra snapshots control and projection data while retaining opaque GeoJSON
-identity at the MapLibre boundary; a bounded, accessor-free comparison verifies the JSON geometry
-graph instead. A missing/duplicate ID, changed geometry, exceeded bound, or uncertain
+identity at the MapLibre boundary. Immutable admitted geometry and bbox identities reuse their
+validated comparison projections; replace those identities when their contents change. Otherwise,
+a bounded, accessor-free comparison verifies the JSON geometry graph. Automatic comparison
+supports at most 10,000 features, with a work budget of at least 50,000 values or 4,096 values per
+feature, whichever is larger, capped at 10,000,000 values. A missing/duplicate ID, changed geometry,
+exceeded bound, or uncertain
 comparison falls back to `setData()` with no change in rendered behaviour. Peers without
 `updateData()` always take the old path.
 
@@ -463,7 +503,8 @@ payload beside the map.
 `LyraMapPointRadiusInterpolation`, `LyraMapPointIcon`, `LyraMapPointIconMode`,
 `LyraMapPointIconLineCap`, `LyraMapPointIconLineJoin`, `LyraMapMarker`, `LyraMapMarkerActivationDetail`,
 `LyraMapMarkerActivationSource`, `LyraMapLegendToggleDetail`, `LyraMapLegendPanelToggleDetail`,
-`LyraMapStyleSpecification`, `LyraMapEngine`, `LyraMapFeatureRequirements`, and `LyraMapInstance`.
+`LyraMapStyleSpecification`, `LyraMapEngine`, `LyraMapFeatureRequirements`, `LyraMapSourceDataDiff`,
+and `LyraMapInstance`.
 
 **Getters:** `map: LyraMapInstance | undefined` → the underlying runtime `maplibregl.Map`, exposed
 through the peer-neutral `getCanvas()`, `getCenter()`, `getZoom()`, `setCenter()`, `setZoom()`, and
@@ -473,6 +514,15 @@ value to the selected engine's `Map` type. `LyraMapInstance.prepareFeatures?()`
 modular engine and absent on canonical MapLibre, so guard it or narrow to the companion `Map`
 before calling. Identity is preserved: `.map` is the engine instance, not a proxy.
 
+After `lr-map-load`, use the narrowed peer's `queryRenderedFeatures(point, { layers: [...] })`
+for identities painted by style-owned vector layers; `point` is a screen position, which can be
+obtained with the peer's `project([longitude, latitude])`. Attach peer interaction listeners when
+the host needs those layers' hits. `lr-map-click` queries only the component-generated choropleth
+and `dataLayers` layers described below; it does not query arbitrary layer IDs from `mapStyle`.
+
+`markersTruncated: boolean` (read-only) is true when authored marker entries exceed the 2,000-entry
+inspection ceiling; it does not count malformed rows skipped within that prefix.
+
 The modular engine automatically prepares initial and replacement style requirements, including
 projection and terrain. `<lr-map>` additionally awaits per-map main-thread and worker readiness
 before adding generated choropleth or `dataLayers` sources and layers. New heatmap, clustering, and
@@ -491,6 +541,15 @@ optional-peer import without constructing a map or allocating a WebGL context. P
 for an explicitly native element. It resolves to `false` when the selected peer is unavailable,
 allowing an application to choose a fallback before connecting an element.
 
+`updateSourceData(sourceId: string, diff: LyraMapSourceDataDiff): boolean` forwards a caller-authored
+incremental GeoJSON diff to an applied `dataLayers` or choropleth public `sourceId`. It returns
+`false` before the source is ready, after disconnect, for an unknown source, or when the engine
+lacks `updateData()`. Feature IDs must be stable and unique; the caller owns diff validity. The
+diff is forwarded without cloning, and peer exceptions propagate. It does not change the controlled
+properties. Automatic comparison history is invalidated before forwarding, so a later controlled
+GeoJSON reassignment replaces the imperative state in full. Use this route for changes beyond the
+automatic comparison ceiling.
+
 `fitBounds(bounds: LyraMapBounds, options?: LyraMapFitBoundsOptions): boolean` frames a box
 `[[west, south], [east, north]]` in the viewport: the way to show every current marker, or a
 selected region, whenever the data set changes. Use it instead of calling the peer's own
@@ -820,7 +879,7 @@ undefined`, or changing `choropleth.sourceId` to a different value, now calls `r
 - Ancestor theme-attribute and custom-property changes repaint the already-applied choropleth and
   data-layer colors/opacities in place. This does not recreate MapLibre sources/layers, replace the
   style, or reset the current viewport.
-- a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
+- a marker whose authored `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
   `Marker` has no `setColor()`) rather than mutated in place — this also closes any popup the user
   currently has open on that marker (a fresh, closed `Popup` is built for the new instance); an
   accepted side effect of the reconstruction fallback, not a bug.

package/llms/components/lr-markdown-core.md

@@ -18,10 +18,10 @@
 
 A build-lean sibling of `<lr-markdown>` above, for a consumer whose `languages` map already covers
 every language it will ever render — mirrors `<lr-code-block-core>`'s relationship to
-`<lr-code-block>`. Where `<lr-markdown>` unconditionally calls `loadShikiHighlighter()` — the
-default ~200-language dynamic-import table loader, whose bundled lookup table a bundler can't
-statically narrow away —
-this component's own module never imports or calls that function at all; it only ever calls
+`<lr-code-block>`. The full `<lr-markdown>` module references `loadShikiHighlighter()` for languages
+absent from its explicit map. That loader includes the default ~200-language dynamic-import table,
+whose bundled lookup table a bundler cannot statically narrow away.
+This component's own module never imports or calls that function; it only calls
 `loadShikiHighlighterCore(languages)`, so a consumer importing this entry point instead of
 `markdown.js` gets a build genuinely free of shiki's full language table.
 
@@ -43,6 +43,10 @@ support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highligh
 `htmlMode`/streaming fallback matrix and known gotchas — is identical to `<lr-markdown>`; see that
 section above for the full write-up of shared behavior.
 
+During progressive streaming, the complete plain-text tail stays in the DOM; its offscreen height
+is estimated until revealed, so the scroll extent can adjust as pending text comes into view or
+becomes settled Markdown.
+
 **Properties:** `content: string = ''`, `tabSize: number = 4` (attribute `tab-size`) — the same
 finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; finite values are
 clamped to `[1, 32]` (`0` becomes `1`, `33` becomes `32`), and only non-finite values (`NaN`,
@@ -55,7 +59,7 @@ instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'e
 `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected),
 `codeBlockHeader: boolean = false` (attribute `code-block-header`),
 `withoutSyntaxHighlighting: boolean = false` (attribute `without-syntax-highlighting`),
-`languages: Record<string, ShikiLanguageSource> = {}` (attribute: false) —
+`languages: Readonly<Record<string, ShikiLanguageSource>> = {}` (attribute: false) —
 required, unlike `<lr-markdown>`'s optional `languages?:`; empty (the default) means every fenced
 block stays unhighlighted permanently. Each value is either an already-resolved grammar or a lazy
 loader (`() => Promise<ShikiLanguageInput | { default: ShikiLanguageInput }>`, e.g.
@@ -70,6 +74,7 @@ The same 1,000,000-code-unit/20,000-node corpus ceiling, 4,096-code-unit quote-f
 4,000,000-code-unit work ceiling, 10,000-record admission ceiling, 1,000-candidate window, and
 100-painted-highlight limit documented for `<lr-markdown>` apply here too, including active-first
 retention from anywhere in the admitted snapshot.
+The same syntax-highlighting admission, source-size and cache bounds documented above also apply.
 
 **Methods:** `renderMarkdown(): void` — immediately reruns the current content through the parse,
 sanitize, highlight, and fallback pipeline after changing this instance's `marked` configuration;

package/llms/components/lr-markdown.md

@@ -116,7 +116,10 @@ uses for its own `[part="body"]`.
   use plain streaming; inline extensions and renderer overrides remain supported. A text tail
   follows the surrounding direction, while its open-fence preview uses code direction. Work is
   bounded per animation frame; after 2,000 settled groups the remaining source stays plain until
-  completion. Large code blocks defer highlighting until completion.
+  completion. Large code blocks defer highlighting until completion. The offscreen plain-text tail
+  uses native rendering containment: its complete text stays in the DOM, but its height is estimated
+  until it is revealed, then remembered by the browser. The scroll extent can adjust as pending text
+  comes into view or becomes settled Markdown. This applies to both Markdown variants.
   Known limits of progressive mode: an in-progress list or table stays plain text until another
   block follows it (and a code fence inside it reads in page direction until then); raw HTML or a
   consumer renderer override that leaves an element open, and a reference definition whose title is
@@ -136,14 +139,18 @@ uses for its own `[part="body"]`.
   the header also removes authored style elements and their CSS text to prevent visual copy
   deception. Trusted mode provides no such guarantee.
 - `withoutSyntaxHighlighting: boolean = false` (attribute `without-syntax-highlighting`) — turns off
-  fenced-code syntax highlighting. Unset (the default), every fenced block is upgraded via the
+  fenced-code syntax highlighting. Unset (the default), eligible fenced blocks are upgraded via the
   optional `shiki` peer once it is available; set it to keep plain output even when `shiki` is
   installed. In progressive mode, a block can be highlighted after it settles; the mutable tail
   remains unhighlighted.
-- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — same shape and purpose as
-  `<lr-code-block>`'s own `languages`: a fine-grained, explicit language-grammar bundle scoping
-  shiki's build output to just those grammars instead of its full ~200-language bundle. Forwarded
-  verbatim to `loadShikiHighlighterCore()`. Unset (the default) uses the default full-bundle loader
+- `languages?: Readonly<Record<string, ShikiLanguageInput>>` (attribute: false) — explicit
+  resolved grammars. Languages absent from both this map and `languageLoaders` use the full
+  loader's built-in fallback. Replace the map identity when changing its grammars.
+- `languageLoaders?: Readonly<Record<string, ShikiLanguageLoader>>` (attribute: false) — lazy
+  grammars such as `{ json: () => import('shiki/langs/json.mjs') }`. Only a matching fenced
+  language invokes its loader; concrete `languages` entries take priority on duplicate keys.
+  Unset preserves concrete-grammar readback and the default loader. Assign a new map object after
+  edits; changing either map invalidates pending highlights and isolates cached output.
 - `headingAnchors: boolean = false` (attribute `heading-anchors`) — stamps a computed
   GitHub-slugger-style slug as `id` on every rendered heading.
 - `math: boolean = false` — renders `$inline$` and `$$block$$` TeX via the optional `katex` peer,
@@ -170,6 +177,16 @@ pass. It reuses that index across navigation and painting. Host-highlight admiss
 1,000 candidates and paints at most 100, with an active entry anywhere in the admitted snapshot
 placed first and preserved inside both ceilings.
 
+Syntax highlighting admits the first 100 distinct language/code pairs in a document, or across a
+progressive session. Each eligible block is limited to 8,192 UTF-16 code units, including its
+terminal newline. Later or larger blocks remain readable plain code. Both Markdown tags share a
+content-addressed cache, partitioned by the supplied `languages` map identity, with at most 100
+entries and 2 MiB of retained key/output storage (two bytes per UTF-16 code unit); each entry is
+limited to 512 KiB. Matching authored grammars share cached output across the full and core tags;
+full-tag fallback languages do not populate the core tag's cache. When highlighted output exceeds
+the byte budget, evicted blocks may remain plain instead of repeatedly tokenizing. Plain streaming
+defers highlighting until completion; progressive streaming highlights settled blocks.
+
 **Methods:**
 
 - `renderMarkdown(): void` — immediately reruns the current content through the parse, selected

package/llms/components/lr-mention-popover.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 7 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 8 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`
 
 ---
@@ -18,7 +18,7 @@
 
 The `more-results` CSS part exposes the additional-results message.
 
-Suggestion listboxes follow the [shared surface treatment](shared/styles-and-tokens.md);
+Suggestion listboxes follow the [shared surface treatment](../shared/styles-and-tokens.md);
 the caller-owned message field retains its fill.
 
 A caret-anchored, keyboard-navigable popover for `@`-mention and `/`-slash-command autocomplete
@@ -43,7 +43,9 @@ preserving null readback; an explicitly empty query remains empty.
   plain `<textarea>` or single-line text `<input type="text"|"search">` gets caret-precise
   positioning; any other element anchors the whole popup under that element's own box.
 - `items: readonly Readonly<LyraMentionItem>[] = []` (attribute: false) — the full candidate set,
-  pre-`query`-filtering. Assignment takes a shallow frozen snapshot. Runtime rows without a string
+  pre-`query`-filtering. Assignment admits the first 10,000 array positions into a shallow frozen
+  snapshot; `items` readback exposes that admitted prefix. Additional input is omitted with a
+  localized notice in `part="limit"`. Runtime rows without a string
   `label` remain in that diagnostic snapshot but are omitted from filtering/rendering before the
   built-in or custom predicate runs, so one malformed provider row cannot take down valid siblings.
   An entry's `disabled` marks that row non-actionable: `aria-disabled="true"` replaces its
@@ -55,7 +57,8 @@ preserving null readback; an explicitly empty query remains empty.
   (see `filter`).
 - `open: boolean = false` (reflected)
 - `filter: LyraMentionFilter | null = null` (attribute: false) — overrides the built-in
-  case-insensitive `label`/`description` substring match entirely.
+  case-insensitive `label`/`description` substring match entirely. Replacing `items` refreshes
+  candidate search text; an explicit `requestUpdate()` refreshes a filter whose closure changed.
 - `emptyText?: string` (attribute `empty-text`) — `undefined` uses localized `noMatches`; every
   supplied string, including `''` and `'No matches'`, is caller-owned
 - `label?: string` — accessible name for the `role="listbox"` popup. `undefined` uses localized
@@ -67,7 +70,8 @@ preserving null readback; an explicitly empty query remains empty.
   filtered by `query` via `filter` (or the built-in default). An empty `query` skips the query
   predicate but still omits malformed-label rows. This getter retains every match; the popup
   renders and navigates the first 50, then adds a localized, non-option count of remaining matches
-  as the listbox description.
+  as the listbox description. This visible-match limit is separate from source admission. Closed
+  popups contain no suggestion rows after their exit transition settles.
 - `activeDescendantId: string | null` — read-only getter; the `id` of the currently-highlighted
   internal row, or `null` while closed or when `filteredItems` is empty. Useful for diagnostics and
   same-tree consumers; do not copy it to an external control as a string IDREF.
@@ -115,7 +119,8 @@ renders `open="false"` on first paint)
 
 **CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
 `option-description` (when `description` is set), `empty`, `more-results` (the localized count
-shown when more suggestions match than the list renders).
+shown when more suggestions match than the list renders), and `limit` (localized notice when
+source admission omits candidates).
 
 **Themeable custom properties:** `--lr-mention-popover-option-active-bg` (default
 `var(--lr-color-brand-quiet)`) — background of the hovered or `[data-active]`