@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
@@ -449,6 +449,11 @@ export interface WrunOverlayLiveContext {
449
449
  * it): they carry no `coveredThroughTs`, so the reconcile keeps asking
450
450
  * their tail while the source ladder owns the window. */
451
451
  degradedLanes?: ReadonlySet<string>;
452
+ /** The full run that installed the session drew a partial picture: over a row lane's first-paint slice (its older
453
+ * bars still loading) or a lane degraded to empty. The fill's or the recovery's run (a whole run of the same
454
+ * settings and market) installs the session that completes it, so this session's passes name no picture
455
+ * (`wrunPictureIdentityOf`): none of its ticks, reseeds or refines stamps a partial heatmap scale as final. */
456
+ picturePartial?: true;
452
457
  /** The row-builder lanes the capability rule (`wrunUnservedLanes`) kept from
453
458
  * dispatch on the session's market (the run pass writes it): never fetched,
454
459
  * their buffers empty, every reader reading its fill on every row. The
@@ -612,6 +617,42 @@ export declare function wrunChartMarketIdentity(metadata: {
612
617
  transformations?: unknown;
613
618
  sessionType?: unknown;
614
619
  } | null | undefined): string;
620
+ /** What a pass's rows were computed for (`wrunPictureIdentityOf`), the only spelling a pass hands the child mount. */
621
+ export type WrunPictureIdentity = string & {
622
+ readonly __wrunPictureIdentity: true;
623
+ };
624
+ /**
625
+ * The picture a pass's rows show, as the run or the live session that computed them knew it: the compute settings
626
+ * revision (`kScriptSettingsRevision`, C1) and the market identity (`wrunChartMarketIdentity`). The one derivation
627
+ * every caller of the child mount hands it (wrun-panel-mount.util `pictureIdentity`: a mounted heatmap keeps its
628
+ * colour scale through a pass of the picture that decided it): a full run from what it computed with
629
+ * (`computed.generation` and its own market identity), a live session's passes (a tick, a reseed, a refine, a style
630
+ * repaint, an adoption) from the session's `settingsRevision` and `marketIdentity`, which its full run stamped at
631
+ * install.
632
+ *
633
+ * Why these two facts and nothing else (2026-11-07, Kyle's "decide the scale once per load, then never move it on its
634
+ * own"): every save that changes what the module computes or reads bumps the revision (a param, a symbol or text
635
+ * param, a Timeframe, a pin, a `style_targets` param such as one bound to a heatmap's quantile), while a paint-only
636
+ * save never does (a Style row, an om style knob, the Sensitivity row itself, a window split, an eye), so presentation
637
+ * keys are never identity and no list of keys can drift. The market identity covers the symbol, the interval, the
638
+ * exchange, the transformations, the session and the candle source. The script itself: an editor draft's Run replaces
639
+ * the parent overlay (its children unmount and install afresh) and a version change is a compute save. The facts are
640
+ * the rows' own, never the settings' current ones: a save leaves the session ticking on the previous computation until
641
+ * its rerun installs, and those ticks hand the session's identity, so no scale is ever decided from them under the new
642
+ * picture.
643
+ *
644
+ * Undefined when the market is unknown (a context stored before the field existed), and for a partial picture
645
+ * (`picturePartial`: a run, or the session it installed, that drew over a row lane's first-paint slice or a lane
646
+ * degraded to empty): the fill's or the recovery's run is a whole run of the same revision and market, so a scale
647
+ * decided from the slice under the final identity would be carried onto the whole history (the seed freeze the
648
+ * options heatmap's `seed` stage avoids). Every heatmap a pass without a picture rebuilds decides its scale again and
649
+ * stamps none, the rule before the hold, so the completing run decides and holds.
650
+ */
651
+ export declare function wrunPictureIdentityOf(source: {
652
+ settingsRevision?: number;
653
+ marketIdentity?: string;
654
+ picturePartial?: boolean;
655
+ }): WrunPictureIdentity | undefined;
615
656
  export declare function registerWrunOverlayDriver(indicatorId: string, driver: WrunOverlayDriver): void;
616
657
  export declare function hasWrunOverlayDriver(indicatorId: string): boolean;
