@aceshooting/lyra-ui 29.0.2 → 29.1.0

package/dist/units.js

@@ -1 +1 @@
-import{getNumberFormat}from"./internal/intl-cache.js";import{snapshotSelectionCatalog}from"./internal/selection-catalog.js";const unitCodes=["acre","bit","byte","celsius","centimeter","day","degree","fahrenheit","fluid-ounce","foot","gallon","gigabit","gigabyte","gram","hectare","hour","inch","kilobit","kilobyte","kilogram","kilometer","liter","megabit","megabyte","meter","microsecond","mile","mile-scandinavian","milliliter","millimeter","millisecond","minute","month","nanosecond","ounce","percent","petabyte","pound","second","stone","terabit","terabyte","week","yard","year"],UNIT_CODES=Object.freeze(unitCodes),unitNames=new Map;function unitNamesFor(locale,code){const key=`${locale}\0${code}`;let names=unitNames.get(key);if(!names){let name=code,symbol=code;const part=unitDisplay=>getNumberFormat(locale,{style:"unit",unit:code,unitDisplay}).formatToParts(1).filter(entry=>entry.type==="unit").map(entry=>entry.value).join("")||code;try{name=part("long"),symbol=part("short")}catch{}unitNames.size>=1024&&unitNames.clear(),unitNames.set(key,names=[name,symbol])}return names}function resolveUnitNames(units,locale){const entries=snapshotSelectionCatalog(units,code=>code.trim())??[];return Object.freeze(entries.map(entry=>{const[name,symbol]=unitNamesFor(locale,entry.code),label=entry.label??name;return Object.freeze({...entry,label,symbol:entry.symbol??symbol,searchText:[entry.code,name,label,symbol,entry.symbol??""].join(" ")})}))}export{UNIT_CODES,resolveUnitNames};
+import{getNumberFormat}from"./internal/intl-cache.js";import{snapshotSelectionCatalog,normalizeSelectionValue}from"./internal/selection-catalog.js";const unitCodes=["acre","bit","byte","celsius","centimeter","day","degree","fahrenheit","fluid-ounce","foot","gallon","gigabit","gigabyte","gram","hectare","hour","inch","kilobit","kilobyte","kilogram","kilometer","liter","megabit","megabyte","meter","microsecond","mile","mile-scandinavian","milliliter","millimeter","millisecond","minute","month","nanosecond","ounce","percent","petabyte","pound","second","stone","terabit","terabyte","week","yard","year"],UNIT_CODES=Object.freeze(unitCodes),unitNames=new Map;function unitNamesFor(locale,code){const key=`${locale}\0${code}`;let names=unitNames.get(key);if(!names){let name=code,symbol=code;const part=unitDisplay=>getNumberFormat(locale,{style:"unit",unit:code,unitDisplay},!1).formatToParts(1).filter(entry=>entry.type==="unit").map(entry=>entry.value).join("")||code;try{name=part("long"),symbol=part("short")}catch{}unitNames.size>=1024&&unitNames.clear(),unitNames.set(key,names=[name,symbol])}return names}function resolveUnitNames(units,locale){const entries=snapshotSelectionCatalog(units,normalizeSelectionValue)??[];return Object.freeze(entries.map(entry=>{const[name,symbol]=unitNamesFor(locale,entry.code),label=entry.label??name;return Object.freeze({...entry,label,symbol:entry.symbol??symbol,searchText:[entry.code,name,label,symbol,entry.symbol??""].join(" ")})}))}export{UNIT_CODES,resolveUnitNames};

package/dist/utilities/data-preparation.d.ts

@@ -0,0 +1,56 @@
+import type{LyraSourceRevision}from'../data-sources.js';export type LyraSourceValue<T> =T|PromiseLike<T>;export interface LyraSourceRequest{readonly signal:AbortSignal;}
+/**
+* Immutable, replayable source positions. Count is a safe nonnegative integer. Each read returns
+* an array of exactly the requested size (at most 8,192); holes remain invalid positions, and
+* non-array/short/long responses reject. Revision and payload must stay unchanged while reading.
+* Source-owned storage is never copied wholesale. Observed count/revision changes reject.
+*/
+export interface LyraIndexedInput<T>{readonly revision:LyraSourceRevision;readonly count:number;read(start:number,count:number,request:LyraSourceRequest):LyraSourceValue<readonly T[]>;}
+/**
+* Preparation inspects all positions in chunks, default 2,048, clamped to 1–8,192. Chunk sizes
+* must be positive safe integers. Tasks yield between chunks and abort before/after each await
+* and before publication. Reader/selector exceptions reject; results are deeply immutable.
+*/
+export interface LyraPreparationOptions{readonly signal?:AbortSignal;readonly batchSize?:number;}export interface LyraObservationCounts{readonly sourceCount:number;readonly validCount:number;readonly invalidCount:number;}export interface LyraNumericDomain{readonly min:number;readonly max:number;}export interface LyraSeriesObservation{readonly x:number;readonly y:number|null;}export interface LyraSeriesSample extends LyraSeriesObservation{readonly sourceIndex:number;readonly breakBefore:boolean;}export interface LyraPreparedSeries{readonly id:string;readonly label:string;readonly counts:LyraObservationCounts;readonly xDomain:LyraNumericDomain|null;readonly yDomain:LyraNumericDomain|null;readonly samples:readonly LyraSeriesSample[];}export interface LyraSeriesRangeRequest extends LyraSourceRequest{readonly seriesId:string;readonly startIndex:number;readonly endIndex:number;readonly maxPoints:number;}export interface LyraSeriesPointRef{readonly seriesId:string;readonly sourceIndex:number;}export interface LyraPreparedSeriesData{readonly kind:'series';readonly revision:LyraSourceRevision;readonly series:readonly LyraPreparedSeries[];getPoint(ref:LyraSeriesPointRef,request:LyraSourceRequest):LyraSourceValue<LyraSeriesObservation|null>;queryRange?(request:LyraSeriesRangeRequest):LyraSourceValue<readonly LyraSeriesSample[]>;}export interface LyraPreparedCategoryData{readonly kind:'categories';readonly revision:LyraSourceRevision;readonly counts:LyraObservationCounts;readonly categories:readonly{readonly id:string;readonly label:string;}[];readonly categoryCounts:readonly number[];readonly series:readonly{readonly id:string;readonly label:string;readonly values:readonly number[];}[];readonly aggregation:'count'|'sum'|'mean'|'host-defined';}export interface LyraHistogramDistribution{readonly revision:LyraSourceRevision;readonly counts:LyraObservationCounts;readonly domain:LyraNumericDomain|null;readonly edges:readonly number[];readonly binCounts:readonly number[];readonly belowCount:number;readonly aboveCount:number;}export interface LyraWeightedWord{readonly id:string;readonly text:string;readonly weight:number;}export interface LyraPreparedWordCloud{readonly revision:LyraSourceRevision;readonly counts:LyraObservationCounts;readonly totalWeight:number;readonly retainedWeight:number;readonly words:readonly LyraWeightedWord[];}export interface LyraPreparedWaveform{readonly revision:LyraSourceRevision;readonly counts:LyraObservationCounts;readonly sampleCount:number;readonly duration:number;readonly buckets:readonly{readonly startIndex:number;readonly endIndex:number;readonly maxAmplitude:number;}[];readonly firstAmplitude:number|null;readonly lastAmplitude:number|null;}
+/**
+* Prepares an extrema-preserving overview, not an exact reconstruction. All observations are
+* inspected in bounded, yielding chunks. Invalid positions remain gaps; x is never renumbered.
+* Budgets default to 500 points per series, require at least 4, and clamp to 1,000. Requested
+* aggregate capacity must fit 9,000 samples (45,000 snapshot nodes at five nodes per sample).
+* IDs are nonblank and at most 256 code units; labels at most 1,024, with 65,536 combined units.
+* Inputs must share one immutable revision. The returned handle intentionally retains their
+* readers/backing storage for exact one-position getPoint reads; it does not implement queryRange.
+*/
+export declare function prepareLyraSeriesData(series:readonly{readonly id:string;readonly label:string;readonly input:LyraIndexedInput<LyraSeriesObservation>;}[],options?:LyraPreparationOptions&{readonly maxPointsPerSeries?:number;}):Promise<LyraPreparedSeriesData>;
+/**
+* Reduces every source position into at most 1,000 declared categories and one result series.
+* Unknown/null categories and nonfinite sum/mean values are invalid, unless an unknown ID maps
+* to the declared Other category. Empty categories have value zero. Means use sums/counts;
+* overflowing finite sums reject. IDs/labels use the same bounds as series preparation.
+* Sum/mean require an own numeric valueOf callback; count ignores valueOf entirely.
+* Selectors must be synchronous scalar functions; their arbitrary computation cost is caller-owned.
+*/
+export declare function prepareLyraCategoryData<T>(input:LyraIndexedInput<T>,options:LyraPreparationOptions&{readonly categories:readonly{readonly id:string;readonly label:string;}[];readonly seriesId:string;readonly seriesLabel:string;readonly categoryOf:(value:T,sourceIndex:number)=>string|null;readonly otherCategoryId?:string;}&({readonly aggregation:'count';readonly valueOf?:(value:T,sourceIndex:number)=>unknown;}|{readonly aggregation:'sum'|'mean';readonly valueOf:(value:T,sourceIndex:number)=>number|null;})):Promise<LyraPreparedCategoryData>;
+/**
+* Builds an exact full-source distribution: half-open bins, with an inclusive last upper edge.
+* Explicit finite increasing edges use one pass; automatic bins use two replayable passes of
+* one immutable revision. Bin counts clamp to 1,000. Unrepresentable distinct edges reject.
+* Constant domains get a finite nonzero display interval; the observed domain stays unchanged.
+*/
+export declare function prepareLyraHistogram(input:LyraIndexedInput<number>,options:LyraPreparationOptions&({readonly edges:readonly number[];}|{readonly binCount:number;})):Promise<LyraHistogramDistribution>;
+/**
+* Selects exact global top-K (default/max 150) from an already aggregated unique-ID word catalog.
+* Stable ties favor earlier positions. Global ID uniqueness is the caller's contract; only
+* duplicates among retained candidates can be detected with bounded memory. Blank or >256-unit
+* text, invalid IDs (>256 units/blank), and negative/nonfinite weights are invalid observations.
+* Valid total weight includes omitted words. If chosen labels exceed 16,384 code units the call
+* rejects; lower maxWords rather than silently clipping labels or dropping selected words.
+*/
+export declare function prepareLyraWordCloud(input:LyraIndexedInput<LyraWeightedWord>,options?:LyraPreparationOptions&{readonly maxWords?:number;}):Promise<LyraPreparedWordCloud>;
+/**
+* Summarizes the complete duration with positional interval maxima, default/max 65,536 buckets.
+* Finite samples clamp to [0,1]; invalid samples contribute no peak but retain their positions.
+* Endpoint amplitudes refer to the original first/last positions (null when invalid/absent).
+* Source storage remains caller-owned; only bounded chunks and output buckets are retained.
+*/
+export declare function prepareLyraWaveform(input:LyraIndexedInput<number>,options:LyraPreparationOptions&{readonly duration:number;readonly maxBuckets?:number;}):Promise<LyraPreparedWaveform>;

