@orangecharts/wrun-chart-host 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/constants/feature-flags.constants.d.ts +1 -0
  2. package/dist/constants/feature-flags.constants.js +4 -0
  3. package/dist/host-env.d.ts +14 -0
  4. package/dist/host-env.js +15 -0
  5. package/dist/index.d.ts +1 -0
  6. package/dist/index.js +1 -0
  7. package/dist/interfaces/wrun-runtime.interface.d.ts +44 -1
  8. package/dist/market-data/venues/index.d.ts +2 -2
  9. package/dist/market-data/venues/opra.js +3 -3
  10. package/dist/market-data/venues/stocks.contract.copy.json +3 -2
  11. package/dist/market-data/venues/stocks.d.ts +2 -2
  12. package/dist/market-data/venues/stocks.js +10 -9
  13. package/dist/settings-templates/indicator-fields.js +15 -0
  14. package/dist/utility/chart/cache-alignment.util.d.ts +23 -0
  15. package/dist/utility/chart/cache-alignment.util.js +36 -6
  16. package/dist/utility/chart/footprint-band.util.d.ts +21 -5
  17. package/dist/utility/chart/footprint-band.util.js +53 -14
  18. package/dist/utility/chart/wrun-run-result.util.d.ts +9 -1
  19. package/dist/utility/chart/wrun-run-result.util.js +8 -2
  20. package/dist/utility/wrun/wrun-batched-marks.util.d.ts +6 -2
  21. package/dist/utility/wrun/wrun-batched-marks.util.js +5 -3
  22. package/dist/utility/wrun/wrun-canvases.util.d.ts +24 -7
  23. package/dist/utility/wrun/wrun-canvases.util.js +92 -27
  24. package/dist/utility/wrun/wrun-hover.util.d.ts +8 -2
  25. package/dist/utility/wrun/wrun-hover.util.js +24 -13
  26. package/dist/utility/wrun/wrun-live-tick.util.js +22 -15
  27. package/dist/utility/wrun/wrun-output-words.util.d.ts +14 -0
  28. package/dist/utility/wrun/wrun-output-words.util.js +51 -0
  29. package/dist/utility/wrun/wrun-overlay-drivers.util.d.ts +41 -0
  30. package/dist/utility/wrun/wrun-overlay-drivers.util.js +32 -0
  31. package/dist/utility/wrun/wrun-overlay-result.util.d.ts +6 -1
  32. package/dist/utility/wrun/wrun-overlay-result.util.js +2 -0
  33. package/dist/utility/wrun/wrun-overlay-run.util.d.ts +8 -2
  34. package/dist/utility/wrun/wrun-overlay-run.util.js +31 -4
  35. package/dist/utility/wrun/wrun-panel-mount.util.d.ts +9 -1
  36. package/dist/utility/wrun/wrun-panel-mount.util.js +102 -5
  37. package/dist/utility/wrun/wrun-run-health.util.d.ts +6 -3
  38. package/dist/utility/wrun/wrun-run-health.util.js +5 -2
  39. package/dist/utility/wrun/wrun-script-inputs.util.d.ts +25 -8
  40. package/dist/utility/wrun/wrun-script-inputs.util.js +145 -45
  41. package/dist/utility/wrun/wrun-style-names.util.d.ts +23 -0
  42. package/dist/utility/wrun/wrun-style-names.util.js +74 -0
  43. package/package.json +3 -3
@@ -111,14 +111,18 @@ export interface WrunBatchedSectionSpec {
111
111
  firstOutput: number;
112
112
  stride: number;
113
113
  declaration: WrunBatchedSection;
114
+ /** The section's title, the one order every surface titles it in (wrun-style-names.util wrunStyleTitle): the
115
+ * sheet's `style_names` label, else its own readout `label`, else its name read as words. Its hover readout
116
+ * carries it (`{{label}}` prints it). */
117
+ title: string;
114
118
  /** Why this chart cannot draw the section (its declaration names a layout newer than this build:
115
119
  * a stride, a key or an option value the gate does not know), absent when it can. Its child is
116
120
  * refused by name ("Needs a newer chart") and the rest of the Indicator runs; the geometry above
117
121
  * is then a placeholder (the section's outputs are never read). */
118
122
  newer?: string;
119
123
  }
120
- /** The sheet slice the sections are read from. */
121
- export type WrunBatchedSheet = Pick<WrunIndicatorMetadata, 'id' | 'outputs'> & Partial<Pick<WrunIndicatorMetadata, WrunBatchedMarksKind>>;
124
+ /** The sheet slice the sections are read from (`style_names`: the words their titles read first). */
125
+ export type WrunBatchedSheet = Pick<WrunIndicatorMetadata, 'id' | 'outputs'> & Partial<Pick<WrunIndicatorMetadata, WrunBatchedMarksKind | 'style_names'>>;
122
126
  /** The cells one kept bar of a section costs: its child row, the timestamp and every field of every
123
127
  * slot (`1 + slots * stride`), and nothing else (the parent run's columns and a replace's old copy
124
128
  * are not charged; the header says why). Empty slots count: the row is as wide as the section. */
@@ -1,6 +1,6 @@
1
1
  import { WRUN_BATCHED_MARKS_KINDS } from './wrun-batched-kinds.leaf.js';
2
2
  import { WRUN_BATCHED_MARKS_CELL_BUDGET } from '../chart/overlay-output-budget.util.js';
3
- import { wrunLegendName } from '../chart/wrun-legend-name.util.js';
3
+ import { wrunStyleTitle } from './wrun-style-names.util.js';
4
4
  import { scheduleWrunCellsCapNotice } from './wrun-cap-notice.util.js';
5
5
  import { forgetWrunCanvasReadout, rememberWrunCanvasReadout } from './wrun-canvas-readout.util.js';
6
6
  import { wrunCanvasMergeLive } from './wrun-canvases.util.js';