617
658
  /** Marked by the shared run pass after a successful integrate, whatever
@@ -445,6 +445,38 @@ export function wrunChartMarketIdentity(metadata) {
445
445
  terms.push(`${rows.exchange}:${rows.symbol}`);
446
446
  return terms.map((part) => (part === undefined || part === null ? '' : String(part))).join('|');
447
447
  }
448
+ /**
449
+ * The picture a pass's rows show, as the run or the live session that computed them knew it: the compute settings
450
+ * revision (`kScriptSettingsRevision`, C1) and the market identity (`wrunChartMarketIdentity`). The one derivation
451
+ * every caller of the child mount hands it (wrun-panel-mount.util `pictureIdentity`: a mounted heatmap keeps its
452
+ * colour scale through a pass of the picture that decided it): a full run from what it computed with
453
+ * (`computed.generation` and its own market identity), a live session's passes (a tick, a reseed, a refine, a style
454
+ * repaint, an adoption) from the session's `settingsRevision` and `marketIdentity`, which its full run stamped at
455
+ * install.
456
+ *
457
+ * Why these two facts and nothing else (2026-11-07, Kyle's "decide the scale once per load, then never move it on its
458
+ * own"): every save that changes what the module computes or reads bumps the revision (a param, a symbol or text
459
+ * param, a Timeframe, a pin, a `style_targets` param such as one bound to a heatmap's quantile), while a paint-only
460
+ * save never does (a Style row, an om style knob, the Sensitivity row itself, a window split, an eye), so presentation
461
+ * keys are never identity and no list of keys can drift. The market identity covers the symbol, the interval, the
462
+ * exchange, the transformations, the session and the candle source. The script itself: an editor draft's Run replaces
463
+ * the parent overlay (its children unmount and install afresh) and a version change is a compute save. The facts are
464
+ * the rows' own, never the settings' current ones: a save leaves the session ticking on the previous computation until
465
+ * its rerun installs, and those ticks hand the session's identity, so no scale is ever decided from them under the new
466
+ * picture.
467
+ *
468
+ * Undefined when the market is unknown (a context stored before the field existed), and for a partial picture
469
+ * (`picturePartial`: a run, or the session it installed, that drew over a row lane's first-paint slice or a lane
470
+ * degraded to empty): the fill's or the recovery's run is a whole run of the same revision and market, so a scale
471
+ * decided from the slice under the final identity would be carried onto the whole history (the seed freeze the
472
+ * options heatmap's `seed` stage avoids). Every heatmap a pass without a picture rebuilds decides its scale again and
473
+ * stamps none, the rule before the hold, so the completing run decides and holds.
474
+ */
475
+ export function wrunPictureIdentityOf(source) {
476
+ if (source.marketIdentity === undefined || source.picturePartial === true)
477
+ return undefined;
478
+ return `${source.settingsRevision ?? 0}|${source.marketIdentity}`;
479
+ }
448
480
  export function registerWrunOverlayDriver(indicatorId, driver) {
449
481
  const existing = drivers.get(indicatorId);
450
482
  if (existing) {
@@ -73,6 +73,11 @@ export interface WrunOverlayResultOptions {
73
73
  legendNote?: string;
74
74
  /** A live tick's build memo (wrun-build-memo.util); full runs, reseeds and pans leave it absent. */
75
75
  buildMemo?: WrunBuildMemo;
76
+ /** The built-in the overlay ports (builtinPortOf over its settings), whose words name the lines it names in the
77
+ * result's `labels` (wrun-run-result.util `builtIn`); undefined for any other package. Required, so every build of
78
+ * the overlay (a full run's integrate, a prefix landing, a live tick, and any build added later) states it and a
79
+ * tick never flips a line's words back to the sheet's ids (TWIN-LEGEND). */
80
+ builtIn: string | undefined;
76
81
  }
77
82
  /**
78
83
  * The price canvases' host fill (WRUN guardrails G1, read by the auto row
@@ -113,7 +118,7 @@ export declare const WRUN_RESULT_CAPTURE_LIMIT = 8;
113
118
  * of trades behind it, more than a rig's process holds (2026-10-17: the TIP corpus run died at 4 GB on the eighth
114
119
  * package). A key added to the options must be added here, or the type below fails to compile.
115
120
  */
116
- export declare const WRUN_OVERLAY_RESULT_OPTION_KEYS: readonly ["metadata", "outputRows", "title", "params", "texts", "position", "axis", "colors", "fills", "candles", "chartNames", "runTimeline", "priceDigits", "sizeUnit", "valuePerUnit", "cellRows", "canvasTailRows", "batchedTailFromTs", "intervalMs", "exchange", "priceTick", "overlayId", "tpoBlockSize", "legendNote"];
121
+ export declare const WRUN_OVERLAY_RESULT_OPTION_KEYS: readonly ["metadata", "outputRows", "title", "params", "texts", "position", "axis", "colors", "fills", "candles", "chartNames", "runTimeline", "priceDigits", "sizeUnit", "valuePerUnit", "cellRows", "canvasTailRows", "batchedTailFromTs", "intervalMs", "exchange", "priceTick", "overlayId", "tpoBlockSize", "legendNote", "builtIn"];
117
122
  /**
118
123
  * Record one build on a corpus lane's page (`globalThis.__omRig === true` and the store `__wrunResultCapture` the lane
119
124
  * created before the app loaded) under `__wrunResultCapture[<overlay id, else the title>]`, newest last, the last
@@ -72,6 +72,7 @@ export function buildWrunOverlayRunResult(options) {
72
72
  // G1: the served TPO block, only when known.
73
73
  ...withCanvasHostFill(options),
74
74
  ...(options.buildMemo !== undefined ? { buildMemo: options.buildMemo } : {}),
75
+ ...(options.builtIn !== undefined ? { builtIn: options.builtIn } : {}),
75
76
  });
76
77
  if (wrunResultCaptureStore() !== undefined)
77
78
  captureWrunOverlayResult(options, result);
@@ -177,6 +178,7 @@ export const WRUN_OVERLAY_RESULT_OPTION_KEYS = [
177
178
  'overlayId',
178
179
  'tpoBlockSize',
179
180
  'legendNote',
181
+ 'builtIn',
180
182
  ];
181
183
  const WRUN_OPTION_KEYS_COMPLETE = true;
182
184
  /**
@@ -78,7 +78,7 @@ import { type WrunRefusalAttemptToken, type WrunRefusalContext, type WrunRefusal
78
78
  import { type WrunHostFillContext } from './wrun-script-inputs.util.js';
79
79
  import { type WrunDownloadMeterPort, type WrunDownloadSummary } from './wrun-download-meter.util.js';
80
80
  import type { WrunLatestSnapshot } from './wrun-latest-snapshot.js';
81
- import { wrunChartMarketIdentity, type WrunOverlayLiveContext, type WrunWarmupMiss } from './wrun-overlay-drivers.util.js';
81
+ import { wrunChartMarketIdentity, type WrunOverlayLiveContext, type WrunPictureIdentity, type WrunWarmupMiss } from './wrun-overlay-drivers.util.js';
82
82
  import { type KScriptProvenanceSettingsLike } from '../chart/kscript-venue-policy.util.js';
83
83
  import type { WrunLegCandleClose } from '@orangecharts/indicator-kit/host';
84
84
  import { type WrunPassRowSource } from './wrun-row-source-factory.js';
@@ -1149,7 +1149,7 @@ export interface WrunIntegrationFacts {
1149
1149
  * design 5): a mount that reaches before it is replaced, never merged onto. */
1150
1150
  retainedFromTs?: number;
1151
1151
  }
1152
- export type WrunIntegrateOptions = WrunOverlayResultOptions & {
1152
+ export type WrunIntegrateOptions = Omit<WrunOverlayResultOptions, 'builtIn'> & {
1153
1153
  tc: unknown;
1154
1154
  meta: Record<string, unknown>;
1155
1155
  indicatorId: string;
@@ -1161,6 +1161,12 @@ export type WrunIntegrateOptions = WrunOverlayResultOptions & {
1161
1161
  /** The clamped window the rows were computed over: a partial one keeps the mounted rows outside
1162
1162
  * it on a remount. */
1163
1163
  window?: WrunRunWindow;
1164
+ /** What the rows were computed for (`wrunPictureIdentityOf`: a full run's `computed.generation` and market
1165
+ * identity, a live session's `settingsRevision` and `marketIdentity`), handed to the child mount: a mounted
1166
+ * heatmap keeps the colour scale on screen through a pass of the picture that decided it and decides it again
1167
+ * on another. Required, so no integrate leaves it out by accident; undefined (an unknown market) decides every
1168
+ * heatmap scale again, the rule before the hold. */
1169
+ pictureIdentity: WrunPictureIdentity | undefined;
1164
1170
  /** The full run's route facts; absent, the result remounts (a reseed, a direct caller). */
1165
1171
  integration?: WrunIntegrationFacts;
1166
1172
  /** A settings gesture's preview (the style patch's session repaint, wrun-style-preview.util): the overlay's
@@ -174,7 +174,7 @@ import { FeatureFlag } from '../../constants/feature-flags.constants.js';
174
174
  import { clearedColorCustomizationFlags } from '../chart/color-customization.leaf.js';
175
175
  import { WRUN_LATEST_HISTORY_LENGTH } from './wrun-latest-history.leaf.js';
176
176
  import { resolveChartPricePrecision } from '../chart/price-precision.util.js';
177
- import { currentWrunOverlayLiveGeneration, getWrunOverlayLiveContext, hasQueuedWrunUserRun, isWrunOverlayFullRerunInFlight, isWrunOverlayReplacementPending, markWrunOverlayComputeSucceeded, nextWrunOverlayLiveGeneration, noteWrunOverlayRunSettle, noteWrunOverlayWholeWindowDrawn, onWrunChartTeardown, onWrunOverlayLiveTeardown, rerunWrunOverlayForChartWave, setWrunOverlayLiveContext, setWrunPrefixRuntime, setWrunUnansweredDropSurface, suspendWrunOverlayLiveSession, withWrunOverlaySessionLock, wrunChartMarketIdentity, } from './wrun-overlay-drivers.util.js';
177
+ import { currentWrunOverlayLiveGeneration, getWrunOverlayLiveContext, hasQueuedWrunUserRun, isWrunOverlayFullRerunInFlight, isWrunOverlayReplacementPending, markWrunOverlayComputeSucceeded, nextWrunOverlayLiveGeneration, noteWrunOverlayRunSettle, noteWrunOverlayWholeWindowDrawn, onWrunChartTeardown, onWrunOverlayLiveTeardown, rerunWrunOverlayForChartWave, setWrunOverlayLiveContext, setWrunPrefixRuntime, setWrunUnansweredDropSurface, suspendWrunOverlayLiveSession, withWrunOverlaySessionLock, wrunChartMarketIdentity, wrunPictureIdentityOf, } from './wrun-overlay-drivers.util.js';
178
178
  import { __resetWrunInstallPacerForTests, admitWrunInstall, dropWrunInstallPacer, noteWrunInstallWrite, wrunInstallLastAdmission, } from './wrun-install-pacer.util.js';
179
179
  import { claimWrunWarmupHead, readWrunWarmupHeadBars, readWrunWarmupHeadSpan, storeWrunWarmupHeadSpan, wrunWarmupHeadStored, } from './wrun-warmup-head-store.util.js';
180
180
  import { protectedKScriptMountedRowCount } from '../chart/protected-kscript-empty-output.util.js';
@@ -1677,7 +1677,9 @@ export function wrunChartRunHealth(metadata, settings, outputRows, sourceAbsent,
1677
1677
  ...output,
1678
1678
  visible: wrunOutputShownOnChart(output, settings, owned) && wrunRowVisibleHere(output.visible_by, sizeUnit),
1679
1679
  })),
1680
- }, outputRows);
1680
+ }, outputRows,
1681
+ // The chip names a silent line by the words the legend does: a built-in's port in its built-in's words.
1682
+ builtinPortOf(settings));
1681
1683
  if (!sourceAbsent || watched.silentOutputs.length === 0)
1682
1684
  return { watched, health: watched };
1683
1685
  return {
@@ -6219,6 +6221,11 @@ async function integrateWrunRunAsk(runTarget, tc, meta, refusal, computed, owner
6219
6221
  // run's copy only), so the live context's ticks and reseeds plan the legs this run fetched.
6220
6222
  const sheetNow = wrunSheetWithRespelledPins(wrunSheetWithSettings(runTarget.metadata, meta.settings), respelledPins);
6221
6223
  assertWrunRunMayPaint(target.chartIndex, target.indicatorId, replay);
6224
+ // A picture over a lane still filling (a row lane's first-paint slice, its older bars loading) or degraded to
6225
+ // empty is not final: the fill's or the recovery's run (a whole run, same generation and market) completes it.
6226
+ // It names no picture, and neither does the session it installs, so no heatmap scale decided from the partial
6227
+ // rows is held as the final picture's (wrunPictureIdentityOf).
6228
+ const picturePartial = fillingLanes.length > 0 || degraded.length > 0;
6222
6229
  const integrateOptions = {
6223
6230
  tc,
6224
6231
  meta,
@@ -6226,6 +6233,9 @@ async function integrateWrunRunAsk(runTarget, tc, meta, refusal, computed, owner
6226
6233
  indicatorId: target.indicatorId,
6227
6234
  metadata: sheetNow,
6228
6235
  outputRows,
6236
+ // What these rows were computed for (the settings generation and the market the run read, the live
6237
+ // context's identity below): a mounted heatmap keeps its colour scale through a rerun of the same picture.
6238
+ pictureIdentity: wrunPictureIdentityOf({ settingsRevision: computed.generation, marketIdentity, picturePartial }),
6229
6239
  params: paramValues,
6230
6240
  title: target.title,
6231
6241
  position: target.position,
@@ -6661,6 +6671,8 @@ async function integrateWrunRunAsk(runTarget, tc, meta, refusal, computed, owner
6661
6671
  // degraded ones, and the ones the capability rule never dispatched.
6662
6672
  ...(window ? { window } : {}),
6663
6673
  ...(degradedLanes.size > 0 ? { degradedLanes } : {}),
6674
+ // The run drew a partial picture (a filling or degraded lane): the session's passes name none either.
6675
+ ...(picturePartial ? { picturePartial: true } : {}),
6664
6676
  ...(unservedLanes.length > 0 || unservedTradeLegs.size > 0
6665
6677
  ? { unservedLanes: new Set([...unservedLanes, ...unservedTradeLegs]) }
6666
6678
  : {}),
@@ -7266,6 +7278,8 @@ async function integrateWrunRowSourceBatch(asked, tc, meta, refusal, computed, o
7266
7278
  indicatorId,
7267
7279
  metadata: sheetNow,
7268
7280
  outputRows,
7281
+ // What the batch was computed for, as on the browser lane (the session installs the same identity).
7282
+ pictureIdentity: wrunPictureIdentityOf({ settingsRevision: computed.generation, marketIdentity }),
7269
7283
  params: paramValues,
7270
7284
  title: runTarget.title,
7271
7285
  position: runTarget.position,
@@ -9181,6 +9195,8 @@ export async function reseedWrunOverlayFromBuffers(indicatorId, reason, options
9181
9195
  indicatorId,
9182
9196
  metadata: context.metadata,
9183
9197
  outputRows,
9198
+ // The session's own picture: a reseed redraws what the session computed, so a heatmap keeps its scale.
9199
+ pictureIdentity: wrunPictureIdentityOf(context),
9184
9200
  title: context.title,
9185
9201
  position: context.position,
9186
9202
  axis: context.axis,
@@ -10551,6 +10567,8 @@ async function reintegrateWrunSession(indicatorId, context, fill, current, optio
10551
10567
  indicatorId,
10552
10568
  metadata: context.metadata,
10553
10569
  outputRows: context.outputRows,
10570
+ // The session's own picture: a refine or a style repaint redraws what the session computed.
10571
+ pictureIdentity: wrunPictureIdentityOf(context),
10554
10572
  title: context.title,
10555
10573
  position: context.position,
10556
10574
  axis: context.axis,
@@ -10921,6 +10939,8 @@ export async function adoptWrunParkedLiveSession(parked, target) {
10921
10939
  indicatorId,
10922
10940
  metadata: context.metadata,
10923
10941
  outputRows: context.outputRows,
10942
+ // The parked session's own picture (the adoption refused a session whose identity moved).
10943
+ pictureIdentity: wrunPictureIdentityOf(context),
10924
10944
  prebuilt: shown.runResult,
10925
10945
  title: context.title,
10926
10946
  position: context.position,
@@ -11403,7 +11423,7 @@ function wrunIntegrationErrorOf(diagnostics) {
11403
11423
  * carried a window (a pan wave's, clamped or the whole loaded range) hands it as the
11404
11424
  * `historyWindow`: a mounted heatmap then merges the run's rows inside that window and keeps the
11405
11425
  * rest (wrun-panel-mount.util), so a pan-back page lands. */
11406
- function mergeWrunChildOverlays(tc, indicatorId, runResult, projection, priceDigits, childMount, chartIndex, historyWindow) {
11426
+ function mergeWrunChildOverlays(tc, indicatorId, runResult, projection, priceDigits, childMount, pictureIdentity, chartIndex, historyWindow) {
11407
11427
  const children = runResult.childOverlays;
11408
11428
  if (children === undefined)
11409
11429
  return;
@@ -11441,6 +11461,7 @@ function mergeWrunChildOverlays(tc, indicatorId, runResult, projection, priceDig
11441
11461
  replaceFrames: false,
11442
11462
  ...(historyWindow ? { historyWindow } : {}),
11443
11463
  ...(projection ? { projection } : {}),
11464
+ ...(pictureIdentity !== undefined ? { pictureIdentity } : {}),
11444
11465
  ...(priceDigits ? { priceDigits } : {}),
11445
11466
  onMainThreadMs: (ms) => {
11446
11467
  childMount.applyMs += ms;
@@ -11547,6 +11568,9 @@ function integrateWrunRunThroughRouteOnce(options, childMount) {
11547
11568
  texts: options.texts ?? wrunTextParamValuesFromSettings(options.metadata, options.meta.settings),
11548
11569
  // An editor draft's legend says it is one (and only in this browser); the tick repeats it.
11549
11570
  legendNote: options.legendNote ?? wrunDraftLegendNote(options.meta.settings),
11571
+ // A built-in's port names its lines in its built-in's words (wrun-output-words.util): builtinPortOf, the
11572
+ // resolver the alert words and the settings page read (the `builtinTwinOf` stamp, else the package's port).
11573
+ builtIn: builtinPortOf(options.meta.settings),
11550
11574
  ...(options.projection ? { runTimeline: true } : {}),
11551
11575
  ...(priceDigits !== undefined ? { priceDigits } : {}),
11552
11576
  overlayId: options.overlayId ?? options.indicatorId,
@@ -11638,6 +11662,7 @@ function integrateWrunRunThroughRouteOnce(options, childMount) {
11638
11662
  runResult,
11639
11663
  ...(partialSpan ? { historyWindow: partialSpan } : {}),
11640
11664
  ...(projection ? { projection } : {}),
11665
+ ...(options.pictureIdentity !== undefined ? { pictureIdentity: options.pictureIdentity } : {}),
11641
11666
  ...(childPriceDigits ? { priceDigits: childPriceDigits } : {}),
11642
11667
  onMainThreadMs: (ms) => {
11643
11668
  childMount.applyMs += ms;
@@ -11666,7 +11691,7 @@ function integrateWrunRunThroughRouteOnce(options, childMount) {
11666
11691
  if (!refresh.ok)
11667
11692
  throw wrunIntegrationErrorOf(refresh.diagnostics);
11668
11693
  if (refresh.applied) {
11669
- mergeWrunChildOverlays(tc, indicatorId, runResult, projection, childPriceDigits, childMount, options.chartIndex, runSpan);
11694
+ mergeWrunChildOverlays(tc, indicatorId, runResult, projection, childPriceDigits, childMount, options.pictureIdentity, options.chartIndex, runSpan);
11670
11695
  render();
11671
11696
  return true;
11672
11697
  }
@@ -13998,6 +14023,8 @@ async function prepareWrunPrefixRun(runTarget, tc, meta, window, landings, start
13998
14023
  ...withPriceTick(hostFill.tickSize),
13999
14024
  ...withCanvasHostFill(wrunSessionCanvasFillOf(context)),
14000
14025
  overlayId: indicatorId,
14026
+ // The words the full run's integrate names a built-in port's lines by, so the landed window reads the same.
14027
+ builtIn: builtinPortOf(meta.settings),
14001
14028
  };
14002
14029
  let runResult = buildWrunOverlayRunResult(resultOptions);
14003
14030
  if (runResult.failureReason !== undefined)
@@ -2,6 +2,7 @@ import { type KScriptLegendEntry } from '../chart/kscript-legend-entries.util.js
2
2
  import { type EnginePanelHooks } from '../chart/om-panel.util.js';
3
3
  import { WRUN_WINDOW_TABLES_ONLY_SETTING } from '../chart/window-geometry.leaf.js';
4
4
  import { wrunSeriesChildId, type WrunRunResult } from '../chart/wrun-run-result.util.js';
5
+ import type { WrunPictureIdentity } from './wrun-overlay-drivers.util.js';
5
6
  import { type WrunBuiltinTwin, type WrunPaneFormatChart } from './wrun-pane-format.util.js';
6
7
  import type { WrunRunIntervalProjection } from './wrun-run-interval-projection.types.js';
7
8
  interface WrunOverlayConfig {
@@ -314,7 +315,7 @@ export { WRUN_WINDOW_TABLES_ONLY_SETTING };
314
315
  * precision (OT29, X7): the panels' formatters and the lower pane's legend
315
316
  * print "price" values with it. A tick's heatmap tail (`tailOnly`) only
316
317
  * ever merges its rows into a mounted canvas. */
317
- export declare function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames, swapCanvasRows, canvasRowsFromTs, historyWindow, projection, cell, priceDigits, onMainThreadMs, chartIndex, }: {
318
+ export declare function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames, swapCanvasRows, canvasRowsFromTs, historyWindow, projection, pictureIdentity, cell, priceDigits, onMainThreadMs, chartIndex, }: {
318
319
  tc: WrunChildOverlayChart;
319
320
  overlayId: string;
320
321
  runResult: WrunRunResult;
@@ -346,6 +347,13 @@ export declare function mountWrunChildOverlays({ tc, overlayId, runResult, repla
346
347
  historyWindow?: WrunChildHistoryWindow;
347
348
  /** The parent ran at another interval: its series child projects the same way. */
348
349
  projection?: WrunRunIntervalProjection;
350
+ /** What the pass's rows were computed for (`wrunPictureIdentityOf`: the run's or the session's compute settings
351
+ * revision and market identity). A mounted heatmap decides its colour scale at its install and at the first
352
+ * whole-window pass (a run's, a swap, a window that rolled past its rows) of another picture; a whole-window pass
353
+ * of the picture that decided it keeps the bounds on screen and the sample a Sensitivity re-pick reads, while
354
+ * its rows swap as before (`holdsHeatmapScale`). A merge never moves the scale. Absent, every whole-window pass
355
+ * decides again, the rule before the hold. */
356
+ pictureIdentity?: WrunPictureIdentity;
349
357
  /** The cell the mount lands on (WrunMountCell); the parent's owner flag decides when absent. */
350
358
  cell?: WrunMountCell;
351
359
  /** The chart's price digits, read per call (the symbol may change). */
@@ -37,7 +37,12 @@
37
37
  * await: prepareWrunHeatmapWindowLanding),
38
38
  * matrices frame-backed like levels; a heatmap takes the viewer's
39
39
  * Sensitivity at this door (`rescaleWrunHeatmapChildren` re-picks the mounted
40
- * bounds with no run). Batched marks (WRUN-BATCHED-MARKS: marks, spans and
40
+ * bounds with no run). A heatmap's colour scale is decided once per picture
41
+ * (the picture identity a pass hands, `wrunPictureIdentityOf`): at its install
42
+ * or at the first whole-window pass of another picture; every other pass keeps
43
+ * the decided bounds and the sample a Sensitivity re-pick reads, while its rows
44
+ * swap or merge as before (`carryHeatmapScale`). Batched marks
45
+ * (WRUN-BATCHED-MARKS: marks, spans and
41
46
  * rays children) are row-backed like heatmaps: a tick merges every row it
42
47
  * re-evaluated, row by row; a windowed run lands inside its window; the engine
43
48
  * gate refuses a kind the chart cannot draw by name; their own cell budget
@@ -56,7 +61,7 @@ import { ownerPaneDrawsNothing, planWindowWeights, reconcileWindowOwnerGeometry,
56
61
  import { wrunLegendName } from '../chart/wrun-legend-name.util.js';
57
62
  import { wrunResultLegendColors, wrunSeriesChildId, } from '../chart/wrun-run-result.util.js';
58
63
  import { budgetWrunBatchedRetained, budgetWrunBatchedRows, commitWrunBatchedPlan, currentWrunBatchedPlan, forgetWrunBatchedCells, isWrunBatchedMarksKind, noteWrunBatchedRowsCut, planWrunBatchedMerged, restoreWrunBatchedLedger, snapshotWrunBatchedLedger, WRUN_BATCHED_MARKS_KINDS, wrunBatchedChargeOf, wrunBatchedChildConfig, wrunBatchedChildrenOverShare, wrunBatchedEngineVerdict, wrunBatchedSiblingsToRebalance, } from './wrun-batched-marks.util.js';
59
- import { forgetWrunCanvasReadout, keepWrunHeatmapScaleSample, rememberWrunCanvasReadout, wrunCanvasChildConfig, wrunHeatmapSensitivityBounds, wrunPlainCanvasRow, } from './wrun-canvases.util.js';
64
+ import { forgetWrunCanvasReadout, keepWrunHeatmapScaleSample, rememberWrunCanvasReadout, wrunCanvasChildConfig, wrunHeatmapScaleDecided, wrunHeatmapScaleKept, wrunHeatmapSensitivityBounds, wrunPlainCanvasRow, } from './wrun-canvases.util.js';
60
65
  import { wrunChildHiddenRowKey } from './wrun-child-overlay-id.util.js';
61
66
  import { wrunHeatmapSensitivitySetting, wrunHeatmapSensitivityValue } from './wrun-color-settings.util.js';
62
67
  import { budgetWrunHeatmapRetained, budgetWrunHeatmapRows, commitWrunHeatmapPlan, currentWrunHeatmapPlan, planWrunHeatmapMerged, restoreWrunHeatmapLedger, snapshotWrunHeatmapLedger, wrunHeatmapCellLayoutOf, wrunHeatmapChildrenOverShare, wrunHeatmapSiblingsToRebalance, } from './wrun-heatmap-cell-budget.util.js';
@@ -1232,6 +1237,74 @@ function isHeatmapRecord(record) {
1232
1237
  function isWindowRecord(record) {
1233
1238
  return isHeatmapRecord(record) || isBatchedRecord(record);
1234
1239
  }
1240
+ // ── A heatmap's colour scale: decided once per picture ──────────────────────────────────────────────────
1241
+ //
1242
+ // Every pass hands the picture its rows were computed for (`pictureIdentity`, the one derivation
1243
+ // `wrunPictureIdentityOf` in wrun-overlay-drivers.util: the compute settings revision and the market identity of the
1244
+ // run or live session that computed them, with the reasons those two facts are the identity).
1245
+ /**
1246
+ * The picture each mounted heatmap's colour scale was decided under, keyed (like its scale sample,
1247
+ * wrun-canvases.util `heatmapSamples`) by its input's `settings` object: every seam that keeps a record (a live
1248
+ * merge, a trim, a windowed landing, a retranslate, a rescale, a blank, a landing's roll-back) copies the input as
1249
+ * `{ ...input, data }` or keeps it whole, so the stamp travels with the bounds it names and no seam has to copy it.
1250
+ */
1251
+ const decidedPictures = new WeakMap();
1252
+ /** A heatmap pass decides its own colour scale (its install, or a whole-window pass of another picture): the
1253
+ * record it becomes is stamped with the pass's picture (none when the pass named none). */
1254
+ function decideHeatmapScale(entry, picture) {
1255
+ if (entry.input.kind !== 'heatmap')
1256
+ return;
1257
+ if (picture !== undefined)
1258
+ decidedPictures.set(entry.input.settings, picture);
1259
+ else
1260
+ decidedPictures.delete(entry.input.settings);
1261
+ }
1262
+ /**
1263
+ * Whether a whole-window pass of `picture` keeps the colour scale `stayed` shows: the same picture decided it, its
1264
+ * sample gave the bounds on screen at the quantile they are read at (`sensitivity`, the viewer's position now;
1265
+ * `wrunHeatmapScaleDecided`: an empty sample, one whose cells all sit at the floor or the centre, or one where the
1266
+ * quantile's share of them does, decided nothing, and its stand-in bounds would saturate every cell the next rows
1267
+ * bring), on a record no blank emptied (a symbol, interval or session switch blanks the children, and the rows that
1268
+ * come after it are a new load), under the same scale declaration. Anything else decides again from the pass's own
1269
+ * rows.
1270
+ */
1271
+ function holdsHeatmapScale(stayed, entry, picture, sensitivity) {
1272
+ return (picture !== undefined &&
1273
+ stayed.blanked !== true &&
1274
+ isHeatmapRecord(stayed) &&
1275
+ entry.input.kind === 'heatmap' &&
1276
+ decidedPictures.get(stayed.input.settings) === picture &&
1277
+ wrunHeatmapScaleDecided(stayed.input, sensitivity) &&
1278
+ heatmapScaleDeclaration(stayed.input) === heatmapScaleDeclaration(entry.input));
1279
+ }
1280
+ /** The words a heatmap's colour scale is built under: its Sensitivity inputs when it has a row (the author's scale
1281
+ * words, the layout and value word the sample reads) and the words its settings carry (the cell layout, the value
1282
+ * word, the curve, the centre). Equal under one picture by construction (they move only with a compute save or
1283
+ * the script); compared all the same, so a scale is never carried onto another declaration. */
1284
+ function heatmapScaleDeclaration(child) {
1285
+ const { cellLayout, valueField, scale, center } = child.settings;
1286
+ return JSON.stringify([child.scale ?? null, cellLayout, valueField, scale, center]);
1287
+ }
1288
+ /**
1289
+ * Carry the colour scale `stayed` shows onto `entry`, the record a pass stores while it keeps that scale: the pass's
1290
+ * own child (its rows, every other setting it built) with the decided own bounds, the decided sample beside them
1291
+ * (`keepWrunHeatmapScaleSample`) and the decided picture, and the config at those bounds (the viewer's Sensitivity
1292
+ * re-picks them from the decided sample right after, `repickHeatmapBounds`). The pass's rows still swap or merge as
1293
+ * it asks; only the scale is held. The run result's own child is never written: the record takes a copy.
1294
+ */
1295
+ function carryHeatmapScale(stayed, entry) {
1296
+ if (entry.input.kind !== 'heatmap')
1297
+ return;
1298
+ const { min, max } = stayed.input.settings;
1299
+ const held = { ...entry.input, settings: { ...entry.input.settings, min, max } };
1300
+ keepWrunHeatmapScaleSample(stayed.input, held);
1301
+ const picture = decidedPictures.get(stayed.input.settings);
1302
+ if (picture !== undefined)
1303
+ decidedPictures.set(held.settings, picture);
1304
+ entry.input = held;
1305
+ entry.config.settings.min = min;
1306
+ entry.config.settings.max = max;
1307
+ }
1235
1308
  /** The merge of a pass into a mounted heatmap's or batched child's window and its budget, planned from the
1236
1309
  * record's rows (the rows the mount means the engine to hold, a trim titan still queues included), writing
1237
1310
  * nothing. */
@@ -1302,8 +1375,9 @@ function landHeatmapWindow(tc, overlayId, state, record, plan, deferred = NO_DEF
1302
1375
  }
1303
1376
  return landed;
1304
1377
  }
1378
+ // The landed input shares the record's settings, so the decided scale (its sample and its picture, both kept
1379
+ // beside the settings) stays the one a Sensitivity re-pick and the next pass read.
1305
1380
  commitWrunHeatmapPlan(tc, plan.budget.plan, held);
1306
- keepWrunHeatmapScaleSample(record.input.data, rows);
1307
1381
  for (const sibling of wrunHeatmapChildrenOverShare(tc, overlayId, plan.childId, held)) {
1308
1382
  if (!deferred.has(sibling))
1309
1383
  budgetMountedHeatmap(tc, overlayId, sibling);
@@ -1764,7 +1838,7 @@ function mountContext(tc, overlayId, parent, children, priceDigits, chartHeightP
1764
1838
  * precision (OT29, X7): the panels' formatters and the lower pane's legend
1765
1839
  * print "price" values with it. A tick's heatmap tail (`tailOnly`) only
1766
1840
  * ever merges its rows into a mounted canvas. */
1767
- export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames = true, swapCanvasRows, canvasRowsFromTs, historyWindow, projection, cell, priceDigits, onMainThreadMs, chartIndex, }) {
1841
+ export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames = true, swapCanvasRows, canvasRowsFromTs, historyWindow, projection, pictureIdentity, cell, priceDigits, onMainThreadMs, chartIndex, }) {
1768
1842
  if (runResult.failureReason !== undefined)
1769
1843
  return Promise.reject(new Error(runResult.failureReason));
1770
1844
  if (tc.isDestroyed)
@@ -2005,7 +2079,8 @@ export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames
2005
2079
  current.children = new Map(preserved);
2006
2080
  // The configs were built before the pack await: a heatmap about to be
2007
2081
  // installed or refreshed re-picks its bounds from the Sensitivity it holds
2008
- // NOW (a drag or a save during the await), never the one it was built with.
2082
+ // NOW (a drag or a save during the await), never the one it was built with,
2083
+ // over the scale its record keeps (its own, or the one carried onto it).
2009
2084
  const repickHeatmapBounds = ({ input, config }) => {
2010
2085
  if (input.kind !== 'heatmap' || input.scale === undefined)
2011
2086
  return;
@@ -2046,6 +2121,8 @@ export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames
2046
2121
  forgetWrunCanvasReadout(id);
2047
2122
  }
2048
2123
  else if (!mounted) {
2124
+ // An install decides a heatmap's colour scale from its own rows, exactly as before the hold.
2125
+ decideHeatmapScale(entry, pictureIdentity);
2049
2126
  repickHeatmapBounds(entry);
2050
2127
  current.children.set(id, entry);
2051
2128
  budgetHeatmapChild(tc, overlayId, entry);
@@ -2104,6 +2181,18 @@ export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames
2104
2181
  swapCanvasRows === true ||
2105
2182
  !sameDataWindow(mountedConfig, config) ||
2106
2183
  canvasGridMoved(mountedConfig, config)) {
2184
+ // A whole-window pass swaps the rows. A heatmap keeps the colour scale on screen while the pass is
2185
+ // of the picture that decided it (a reseed, a refine, an eviction's or a gap's swap, a window that
2186
+ // rolled past the mounted rows, a rerun with nothing changed): its rows repaint at the decided
2187
+ // bounds. A pass of another picture (an input, the symbol or the interval moved), one that named no
2188
+ // picture, and a record whose scale an empty sample or a blank left undecided decide it again from
2189
+ // the pass's own rows (2026-11-07: every rebuild re-picked from the rows held then, so cells on
2190
+ // screen changed brightness while nothing they showed had changed).
2191
+ const sensitivity = heatmapSensitivityOf(current.previews, parent, input.name);
2192
+ if (holdsHeatmapScale(stayed, entry, pictureIdentity, sensitivity))
2193
+ carryHeatmapScale(stayed, entry);
2194
+ else
2195
+ decideHeatmapScale(entry, pictureIdentity);
2107
2196
  repickHeatmapBounds(entry);
2108
2197
  budgetHeatmapChild(tc, overlayId, entry);
2109
2198
  refreshChildInPlace(tc, mountedConfig, config);
@@ -2116,6 +2205,14 @@ export function mountWrunChildOverlays({ tc, overlayId, runResult, replaceFrames
2116
2205
  const held = mountedHeatmapRecord(tc, id);
2117
2206
  if (held !== undefined)
2118
2207
  keepHeatmapRows(entry, held.config.data);
2208
+ // A merge hands the engine rows only, so the screen keeps the scale it shows; the record keeps it too
2209
+ // (the pass's own bounds and sample, picked from its rows, would reach the screen at the next
2210
+ // retranslate, Sensitivity re-pick or windowed landing), a stand-in included: the next whole-window
2211
+ // pass decides that one again (holdsHeatmapScale).
2212
+ if (isHeatmapRecord(held) && wrunHeatmapScaleKept(held.input)) {
2213
+ carryHeatmapScale(held, entry);
2214
+ repickHeatmapBounds(entry);
2215
+ }
2119
2216
  current.children.set(id, entry);
2120
2217
  }
2121
2218
  }
@@ -140,11 +140,14 @@ export interface WrunRunHealth {
140
140
  warmup: number;
141
141
  /** Continuous plots that are NaN (or never finite) on every ready row, in slot order. */
142
142
  silentOutputs: string[];
143
- /** The display label of each silent output by name (the declared `label`, else the name read
144
- * as words): present only while an output is silent. */
143
+ /** The display label of each silent output by name, the words the chart's surfaces name it by
144
+ * (wrun-output-words.util wrunOutputWords: the declared `label`, else the name read as words; a
145
+ * built-in port's line in its built-in's words): present only while an output is silent. */
145
146
  labels?: Readonly<Record<string, string>>;
146
147
  }
147
- export declare function wrunRunHealth(metadata: Pick<WrunIndicatorMetadata, 'outputs'>, rows: ReadonlyArray<WrunOutputRow>): WrunRunHealth;
148
+ /** The run's health over `rows`; `builtIn` is the built-in the overlay ports (builtinPortOf over
149
+ * its settings), whose words name a silent line it names (absent: the sheet's words). */
150
+ export declare function wrunRunHealth(metadata: Pick<WrunIndicatorMetadata, 'outputs'>, rows: ReadonlyArray<WrunOutputRow>, builtIn?: string): WrunRunHealth;
148
151
  /** True when two health row sets state the same verdicts (a live session recomputing its
149
152
  * health on every tick republishes only when the verdict changes, never for a bar count). */
150
153
  export declare function sameWrunRunHealthVerdict(current: ReadonlyArray<RuntimeDiagnostic>, next: ReadonlyArray<RuntimeDiagnostic>): boolean;
@@ -1,5 +1,6 @@
1
1
  import { wrunLegendName } from '../chart/wrun-legend-name.util.js';
2
2
  import { isWrunLegStreamClass } from './wrun-leg-stream-classes.js';
3
+ import { wrunOutputWords } from './wrun-output-words.util.js';
3
4
  import { WRUN_VISIBILITY_RULES, wrunOutputDraw } from './wrun-visibility-table.js';
4
5
  import { attachWrunRefusal, wrunOptionsStopSeed, wrunRefusalFor, } from './wrun-refusal.util.js';
5
6
  export const WRUN_NO_READY_ROWS_CODE = 'WRUN_NO_READY_ROWS';
@@ -182,7 +183,9 @@ export function wrunUnservedLegDiagnostics(legs, ctx) {
182
183
  /** Plots that draw a value on every ready bar; a sheet output with no `plot` draws a line. */
183
184
  const CONTINUOUS_PLOTS = new Set(['line', 'area', 'histogram', 'bar']);
184
185
  const DEFAULT_PLOT = 'line';
185
- export function wrunRunHealth(metadata, rows) {
186
+ /** The run's health over `rows`; `builtIn` is the built-in the overlay ports (builtinPortOf over
187
+ * its settings), whose words name a silent line it names (absent: the sheet's words). */
188
+ export function wrunRunHealth(metadata, rows, builtIn) {
186
189
  const outputs = Array.isArray(metadata?.outputs) ? metadata.outputs : [];
187
190
  const watched = outputs.filter((output) => CONTINUOUS_PLOTS.has(output.plot ?? DEFAULT_PLOT) &&
188
191
  output.legend !== false &&
@@ -210,7 +213,7 @@ export function wrunRunHealth(metadata, rows) {
210
213
  warmup: rows.length - ready,
211
214
  silentOutputs: silent.map((output) => output.name),
212
215
  ...(silent.length > 0
213
- ? { labels: Object.fromEntries(silent.map((output) => [output.name, wrunLegendName(output.name, output.label)])) }
216
+ ? { labels: Object.fromEntries(silent.map((output) => [output.name, wrunOutputWords(output, builtIn)])) }
214
217
  : {}),
215
218
  };
216
219
  }
@@ -83,7 +83,16 @@
83
83
  * and wrun-style-patch.util; a `colors` row and a prefixed target's rows
84
84
  * repaint through a rerun). A cloud record mounts the same rows (the registry
85
85
  * loader builds both lanes' records here, over the full sheet): the one pass
86
- * paints either row source's batch through the chart's own builders.
86
+ * paints either row source's batch through the chart's own builders. The
87
+ * page's words for a batched section or a renderer come first from the
88
+ * sheet's `style_names` table (wrun-style-names.util, the one reader): its
89
+ * label titles the line (styleTargetTitle) and its colour names name each
90
+ * swatch of the line's colours row (`swatchNames`). Its entry for an output
91
+ * or a heatmap names colours alone (the title stays their own `label`): a
92
+ * heatmap's palette stops, an output's two-tone pair, and a `color_by` ladder
93
+ * whose every rung it names, which gains a colours row even where an unnamed
94
+ * ladder has none (three or more rungs, a line's, an inset strip's:
95
+ * outputColorList). A sheet without the table reads as before.
87
96
  *
88
97
  * The layout (buildWrunScriptLayout) groups the flat rows into pages and
89
98
  * sections: from the sheet's `layout` when it declares one (params before
@@ -210,6 +219,11 @@ export interface WrunScriptInputDeclaration {
210
219
  };
211
220
  /** A `colors` style row: what each swatch paints, in value order. */
212
221
  swatches?: WrunStyleSwatch[];
222
+ /** A `colors` style row the sheet's `style_names` table names (wrun-style-names.util): one plain name per swatch, in
223
+ * value order, as long as `swatches`. Slots that share a name are one swatch on the page whose pick writes every
224
+ * one of them (wrun-dialog-rows wrunSwatchViews); a named swatch's hover title is its name. Absent while the table
225
+ * names none of the row's slots, so an unnamed row is exactly what it always was. */
226
+ swatchNames?: string[];
213
227
  /** A text row (wrun-5): the UTF-8 byte cap the field enforces and whether
214
228
  * it takes several lines (a text area; newlines survive). Carried on the
215
229
  * row so the dialog and the hosted lanes know them without the sheet. */
@@ -260,7 +274,7 @@ export interface WrunScriptLayout {
260
274
  * visibility table lists (the Style rows' targets, wrun-visibility-table.ts
261
275
  * WrunVisibilitySheet: no list of its own here), input sources (host
262
276
  * bindings), layout and presets when present. */
263
- export type WrunScriptInputsSheet = Pick<WrunIndicatorMetadata, 'params'> & WrunVisibilitySheet & Partial<Pick<WrunIndicatorMetadata, 'inputSources' | 'layout' | 'presets'>>;
277
+ export type WrunScriptInputsSheet = Pick<WrunIndicatorMetadata, 'params'> & WrunVisibilitySheet & Partial<Pick<WrunIndicatorMetadata, 'inputSources' | 'layout' | 'presets' | 'style_names'>>;
264
278
  /**
265
279
  * The words a settings row prints: its label verbatim (an author's words are
266
280
  * never re-cased: "ATRs" stays "ATRs"), else the name read as words. A label
@@ -341,12 +355,15 @@ export declare function wrunRowSettingReader(rows: ReadonlyArray<WrunScriptInput
341
355
  * its label and hint from that build, matched by name (a unit composite and
342
356
  * its value member, which share a name, each from its own kind). An older
343
357
  * build stamped a param's description as its label and no hint; the saved
344
- * indicator reads the same as a fresh add without a rerun. Values, types and
345
- * every other key stay as persisted; a style row (its label is its property
346
- * key) and a row the sheet no longer builds keep their own; a row whose
347
- * words already match is returned as is. `options` builds the words as the
348
- * mount did (a port's hint rule, WrunRowBuildOptions), so a row persisted
349
- * before the rule reads without its encoding legend.
358
+ * indicator reads the same as a fresh add without a rerun. A style row keeps
359
+ * its label (its property key) and takes the swatch names the sheet's
360
+ * `style_names` table gives its colours now (`swatchNames`, or none), so a
361
+ * row persisted before the table names its swatches as a fresh add does.
362
+ * Values, types and every other key stay as persisted; a row the sheet no
363
+ * longer builds keeps its own; a row whose words already match is returned
364
+ * as is. `options` builds the words as the mount did (a port's hint rule,
365
+ * WrunRowBuildOptions), so a row persisted before the rule reads without its
366
+ * encoding legend.
350
367
  */
351
368
  export declare function wrunRowsWithSheetWords(rows: ReadonlyArray<WrunScriptInputDeclaration>, sheet: WrunScriptInputsSheet | undefined, options?: WrunRowBuildOptions): WrunScriptInputDeclaration[];
352
369
  /**