package/dist/utilities/data-preparation.js

@@ -0,0 +1 @@
+import{sourceCount,sourceRevision}from"../internal/source-request-controller.js";function budget(value,fallback,minimum,maximum){if(value===void 0)return fallback;if(typeof value!="number"||!Number.isSafeInteger(value)||value<minimum)throw new RangeError("Invalid preparation budget");return Math.min(value,maximum)}function preparation(options={}){const signal=options.signal??new AbortController().signal;return signal.throwIfAborted(),{signal,batchSize:budget(options.batchSize,2048,1,8192)}}function snapshot(input){const revision=sourceRevision(input.revision),count=sourceCount(input.count),read2=input.read;if(typeof read2!="function")throw new TypeError("Invalid source reader");return{input,revision,count,read:read2}}function current(source,signal){if(signal.throwIfAborted(),source.input.revision!==source.revision||source.input.count!==source.count)throw new Error("Source snapshot revision or count changed")}function abortable(value,signal){return new Promise((resolve,reject)=>{const aborted=()=>{signal.removeEventListener("abort",aborted),reject(signal.reason)};signal.addEventListener("abort",aborted,{once:!0}),Promise.resolve(value).then(result=>{signal.removeEventListener("abort",aborted),signal.aborted?reject(signal.reason):resolve(result)},error=>{signal.removeEventListener("abort",aborted),reject(error)}),signal.aborted&&aborted()})}async function read(source,start,count,signal){current(source,signal);const values=await abortable(source.read.call(source.input,start,count,{signal}),signal);if(current(source,signal),!Array.isArray(values)||values.length!==count)throw new TypeError("Invalid source range response");return values}async function scan(source,state,visit){current(source,state.signal);for(let start=0;start<source.count;){const size=Math.min(state.batchSize,source.count-start),values=await read(source,start,size,state.signal);for(let offset=0;offset<size;offset++){state.signal.throwIfAborted();const present=Object.hasOwn(values,offset);visit(present?values[offset]:void 0,start+offset,present)}start+=size,current(source,state.signal),start<source.count&&(await abortable(new Promise(resolve=>setTimeout(resolve,0)),state.signal),current(source,state.signal))}current(source,state.signal)}function finite(value){return typeof value=="number"&&Number.isFinite(value)}function sum(a,b){const value=a+b;if(!Number.isFinite(value))throw new RangeError("Numeric accumulation overflow");return value}function counts(sourceCount2,validCount){return Object.freeze({sourceCount:sourceCount2,validCount,invalidCount:sourceCount2-validCount})}function domain(min,max){return min===1/0?null:Object.freeze({min,max})}function metadata(id,label){if(typeof id!="string"||id.length>256||!id.trim())throw new TypeError("Invalid metadata ID");if(typeof label!="string"||label.length>1024)throw new TypeError("Invalid metadata label");return Object.freeze({id,label})}function metadataBudget(entries){let units=0;for(const entry of entries)units+=entry.id.length+entry.label.length;if(units>65536)throw new RangeError("Metadata label budget exceeded")}function boundary(count,partitions,index){return Math.floor(count/partitions)*index+Math.min(index,count%partitions)}function observation(value){if(!value||typeof value!="object")return null;const x=value.x,y=value.y;return finite(x)&&finite(y)?{x,y}:null}async function prepareLyraSeriesData(series,options={}){const state=preparation(options),capacity=budget(options.maxPointsPerSeries,500,4,1e3);if(!Array.isArray(series)||!series.length)throw new RangeError("At least one series is required");if(series.length>Math.floor(9e3/capacity))throw new RangeError("Series snapshot capacity budget exceeded");const sources=new Map,entries=series.map(entry=>{const meta=metadata(entry.id,entry.label);if(sources.has(meta.id))throw new TypeError("Duplicate series ID");return sources.set(meta.id,snapshot(entry.input)),meta});metadataBudget(entries);const revision=sources.get(entries[0].id).revision;for(const source of sources.values())if(source.revision!==revision)throw new Error("Series revision mismatch");const prepared=[];for(const entry of entries){const source=sources.get(entry.id);let valid=0,gaps=0,xMin=1/0,xMax=-1/0,yMin=1/0,yMax=-1/0,first,last,low,high;const candidates=[],exact=source.count<=capacity,partitions=Math.floor((capacity-2)/2);let partition=0;const flush=()=>{low&&candidates.push(low),high&&high!==low&&candidates.push(high),low=high=void 0};await scan(source,state,(value,sourceIndex)=>{!exact&&sourceIndex>=boundary(source.count,partitions,partition+1)&&(flush(),partition++);const point=observation(value);if(!point){gaps++;return}valid++,xMin=Math.min(xMin,point.x),xMax=Math.max(xMax,point.x),yMin=Math.min(yMin,point.y),yMax=Math.max(yMax,point.y);const candidate={...point,sourceIndex,gaps};first??=candidate,last=candidate,exact?candidates.push(candidate):((!low||point.y<low.y)&&(low=candidate),(!high||point.y>high.y)&&(high=candidate))}),exact||(flush(),first&&candidates.push(first),last&&last!==first&&candidates.push(last)),candidates.sort((a,b)=>a.sourceIndex-b.sourceIndex);const samples=[];let previous;for(const point of candidates)point.sourceIndex!==previous?.sourceIndex&&(samples.push(Object.freeze({x:point.x,y:point.y,sourceIndex:point.sourceIndex,breakBefore:!previous||point.gaps!==previous.gaps})),previous=point);prepared.push(Object.freeze({...entry,counts:counts(source.count,valid),xDomain:domain(xMin,xMax),yDomain:domain(yMin,yMax),samples:Object.freeze(samples)}))}for(const source of sources.values())current(source,state.signal);return Object.freeze({kind:"series",revision,series:Object.freeze(prepared),async getPoint(ref,request){const source=sources.get(ref.seriesId);if(!source)throw new RangeError("Unknown series ID");if(!Number.isSafeInteger(ref.sourceIndex)||ref.sourceIndex<0||ref.sourceIndex>=source.count)throw new RangeError("Source index out of range");const values=await read(source,ref.sourceIndex,1,request.signal),point=Object.hasOwn(values,0)?observation(values[0]):null;return current(source,request.signal),point?Object.freeze(point):null}})}async function prepareLyraCategoryData(input,options){const state=preparation(options),source=snapshot(input),aggregation=options.aggregation,categoryOf=options.categoryOf,valueOf=aggregation==="count"?void 0:options.valueOf;if(!["count","sum","mean"].includes(aggregation)||typeof categoryOf!="function"||aggregation!=="count"&&(!Object.hasOwn(options,"valueOf")||typeof valueOf!="function"||Object.is(valueOf,Object.prototype.valueOf)))throw new TypeError("Invalid category reducer");if(!Array.isArray(options.categories)||options.categories.length>1e3)throw new RangeError("Category budget exceeded");const categories=options.categories.map(entry=>metadata(entry.id,entry.label)),meta=metadata(options.seriesId,options.seriesLabel);metadataBudget([...categories,meta]);const positions=new Map;categories.forEach((entry,index)=>{if(positions.has(entry.id))throw new TypeError("Duplicate category ID");positions.set(entry.id,index)});const other=options.otherCategoryId===void 0?void 0:positions.get(options.otherCategoryId);if(options.otherCategoryId!==void 0&&other===void 0)throw new TypeError("Unknown Other category ID");const totals=new Array(categories.length).fill(0),categoryCounts=new Array(categories.length).fill(0);let valid=0;if(await scan(source,state,(value,index,present)=>{if(!present)return;const id=categoryOf(value,index);if(typeof id!="string"||!id||id.length>256)return;const position=positions.get(id)??other;if(position===void 0)return;const amount=aggregation==="count"?1:valueOf(value,index);finite(amount)&&(totals[position]=sum(totals[position],amount),categoryCounts[position]=categoryCounts[position]+1,valid++)}),aggregation==="mean")for(let index=0;index<totals.length;index++)categoryCounts[index]&&(totals[index]=totals[index]/categoryCounts[index]);return current(source,state.signal),Object.freeze({kind:"categories",revision:source.revision,counts:counts(source.count,valid),categories:Object.freeze(categories),categoryCounts:Object.freeze(categoryCounts),series:Object.freeze([Object.freeze({...meta,values:Object.freeze(totals)})]),aggregation})}function checkedEdges(edges){if(!Array.isArray(edges)||edges.length<2||edges.length>1001)throw new RangeError("Invalid histogram edge budget");const result=[];for(const edge of edges){if(!finite(edge)||result.length&&edge<=result[result.length-1])throw new RangeError("Histogram edges must be finite and strictly increasing");result.push(edge)}return result}function automaticEdges(min,max,bins){if(min===1/0)return[];let low=min,high=max;if(low===high){const padding=Math.max(.5,Math.abs(low)*.01);Number.isFinite(low-padding)&&(low-=padding),Number.isFinite(high+padding)&&(high+=padding)}const edges=[low],width=high-low;for(let index=1;index<bins;index++){const fraction=index/bins;edges.push(Number.isFinite(width)?low+width*fraction:low*(1-fraction)+high*fraction)}return edges.push(high),checkedEdges(edges)}async function prepareLyraHistogram(input,options){const state=preparation(options),source=snapshot(input);let min=1/0,max=-1/0,valid=0;const explicit="edges"in options;let edges;if(explicit)edges=checkedEdges(options.edges);else{const bins=budget(options.binCount,10,1,1e3);await scan(source,state,value=>{finite(value)&&(min=Math.min(min,value),max=Math.max(max,value))}),edges=automaticEdges(min,max,bins)}const binCounts=new Array(Math.max(0,edges.length-1)).fill(0);let belowCount=0,aboveCount=0;return await scan(source,state,value=>{if(!finite(value))return;if(valid++,explicit&&(min=Math.min(min,value),max=Math.max(max,value)),!edges.length)throw new Error("Source snapshot values changed between passes");if(value<edges[0]){belowCount++;return}if(value>edges[edges.length-1]){aboveCount++;return}let low=0,high=edges.length-1;for(;low+1<high;){const middle=Math.floor((low+high)/2);value<edges[middle]?high=middle:low=middle}const position=Math.min(low,binCounts.length-1);binCounts[position]=binCounts[position]+1}),current(source,state.signal),Object.freeze({revision:source.revision,counts:counts(source.count,valid),domain:domain(min,max),edges:Object.freeze(edges),binCounts:Object.freeze(binCounts),belowCount,aboveCount})}function worse(a,b){return a.word.weight<b.word.weight||a.word.weight===b.word.weight&&a.index>b.index}async function prepareLyraWordCloud(input,options={}){const state=preparation(options),source=snapshot(input),capacity=budget(options.maxWords,150,1,150),heap=[],ids=new Set;let valid=0,totalWeight=0;await scan(source,state,(value,index)=>{if(!value||typeof value!="object")return;const{id,text,weight}=value;if(typeof id!="string"||id.length>256||!id.trim()||typeof text!="string"||text.length>256||!text.trim()||!finite(weight)||weight<0)return;if(valid++,totalWeight=sum(totalWeight,weight),ids.has(id))throw new TypeError("Duplicate retained word ID");const candidate={word:Object.freeze({id,text,weight}),index};if(heap.length<capacity){ids.add(id),heap.push(candidate);let position=heap.length-1;for(;position>0;){const parent=Math.floor((position-1)/2);if(!worse(heap[position],heap[parent]))break;[heap[position],heap[parent]]=[heap[parent],heap[position]],position=parent}}else if(worse(heap[0],candidate)){ids.delete(heap[0].word.id),ids.add(id),heap[0]=candidate;let position=0;for(;;){const left=2*position+1,right=left+1;if(left>=heap.length)break;const child=right<heap.length&&worse(heap[right],heap[left])?right:left;if(!worse(heap[child],heap[position]))break;[heap[position],heap[child]]=[heap[child],heap[position]],position=child}}}),heap.sort((a,b)=>b.word.weight-a.word.weight||a.index-b.index);let retainedWeight=0,textUnits=0;const words=heap.map(({word})=>(retainedWeight=sum(retainedWeight,word.weight),textUnits+=word.text.length,word));if(textUnits>16384)throw new RangeError("Selected word label budget exceeded");return current(source,state.signal),Object.freeze({revision:source.revision,counts:counts(source.count,valid),totalWeight,retainedWeight,words:Object.freeze(words)})}async function prepareLyraWaveform(input,options){const state=preparation(options),source=snapshot(input),duration=options.duration;if(!finite(duration)||duration<0)throw new RangeError("Invalid waveform duration");const size=Math.min(source.count,budget(options.maxBuckets,65536,1,65536)),buckets=Array.from({length:size},(_,index)=>({startIndex:boundary(source.count,size,index),endIndex:boundary(source.count,size,index+1),maxAmplitude:0}));let position=0,valid=0,firstAmplitude=null,lastAmplitude=null;return await scan(source,state,(value,index)=>{index>=buckets[position].endIndex&&position++;const amplitude=finite(value)?Math.min(1,Math.max(0,value)):null;amplitude!==null&&(valid++,buckets[position].maxAmplitude=Math.max(buckets[position].maxAmplitude,amplitude)),index===0&&(firstAmplitude=amplitude),index===source.count-1&&(lastAmplitude=amplitude)}),current(source,state.signal),Object.freeze({revision:source.revision,counts:counts(source.count,valid),sampleCount:source.count,duration,buckets:Object.freeze(buckets.map(bucket=>Object.freeze(bucket))),firstAmplitude,lastAmplitude})}export{prepareLyraCategoryData,prepareLyraHistogram,prepareLyraSeriesData,prepareLyraWaveform,prepareLyraWordCloud};