@@ -202,6 +202,7 @@ export function readWrunBatchedSections(sheet) {
202
202
  if (names.has(name))
203
203
  throw sectionRefusal(sheetId, subject, 'the name is taken by another batched section');
204
204
  names.add(name);
205
+ const title = wrunStyleTitle(sheet, `${kind}:${name}`, name, entry.label);
205
206
  // A layout newer than this chart (the gate, cached per declaration): its child alone is refused, by
206
207
  // name, at the mount; the rules below are this layout's and never judge a newer one.
207
208
  const newer = wrunBatchedLayoutVerdict(kind, entry);
@@ -213,6 +214,7 @@ export function readWrunBatchedSections(sheet) {
213
214
  firstOutput: 0,
214
215
  stride: WRUN_BATCHED_STRIDE[kind],
215
216
  declaration: entry,
217
+ title,
216
218
  newer,
217
219
  });
218
220
  return;
@@ -267,6 +269,7 @@ export function readWrunBatchedSections(sheet) {
267
269
  firstOutput: first,
268
270
  stride,
269
271
  declaration: entry,
272
+ title,
270
273
  });
271
274
  });
272
275
  }
@@ -717,7 +720,6 @@ function readoutOf(spec, valuePerUnit) {
717
720
  const tooltip = tooltipOf(spec.declaration);
718
721
  if (tooltip === null)
719
722
  return undefined;
720
- const label = spec.declaration.label;
721
723
  const words = spec.kind === 'marks'
722
724
  ? []
723
725
  : spec.kind === 'flags'
@@ -726,7 +728,7 @@ function readoutOf(spec, valuePerUnit) {
726
728
  const timed = isWrunBatchedTimedLayout(spec.kind, spec.stride);
727
729
  const readout = {
728
730
  kind: spec.kind,
729
- label: typeof label === 'string' && label.trim() !== '' ? label : wrunLegendName(spec.name),
731
+ label: spec.title,
730
732
  tooltip,
731
733
  format: {},
732
734
  ...(words.length > 0 ? { words } : {}),
@@ -176,13 +176,28 @@ export declare function wrunCellRowsOf(metadata: Pick<WrunIndicatorMetadata, 'in
176
176
  inputIndexes: ReadonlyArray<number>;
177
177
  }>): WrunCellRows;
178
178
  /**
179
- * A windowed landing (wrun-panel-mount.util: a pan-back page or a prefix run landed inside its history
180
- * window) keeps the colour scale its heatmap was drawn with; only a full run samples again. The rows it lands
181
- * take the sample the mounted rows' bounds were picked from, so a Sensitivity re-pick afterwards reads that
182
- * sample instead of walking the landed rows into another basis. A child with no kept sample (one that
183
- * crossed a copy or a trim) still walks its rows on the next re-pick, as before.
179
+ * The colour scale a heatmap child was decided with, carried onto another child: `to` takes the sample `from`'s
180
+ * bounds were picked from, so a Sensitivity re-pick on `to` reads that sample instead of walking `to`'s rows into
181
+ * another basis. The mount's scale hold calls it when a pass of the same picture brings new rows
182
+ * (wrun-panel-mount.util `carryHeatmapScale`: the held child is the pass's own with the decided bounds). A child
183
+ * with no kept sample (one that crossed a copy) still walks its rows on the next re-pick, as before.
184
184
  */
185
- export declare function keepWrunHeatmapScaleSample(from: object, to: object): void;
185
+ export declare function keepWrunHeatmapScaleSample(from: Pick<WrunCanvasChildOverlay, 'settings'>, to: Pick<WrunCanvasChildOverlay, 'settings'>): void;
186
+ /** Whether a heatmap child's colour bounds were picked from a sample kept beside it (`heatmapSamples`), whatever it
187
+ * gave: false for a child whose bounds were all declared and for one that crossed a copy. A mount's merge keeps
188
+ * such a scale on its record, as the engine keeps it on screen. */
189
+ export declare function wrunHeatmapScaleKept(child: Pick<WrunCanvasChildOverlay, 'settings'>): boolean;
190
+ /**
191
+ * Whether the colour bounds a heatmap child shows were given by its kept sample, judged on the sample at the
192
+ * quantile they are read at (`pickCanvasScale`'s `spread`, never the bound numbers): its own bounds at the
193
+ * author's quantile, or, with the viewer's Sensitivity on a child with scale words, the re-pick at that position's
194
+ * quantile. False for a sample with no finite cell, one whose cells all sit at the zero floor, a declared bound or
195
+ * the centre (a grid writing 0 until a late input lands, a window of zero-volume buckets), one where at least the
196
+ * quantile's share of them does, a child with no kept sample, and one whose bounds were all declared: the bounds
197
+ * are then stand-ins or the author's, never a scale the cells chose. The mount holds a scale only when this is true
198
+ * (wrun-panel-mount.util `holdsHeatmapScale`); anything else is decided again by the next pass.
199
+ */
200
+ export declare function wrunHeatmapScaleDecided(child: WrunCanvasChildOverlay, sensitivity: number | undefined): boolean;
186
201
  /** A canvas row as the engine reads it: a plain array. The live book lane
187
202
  * hands typed rows (`Float64Array`, wrunLiveBookRows) the worker run wants,
188
203
  * which the engine's row readers and live merge skip, so the bars fed live
@@ -213,7 +228,9 @@ export declare function wrunHeatmapSensitivityRows(sheet: Pick<WrunIndicatorMeta
213
228
  * re-picked from the child's own scale sample at the position's quantile
214
229
  * (the options heatmap's map); the child's own bounds, the author's exactly,
215
230
  * when no position is set or the child carries no scale words. The centre
216
- * never depends on the quantile, so only `min` and `max` move.
231
+ * never depends on the quantile, so only `min` and `max` move. A mounted
232
+ * record's own bounds and sample are its decided scale's (the mount's scale
233
+ * hold), so a re-pick never reads the rows the canvas holds now.
217
234
  */
218
235
  export declare function wrunHeatmapSensitivityBounds(child: WrunCanvasChildOverlay, sensitivity: number | undefined): {
219
236
  min: number;
@@ -245,6 +245,18 @@ function nthZeroOf(values, index) {
245
245
  * zero pick re-reads the zero at its rank in that order.
246
246
  */
247
247
  export function wrunCanvasScaleOf(words, values, options) {
248
+ return pickCanvasScale(words, values, options).scale;
249
+ }
250
+ /**
251
+ * `wrunCanvasScaleOf`'s pick, and whether the sample gave every bound left to it (`spread`). It did not when it held
252
+ * no finite cell, or when the quantiles it was read at meet (every cell at the zero floor, a declared bound or the
253
+ * centre, or at least the quantile's share of them): the bounds are then stand-ins (`[floor, floor + 1]`,
254
+ * `centre +- 1`), chosen for want of a scale, never one the cells chose. A mounted heatmap holds only a scale its
255
+ * sample gave (wrun-panel-mount.util `holdsHeatmapScale`, `wrunHeatmapScaleDecided`): a stand-in held through the
256
+ * passes after it would saturate every cell the next rows bring. Bounds all declared take nothing from the sample
257
+ * and read as given.
258
+ */
259
+ function pickCanvasScale(words, values, options) {
248
260
  const q = finite(words.auto_quantile) ? words.auto_quantile : WRUN_CANVAS_DEFAULT_QUANTILE;
249
261
  const scale = words.scale ?? 'linear';
250
262
  const diverging = options.diverging || finite(words.center);
@@ -260,11 +272,13 @@ export function wrunCanvasScaleOf(words, values, options) {
260
272
  deviations[count++] = Math.abs(value - center);
261
273
  }
262
274
  let reach = count === 0 ? 0 : selectKth(deviations, count, quantileRank(count, q));
263
- if (!(reach > 0))
275
+ const reached = reach > 0;
276
+ if (!reached)
264
277
  reach = 1;
265
278
  const min = finite(words.min) ? words.min : center - reach;
266
279
  const max = finite(words.max) ? words.max : center + reach;
267
- return { min, max: max > min ? max : min + 1, center, scale };
280
+ const given = finite(words.min) && finite(words.max);
281
+ return { scale: { min, max: max > min ? max : min + 1, center, scale }, spread: given || (reached && max > min) };
268
282
  }
269
283
  const work = new Float64Array(values.length);
270
284
  let count = 0;
@@ -289,7 +303,8 @@ export function wrunCanvasScaleOf(words, values, options) {
289
303
  };
290
304
  const min = finite(words.min) ? words.min : options.zeroFloor ? 0 : count === 0 ? 0 : pick(1 - q);
291
305
  const max = finite(words.max) ? words.max : count === 0 ? min + 1 : pick(q);
292
- return { min, max: max > min ? max : min + 1, scale };
306
+ const given = finite(words.max) && (finite(words.min) || options.zeroFloor === true);
307
+ return { scale: { min, max: max > min ? max : min + 1, scale }, spread: given || (count > 0 && max > min) };
293
308
  }
294
309
  /** A value's position (0..1) on the scale: the diverging ramp sits its
295
310
  * centre at 0.5, `sqrt` lifts the small values, `log` (sequential only)
@@ -667,8 +682,13 @@ function heatmapSensitivityRule(sheet, heatmap, index) {
667
682
  const rule = heatmapScaleRule(sheet, heatmap);
668
683
  if (rule === null)
669
684
  return null;
670
- const fromQuantile = !finite(heatmap.max) || (!finite(heatmap.min) && !rule.zeroFloor);
671
- return fromQuantile && !quantileBoundByParam(sheet, heatmap, index) ? rule : null;
685
+ return boundFromSample(heatmap, rule) && !quantileBoundByParam(sheet, heatmap, index) ? rule : null;
686
+ }
687
+ /** A bound of the heatmap's colour scale comes from the cell sample (`wrunCanvasScaleOf`): `max` undeclared, or
688
+ * `min` undeclared where the word has no zero floor (a diverging heatmap never has one). Both declared (or `max`
689
+ * declared over a zero floor) and the sample decides nothing. */
690
+ function boundFromSample(heatmap, rule) {
691
+ return !finite(heatmap.max) || (!finite(heatmap.min) && !rule.zeroFloor);
672
692
  }
673
693
  /** The author's scale words as declared (absent words stay absent). */
674
694
  function heatmapScaleWords(heatmap) {
@@ -680,21 +700,56 @@ function heatmapScaleWords(heatmap) {
680
700
  ...(heatmap.scale !== undefined ? { scale: heatmap.scale } : {}),
681
701
  };
682
702
  }
683
- /** The scale sample a heatmap child was built with, kept beside it (keyed by
684
- * the child's own rows array, a fresh array per child): a Sensitivity re-pick
685
- * needs only a new selection, never another walk of the window. */
703
+ /**
704
+ * The scale sample a heatmap child's bounds were picked from, kept beside it, keyed by the child's own
705
+ * `settings` object (a fresh object per child per build, holding the bounds the sample gave): a Sensitivity
706
+ * re-pick needs only a new selection, never another walk of the window. The key is the settings and never the
707
+ * rows: every seam that keeps a mounted record (a live merge adopting the engine's rows, a cell-budget trim, a
708
+ * windowed landing, a retranslate, a blank) copies the child as `{ ...child, data }`, which shares the settings,
709
+ * so the sample stays with the bounds it gave while the rows move under them. Keyed by the rows (as it was until
710
+ * 2026-11-07), the first live merge or trim lost it and the next re-pick sampled whatever rows the canvas held
711
+ * then. Kept whenever a bound comes from the sample (`boundFromSample`), with or without a Sensitivity row, beside
712
+ * whether the sample gave the bounds it was read for (`pickCanvasScale`'s `spread`): the mount's scale hold reads it
713
+ * (`wrunHeatmapScaleDecided`).
714
+ */
686
715
  const heatmapSamples = new WeakMap();
687
716
  /**
688
- * A windowed landing (wrun-panel-mount.util: a pan-back page or a prefix run landed inside its history
689
- * window) keeps the colour scale its heatmap was drawn with; only a full run samples again. The rows it lands
690
- * take the sample the mounted rows' bounds were picked from, so a Sensitivity re-pick afterwards reads that
691
- * sample instead of walking the landed rows into another basis. A child with no kept sample (one that
692
- * crossed a copy or a trim) still walks its rows on the next re-pick, as before.
717
+ * The colour scale a heatmap child was decided with, carried onto another child: `to` takes the sample `from`'s
718
+ * bounds were picked from, so a Sensitivity re-pick on `to` reads that sample instead of walking `to`'s rows into
719
+ * another basis. The mount's scale hold calls it when a pass of the same picture brings new rows
720
+ * (wrun-panel-mount.util `carryHeatmapScale`: the held child is the pass's own with the decided bounds). A child
721
+ * with no kept sample (one that crossed a copy) still walks its rows on the next re-pick, as before.
693
722
  */
694
723
  export function keepWrunHeatmapScaleSample(from, to) {
695
- const sample = heatmapSamples.get(from);
696
- if (sample !== undefined && from !== to)
697
- heatmapSamples.set(to, sample);
724
+ const sample = heatmapSamples.get(from.settings);
725
+ if (sample !== undefined && from.settings !== to.settings)
726
+ heatmapSamples.set(to.settings, sample);
727
+ }
728
+ /** Whether a heatmap child's colour bounds were picked from a sample kept beside it (`heatmapSamples`), whatever it
729
+ * gave: false for a child whose bounds were all declared and for one that crossed a copy. A mount's merge keeps
730
+ * such a scale on its record, as the engine keeps it on screen. */
731
+ export function wrunHeatmapScaleKept(child) {
732
+ return heatmapSamples.has(child.settings);
733
+ }
734
+ /**
735
+ * Whether the colour bounds a heatmap child shows were given by its kept sample, judged on the sample at the
736
+ * quantile they are read at (`pickCanvasScale`'s `spread`, never the bound numbers): its own bounds at the
737
+ * author's quantile, or, with the viewer's Sensitivity on a child with scale words, the re-pick at that position's
738
+ * quantile. False for a sample with no finite cell, one whose cells all sit at the zero floor, a declared bound or
739
+ * the centre (a grid writing 0 until a late input lands, a window of zero-volume buckets), one where at least the
740
+ * quantile's share of them does, a child with no kept sample, and one whose bounds were all declared: the bounds
741
+ * are then stand-ins or the author's, never a scale the cells chose. The mount holds a scale only when this is true
742
+ * (wrun-panel-mount.util `holdsHeatmapScale`); anything else is decided again by the next pass.
743
+ */
744
+ export function wrunHeatmapScaleDecided(child, sensitivity) {
745
+ const kept = heatmapSamples.get(child.settings);
746
+ if (kept === undefined)
747
+ return false;
748
+ const inputs = child.scale;
749
+ if (child.kind !== 'heatmap' || inputs === undefined || !finite(sensitivity))
750
+ return kept.spread;
751
+ const words = { ...inputs.words, auto_quantile: heatmapSensitivityQuantile(sensitivity) };
752
+ return pickCanvasScale(words, kept.values, { diverging: inputs.diverging, zeroFloor: inputs.zeroFloor }).spread;
698
753
  }
699
754
  /** The newest `tailRows` rows of a source (a live tick's tail), else all of them. */
700
755
  function newestRows(rows, tailRows) {
@@ -722,15 +777,16 @@ function heatmapChild(sheet, heatmap, index, cellRows, outputRows, tailRows) {
722
777
  data = newestRows((layout === 'book' ? cellRows?.bookRows : cellRows?.volumeProfileRows) ?? [], tailRows).map(wrunPlainCanvasRow);
723
778
  // A tick's tail samples no scale and keeps no Sensitivity inputs: its rows
724
779
  // only merge into a mounted canvas, which keeps the bounds (and the sample a
725
- // Sensitivity re-pick reads) of the full run that mounted it.
780
+ // Sensitivity re-pick reads) of the pass that decided them.
726
781
  let scale;
782
+ let sample;
727
783
  let sensitivity = null;
728
784
  if (tailRows === undefined) {
729
- const sample = sampleCellValues(layout, valueField, data);
730
- scale = wrunCanvasScaleOf(heatmap, sample, { diverging, zeroFloor });
785
+ const values = sampleCellValues(layout, valueField, data);
786
+ const picked = pickCanvasScale(heatmap, values, { diverging, zeroFloor });
787
+ scale = picked.scale;
788
+ sample = { values, spread: picked.spread };
731
789
  sensitivity = heatmapSensitivityRule(sheet, heatmap, index);
732
- if (sensitivity !== null)
733
- heatmapSamples.set(data, sample);
734
790
  }
735
791
  const format = numberFormatOf(heatmap);
736
792
  const rowHeight = heatmap.row_height ?? (layout === 'book' ? bookGroupingOf(data) : undefined);
@@ -762,6 +818,9 @@ function heatmapChild(sheet, heatmap, index, cellRows, outputRows, tailRows) {
762
818
  valueFormat: format,
763
819
  hoverReadout: heatmap.tooltip !== undefined,
764
820
  };
821
+ // The sample beside the settings holding the bounds it gave (heatmapSamples), whenever a bound came from it.
822
+ if (sample !== undefined && boundFromSample(heatmap, rule))
823
+ heatmapSamples.set(settings, sample);
765
824
  const readout = heatmap.tooltip !== undefined
766
825
  ? { kind: 'heatmap', label: heatmap.label ?? wrunCanvasNameWords(heatmap.name), tooltip: heatmap.tooltip, format }
767
826
  : undefined;
@@ -815,20 +874,26 @@ export function wrunHeatmapSensitivityRows(sheet) {
815
874
  * re-picked from the child's own scale sample at the position's quantile
816
875
  * (the options heatmap's map); the child's own bounds, the author's exactly,
817
876
  * when no position is set or the child carries no scale words. The centre
818
- * never depends on the quantile, so only `min` and `max` move.
877
+ * never depends on the quantile, so only `min` and `max` move. A mounted
878
+ * record's own bounds and sample are its decided scale's (the mount's scale
879
+ * hold), so a re-pick never reads the rows the canvas holds now.
819
880
  */
820
881
  export function wrunHeatmapSensitivityBounds(child, sensitivity) {
821
882
  const own = { min: child.settings.min, max: child.settings.max };
822
883
  const inputs = child.scale;
823
884
  if (child.kind !== 'heatmap' || inputs === undefined || !finite(sensitivity))
824
885
  return own;
825
- let sample = heatmapSamples.get(child.data);
826
- if (sample === undefined) {
886
+ // The sample the child's own bounds were picked from (kept beside its settings, heatmapSamples): on a mounted
887
+ // record that is the decided scale's, whatever rows the record holds now.
888
+ let kept = heatmapSamples.get(child.settings);
889
+ if (kept === undefined) {
827
890
  // A child that crossed a copy (no kept sample) walks its rows again.
828
- sample = sampleCellValues(inputs.layout, inputs.valueField, child.data);
829
- heatmapSamples.set(child.data, sample);
891
+ const values = sampleCellValues(inputs.layout, inputs.valueField, child.data);
892
+ const rule = { diverging: inputs.diverging, zeroFloor: inputs.zeroFloor };
893
+ kept = { values, spread: pickCanvasScale(inputs.words, values, rule).spread };
894
+ heatmapSamples.set(child.settings, kept);
830
895
  }
831
- const scale = wrunCanvasScaleOf({ ...inputs.words, auto_quantile: heatmapSensitivityQuantile(sensitivity) }, sample, {
896
+ const scale = wrunCanvasScaleOf({ ...inputs.words, auto_quantile: heatmapSensitivityQuantile(sensitivity) }, kept.values, {
832
897
  diverging: inputs.diverging,
833
898
  zeroFloor: inputs.zeroFloor,
834
899
  });
@@ -39,12 +39,16 @@ import { type WrunColorTheme } from './wrun-style-words.util.js';
39
39
  * `colorTheme` (DW13, TH-theme-tokens): the owning chart's palette; with it
40
40
  * every colour word a block or an output declares resolves here (a theme
41
41
  * token becomes the chart's colour), without it the words pass as written.
42
+ * `builtIn` (TWIN-LEGEND): the built-in the package ports (builtinPortOf),
43
+ * whose words name every line it names on the card, like the legend
44
+ * (wrun-output-words.util); absent, the sheet's words.
42
45
  */
43
46
  export interface WrunValuePlacement {
44
47
  priceDigits: number;
45
48
  onPrice: (name: string | undefined) => boolean;
46
49
  builtinTwin?: WrunBuiltinTwin;
47
50
  colorTheme?: WrunColorTheme;
51
+ builtIn?: string;
48
52
  }
49
53
  /** The number-format companions an output declares beside `format` (OT32,
50
54
  * conventions 8): the formatter's 4th argument. */
@@ -123,8 +127,10 @@ export declare const WRUN_SPARK_DEFAULT_BARS = 32;
123
127
  * else undefined. The gate paintColor and every block view sink (WrunBlocks) share. */
124
128
  export declare function wrunPaintColor(value: unknown): string | undefined;
125
129
  /** An output's display label: the declared `label`, else its name read as
126
- * words (the legend's own rule, wrunLegendName). */
127
- export declare function wrunOutputDisplayLabel(output: Pick<WrunMetadataOutput, 'name' | 'label'>): string;
130
+ * words (the legend's own rule, wrunLegendName); for a package that ports
131
+ * built-in `builtIn`, a line the built-in names in its built-in's words
132
+ * (wrunOutputWords, the words its legend line carries). */
133
+ export declare function wrunOutputDisplayLabel(output: Pick<WrunMetadataOutput, 'name' | 'label'>, builtIn?: string): string;
128
134
  /** A sheet name as a legend surface prints it where the declaration carries
129
135
  * no words of its own (a `render.legend` entry without `text`, a HUD's
130
136
  * settings rows): the legend's own rule (wrunLegendName: `spot_entry` reads
@@ -23,6 +23,7 @@
23
23
  * unknown name stays as written too, so a typo shows instead of vanishing.
24
24
  */
25
25
  import { wrunLegendName } from '../chart/wrun-legend-name.util.js';
26
+ import { wrunDeclaredOutputWords, wrunOutputWords } from './wrun-output-words.util.js';
26
27
  import { WRUN_MAX_BLOCK_HEIGHT_PX, WRUN_MAX_HUD_FONT_SIZE_PX, WRUN_MAX_HUD_RINGS, WRUN_MIN_BLOCK_HEIGHT_PX, WRUN_MIN_HUD_FONT_SIZE_PX, isWrunRowLeader, wrunBlockDraw, } from './wrun-hud-looks.util.js';
27
28
  import { formatWrunLegendValue, formatWrunValue, isWrunValueFormat, } from './wrun-pane-format.util.js';
28
29
  import { isWrunColorWord, parseWrunThemeToken, resolveWrunColorWord, } from './wrun-style-words.util.js';
@@ -127,9 +128,11 @@ function paintColor(word, placement) {
127
128
  return isWrunColorWord(word) || wrunPaintColor(word) !== undefined ? word : undefined;
128
129
  }
129
130
  /** An output's display label: the declared `label`, else its name read as
130
- * words (the legend's own rule, wrunLegendName). */
131
- export function wrunOutputDisplayLabel(output) {
132
- return wrunLegendName(output.name, output.label);
131
+ * words (the legend's own rule, wrunLegendName); for a package that ports
132
+ * built-in `builtIn`, a line the built-in names in its built-in's words
133
+ * (wrunOutputWords, the words its legend line carries). */
134
+ export function wrunOutputDisplayLabel(output, builtIn) {
135
+ return wrunOutputWords(output, builtIn);
133
136
  }
134
137
  /** A sheet name as a legend surface prints it where the declaration carries
135
138
  * no words of its own (a `render.legend` entry without `text`, a HUD's
@@ -227,14 +230,17 @@ function referenceText(name, format, snapshot, metadata, placement) {
227
230
  const output = outputByName(metadata, name);
228
231
  return formatPlacedValue(latestValue(snapshot, name), name, formatWordFor(format, output), placement, formatOptionsFor(output));
229
232
  }
230
- /** The label a block shows: its own, else its reference's display label. */
231
- function blockLabel(block, metadata) {
232
- if (typeof block.label === 'string' && block.label.trim() !== '')
233
- return block.label;
233
+ /** The label a block shows: its own (words that restate its output's line
234
+ * read that line's words, wrunDeclaredOutputWords), else its reference's
235
+ * display label; `builtIn` names a built-in port's lines in its words. */
236
+ function blockLabel(block, metadata, builtIn) {
234
237
  const name = block.output ?? block.slot;
235
238
  const output = outputByName(metadata, name);
239
+ if (typeof block.label === 'string' && block.label.trim() !== '') {
240
+ return wrunDeclaredOutputWords(block.label, output, builtIn);
241
+ }
236
242
  if (output !== undefined)
237
- return wrunOutputDisplayLabel(output);
243
+ return wrunOutputDisplayLabel(output, builtIn);
238
244
  return name === undefined ? undefined : wrunLegendName(name);
239
245
  }
240
246
  /** The kinds that draw a mark in the series' own colour (a sparkline, an
@@ -297,9 +303,12 @@ function ringViews(block, snapshot, metadata, placement) {
297
303
  const output = outputByName(metadata, ring.output);
298
304
  const current = latestValue(snapshot, ring.output);
299
305
  const color = paintColor(typeof ring.color === 'string' && ring.color !== '' ? ring.color : undefined, placement);
306
+ const builtIn = placement?.builtIn;
300
307
  return [
301
308
  {
302
- label: typeof ring.label === 'string' && ring.label !== '' ? ring.label : wrunLegendName(ring.output, output?.label),
309
+ label: typeof ring.label === 'string' && ring.label !== ''
310
+ ? wrunDeclaredOutputWords(ring.label, output, builtIn)
311
+ : wrunOutputWords(output ?? { name: ring.output }, builtIn),
303
312
  value: formatPlacedValue(current, ring.output, formatWordFor(undefined, output), placement, formatOptionsFor(output)),
304
313
  fraction: shareOf(current, ring.min, ring.max) ?? 0,
305
314
  ...(color !== undefined ? { color } : {}),
@@ -331,7 +340,7 @@ function deltaTone(delta) {
331
340
  function buildBlockView(block, snapshot, metadata, placement) {
332
341
  if (!block || typeof block !== 'object')
333
342
  return undefined;
334
- const label = blockLabel(block, metadata);
343
+ const label = blockLabel(block, metadata, placement?.builtIn);
335
344
  const color = blockColor(block, snapshot, metadata, placement);
336
345
  const labelled = label !== undefined ? { label } : {};
337
346
  const words = blockLookWords(block);
@@ -408,11 +417,13 @@ function buildBlockView(block, snapshot, metadata, placement) {
408
417
  // A row is [label, reference] or [label, reference, format].
409
418
  const [rowLabel, reference, rowFormat] = row;
410
419
  const name = typeof reference === 'string' ? reference : undefined;
411
- const swatch = paintColor(outputByName(metadata, name)?.color, placement);
420
+ const output = outputByName(metadata, name);
421
+ const swatch = paintColor(output?.color, placement);
412
422
  const format = typeof rowFormat === 'string' ? rowFormat : undefined;
413
423
  return [
414
424
  {
415
- label: rowLabel,
425
+ // A row that names its line by the line's own words reads them as the legend does.
426
+ label: wrunDeclaredOutputWords(rowLabel, output, placement?.builtIn),
416
427
  value: referenceText(name, format, snapshot, metadata, placement),
417
428
  ...(swatch !== undefined ? { swatch } : {}),
418
429
  },
@@ -511,7 +522,7 @@ const WRUN_HEADER_SEPARATOR = ' \u00b7 ';
511
522
  */
512
523
  export function wrunOutputHoverView(output, snapshot, metadata, options = {}) {
513
524
  const { placement } = options;
514
- const label = wrunOutputDisplayLabel(output);
525
+ const label = wrunOutputDisplayLabel(output, placement?.builtIn);
515
526
  const value = options.value ?? latestValue(snapshot, output.name);
516
527
  const format = formatWordFor(undefined, output);
517
528
  const formatOptions = formatOptionsFor(output);
@@ -227,7 +227,7 @@ import { serverNowMs } from '../auth/server-clock.util.js';
227
227
  import { wrunModuleReadsBarCount } from './wrun-bar-count.util.js';
228
228
  import { isWrunBatchedChildRefused, mountWrunChildOverlays } from './wrun-panel-mount.util.js';
229
229
  import { getWrunBrowserHost, wrunLiveOf, WrunLiveOrderError, WrunLiveSessionLostError, } from './wrun-host.service.js';
230
- import { getWrunOverlayLiveContext, isWrunOverlayRerunInFlight, onWrunOverlayLiveTeardown, rerunWrunOverlayForChartWave, setWrunChartRowsIdentityReader, setWrunLazyWaveAbsorber, setWrunLiveSheetReader, suspendWrunOverlayLiveSession, teardownWrunOverlay, withWrunOverlaySessionLock, wrunChartMarketIdentity, } from './wrun-overlay-drivers.util.js';
230
+ import { getWrunOverlayLiveContext, isWrunOverlayRerunInFlight, onWrunOverlayLiveTeardown, rerunWrunOverlayForChartWave, setWrunChartRowsIdentityReader, setWrunLazyWaveAbsorber, setWrunLiveSheetReader, suspendWrunOverlayLiveSession, teardownWrunOverlay, withWrunOverlaySessionLock, wrunChartMarketIdentity, wrunPictureIdentityOf, } from './wrun-overlay-drivers.util.js';
231
231
  import { composeWrunSessionSources, takeWrunCompositionRevisionKept, wrunSessionCompositionToken, wrunSessionLanesOfContext, } from './wrun-session-composition.util.js';
232
232
  import { withWrunOverlayExecutionMeasure } from './wrun-overlay-lifecycle.util.js';
233
233
  import { cutWrunReplayRows, cutWrunReplayRowsAfterApply } from './wrun-replay-rows.util.js';
@@ -239,6 +239,7 @@ import { wrunCanvasChildId, wrunCellRowsOf } from './wrun-canvases.util.js';
239
239
  import { readWrunBatchedSections, wrunBatchedChildId, wrunSheetHasBatchedMarks } from './wrun-batched-marks.util.js';
240
240
  import { isWrunStyleTargetHidden } from './wrun-color-settings.util.js';
241
241
  import { buildWrunOverlayRunResult, closedLegCandles, forgetWrunOverlayCanvasState, openLegCandles, wrunLegReadsFormingOpen, wrunLegReadsLiveCandleOnly, cutWrunOddsLegRows, placeWrunResultTables, presentWrunIntegration, publishWrunRunHealth, publishWrunSessionCanvasNotices, recordWrunHostBuildMs, reseedWrunOverlayFromBuffers, wrunCandleAskSource, wrunCanvasHostFillFor, wrunChartPriceDigits, wrunHostFillContextFor, wrunLegFetchType, wrunLegPayloadExtras, wrunIntegratedRowsView, wrunSessionCanvasFillOf, wrunSessionPinnedSheet, wrunSessionRespelledSheet, wrunResultMarketUnits, wrunSessionRunHealth, } from './wrun-overlay-run.util.js';
242
+ import { builtinPortOf } from './wrun-builtin-twin.util.js';
242
243
  import { forgetWrunCanvasCache } from './wrun-canvas-cache.util.js';
243
244
  import { wrunLegNativeRowsOption } from './wrun-pin-venues.util.js';
244
245
  import { wrunSessionChartNamesOf } from './wrun-chart-context-names.util.js';
@@ -1967,8 +1968,8 @@ export async function integrateWrunOverlayLiveFrame(indicatorId, frame, cellRows
1967
1968
  hostStartMs,
1968
1969
  cellRowsOf: () => cellRowsOf(ohlcvRows),
1969
1970
  });
1970
- // A held chart took the frame's apply as a deferred unit (integrateWrunLiveTail): the frame is taken, so its
1971
- // callers (the replay lane's cutoff) read it as applied rather than reopening the session.
1971
+ // The engine's ordering door took the frame's apply as a deferred unit (integrateWrunLiveTail): the frame is
1972
+ // taken, so its callers (the replay lane's cutoff) read it as applied rather than reopening the session.
1972
1973
  outcome = 'applied';
1973
1974
  });
1974
1975
  return outcome;
@@ -2800,14 +2801,14 @@ async function integrateWrunLiveTail(tail) {
2800
2801
  return 'applied';
2801
2802
  }
2802
2803
  /**
2803
- * The live hold (LIVE-UPDATES-WAIT): while the chart is held (the engine's gesture live hold or motion mode, or its
2804
- * release backlog still draining) the WHOLE apply phase of this integrate waits in the engine's ordered ingest log as
2805
- * one host unit owned by the overlay: the parent's live ladder, the child overlays (their pack wait included), the
2806
- * presentation, the painted watermark and repaint bookkeeping, and the failure path. Nothing of it runs now, so no
2807
- * mounted row (the parent's or a lower-pane child's) moves under the hold and nothing is presented before its rows
2808
- * land. The door is the chart's own `enqueueHeldHostApply` (the one gesture-motion-host.util `enqueueHeldOverlayApply`
2809
- * calls; the package reaches the chart, not that module): it answers false when nothing is held, and inside a
2810
- * replayed unit, and the integrate then runs in the tick as before. True when the log took the unit.
2804
+ * Ordered behind the overlay's queued updates: while the engine's ingest queue still holds updates of this overlay
2805
+ * (a gesture's sliced ingest), the WHOLE apply phase of this integrate waits behind them as one host unit owned by
2806
+ * the overlay: the parent's live ladder, the child overlays (their pack wait included), the presentation, the
2807
+ * painted watermark and repaint bookkeeping, and the failure path. Nothing of it runs now, so no mounted row (the
2808
+ * parent's or a lower-pane child's) moves before the queued updates land. The door is the chart's own
2809
+ * `enqueueHeldHostApply` (live-feed.service.ts `enqueueHeldOverlayApply` calls the same door; the package reaches
2810
+ * the chart): it answers false when nothing of the overlay is queued, and inside a queued unit, and the integrate
2811
+ * then runs in the tick as before. True when the queue took the unit.
2811
2812
  */
2812
2813
  function deferWrunLiveTailWhileHeld(tail) {
2813
2814
  const door = tail.tc.enqueueHeldHostApply;
@@ -2821,11 +2822,11 @@ function deferWrunLiveTailWhileHeld(tail) {
2821
2822
  }
2822
2823
  }
2823
2824
  /**
2824
- * The held unit at the replay. The tick's apply gates are read again (the context and its generation, replay, pause
2825
+ * The queued unit when it runs. The tick's apply gates are read again (the context and its generation, replay, pause
2825
2826
  * or a tripped guard, the market identity, protection, the pane budget), and the chart must still be the tick's chart
2826
2827
  * mounting the tick's meta under the overlay id (a remount without a generation bump hands a fresh meta): a failing
2827
2828
  * recheck drops the unit, nothing applied. The integrate starts inside the engine's drain, in order with the overlay's
2828
- * other held units; it does not take the session lock (that wait is a promise, and the parent's apply must land inside
2829
+ * other queued units; it does not take the session lock (that wait is a promise, and the parent's apply must land inside
2829
2830
  * the unit), and a tick holding the lock meanwhile defers its own apply behind it while the engine still drains. A
2830
2831
  * failure runs the tick's own failure path: the repaint stays owed and a classified refusal is said once.
2831
2832
  */
@@ -2841,11 +2842,11 @@ function replayWrunLiveTail(tail) {
2841
2842
  // The tick's clock stopped with the tick: the replay is its own apply sample.
2842
2843
  const mainClock = new MainThreadClock();
2843
2844
  void integrateWrunLiveTailNow({ ...tail, mainClock, hostStartMs: mainClock.read() }).catch((error) => {
2844
- console.warn(`[wrun] held live apply failed for '${indicatorId}' (keeping the last rendered result):`, error);
2845
+ console.warn(`[wrun] queued live apply failed for '${indicatorId}' (keeping the last rendered result):`, error);
2845
2846
  void noteWrunLiveTickRefusal(context, ledger, generation, error);
2846
2847
  });
2847
2848
  }
2848
- /** The integrate itself, now (`integrateWrunLiveTail` decides whether it waits for the hold first). */
2849
+ /** The integrate itself, now (`integrateWrunLiveTail` decides whether it waits behind queued updates first). */
2849
2850
  async function integrateWrunLiveTailNow(tail) {
2850
2851
  const { context, ledger, generation, tc, meta, outputRows, newestTs, tailFromTs, framesReplaced, holdsResult, evicted = false, runSession, mainClock, hostStartMs, cellRowsOf, } = tail;
2851
2852
  const { indicatorId } = context;
@@ -2930,6 +2931,8 @@ async function integrateWrunLiveTailNow(tail) {
2930
2931
  ...(hostFill.tickSize !== undefined ? { priceTick: hostFill.tickSize } : {}),
2931
2932
  ...(canvasFill.tpoBlockSize !== undefined ? { tpoBlockSize: canvasFill.tpoBlockSize } : {}),
2932
2933
  overlayId: indicatorId,
2934
+ // A built-in's port names its lines in its built-in's words, as its full run did (wrun-output-words.util).
2935
+ builtIn: builtinPortOf(meta.settings),
2933
2936
  };
2934
2937
  const projection = runSession
2935
2938
  ? wrunRunIntervalProjectionOf(runSession.run, context.chartIndex, context.market?.exchange)
@@ -2984,6 +2987,10 @@ async function integrateWrunLiveTailNow(tail) {
2984
2987
  // The canvases' rows since the bar they last painted (or swapped whole).
2985
2988
  ...canvasPass.mount,
2986
2989
  ...(projection ? { projection } : {}),
2990
+ // What the session computed these rows for (its full run's settings generation and market, never the
2991
+ // settings' current ones: a save leaves the session ticking until its rerun installs): an eviction's or a
2992
+ // gap's swap, or a window that rolled past the mounted rows, keeps each heatmap's colour scale.
2993
+ pictureIdentity: wrunPictureIdentityOf(context),
2987
2994
  // OT29: the lower pane's legend prints prices at the chart's digits.
2988
2995
  priceDigits: () => wrunChartPriceDigits(context.chartIndex) ?? priceDigits ?? 2,
2989
2996
  onMainThreadMs: (ms) => mainClock.add(ms),
@@ -0,0 +1,14 @@
1
+ import type { WrunMetadataOutput } from '../../interfaces/wrun-runtime.interface.js';
2
+ /** The sheet facts an output's words read. */
3
+ export type WrunOutputWordsSubject = Pick<WrunMetadataOutput, 'name' | 'label'>;
4
+ /** The words `output` reads on a chart surface of an overlay that ports built-in `builtIn` (undefined for any other
5
+ * package): a line its built-in names reads the built-in's words, every other line the legend's rule (wrunLegendName:
6
+ * the declared label, else the name read as words). */
7
+ export declare function wrunOutputWords(output: WrunOutputWordsSubject, builtIn: string | undefined): string;
8
+ /** Whether declared `words` name `output` by its own sheet label or name: an author restating the line in a card. */
9
+ export declare function wrunWordsRestateOutput(words: string, output: WrunOutputWordsSubject): boolean;
10
+ /** The words a declaration that names `output` prints (a hover block's or a ring's `label`, a rows block's row label),
11
+ * declared as `words`: words that restate the line (wrunWordsRestateOutput) read the built-in's words for it when the
12
+ * overlay's built-in names it, like the line itself; any other words are the author's and stay as written ("Overbought
13
+ * / oversold" over MFI's meter). */
14
+ export declare function wrunDeclaredOutputWords(words: string, output: WrunOutputWordsSubject | undefined, builtIn: string | undefined): string;
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The words a chart surface names a wrun output by (TWIN-LEGEND, Kyle 2026-11-08): the one rule the legend's line
3
+ * names (the run result's `labels`, wrun-run-result.util, which the legend, the data window and a lower pane's legend
4
+ * read), the hover cards (wrun-hover.util) and the silent-output chip (wrun-run-health.util) read.
5
+ *
6
+ * A proven twin's sheet keeps each line's kScript label as the output's `label` (MACD's `macdLine` and `signalLine`,
7
+ * Bollinger Bands' `UpperBand` and `Lower Band`, ADX's `DiPlus`): that label is the built-in's contract output, the
8
+ * anchor its alerts and stored settings match the line by, so the sheet cannot reword it. The legend's rule prints a
9
+ * declared label as written (wrunLegendName), so every chart surface printed those ids. For an overlay that ports a
10
+ * built-in (`builtIn`: builtinPortOf over its settings, the `builtinTwinOf` stamp, else the package's own port), a line
11
+ * its built-in names reads the built-in's own words in the viewer's language, the words its alert pickers, its card and
12
+ * its settings page already show. The host answers them (the env's `builtinLineWords`; web: `builtinOutputI18nKey`
13
+ * through the i18n plugin), so this package holds no built-in's vocabulary. Any other package, any line the built-in
14
+ * does not name (a guide level, a data-only helper) and a host without the member keep the legend's rule. The sheet,
15
+ * the output keys, the plot ids and every binding keep the label as published: only the words a user reads change.
16
+ */
17
+ import { wrunHostBuiltinLineWords } from '../../host-env.js';
18
+ import { wrunLegendName } from '../chart/wrun-legend-name.util.js';
19
+ /** The built-in's words for `output`, or undefined: no built-in, no sheet label, or a line the built-in does not
20
+ * name (the host answers nothing). */
21
+ function builtinWordsFor(output, builtIn) {
22
+ if (builtIn === undefined || typeof output.label !== 'string')
23
+ return undefined;
24
+ return wrunHostBuiltinLineWords(builtIn, output.label);
25
+ }
26
+ /** The words `output` reads on a chart surface of an overlay that ports built-in `builtIn` (undefined for any other
27
+ * package): a line its built-in names reads the built-in's words, every other line the legend's rule (wrunLegendName:
28
+ * the declared label, else the name read as words). */
29
+ export function wrunOutputWords(output, builtIn) {
30
+ return builtinWordsFor(output, builtIn) ?? wrunLegendName(output.name, output.label);
31
+ }
32
+ /** A name's letters, case, spaces, `_` and `-` aside ("Upper band", `UpperBand` and `upper_band` alike). */
33
+ function letters(words) {
34
+ return words.toLowerCase().replace(/[\s_-]+/g, '');
35
+ }
36
+ /** Whether declared `words` name `output` by its own sheet label or name: an author restating the line in a card. */
37
+ export function wrunWordsRestateOutput(words, output) {
38
+ const said = letters(words);
39
+ if (said === '')
40
+ return false;
41
+ return said === letters(output.name) || (typeof output.label === 'string' && said === letters(output.label));
42
+ }
43
+ /** The words a declaration that names `output` prints (a hover block's or a ring's `label`, a rows block's row label),
44
+ * declared as `words`: words that restate the line (wrunWordsRestateOutput) read the built-in's words for it when the
45
+ * overlay's built-in names it, like the line itself; any other words are the author's and stay as written ("Overbought
46
+ * / oversold" over MFI's meter). */
47
+ export function wrunDeclaredOutputWords(words, output, builtIn) {
48
+ if (output === undefined || !wrunWordsRestateOutput(words, output))
49
+ return words;
50
+ return builtinWordsFor(output, builtIn) ?? words;
51
+ }