package/dist/utilities/data-spatial.d.ts

@@ -0,0 +1,26 @@
+import type{LyraSourceRevision}from'../data-sources.js';import type{LyraNumericDomain,LyraSourceRequest,LyraSourceValue}from'./data-preparation.js';
+/** Finite full-source or viewport coordinates; an equal pair denotes a collapsed global axis. */
+export interface LyraSpatialBounds{readonly minX:number;readonly maxX:number;readonly minY:number;readonly maxY:number;}
+/** Stable identity in a source revision, independent of representative-array position. */
+export interface LyraSpatialPoint{readonly id:string;readonly sourceIndex:number;readonly x:number;readonly y:number;}
+/** A positive-count density region. Adjacent regions may share boundaries, never interiors. */
+export interface LyraSpatialBin{readonly bounds:LyraSpatialBounds;readonly count:number;}
+/** Bins account for every match; representative points are overlays, not additional counts. */
+export interface LyraSpatialQuery<T extends LyraSpatialPoint>{readonly points:readonly T[];readonly bins:readonly LyraSpatialBin[];readonly matchedCount:number;}
+/**
+* Host-owned spatial index with globally unique IDs. Query returns bounded complete density
+* bins and optional representative overlays; getPoint resolves an exact original ID. Source
+* metadata/payload stay immutable within a revision. Replacement or explicit refresh rebinds it.
+* Methods and payload fields must be own data properties, not accessors. Storage stays host-owned.
+*/
+export interface LyraSpatialPointSource<T extends LyraSpatialPoint>{readonly revision:LyraSourceRevision;readonly count:number;readonly bounds:LyraSpatialBounds|null;query(request:LyraSourceRequest&{readonly bounds:LyraSpatialBounds;readonly maxPoints:number;readonly maxBins:number;}):LyraSourceValue<LyraSpatialQuery<T>>;getPoint(id:string,request:LyraSourceRequest):LyraSourceValue<T|null>;}
+/** Immutable activation of a density region, not an individual observation. */
+export interface LyraSpatialBinSelectDetail{readonly revision:LyraSourceRevision;readonly bounds:LyraSpatialBounds;readonly count:number;}
+/** Declared full-source series metadata, independent of the current representatives. */
+export interface LyraSpatialChartSeries{readonly id:string;readonly label:string;readonly color?:string;}
+/** Original chart observation; radius is semantic data, not a renderer-clamped value. */
+export interface LyraSpatialChartPoint extends LyraSpatialPoint{readonly seriesId:string;readonly radius?:number;readonly label?:string;}
+/** Bounded spatial chart source with exact full-source series and radius metadata. */
+export interface LyraSpatialChartSource extends LyraSpatialPointSource<LyraSpatialChartPoint>{readonly kind:'spatial';readonly series:readonly LyraSpatialChartSeries[];readonly radiusDomain?:LyraNumericDomain|null;}
+/** Activation preserves the original observation identity and scalar chart metadata. */
+export interface LyraChartSpatialPointSelectDetail{readonly revision:LyraSourceRevision;readonly point:LyraSpatialChartPoint;}

package/dist/utilities/data-spatial.js

@@ -0,0 +1 @@
+export {};

package/dist/utilities/index.d.ts

@@ -1 +1 @@
-export{LyraElement}from'./lyra-element.js';export{installDeprecatedAliases}from'./deprecated-aliases.js';export type{LyraAliasMapping,LyraDeprecatedAliases}from'./deprecated-aliases.js';export type{LyraEmitArgs,LyraEmittedEvent,LyraEmitOptions,LyraEventMap,}from'./lyra-element.js';export{defineElement,LYRA_PREFIX,tag}from'./prefix.js';export{nextId,srOnly}from'./a11y.js';export{calendarIcon,chevronIcon,closeIcon,expandIcon,eyeIcon,eyeOffIcon,fileIcon,folderIcon,pauseIcon,playIcon,spinnerIcon,}from'./icons.js';export{place,trackRect,virtualAnchorFromRect}from'./positioner.js';export type{PlacementResult,PlaceAutoSize,PlaceBoundary,PlaceFlipFallbackStrategy,PlaceOptions,PlaceStrategy,PlaceSync,VirtualAnchor,}from'./positioner.js';export{activateOverlay,suspendLyraModalsFor}from'./overlay-manager.js';export type{OverlayActivationOptions,OverlayDeactivateOptions,OverlayHandle,OverlayRestoreFocusTarget,}from'./overlay-manager.js';export{lockScroll}from'./scroll-lock.js';export{acquireAnnouncementSink,ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer,}from'./announcer.js';export type{AnnounceOptions,AnnouncementPoliteness,AnnouncementSink,AnnouncementSinkOptions,AnnouncerOptions,AnnouncerTimerHost,}from'./announcer.js';export{layeredLayout}from'./layered-layout.js';export type{LayeredLayoutEdge,LayeredLayoutNode,LayeredLayoutOptions,LayeredLayoutResult,}from'./layered-layout.js';export{attachInternalsSafely,createFallbackInternals,createStringArrayFormDataState,FormAssociated,isEmptyFormValue,readStringArrayFormDataState,stringFormValueAdapter,}from'./form-associated.js';export type{FormAssociatedInterface,FormAssociatedSubclassInterface,FormOwnerValue,FormSubmissionValue,FormValueAdapter,}from'./form-associated.js';export{groupByRecency}from'./group-by-recency.js';export type{GroupByRecencyOptions,RecencyBucket,RecencyLabels,}from'./group-by-recency.js';export{bridgeLyraLocale,resolveLyraScopedString}from'../localization.js';export{subscribeLyraLocale}from'../internal/localization-runtime.js';export type{LyraLocaleBridgeCleanup,LyraLocaleBridgeOptions,}from'../localization.js';export{getAnimation,setAnimation,setDefaultAnimation}from'./animation-registry.js';export type{LyraAnimationCleanup,LyraElementAnimation,LyraGetAnimationOptions,LyraResolvedElementAnimation,}from'./animation-registry.js';export{allDefined}from'./defined.js';export type{AllDefinedOptions,LyraDefinitionRoot}from'./defined.js';export{resolveCssLength}from'./css-length.js';export type{ResolveCssLengthOptions}from'./css-length.js';export{formatBytes,formatDate,formatNumber,formatRelativeTime}from'./format.js';export type{LyraFormatBytesOptions,LyraFormatRelativeTimeOptions,LyraFormattableNumber,}from'./format.js';export{invalidateLyraTheme}from'./theme.js';export type{LyraThemeRoot}from'./theme.js';export{adoptLyraTokens}from'./tokens.js';export{findUnscopedThemeInputs}from'./theme-scopes.js';export type{LyraCatalog,LyraCatalogEntry}from'./catalog.js';export type{LyraAnchorTarget,LyraAnchorTargetEventMap,}from'./anchor-target.js';
+export{LyraElement}from'./lyra-element.js';export{installDeprecatedAliases}from'./deprecated-aliases.js';export type{LyraAliasMapping,LyraDeprecatedAliases}from'./deprecated-aliases.js';export type{LyraEmitArgs,LyraEmittedEvent,LyraEmitOptions,LyraEventMap,}from'./lyra-element.js';export{defineElement,LYRA_PREFIX,tag}from'./prefix.js';export{nextId,srOnly}from'./a11y.js';export{calendarIcon,chevronIcon,closeIcon,expandIcon,eyeIcon,eyeOffIcon,fileIcon,folderIcon,pauseIcon,playIcon,spinnerIcon,}from'./icons.js';export{place,trackRect,virtualAnchorFromRect}from'./positioner.js';export type{PlacementResult,PlaceAutoSize,PlaceBoundary,PlaceFlipFallbackStrategy,PlaceOptions,PlaceStrategy,PlaceSync,VirtualAnchor,}from'./positioner.js';export{activateOverlay,suspendLyraModalsFor}from'./overlay-manager.js';export type{OverlayActivationOptions,OverlayDeactivateOptions,OverlayHandle,OverlayRestoreFocusTarget,}from'./overlay-manager.js';export{lockScroll}from'./scroll-lock.js';export{acquireAnnouncementSink,ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer,}from'./announcer.js';export type{AnnounceOptions,AnnouncementPoliteness,AnnouncementSink,AnnouncementSinkOptions,AnnouncerOptions,AnnouncerTimerHost,}from'./announcer.js';export{layeredLayout}from'./layered-layout.js';export type{LayeredLayoutEdge,LayeredLayoutNode,LayeredLayoutOptions,LayeredLayoutResult,}from'./layered-layout.js';export{attachInternalsSafely,createFallbackInternals,createStringArrayFormDataState,FormAssociated,isEmptyFormValue,readStringArrayFormDataState,stringFormValueAdapter,}from'./form-associated.js';export type{FormAssociatedInterface,FormAssociatedSubclassInterface,FormOwnerValue,FormSubmissionValue,FormValueAdapter,}from'./form-associated.js';export{groupByRecency}from'./group-by-recency.js';export type{GroupByRecencyOptions,RecencyBucket,RecencyLabels,}from'./group-by-recency.js';export{bridgeLyraLocale,resolveLyraScopedString}from'../localization.js';export{subscribeLyraLocale}from'../internal/localization-runtime.js';export type{LyraLocaleBridgeCleanup,LyraLocaleBridgeOptions,}from'../localization.js';export{getAnimation,setAnimation,setDefaultAnimation}from'./animation-registry.js';export type{LyraAnimationCleanup,LyraElementAnimation,LyraGetAnimationOptions,LyraResolvedElementAnimation,}from'./animation-registry.js';export{allDefined}from'./defined.js';export type{AllDefinedOptions,LyraDefinitionRoot}from'./defined.js';export{resolveCssLength}from'./css-length.js';export type{ResolveCssLengthOptions}from'./css-length.js';export{formatBytes,formatDate,formatNumber,formatRelativeTime}from'./format.js';export type{LyraFormatBytesOptions,LyraFormatRelativeTimeOptions,LyraFormattableNumber,}from'./format.js';export{invalidateLyraTheme}from'./theme.js';export type{LyraThemeRoot}from'./theme.js';export{adoptLyraTokens}from'./tokens.js';export{findUnscopedThemeInputs}from'./theme-scopes.js';export type{LyraCatalog,LyraCatalogEntry}from'./catalog.js';export type{LyraAnchorTarget,LyraAnchorTargetEventMap,}from'./anchor-target.js';export{prepareLyraSeriesData,prepareLyraCategoryData,prepareLyraHistogram,prepareLyraWordCloud,prepareLyraWaveform,}from'./data-preparation.js';export type{LyraSourceValue,LyraSourceRequest,LyraIndexedInput,LyraPreparationOptions,LyraObservationCounts,LyraNumericDomain,LyraSeriesObservation,LyraSeriesSample,LyraPreparedSeries,LyraSeriesRangeRequest,LyraSeriesPointRef,LyraPreparedSeriesData,LyraPreparedCategoryData,LyraHistogramDistribution,LyraWeightedWord,LyraPreparedWordCloud,LyraPreparedWaveform,}from'./data-preparation.js';

package/dist/utilities/index.js

@@ -1 +1 @@
-import{LyraElement}from"./lyra-element.js";import{installDeprecatedAliases}from"./deprecated-aliases.js";import{defineElement,LYRA_PREFIX,tag}from"./prefix.js";import{nextId,srOnly}from"./a11y.js";import{calendarIcon,chevronIcon,closeIcon,expandIcon,eyeIcon,eyeOffIcon,fileIcon,folderIcon,pauseIcon,playIcon,spinnerIcon}from"./icons.js";import{place,trackRect,virtualAnchorFromRect}from"./positioner.js";import{activateOverlay,suspendLyraModalsFor}from"./overlay-manager.js";import{lockScroll}from"./scroll-lock.js";import{acquireAnnouncementSink,ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer}from"./announcer.js";import{layeredLayout}from"./layered-layout.js";import{attachInternalsSafely,createFallbackInternals,createStringArrayFormDataState,FormAssociated,isEmptyFormValue,readStringArrayFormDataState,stringFormValueAdapter}from"./form-associated.js";import{groupByRecency}from"./group-by-recency.js";import{bridgeLyraLocale,resolveLyraScopedString}from"../localization.js";import{subscribeLyraLocale}from"../internal/localization-runtime.js";import{getAnimation,setAnimation,setDefaultAnimation}from"./animation-registry.js";import{allDefined}from"./defined.js";import{resolveCssLength}from"./css-length.js";import{formatBytes,formatDate,formatNumber,formatRelativeTime}from"./format.js";import{invalidateLyraTheme}from"./theme.js";import{adoptLyraTokens}from"./tokens.js";import{findUnscopedThemeInputs}from"./theme-scopes.js";export{ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer,FormAssociated,LYRA_PREFIX,LyraElement,acquireAnnouncementSink,activateOverlay,adoptLyraTokens,allDefined,attachInternalsSafely,bridgeLyraLocale,calendarIcon,chevronIcon,closeIcon,createFallbackInternals,createStringArrayFormDataState,defineElement,expandIcon,eyeIcon,eyeOffIcon,fileIcon,findUnscopedThemeInputs,folderIcon,formatBytes,formatDate,formatNumber,formatRelativeTime,getAnimation,groupByRecency,installDeprecatedAliases,invalidateLyraTheme,isEmptyFormValue,layeredLayout,lockScroll,nextId,pauseIcon,place,playIcon,readStringArrayFormDataState,resolveCssLength,resolveLyraScopedString,setAnimation,setDefaultAnimation,spinnerIcon,srOnly,stringFormValueAdapter,subscribeLyraLocale,suspendLyraModalsFor,tag,trackRect,virtualAnchorFromRect};
+import{LyraElement}from"./lyra-element.js";import{installDeprecatedAliases}from"./deprecated-aliases.js";import{defineElement,LYRA_PREFIX,tag}from"./prefix.js";import{nextId,srOnly}from"./a11y.js";import{calendarIcon,chevronIcon,closeIcon,expandIcon,eyeIcon,eyeOffIcon,fileIcon,folderIcon,pauseIcon,playIcon,spinnerIcon}from"./icons.js";import{place,trackRect,virtualAnchorFromRect}from"./positioner.js";import{activateOverlay,suspendLyraModalsFor}from"./overlay-manager.js";import{lockScroll}from"./scroll-lock.js";import{acquireAnnouncementSink,ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer}from"./announcer.js";import{layeredLayout}from"./layered-layout.js";import{attachInternalsSafely,createFallbackInternals,createStringArrayFormDataState,FormAssociated,isEmptyFormValue,readStringArrayFormDataState,stringFormValueAdapter}from"./form-associated.js";import{groupByRecency}from"./group-by-recency.js";import{bridgeLyraLocale,resolveLyraScopedString}from"../localization.js";import{subscribeLyraLocale}from"../internal/localization-runtime.js";import{getAnimation,setAnimation,setDefaultAnimation}from"./animation-registry.js";import{allDefined}from"./defined.js";import{resolveCssLength}from"./css-length.js";import{formatBytes,formatDate,formatNumber,formatRelativeTime}from"./format.js";import{invalidateLyraTheme}from"./theme.js";import{adoptLyraTokens}from"./tokens.js";import{findUnscopedThemeInputs}from"./theme-scopes.js";import{prepareLyraSeriesData,prepareLyraCategoryData,prepareLyraHistogram,prepareLyraWordCloud,prepareLyraWaveform}from"./data-preparation.js";export{ANNOUNCEMENT_SINK_ATTRIBUTE,Announcer,FormAssociated,LYRA_PREFIX,LyraElement,acquireAnnouncementSink,activateOverlay,adoptLyraTokens,allDefined,attachInternalsSafely,bridgeLyraLocale,calendarIcon,chevronIcon,closeIcon,createFallbackInternals,createStringArrayFormDataState,defineElement,expandIcon,eyeIcon,eyeOffIcon,fileIcon,findUnscopedThemeInputs,folderIcon,formatBytes,formatDate,formatNumber,formatRelativeTime,getAnimation,groupByRecency,installDeprecatedAliases,invalidateLyraTheme,isEmptyFormValue,layeredLayout,lockScroll,nextId,pauseIcon,place,playIcon,prepareLyraCategoryData,prepareLyraHistogram,prepareLyraSeriesData,prepareLyraWaveform,prepareLyraWordCloud,readStringArrayFormDataState,resolveCssLength,resolveLyraScopedString,setAnimation,setDefaultAnimation,spinnerIcon,srOnly,stringFormValueAdapter,subscribeLyraLocale,suspendLyraModalsFor,tag,trackRect,virtualAnchorFromRect};

package/llms/components/lr-activity-feed.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [agent-tools](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/agent-tools.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 17 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 18 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`
 
 ---
@@ -28,6 +28,11 @@ left alone — appending a live entry never steals focus from an unrelated, stil
 Above `virtualizeAt`
 entries, the body renders through an internal `<lr-virtual-list>` instead of a plain keyed list.
 
+`entries` retains the newest 10,000 identities. The visible `limit` part discloses omitted entries
+through `activityFeedInputLimit`, with `count` and `total` placeholders. The existing follow and
+tail controls reach the newest retained entry. After changing external state read by a stable
+`renderText` or `formatTimestamp` callback, call `requestUpdate()` to refresh rendered rows.
+
 **Properties:** `entries: ActivityEntry[] = []` (attribute: false) — `ActivityEntry { id: string;
 text: string; icon?: string; timestamp?: Date | string; variant?: LyraVariant; data?: unknown }`
 (exported here). `icon` is a literal glyph hint (e.g. an emoji), the same convention
@@ -73,7 +78,7 @@ outer card goes.
 **Toggle request, follow and threshold:** `lr-toggle-request` (`detail: { expanded }`) is a cancelable proposal dispatched before the header toggles. `follow` reflects like every `true`-defaulting boolean: absent while following, `follow="false"` once released. The body virtualizes when entries exceed (not equal) `virtualize-at`.
 
 **CSS parts:** `base`, `header` (a `<button>`), `status-dot` (pulses while `mode="live"`), `label`,
-`summary`, `toggle`, `body` (the scrollable region, or the internal virtual-list), `entry` (carries
+`summary`, `toggle`, `limit` (input-loss notice), `body` (the scrollable region, or the internal virtual-list), `entry` (carries
 `data-variant`), `entry-icon`, `variant-dot` (the dot rendered inside `entry-icon` when the entry
 sets no literal `icon`), `variant-dot-neutral`/`variant-dot-brand`/`variant-dot-success`/
 `variant-dot-warning`/`variant-dot-danger` (each also carries `variant-dot`), `entry-text`, and

package/llms/components/lr-agent-trace.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [agent-tools](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/agent-tools.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 5 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -19,18 +19,54 @@
 Provider-neutral agent/LLM trace view combining span-kind filters, handoff quick-jumps, and a
 hierarchical trace tree from one shared `spans` array.
 
-Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
+With `treeSource` unset, span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
 surrounding whitespace. The first valid admitted duplicate continues to win.
 
+**Complete provider trace:** `treeSource: TraceTreeSource | undefined` (attribute:
+false) forwards the exact trace-tree provider contract above to the existing single child. It takes
+precedence over `spans`; invalid defined input fails visibly without restoring legacy content.
+Setting `undefined` restores current legacy spans, kind inventory and handoff quick-jumps.
+
+```ts
+import type { TraceTreeSource } from
+  "@aceshooting/lyra-ui/components/agent-tools/agent-trace/agent-trace.class.js";
+```
+
+The child owns the complete preorder, authoritative topology, required global trace extent,
+provider actions and bounded 400-row cache plus focused row/301 mounted rows/two range-read
+permits. The wrapper creates no second provider controller, loaded-span collection, topology index
+or window-derived summary. It never scans source rows to discover kinds or handoffs. Provider mode
+shows the fixed six public choices, in order: `agent`, `llm`, `tool`, `retriever`, `embedding`,
+`other`. Existing `hiddenKinds` is forwarded globally to the child. Handoff quick-jumps and the
+outer legacy admission notice are absent; provider rows and key reveal provide global navigation.
+
+`revealSourceKey(key: string): Promise<boolean>` waits for the current child binding and delegates
+to that child once, resolving `false` for missing, invalid, disabled, failed, obsolete, disconnected
+or unset-source targets. It does not activate or change selection. Same-identity assignment and
+keyless `requestUpdate()` forward a single refresh; named presentation/active-ID paints reuse the
+child. Source replacement/removal and lifecycle changes revoke obsolete child and wrapper controls.
+`label`, `withTokens`, `withCost`, `withoutBars`, `activeSpanId` and strings forward to the child;
+locale and direction inherit normally.
+
+The child remains caller-controlled when used alone. This wrapper preserves its two-way active
+binding: an accepted child's `lr-span-select` updates wrapper `activeSpanId` before that original
+event bubbles to external listeners, without re-emission. `lr-span-toggle` also bubbles once.
+Kind filtering keeps the existing veto/containment behavior and emits only the domain
+`lr-span-visibility-change { hiddenKinds }` after a current accepted change. No second source event
+or provider summary/filter API is added. The following span-array projection/handoff details apply
+with `treeSource` unset.
+
 **Properties:**
 
 - `spans: LyraSpan[] = []` (attribute: false) — the full, unfiltered array; identical contract to
   `lr-trace-tree.spans` (see `lr-span-waterfall` above for the `LyraSpan` shape). Controlled and
   never mutated
 - `activeSpanId: string | null = null` (attribute `active-span-id`) — controlled selection forwarded
-  into the composed `lr-trace-tree`; also updated locally (and re-emitted as `lr-span-select`) when a
-  span is activated from either the tree or the handoff quick-jump list, so it works as a two-way
-  binding
+  into the composed `lr-trace-tree`; tree activation updates it before the original
+  `lr-span-select` bubbles, while a legacy handoff quick-jump updates it and emits that event.
+  Both routes support two-way binding
+- `maxNodes: number = 500` (attribute `max-nodes`) — projected span budget forwarded to the tree,
+  normalized to `1..5000`; unset or non-finite values restore 500
 - `hiddenKinds: LyraSpan['kind'][] = []` (attribute: false) — span kinds hidden from the tree
   (`'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other'`). Empty shows every kind;
   pre-settable (e.g. to hide `retriever`/`embedding` by default) and readable back after
@@ -47,15 +83,19 @@ expanded: boolean }`), and `lr-span-visibility-change` (`detail: { hiddenKinds:
 LyraSpan['kind'][] }`). The internal graph legend's generic `lr-visibility-change` event is
 contained; consumers receive this trace-domain event instead.
 
-`spans` is normalized through the same at-most-500-record projection as `<lr-trace-tree>` before
+With `treeSource` unset, `spans` is normalized through the same bounded projection as `<lr-trace-tree>` before
 filtering, handoff lookup, and tree rendering. The controlled active span and its ancestor path
 reserve positions, and malformed records plus later duplicate ids are omitted, so the composed
-surfaces cannot disagree.
+surfaces cannot disagree. The first 10,000 outer entries are admitted without traversing opaque
+provider metadata; active reservation stays inside admitted data and `maxNodes`. A visible limit
+notice discloses source or projection loss without duplicating the composed tree's notice. It is
+silent on initial mount; a later transition into truncation is announced politely.
 
 **CSS parts:** `base`, `filter` (the composed `lr-graph-legend` filter row, only rendered while
-`spans` is non-empty), `handoffs` (the quick-jump list wrapper, only rendered while at least one
+legacy `spans` is non-empty, or while a provider is defined), `handoffs` (the quick-jump list wrapper, only rendered while at least one
 visible span has `kind: 'agent'`), `handoff` (one entry — a `<button>` wrapping an
-`lr-handoff-divider`, carrying `data-active`), `tree` (the composed `lr-trace-tree`).
+`lr-handoff-divider`, carrying `data-active`), `tree` (the composed `lr-trace-tree`), and `limit`
+(source truncation notice when the tree does not already show its own notice).
 
 **Themeable custom properties:** `--lr-agent-trace-handoff-active-bg` (default
 `var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) handoff quick-jump

package/llms/components/lr-agent-workspace.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [conversation](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/conversation.md)
 - **Deprecations** none
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
-- **Themeable via** 16 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 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`
 
 ---
@@ -41,11 +41,13 @@ metadata?: Record<string, unknown> }`. Each entry renders as an `lr-chat-message
   `role`/`status`/`timestamp` come straight across. A nonempty `parts` array renders in order through
   `lr-message-parts` and takes precedence over the legacy `text` shortcut; otherwise `text` renders
   as sanitized Markdown through `lr-markdown`. Replace the whole region with the `messages` slot for
-  richer bodies. Empty ids and later duplicates are omitted first-wins before the latest 500 valid
-  identities are chosen, so malformed tail rows cannot evict earlier valid messages. Host owns
-  ordering, updates, and persistence
+  richer bodies. Within the admitted input tail, empty ids and later duplicates are omitted
+  first-wins before the latest 500 valid identities are chosen. Host owns ordering, updates, and
+  persistence
 - `follow: boolean = true` (reflected) — forwarded to the internal `lr-chat-viewport`
-- `unreadStartIndex: number | null = null` (attribute `unread-start-index`) — forwarded to the viewport
+- `unreadStartIndex: number | null = null` (attribute `unread-start-index`) — an index in the
+  original assigned message array, translated into the retained rendered message window while
+  preserving positions occupied by invalid or duplicate records
 
 **Properties (details pane):**
 
@@ -157,12 +159,17 @@ directly, or exactly one `lr-virtual-list` when the slot itself owns virtualizat
 built-in run/tool/retrieval/grounding/context details pane while keeping the responsive shell),
 `composer` (replaces the built-in plain-frame `lr-chat-composer`; supplied content keeps its own
 frame), `header-actions` (model selection, settings, export controls).
+Supplying `messages` or `details` suppresses evaluation and mounting of that region's built-in
+fallback; removing the slot content restores it. Messages and tool calls retain a bounded newest
+tail, while retrieval, context, and citation inputs retain a bounded prefix. Localized
+`input-limit` notes disclose the original collection count when admission drops entries. Initial
+and reconnect notices are quiet; a later changed omission is politely announced.
 
 **CSS parts:** `base`, `header`, `heading`, `header-actions`, `body`, `conversation`, `viewport` (the
 composed `lr-chat-viewport`), `messages`, `messages-empty`, `details`, `details-content`, `section`
-(one run/tools/retrieval/grounding/context section), `section-heading`, `composer`, `composer-input`,
-`message`
-(the composed `lr-chat-composer`).
+(one run/tools/retrieval/grounding/context section), `section-heading`, `composer`,
+`composer-input` (the composed `lr-chat-composer`), `message`, `input-limit` (original collection
+admission-loss notes).
 
 **Themeable custom properties:** shared tokens only.
 

package/llms/components/lr-av-player.md

@@ -36,10 +36,12 @@ Removing `mime-type` consumes the absent hint safely and restores automatic vide
 `kind` explicitly selects audio. Attribute removal keeps its `null` property readback; an explicit
 empty hint remains empty, and a later audio MIME value restores audio detection.
 
-A cue with no `end` extends to the next strictly chronological applicable start, or remains
+With `cueSource` null, a cue with no `end` extends to the next strictly chronological applicable start, or remains
 open-ended when none exists. Equal starts do not end each other. The player indexes starts on cue
-assignment in at most O(n log n) work and reconciles each seek/time update in O(n) work. Caller
-order, first ID admission, explicit ends and overlap arbitration are retained; a paused seek uses
+assignment/duration changes in O(n log n) work with O(n) retained intervals. Seek/time updates
+resolve the interval in O(log n), or O(1) while the previous answer interval still applies. Overlaps
+choose the greatest effective start, then the later original index. Caller order, first ID
+admission and explicit ends are retained; a paused seek uses
 replacement cues immediately, even before rendering. Duration changes preserve the same
 effective-start rules.
 
@@ -49,7 +51,116 @@ seeking retains token-driven pointer feedback.
 The default document-viewer renderer advertises `time-range` anchors but not search: the generic
 document payload has no cue/transcript field, so advertising search there would expose a control
 whose result is always empty. Standalone `<lr-av-player>` search remains available whenever the
-consumer supplies `cues` directly.
+consumer supplies `cues` or a complete `cueSource` directly.
+
+**Complete indexed transcript:** `cueSource: LyraAvCueSource | null = null` (attribute: false)
+takes display precedence over `cues`, bypassing the legacy snapshot, tick index and search scans.
+Invalid non-null providers fail visibly; setting `null` restores the current legacy cue input and
+recomputes its retained search. The legacy `cues` route retains its 10,000-cue cap. Provider storage,
+interval indexing and full-text/speaker search remain host-owned; no complete transcript array,
+all-ID index or match array is retained by the player.
+
+```ts
+import type { LyraAvCueSource, LyraAvActiveCue, LyraAvCueSearch, LyraAvCue } from
+  "@aceshooting/lyra-ui/components/media/av-player/av-player.class.js";
+import type { LyraSourceRequest, LyraSourceValue } from
+  "@aceshooting/lyra-ui/utilities/data-preparation.js";
+```
+
+`LyraAvCueSource` supplies immutable `revision` (a nonempty string or finite number), safe
+nonnegative integer `count`, and four required own-data methods. Methods may return values or
+PromiseLike results; requests include an abort `signal`:
+
+- `getCue(index, request): LyraSourceValue<LyraAvCue | null>` returns the cue at its exact original
+  zero-based source index. An unavailable/null in-range position stays an unavailable,
+  noninteractive row; it never deletes or compacts a logical position.
+- `findCue(cueId, request): LyraSourceValue<{ index, cue } | null>` resolves a globally unique ID
+  directly, without scanning cached rows. Returned identity/index must agree with the request.
+- `activeAt(time, request): LyraSourceValue<LyraAvActiveCue>` resolves the complete source's active
+  cue and its exact validity interval.
+- `search(query, request): LyraSourceValue<LyraAvCueSearch>` searches the complete index; this
+  request additionally includes the effective `locale`.
+
+Provider cue records are closed, cloned and frozen own-data values:
+`{ cueId, start, end?, text, speaker? }`. `cueId` must already be trimmed, nonempty and at most
+256 UTF-16 units; `text` is at most 100,000 units and `speaker` at most 4,096. Start is finite and
+nonnegative; an explicit end is finite and at least start. Malformed, accessor-backed, oversized,
+duplicate or contradictory locally observed records fail without silent coercion/truncation.
+The provider guarantees global ID uniqueness and immutable agreement among row, lookup, active
+and search replies; the player checks only its bounded observable records. Source timestamps are
+absolute media seconds and are never clamped into invented end-of-media active cues. Committed
+row activation seeks that row's original start through the existing media seek contract.
+
+`LyraAvActiveCue` is `{ index: number | null, cue: LyraAvCue | null, validFrom, validUntil }`.
+Index/cue must both be null or both valid; a real index is below source count. The half-open
+`[validFrom, validUntil)` interval must be nonempty and contain the requested time; infinities
+are allowed only as interval bounds. Explicit cue start/end must also contain the requested time.
+The provider resolves omitted ends and overlaps using greatest start, then later original source
+index, including complete no-active intervals. The player retains one completed answer interval;
+ticks inside it make no active request. Seeks invalidate that interval even when they stay within
+its bounds. Out-of-interval ticks coalesce to the latest desired time; returning to a cached answer
+revokes an obsolete pending intent. `lr-cue-change` retains `{ cueId, index }` with the original
+source index, or `null`/`-1`, and emits only on an actual active identity/index transition.
+
+The transcript uses 32-row pages, at most 128 ready cues/four pages, and at most two staged pages
+(64 cues). `getCue` calls are sequential within each page, with at most two physically pending
+calls across pages. At most two additional active/selected-or-transient-match records are retained.
+The resulting 194-record payload ceiling is 20,244,288 UTF-16 units at maximum field sizes,
+separate from object overhead, validation temporaries, query strings and opaque provider storage.
+The list exposes the full logical `count`; cache size does not redefine transcript length.
+
+Existing `search(query): Promise<number>` trims its query and matches locale-aware,
+case-insensitive substrings of complete cue text OR speaker. `LyraAvCueSearch` supplies exact safe
+`count <= source.count` and own-data `getMatch(matchIndex, request)`, returning `{ index, cue }`
+for an original row. Each source index occurs at most once in provider match order. The player
+captures this indexed handle without enumerating hits, reveals the first match before resolving,
+and retains only the count, match ordinal and one selected record. `searchNext()`/`searchPrevious()`
+wrap the complete match ordinal and reveal the original list row without seeking media. Returned
+matches must satisfy the query and agree with subsequently loaded rows before scroll/highlight
+commit. Visible ready-row highlighting checks only bounded cue text/speaker.
+
+`lr-search-change` keeps `{ query, matchCount, matchCountExact: true, activeIndex }`, where
+`activeIndex` is the match ordinal, not the cue's original row index. Only authoritative completed
+matches, exact-zero results and explicit clears emit. Empty queries/`clearSearch()` clear state
+without provider work; canceled/unavailable search resolves `0` and navigation resolves `false`
+without fabricating an exact-zero event. Unavailable text uses the existing localized `error`
+surface and light-DOM failure announcements; loading uses the existing loading label. Locale
+changes restart the current query;
+ordinary playback ticks do not repeat search.
+
+One physical `activeAt`, one `findCue`, one `search` and one `getMatch` may run alongside the two
+`getCue` calls: six fixed physical permits, each with only the latest logical demand. Ignored aborts
+hold permits until actual settlement; cancellation settles obsolete search/navigation promises
+promptly without allowing overlapping replacement calls. Reassign even the same source, or call
+a keyless `requestUpdate()`, after revision/state changes. Named presentation updates reuse admitted
+data. Rebind, replacement, clearing, disconnect and adoption revoke old rows, intervals, search
+handles and effects; reconnect recaptures current input. Existing transcript/cue/state parts and
+time-range anchor methods apply; no new cue-ID anchor kind or cue-selection event is added.
+
+**Exported cue-source declarations:**
+
+These types are exported from the granular AV class entry shown above.
+
+`LyraAvCueSource {
+  readonly revision: LyraSourceRevision;
+  readonly count: number;
+  getCue(index: number, request: LyraSourceRequest): LyraSourceValue<LyraAvCue | null>;
+  findCue(cueId: string, request: LyraSourceRequest): LyraSourceValue<{ readonly index: number; readonly cue: LyraAvCue } | null>;
+  activeAt(time: number, request: LyraSourceRequest): LyraSourceValue<LyraAvActiveCue>;
+  search(query: string, request: LyraSourceRequest & { readonly locale: string }): LyraSourceValue<LyraAvCueSearch>;
+}`
+
+`LyraAvActiveCue {
+  readonly index: number | null;
+  readonly cue: LyraAvCue | null;
+  readonly validFrom: number;
+  readonly validUntil: number;
+}`
+
+`LyraAvCueSearch {
+  readonly count: number;
+  getMatch(matchIndex: number, request: LyraSourceRequest): LyraSourceValue<{ readonly index: number; readonly cue: LyraAvCue }>;
+}`
 
 **Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'`
 (attribute-backed auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
@@ -62,8 +173,8 @@ gradient scrim, while browser-owned native media controls are unchanged,
 `rates: readonly number[] = [0.75, 1, 1.25, 1.5, 2]` (attribute: false),
 `cues: readonly LyraAvCue[] = []` (attribute: false), `peaks: readonly number[] = []`
 (attribute: false), and `tracks: readonly LyraAvTrack[] = []` (attribute: false). Each collection is
-normalized synchronously on assignment into a bounded, cloned, frozen snapshot; mutate by assigning a
-new collection. The inherited
+normalized synchronously on assignment into a bounded, cloned, frozen snapshot when its legacy
+route is active; mutate by assigning a new collection. The inherited
 anchor-target surface is `highlights: readonly LyraHighlight[] = []` (property only; assign a new
 collection to update), `activeHighlightId: string | null = null` (attribute `active-highlight-id`),
 `anchor: LyraAnchor | string | null = null` (property only), and readonly
@@ -81,12 +192,71 @@ renders video) and never appears in `lr-load`'s `detail.kind`.
 `poster` is ignored for audio and is validated with the same safe media-source allowlist as `src`
 before reaching the native video element; an unsafe poster URL is omitted.
 
-Runtime numeric input is normalized before it reaches media, canvas, or `Intl`: cue/highlight times
+Runtime legacy input is normalized before it reaches media, canvas, or `Intl`: cue/highlight times
 and waveform peaks are clamped to their valid ranges; non-finite native duration/current time
 cannot leak into state or events. `rates` keeps only unique finite values in the supported
 `0.0625..16` range, while always including the normalized current `playbackRate`.
 
-**Waveform lifecycle:** with `peaks`, waveform canvas painting is gated by player visibility when
+**Prepared whole-duration waveform:** `waveform: LyraPreparedWaveform | null = null`
+(attribute: false) takes precedence over `peaks` for waveform presence, painting and failure state.
+Set `null` to restore current legacy peaks/validity. The supplied descriptor remains caller-owned
+and retained by identity; the player clones/freezes only its bounded accepted fields/buckets.
+It never decodes media, calls a sample reader or materializes original samples.
+
+```ts
+import { prepareLyraWaveform } from "@aceshooting/lyra-ui/utilities/data-preparation.js";
+import type { LyraPreparedWaveform, LyraIndexedInput } from
+  "@aceshooting/lyra-ui/utilities/data-preparation.js";
+
+player.waveform = await prepareLyraWaveform(samples, {
+  duration: durationSeconds,
+  maxBuckets: 1000,
+});
+```
+
+`prepareLyraWaveform(input: LyraIndexedInput<number>, options: LyraPreparationOptions &
+{ duration: number; maxBuckets?: number }): Promise<LyraPreparedWaveform>` asynchronously scans
+every original position once. Its immutable reader supplies `revision`, safe nonnegative `count`,
+and `read(start, count, { signal })`; each response must be an array of exactly the requested size.
+Preparation yields between chunks, supports `signal`, defaults `batchSize` to 2,048 and clamps it
+to at most 8,192. Budgets must be positive safe integers; `maxBuckets` defaults/clamps to 65,536.
+Finite samples clamp to `[0, 1]`; nonfinite/missing samples preserve their positions and contribute
+no peak. Revision/count changes or reader failures reject. Only bounded chunks and output buckets
+are retained; source storage/index construction remains caller-owned. Hosts may also author a
+complete bounded envelope directly, with responsibility for truthful full-source statistics.
+
+`LyraPreparedWaveform` has `{ revision, counts: { sourceCount, validCount, invalidCount },
+sampleCount, duration, buckets, firstAmplitude, lastAmplitude }`. Counts/sampleCount are safe
+nonnegative integers, `sampleCount === sourceCount`, and valid/invalid counts conserve the source.
+Revision is a nonempty string or finite number; duration is finite nonnegative seconds.
+At most 65,536 own-data buckets `{ startIndex, endIndex, maxAmplitude }` must form ordered,
+contiguous, nonempty half-open intervals partitioning `[0, sampleCount)`. Maxima are finite in
+`[0, 1]`. Endpoint amplitudes describe the original first/last samples, each null when invalid or
+absent, otherwise finite `[0, 1]` and no larger than its covering bucket's maximum. Empty input
+requires zero counts, empty buckets and null endpoints; all-invalid input has zero bucket maxima
+and null endpoints. Accessors, sparse fields, gaps/overlaps and malformed counts/amplitudes reject
+without clipping or legacy fallback.
+
+Painting maps each original index interval across the complete duration; unequal intervals retain
+their actual proportions. A monotone O(bucketCount + barCount) pass merges overlapping interval
+maxima into at most 4,096 physical bars. Final-bucket energy survives even when the final endpoint
+amplitude is quiet. Canvas backing stores stay within 4,096 per dimension and 8,388,608 pixels.
+Once positive native media metadata is authoritative, envelope duration must agree within
+`0.001 + 4 * Number.EPSILON * max(mediaDuration, envelopeDuration)` seconds. Mismatch shows a
+localized `error` and plain seek rail until metadata/envelope agree, without changing native
+duration or seek coordinates. Before metadata the envelope may show proportions, but cannot enable
+native seeking. Source/kind/MIME changes reset old metadata authority; duration changes recheck it.
+
+Malformed/mismatched waveforms use localized `avPlayerWaveformUnavailable` feedback and a fresh
+post-mount assertive light-DOM announcement, without a new waveform event or `lr-render-error`.
+Reassign even the same descriptor, or call a keyless `requestUpdate()`, after changing it; named
+playback/presentation updates reuse the accepted snapshot. Legacy `peaks` must already represent
+the whole recording: arrays over 65,536 entries reject before reading any entry, retaining no
+prefix. Valid bounded peaks keep their existing normalization and endpoint-preserving downsampling.
+Prepared presence hides inactive legacy admission errors; clearing it exposes current legacy
+validity again.
+
+**Waveform lifecycle:** with `peaks` or `waveform`, waveform canvas painting is gated by player visibility when
 `IntersectionObserver` is available. Peak, theme, and resize changes while the player is
 off-screen coalesce into one paint on re-entry; environments without that API retain eager
 painting.
@@ -109,8 +279,8 @@ unsupported or unresolved targets report `false` through the return value and `l
 (`detail: { readonly cueId, readonly index }`; `cueId` is `null` and `index` is `-1` when no cue is active),
 `lr-highlight-activate` (`detail: { highlightId }`), `lr-anchor-result` (`detail: {
 found }`), `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`;
-`matchCountExact` is always `true` — `search()` matches over the already-loaded `cues` array with no
-additional ceiling), and
+`matchCountExact` is always `true` for emitted results — legacy search covers the admitted `cues`
+array with no additional ceiling, while source search reports the complete indexed count), and
 `lr-render-error` (`detail: { error }`). The native `ended`, `error`, `loadedmetadata`, `pause`,
 `play`, `timeupdate`, and `volumechange`
 events are also relayed exactly once from the host as native `Event` instances. Like the original

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

@@ -9,6 +9,6 @@
 - **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** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
+- **Themeable via** 18 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

package/llms/components/lr-box-plot.md

@@ -19,6 +19,14 @@
 Box-and-whisker chart from a precomputed five-number summary (no raw sample data sent to the
 browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 
+A bounded set of group summaries can cover every observation in a much larger population: four
+groups can, for example, summarize one million observations. Compute each group's five numbers on
+the host or server, and keep its sample count, quantile definition, and exact or approximate
+provenance in the surrounding description or data table. Raw observation access and quantile
+computation remain with the host; the component consumes the summaries. Distinct group counts
+still obey the collection and rendering bounds below. Query a bounded group window or use a
+paged data browser to traverse a large group catalogue.
+
 If the browser cannot acquire a 2D canvas context, a localized visible message replaces the plot
 and the generated or slotted data table becomes visible. No failed Chart.js instance is retained.
 Changing the data or calling `refreshTheme()` retries rendering, so the plot recovers when the