@wafertools/wafermap 0.30.1 → 0.30.3

package/AGENTS.md

@@ -25,8 +25,24 @@ loudly over guessing.
 - `@wafertools/wafermap/worker` — `createWafermapWorker()` for off-main-thread builds.
 
 Default path: `buildWaferMap()` once when data loads, then `renderWaferMap()` for a
-single wafer or `renderWaferGallery()` for several. Do not use `toCanvas()`, `buildView()`
-or the other low-level pipeline functions: they are deprecated and removed in 0.31.0.
+single wafer or `renderWaferGallery()` for several.
+
+**The types still export a large deprecated surface that is removed in 0.31.0 — do not
+reach into it just because autocomplete offers it.** Four groups, all replaced by the
+default path above:
+
+- the low-level drawing pipeline — `buildView()`, `toCanvas()`, `createWafer()`,
+  `generateDies()`, and the geometry and transform helpers around them;
+- the chart-data builders — `buildYieldData()`, `buildCorrelationMatrix()`,
+  `buildTestBoxplotData()` and the rest: these were the internals of the Insights tab,
+  which the renderers now mount for you (see below);
+- the region builders — `buildRingRegions()`, `buildQuadrantRegions()` and friends:
+  region yield comes back from `analyzeWaferMap()`;
+- per-die and per-colour helpers — `getDieTestValue()`, `buildHoverText()`,
+  `resolveBinColors()`, `getValueColorScheme()`, `valueToViridis()`.
+
+If the only way to do something is through one of these, that is a library gap worth
+reporting, not a pattern to build on.
 
 ### Traps that produce silently wrong maps
 
@@ -37,8 +53,20 @@ or the other low-level pipeline functions: they are deprecated and removed in 0.
   through unchanged; `dieConfig.width`/`height` convert to physical units. Do not
   pre-multiply. The geometry inputs are `waferConfig` (type `WaferConfig`) and
   `dieConfig` (type `DieConfig`) — both optional, both inferred when omitted.
-- **`passBins` decides both the yield number and the wording of its label.** Set it
-  from the actual test program. Do not assume `[1]`.
+- **Bins and test values must be numbers, and verdicts booleans.** Every parser —
+  CSV, JSON, a spreadsheet export — hands you `"1"`, and `"1"` is not pass bin 1: those
+  dies count as fails and the yield is wrong, while a test value left as text is not
+  plotted or analysed correctly. Convert with `Number()` at parse time. `buildWaferMap`
+  samples the input and reports `input-values-not-numbers` (severity `'error'`) rather
+  than coercing behind your back, so a build that "works" can still be wrong — read the
+  warnings.
+- **`passBins` and `ringCount` are set once, on `buildWaferMap`, and travel on the
+  result.** Neither is an option on `analyzeWaferMap`, `analyzeWaferLot`,
+  `renderWaferMap` or `renderWaferGallery` — passing one there is a type error in
+  TypeScript, and in JavaScript it is ignored with an `analysis-option-corrected`
+  warning while the real value is read from the map. `passBins` decides both the yield
+  number and the wording of its label, so set it from the actual test program: do not
+  assume `[1]`, and never re-default to `[1]` downstream — read `result.passBins`.
 - **`testValues` is keyed by test number**, e.g. `{ 1050: 0.42 }` — not a positional
   array. `activeTest` likewise takes a *test number* (`1050`), not an index.
 - **Functional tests (`testType: 'F'`) have no measured value.** Read their verdicts
@@ -88,7 +116,37 @@ or the other low-level pipeline functions: they are deprecated and removed in 0.
   your own (a table swatch, an export)? Read `controller.getBinColors()` for a live map,
   or `binColorsForMaps(results)` — never a palette lookup of your own.
 - Build once, render many: `buildWaferMap()` handles data + geometry; re-render UI
-  changes through the controller's `setOptions()`, not by rebuilding.
+  changes through the controller's `setOptions()`, not by rebuilding. New data for a
+  map that is already mounted goes through `setResult()` — do not `destroy()` and
+  remount.
+- **The analysis surfaces are already built — do not reimplement them.** Pass
+  `statsSummary` to `renderWaferMap` and it mounts the Summary panel; pass
+  `insights: { enabled: true }` and it mounts the chart suite (yield, bin pareto,
+  boxplot, histogram, correlation, scatter, capability, and one card per
+  `insights.sweeps` entry). `renderWaferGallery` takes the same option across a whole
+  lot. Supply or replace the analysis later with `setStatsSummary()`. Hand-building
+  those charts is what the deprecated chart-data builders were for, and they go in
+  0.31.0. Charting a selection or one wafer (right-click → histogram, capability,
+  sweeps) is built in too, with no wiring.
+- **A value computed from other tests is a derived test, not a host-side column.** Pass
+  `derivedTests` (a `TestDef` plus an `expression`, e.g. `'abs(t[1020] - t[1010])'`) to
+  `buildWaferMap`; it then behaves as a measured test everywhere, marked `†` as not
+  measured. Computing it in the host and injecting it into `testValues` loses that
+  mark, the missing-input rule (absent, never 0) and the collision check. A boolean
+  expression must be declared `testType: 'F'`.
+- **A sweep's x values are data, not guesses.** Give `xValues`, or `xFromName` (a
+  `{x}` placeholder pattern, not a regex) when the swept value is only in the test
+  name. Never derive x from test numbers: they are identifiers, not a scale.
+- **Click-to-highlight is wired, not hand-rolled.** `onSelect` reports what the user
+  picked; `setSelection(dies)` / `clearSelection()` drive it from your own UI — for
+  example from a finding, whose `dieKeys` match `getDieKey(die)` exactly.
+- A die layout with no test data — a map of the reticle or the grid alone — is
+  `buildWaferMap({ layout: true, waferConfig, dieConfig })`, not a synthesized results
+  array.
+- `valueColorScheme` and `reverseValueScheme` travel as a pair. Every built-in gradient
+  but `'traffic'` and `'jet'` reads low = dark, high = light; if you draw your own
+  colorbar or swatch, resolve the colour through `resolveValueColorFn(name, reversed)`
+  so it cannot disagree with the dies.
 - `result.view` is internal. Use the promoted fields: `result.plotMode`,
   `result.metadata`, `result.isLotStack`, `result.hbinDefs`, `result.sbinDefs`,
   `result.testDefs`.
@@ -135,10 +193,10 @@ it is handed, because it has no way to know which tests anyone will look at.
 - **A Web Worker buys responsiveness, not speed.** `createWafermapWorker` copies data
   across `postMessage`, so total time goes *up*. Use it when a build would otherwise
   visibly freeze the page, not for small datasets.
-- **Capability, pass rates and region yield come back from the analysis** —
-  `stats.capability` (with `computePerTestStats`), `stats.testSpecYield`,
-  `stats.testFlagYield`, `stats.functionalYield` and `stats.regionYield`, on wafer and
-  lot summaries alike. Do not compute Cp/Cpk or ring yield yourself: the pooled
+- **Capability, pass rates, region yield and the spatial-pattern label come back from
+  the analysis** — `stats.capability` (with `computePerTestStats`), `stats.testSpecYield`,
+  `stats.testFlagYield`, `stats.functionalYield`, `stats.regionYield` and
+  `stats.spatialPattern`, on wafer and lot summaries alike. Do not compute Cp/Cpk or ring yield yourself: the pooled
   within-wafer stddev and per-wafer pass bins are easy to get subtly wrong.
 - **Reports from code: `renderWaferReportHtml(result, summary)` and
   `renderLotReportHtml(results)`** — they take the built maps, so pass bins and ring
@@ -157,7 +215,7 @@ it is handed, because it has no way to know which tests anyone will look at.
 | `WaferMapResult.inference.warnings` | `WaferMapResult.warnings` (structured, with a `code`) |
 | `ViewOptions.testIndex` | `activeTest` |
 | `mountWaferCanvas` | `renderWaferMap` |
-| `HARD_BIN_COLORS` / `SOFT_BIN_COLORS` | `BIN_PALETTE` |
+| `HARD_BIN_COLORS` / `SOFT_BIN_COLORS` | `BinDef.color`, or `registerBinColorScheme` — there is no exported palette constant |
 | `GalleryItem` | `WaferMapDisplayItem` |
 | `MountOptions` | `RenderOptions` |
 | `WaferCanvasController` | `WaferMapController` |
@@ -172,6 +230,8 @@ it is handed, because it has no way to know which tests anyone will look at.
 | `plotMode: 'specLimit'` | `passFailDisplay: 'spec'` |
 | standalone `getDieAtPoint` | `onHover` / `onClick` on `renderWaferMap` |
 | `RenderOptions.tooltipTestLimit` | (was a no-op; nothing replaces it) |
+| `enableYieldAnalysis` / `enableHardBinAnalysis` / `enableSoftBinAnalysis` / `enableReticlePositionAnalysis` / `enableTestSiteAnalysis` / `enableClusterAnalysis` / `enableAngularAnalysis` / `enablePatternClassification` | nothing — every analysis runs; scope cost with `testNumbers` instead |
+| `WaferMapController.setIdentityVisible` | `showIdentity` in `RenderOptions` |
 
 Passing a removed option is a type error, and is ignored at runtime. Do not add
 compatibility shims for them.
@@ -191,7 +251,7 @@ compatibility shims for them.
 - [API reference](https://wafertools.github.io/wafermap/api/) — every type, option and return value
 - [Developer guide](https://wafertools.github.io/wafermap/guide/) — worked walkthroughs
 - [Troubleshooting](https://wafertools.github.io/wafermap/troubleshooting/)
-- [Examples](https://wafertools.github.io/wafermap/examples/) — 20 runnable pages, also
+- [Examples](https://wafertools.github.io/wafermap/examples/) — 22 runnable pages, also
   [downloadable](https://wafertools.github.io/wafermap/wafermap-examples.zip) to run offline
 
 When a rule here and the API reference disagree, the API reference wins — tell the

package/CHANGELOG.md

@@ -22,18 +22,474 @@ under `### Breaking`.
 
 ---
 
+## [0.30.3] — 2026-09-23
+
+### Added
+
+- **Sweep x values from test names, an x unit, and a log x axis.** For a
+  program that records the swept quantity only in the test text — a
+  resistance CDF named `Normalized_LRS= LRS_STATS_12K / …`, one test per
+  threshold:
+  - `SweepSeriesSpec.xFromName` reads each test's x from its name with a
+    placeholder pattern, `"LRS_STATS_{x}"`: `{x}` reads a number with its SI
+    prefix (`12K` → 12,000; case-sensitive, `K` accepted as kilo; a letter is a
+    prefix only alone or before a unit, so `12Kangaroos` reads 12; in an all-capitals
+    name the unit's case is gone, so `5NS` is 5 ns and `2MV` — milli or mega? — is
+    reported, not guessed), `*` matches
+    anything, literal text matches in any case, anywhere in the name. Not a
+    regular expression: a sweeps file is shared, and JavaScript cannot
+    interrupt a runaway regex, whereas this matcher's cost is bounded whatever
+    the pattern (`stats/sweepXFromName.ts`). Each x stays attached to its own
+    test, so a missing test loses one point instead of shifting the rest.
+  - `SweepSpec.xUnit` prints the x axis, crossing and widths SI-prefixed
+    (`47.3 kΩ`), trailing zeros dropped (`2 kΩ`, not `2.00 kΩ`).
+  - `SweepSpec.xScale: 'log'` places x on a log axis; the crossing is
+    interpolated along log x and a width is reported as a ratio with both ends
+    (`×2.49 (15.9 kΩ → 39.7 kΩ)`), via new `SweepSeparation.ratio`/`from`/`to`.
+    `SweepData.xScale` is the axis actually drawn: a non-positive x keeps it
+    linear, with a warning.
+  - Reported, never guessed, and then not measured: a name the pattern does not
+    fit, a series giving both `xValues` and `xFromName`, and — for every x
+    source — a series that revisits an x value, which the crossing previously
+    mis-paired silently.
+
+- **Drilldown: chart a selection or a wafer.** Right-click a population for a
+  menu of charts drawn from just those dies, opened in the same modal as an
+  expanded Insights card:
+  - **Populations:** the dies selected on a map (a single map or any gallery
+    card); a whole wafer, from empty map space with nothing selected, from a
+    gallery card anywhere outside its map, or from one wafer's bar, box or point
+    in *Yield by wafer*, *Test value distribution* or *Wafer-to-wafer trend* in
+    Insights (their tooltips say "right-click to chart this wafer"). The Menu
+    key, Shift+F10 and a new map toolbar **Chart** button (the selection if
+    there is one, else the wafer) reach the same menu without a mouse.
+  - **Charts:** value histogram (opening on the test the map shows), process
+    capability, and the sweeps defined in `insights.sweeps` — the gallery now
+    passes those to each card, and a single map offers them whether or not
+    `insights.enabled` is set.
+  - **Population stated on every chart**, in the modal title and on the card
+    ("12 dies selected on W03", "10 of 12 … (partial and edge-excluded dies left
+    out)"). Capability below 30 dies adds that each Ppk is a rough estimate.
+    Charts are snapshots: changing the selection afterwards does not change them.
+    The wafer is named by the item's `label`, else its `metadata.waferId` — never a
+    positional "Wafer 3 (no ID)" — on the map, the gallery and Insights alike.
+  - **The library decides what is offered:** a chart that cannot be drawn stays
+    listed, greyed, with the reason (no values for its tests; fewer than two
+    dies for capability; a lot-stack map, whose dies are per-position aggregates
+    rather than measured dies). Right-clicking an unselected die selects it
+    first. A map with no parametric tests and no sweeps leaves right-click to
+    the browser or host, and the map canvas owns right-click on itself: one it
+    declines (the bin legend) never reaches a gallery card or host handler.
+  - Documented in api.md §5.12, the user guide §4.4 (with screenshots from
+    `capture-definitions.mjs`) and the developer guide.
+  - Built on one source/target mechanism (`canvas-adapter/chartPopulation.ts`
+    builds the populations, `drilldown.ts` the menu and charts, loaded on first
+    use and pinned by `tests/bundle-size.test.mjs`), so a further population or
+    chart is one more of either rather than a menu per pairing.
+
+- **Derived tests** — `WaferMapInput.derivedTests`: tests computed from other tests
+  on the same die, rather than measured. Each entry is a `TestDef` plus an
+  `expression`, and from the build onwards it is an ordinary test — it appears in
+  `result.testDefs`, in the value plot modes, the colorbar, tooltips,
+  `analyzeWaferMap`, Insights and the report, with no other change required.
+
+  ```ts
+  derivedTests: [
+    { testNumber: 900001, name: 'Leakage Shift', unit: 'uA',
+      expression: 'abs(t[1020] - t[1010])', limitHigh: 5 },
+    { testNumber: 900002, name: 'Sweep All Pass', testType: 'F',
+      expression: 'all(testPass[1010..1025])' },
+  ]
+  ```
+
+  Expressions read `t[n]` (measured value), `testPass[n]` (the tester's recorded
+  verdict), `specPass[n]` (spec-limit judgement) and `diePass()` (the die's bin
+  verdict) — the same `'test'`/`'spec'` distinction `passFailDisplay` already
+  draws, because they are different questions and a single accessor would have
+  silently meant "recorded verdict" for parametric data that has none. A range
+  (`t[1010..1015]`) yields a set that must be reduced by `mean`, `sum`, `min`,
+  `max`, `all`, `any`, `none`, `countTrue`, `countFalse` or `countKnown`; there is
+  no vector arithmetic, which is what stops the grammar becoming an array
+  language. Operators `+ - * / % ^`, comparisons, `and`/`or`/`not`, and
+  `if(cond, a, b)`.
+
+  Parsed to a typed tree at build time and walked per die — **no `eval`, no
+  `Function`, no third-party expression engine, and no way to name a host
+  object** — so a chart spec can be shared between teams as plain JSON. This is
+  why the root bundle grows ~5 KB gzip.
+
+  Evaluated on raw probe records **before** lot stacking and retest resolution, so
+  every derived value comes from one real touchdown: deriving after a stack would
+  subtract one aggregate from another, and deriving after retest collapse could mix
+  a value from one touchdown with a verdict from another.
+
+  A boolean expression is a verdict — declare `testType: 'F'` and the result lands
+  in `die.testPass`, never as a 1/0 in `testValues` where it would enter the
+  correlation matrix and the Cpk table. An unknown input yields an **absent** value
+  (no-data grey), never `0` and never `false`.
+
+  Everything statically knowable is checked at build and reported as a
+  `derived-test-invalid` warning naming the position — a parse or type error, a
+  `testNumber` colliding with measured data, a `testType` that disagrees with the
+  expression, `t[n]` on a functional test, `specPass[n]` on a test with no limits.
+  A rejected derived test is **dropped**, never half-applied.
+
+- **Parametric sweeps** — `insights.sweeps` on `renderWaferMap`/`renderWaferGallery`:
+  an ordered run of tests read as a response curve rather than as independent
+  tests, with the crossing point of the first two series and the horizontal
+  separation at named levels measured and stated. `xValues` supplies the real
+  swept quantity so the crossing is reported in physical units; without it the
+  axis is the ordinal position, because test numbers are identifiers and are not
+  guaranteed to be evenly spaced. Each line is the population median with a
+  p10–p90 band. A multiple crossing says so; a level neither curve reaches reads
+  "not measurable" naming the series, never `0`.
+- **Test ranges in a sweep's `tests`** — an entry may be `"1010..1030"`, the exact
+  syntax of a derived-test expression's `t[1010..1030]` and parsed by the same code
+  (`parseTestReference`), so the same text always names the same tests. A range
+  expands to the declared tests inside it, ascending — a program numbered in steps
+  of 2 needs no step syntax. `xValues` is checked against the expanded list: when
+  a test is missing from a range, the footer lists what the range matched and the
+  card is drawn in test order with the crossing and widths **not measured**
+  (`SweepData.notMeasured`), rather than sliding every later x value onto the
+  wrong test. The same now applies when only some series carry `xValues`, which
+  before put physical and ordinal x positions on one axis and reported an ordinal
+  crossing under the physical x label. A range resolves by filtering the declared
+  tests rather than counting through every integer, so `0..2000000000` in a shared
+  template is not a two-billion-step loop — in expressions too.
+- **Nested derived tests** — a derived test may read another. Compilation
+  topologically sorts by what each expression reads, so declaration order does
+  not matter; cycles, self-references and dependents of a rejected test are
+  dropped with the cause named.
+- New example: **Derived tests and sweeps** (`docs/examples/derived-tests.html`).
+- **Sweeps have their own Insights sub-tab**, shown only when `insights.sweeps`
+  defines at least one; `InsightsView` gains `'sweeps'` for `defaultView`, which
+  falls back to `'overview'` when there are none. Not an option and not a count
+  threshold: a threshold would move a sweep between tabs the day a colleague
+  added another, and an option would be a layout flag with one right answer.
+  They never belonged in Distributions either — that view is driven by one
+  selected test (capability → boxplot → histogram → trend), while a sweep draws
+  many tests as one curve and ignores the selection.
+- New example: **Parametric sweeps** (`docs/examples/sweeps.html`) — four
+  characterisation sweeps in the Sweeps tab, each a different use of the
+  crossing and the width: the temperature-inversion voltage (Fmax vs VDD at
+  25/125 °C, with the iso-frequency VDD gap at two speeds), DIBL from an NMOS
+  transfer curve at two drain biases, the retention bake at which the read
+  window closes (uneven read times, which is what `xValues` is for), and an
+  output driver's maximum drive current (VOH vs VOL under load). The transfer
+  curve is swept over **derived** `log10(t[n])` tests — a sweep reads any test,
+  which is how a log-scale curve is drawn without a log option.
+- **Derived tests are marked on the sweep card**: `SweepPoint` carries `derived`
+  and `expression`, ordinal tick labels keep the `†` in front of a truncated name, the
+  tooltip marks each series row and adds each expression, and the footer shows
+  the key.
+- **Sweep card text.** The crossing line lower-cased the y label ("Cell Vt"
+  became "cell vt", "Fmax" became "fmax") — the width line had already been
+  fixed for the same reason ("dBm" → "dbm"); widths printed in engineering
+  notation (`32.7E-3`); and an x label carrying its own unit doubled the
+  brackets (`(VDD (V))`). X values — ticks, crossing and widths — now share one
+  plain-decimal rule, and a width reads "0.0327 on the VDD (V) axis".
+- The derived-tests example opened on a Switching Window measured at the step
+  where its two curves cross, so the gap sat around zero against `limitLow: 0`
+  and nearly every die carried a ▽. It is now measured at a fixed read step
+  with a 0.33 V margin, so only an edge band fails.
+- **A derived test is now identifiable from `result.testDefs` alone.** `derived`
+  was declared only on the `DerivedTestDef` *input* type, while `result.testDefs`
+  is a homogeneous `TestDef[]` — so every display surface needed a cast to ask
+  whether a value was measured or derived, and `expression`/`constants` were
+  stripped off the admitted def entirely, leaving nothing to say where a number
+  came from. All three now travel on `TestDef` as `readonly` fields set by
+  `buildWaferMap`. This is the prerequisite for marking derived tests in the UI:
+  a display that cannot ask the question cannot mark it, and an engineer reading a
+  Cpk table should never be left to assume a number came off the tester. The
+  alternative — hosts holding their own `derivedTests` input beside the result and
+  joining by test number — is a second source of truth that can disagree with the
+  def actually admitted, which carries the resolved `testType`.
+- **`testLabel` / `isDerivedTest` / `derivedTestSource` / `hasDerivedTests`**
+  (`renderer/testLabel.ts`, internal) — one definition of how a test is named and
+  how a derived one is distinguished. The "name, or *Test N* when it has none"
+  fallback existed in six places (`stats/sweep.ts`, `capability.ts`, `testPassRate.ts`,
+  `analyzeWaferMap.ts`, `charts/chartShell.ts`), all now routed through it. Around
+  sixteen surfaces display a test name; a marker added per surface would have been
+  that rule twenty-odd times over, which is how two of them end up disagreeing.
+- **Derived tests are marked in the process capability panel.** A `†` precedes
+  the test name, the legend gains the key "† Derived, not measured", and the
+  tooltip says the same in words and shows the expression the value was
+  computed from. A dagger, not `ƒ`: in this domain `f` reads as femto,
+  and a `ƒ` beside `fA`/`fF` units is a real misread.
+  `TestCapability`/`CapabilityDatum` gain `derived` and `expression`.
+- **…and everywhere else a test is named, always in front of the name.** In a
+  list the marks then form a column down the left edge, so a derived test is found
+  at a glance, and truncating a long name can never cut the mark off; a list
+  holding a derived test pads its measured names by the mark's width so names stay
+  aligned, and a list without one is unchanged. The map title and colorbar
+  (`† Leak Shift (nA)`)
+  with the key on its own line beneath, drawn via a new optional
+  `MapTitleParts.note`; the map tooltip, which adds the key and the expression;
+  finding labels and sentences, marked at the source so no reader of a finding
+  can show it unmarked, with `StatsFinding.variable.derived`/`expression` as the
+  structured form; `stats.functionalYield[].label` (plus `derived`/`expression`);
+  the Summary panel's parametric and functional tables and its findings list,
+  each with a key line naming every expression; and both HTML reports, whose key
+  lists the expressions because a printed report has no hover. CSV exports carry
+  plain names plus a trailing **Derived from** column, only when a row is
+  derived — a CSV has nowhere to put a key. The key is a single short string,
+  *Derived, not measured*, so it fits the corner of a map and cannot drift
+  between surfaces. Every surface goes through `renderer/testLabel.ts`, which
+  also replaced two more hand-written *Test N* fallbacks in `buildView.ts` and
+  one in the gallery's stacked cards, whose synthetic def now keeps the flag.
+  The finding tooltip now has one rule, `formatFindingTooltip`, which the
+  Summary panel shares with both reports instead of using `summary` directly.
+  The places a test is *chosen* are marked too: the plot-mode test menu (a slot
+  in front of each name, reserved only when a derived test is listed, and a key
+  line at the foot), the Insights test pickers (`testOptionLabels`), the
+  correlation matrix's axis labels and tooltip (key on its hint line; its CSV
+  gains per-side *derived from* columns) and the die list's column headers (key
+  line above the table; the CSV header states the expression). The last two
+  hand-written *Test N* fallbacks, in the plot-mode menu and the die list, now go
+  through `testLabel`.
+- **`DERIVED_MARK` and `DERIVED_KEY` are exported** (root and `/renderer`), so a
+  host listing tests in its own UI marks derived tests exactly as the library does
+  instead of keeping its own copy of the glyph and the words. tsmap's test selector
+  is the first use.
+- Getting there turned up two places that dropped the flag. **`mergeTestDefs`**,
+  which builds a gallery's single test list, rebuilt each def field by field and
+  never named `derived`, so every cross-wafer panel would have shown a derived
+  test unmarked while the single-wafer view marked it. It now carries `derived`
+  and `expression`, marking a test derived when **any** wafer says so: marking
+  a measured test is an oddity someone queries, while leaving a derived one
+  unmarked goes unnoticed. The Summary panel's per-test table narrowed defs the
+  same way and now keeps both fields. It also held a seventh copy of the
+  *Test N* fallback, now routed through `testLabel`.
+
+### Changed
+
+- **Docs and examples brought up to date with this release.** The developer
+  guide's sweep section no longer says `tests` has no range syntax or that a
+  sweep has no log option; it covers ranges, `xFromName`, `xUnit`, `xScale` and
+  drilldown. The sweeps example adds a fifth sweep (an RRAM resistance
+  distribution read from test names on a log axis) and gives the output-driver
+  sweep an x unit; the derived-tests example's sweep uses ranges and a real swept
+  quantity (pulse amplitude in volts) instead of ordinal steps, and places the †
+  in front of the name as everywhere else. The README, `AGENTS.md` and
+  `llms.txt` now mention derived tests, sweeps and drilldown.
+  Those two examples' code cards, a four-across grid that cut every code
+  block off at about half its width in 12 px type, now show one example per
+  row — the code whole, in monospace at 13.5 px, beside notes at 14.5 px,
+  stacked on narrow screens — from one shared style in `demo.css`. `--mono`,
+  which every example's code referenced and nothing defined, is now set.
+  The derived-tests example is now in two labelled parts — derived tests are
+  *data* (`buildWaferMap`'s `derivedTests`; tsmap's test-definitions file), a
+  sweep is a *chart* (the renderer's `insights.sweeps`; tsmap's separate sweeps
+  file) — because a run of look-alike snippets read as one list. Its snippets
+  show the whole call each belongs to, it says the sweep is in Insights →
+  Sweeps, with a *Show the sweep* button that presses the gallery's own Insights
+  button, and it links to the sweeps example. The sweeps example opens with
+  where its entries go.
+
+- **`scripts/check-bundle-size.mjs` attributes lazy chunks by what imports
+  them, not by file name.** Once drilldown and Insights shared the chart panels,
+  esbuild split the shared code into an anonymous `chunk-*.js`, which a file-name
+  test counted as core. That would have added ~5 KB of lazy code to the "always
+  downloaded" figure. The guide, Insights and drilldown now count as their own
+  static closure minus what the entry already loads. The Insights figure now
+  includes the chart code it shares with drilldown, because opening Insights
+  downloads it.
+- **Axis ticks sit on round values, and are labelled to their spacing.** Tick
+  labels used to take their decimals from each value's own size, never from the
+  gap between ticks, so a 1–10 axis read "2.00 4.00 6.00 8.00" and a bandgap's
+  1.195–1.205 V read "1.20" five times — a sloped curve labelled as a flat line.
+  And only the colorbar placed ticks on round numbers: the box plot, scatter,
+  trend and sweep divided the data range into equal fractions (2.54 / 2.04 /
+  1.53 GHz), the histogram labelled its bucket edges, and its count axis carried
+  an inline copy of the rounding rule with different breakpoints. Every numeric
+  axis now goes through `renderer/axisTicks.ts` — one 1-2-5 rounding rule
+  (`niceStep`), round ticks inside the data range, and labels with exactly the
+  decimals the step needs (`stepDecimals`): "2 4 6 8", "1.196 1.198 1.200".
+  **Density comes from the space, not a tick count:** `fitTicks` takes the
+  finest round step whose labels fit — measured label widths plus an 8 px gap
+  on a horizontal axis, a line spacing on a vertical one. A fixed count, tried
+  first, rounded a 200 px Idsat box plot (0.863–1.56 mA) to 1.0 / 1.2 / 1.4 —
+  fewer ticks than the five it replaced; it now reads 0.9 / 1.0 / … / 1.5. The colorbar's exact min and max are data values rather than grid
+  values, so they get one decimal more, dropped when it is a zero — a 9.87
+  maximum no longer rounds to "10". Log-scale and integer-valued colorbars, die
+  labels and limit labels keep size-based formatting; they are not tick grids.
+  Every chart's tick labels change, so doc screenshots need recapturing.
+- **The wafer and lot reports' findings table now uses plain bin terms**
+  ("hard bin 2", not "HBin 2"). Both HTML reports render one findings table,
+  `findingsTableHtml`; each report module had kept its own, and only the
+  findings-only report translated the bin terms.
+
+### Deprecated
+
+- **`renderFindingsReportHtml`** — removed in 0.31.0. Use
+  `renderWaferReportHtml(result, summary)` or `renderLotReportHtml(results)`:
+  their Findings section is the same table, alongside the population and yield
+  it was found in. It was kept in 0.30.1 on the grounds that the Summary panel
+  used it, which had not been true since 0.20.0; nothing in wmap or tsmap calls
+  it. It ships deprecated in this release, so it goes in 0.31.0 with the 0.30.0
+  deprecations. `deprecated()` now takes a removal version per name, for a name
+  deprecated too late to go with the rest.
+
+### Fixed
+
+- **A menu row's hint is no longer drawn under its own menu.** Menus sit in a
+  dedicated layer (`menuLayerFor`) that outranks everything else in its root,
+  and the shared tooltip was placed beside that layer — so the reason on a
+  greyed-out row (the drilldown menu's, the Overlays menu's) appeared behind the
+  menu it explained. `positionTooltip` now places the tooltip inside the
+  anchor's menu layer at `Z_ABOVE2`, above every menu there, still resolved per
+  root (a host `<dialog>`, a wmap modal).
+
+- **The map's hover tooltip no longer jumps away from the die.** The shared
+  tooltip steps clear of its anchor when the anchor is under 40% of the window
+  tall — right for a toolbar button, which its tip must not cover, and wrong
+  for the map canvas, where the pointer is on the die the tip describes. Every
+  map that small (every gallery card, the smaller maps on a page such as the
+  geometry example, any map in a tall window) had its tip thrown below or above
+  the whole canvas, measured at up to 266 px from the pointer. The map now
+  passes `followPointer` to `positionTooltip` and the tip stays beside the
+  pointer; control tips keep stepping around their buttons.
+
+- **An expanded chart grows into its modal, in the direction that suits it.**
+  Several cards kept their grid-card size inside the expand modal: the trend
+  and sweep plots stayed a few hundred pixels tall, ring and quadrant yield
+  kept a fixed-size circle, the correlation matrix kept small cells, process
+  capability stopped at ~160 px per test, and row charts (yield by wafer,
+  pareto, pass rate, value distribution) left most of a 700 px box empty. Each
+  card now declares how it grows (`setChartGrow`): **plots** fill width and
+  height in a wider box; **row charts** keep bars full-width, show every row the
+  box has room for, and the box opens sized to its rows (within the viewport);
+  **square** charts grow to the shorter side in a square box. Capability's
+  columns spread across the width while each box keeps its grid maximum width.
+  Growth past the grid size happens only while expanded, so the Insights grid
+  is unchanged; maximise/restore and drag-resize shrink back correctly.
+- **Chart cards measure their chrome, not their stretch.**
+  `growCardToFitContent` took the card's overhead as `card height − body
+  height`, which counts any stretch as overhead and grows the card on every
+  redraw — why several panels opted out of stretching (`alignSelf: 'start'`),
+  which is what kept them small in the modal. It now sums the card's other
+  children, so a stretched card is harmless. Trend and sweep no longer ask for
+  the height they were given as their minimum, which would have stopped a
+  shrinking modal.
+- **Chart tooltips wrap inside their background.** They were `nowrap` under a
+  280 px cap, so a longer line — a sweep row with its p10–p90 and n, a derived
+  test's expression — ran out past the dark box. They now wrap within 320 px,
+  breaking an unbroken expression if they must. The sweep tooltip puts each
+  series' spread and n on a line of their own under its median.
+
+- **A functional-test finding merged across adjacent regions reported no
+  difference, and hid the real one.** Since 0.20.3, when a functional pass-rate
+  signal spanned adjacent rings, sectors or quadrants, the merge pass that joins
+  them into one finding (`Rings 1–2`) had no functional branch and fell through
+  to the bin one. It counted dies whose hard bin equalled `variable.bin` — which
+  a functional finding does not have — so both sides counted 0, and the merged
+  finding read *"Rings 1–2 has HBin undefined occurrence 0.0 percentage points
+  lower than the rest of the map"*, with a meaningless p-value. It also
+  **replaced** the correct per-region findings it merged, so a real functional
+  signal spanning adjacent regions was shown as no difference at all. The merge
+  now recomputes the pass rate over the merged region exactly as the per-region
+  builder does (verdicts through `getTestPassStatus`, dies without a verdict
+  excluded), and the sentence names the test. Found while testing the
+  derived-test marker, whose test wafer happened to have exactly this shape.
+- **Merged-region findings used a singular verb:** *"Rings 1–2 has HBin 3
+  occurrence…"*, *"Quadrants NE & SE has…"*. A merged region is plural; bin and
+  functional pass-rate sentences now say "have". The Summary panel, which strips
+  the region from a row shown under its own group header, accepts either verb.
+- **A `NaN` test value was classified as in-spec.** The spec-limit rule existed in
+  two places — `classifySpec` (die colouring, ▽/△ markers, the legend's spec tally)
+  and a private `specJudgement` in `stats/testPassRate.ts` (spec pass-rate tables) —
+  and they disagreed on two cases. `classifySpec` compared with `<` and `>`, which
+  are both false for `NaN`, so a non-finite measurement fell through to `'pass'`:
+  the exact "never drawn as plain in-spec" failure its own doc comment described.
+  It also reported `'pass'` for a test declaring no limits at all, inflating a spec
+  pass rate to 100% for every unlimited test. There is now one implementation
+  (`renderer/spec.ts`), strict on both, used by the renderer, stats and the
+  `specPass[n]` accessor.
+
+## [0.30.2] — 2026-09-20
+
+### Added
+
+- **A gallery now reports its own progress, so a host's indicator can be honest about a long
+  load.** `GalleryOptions` gains two callbacks (API §6.2):
+  - `onItemResolved(resolved, total)` — the **advance** signal, fired as each card is built.
+    `total` is the count you passed, so it is right from the first call and a progress bar can be
+    sized before anything arrives.
+  - `onItemsResolved()` — the **settled** signal, fired once the gallery has finished: every
+    factory resolved *and* the lot-wide legend, shared colours and Summary panel up to date. On a
+    large lot the panel keeps filling in for seconds after the last card, so this is deliberately
+    later than "the cards are in" — a host clearing its indicator when the cards land leaves the
+    rest of the wait unexplained.
+  - Both fire whichever form the items took, so no host branches on the path the gallery chose: a
+    fully pre-built mount is one `onItemResolved` call with `resolved === total`, and
+    `onItemsResolved` always fires asynchronously, after `renderWaferGallery` has returned. Both
+    fire again on a rebuild (`setItems`, or switching into a stacked mode).
+- **`CorrelationMatrix.sample`** — present only when the matrix was computed from a sample of the
+  dies, with `of` (the dies that carried test values) and `used` (how many were read).
+  The Insights correlation panel labels a sampled matrix from it; a host reading the matrix
+  directly must do the same.
+
+### Changed
+
+- **Correlation is computed from at most 25,000 dies.** It is the only analysis here that is
+  quadratic in tests and linear in dies — a 400,000-die, 50-test lot is 490 million pair updates,
+  which in a browser presents as a panel that never renders. Above that budget the dies are
+  sampled by an even stride across the whole population, never a prefix (dies arrive grouped by
+  wafer, so the first 25,000 of a lot are its first few wafers and would describe those rather
+  than the lot). At 25,000 dies the standard error of `r` is under 0.007, so the coefficients are
+  unchanged at the precision they are displayed to. **A sampled matrix always says so** — in the
+  Insights panel and in `CorrelationMatrix.sample`.
+- **The lot and wafer Summary panels are built across tasks instead of in one block, and fill in
+  section by section.** Pooling every die of every wafer and deriving the bin, region and
+  per-test sections from it is the longest single piece of work this library does: 15.3 s on a
+  50-wafer lot of 4,000 dies × 100 tests, which is where a browser starts offering to kill the
+  page. It is now around 335 steps of a few hundred ms at most. An ordinary lot still renders in
+  one synchronous pass and looks exactly as it did. A panel render in flight is abandoned when
+  the lot, filter or highlight changes, and on `destroy()`.
+- **The same panel work is also about 2.3× cheaper, and a lot pays for it once.** The per-test
+  pass over a lot's pooled dies is memoised on the population it describes, so the lot Summary
+  panel, the Insights Overview and the Insights capability chart share one computation instead of
+  running three; the sort inside it uses a `Float64Array` (4× on the whole pooled pass); and the
+  Test Values rows are built in one pass instead of three.
+- **Switching Insights tabs no longer rebuilds the panel you are returning to.** A built section
+  is kept per view, so going back to Distributions is instant rather than re-running capability,
+  boxplot, histogram and trend (about 5 s at 400,000 dies). Only a pure tab switch reuses it —
+  new data, Group by, scope or an axis preference still rebuilds everything.
+- **A lot-wide option is pushed to the cards only when its value actually changed.** `binColors`,
+  `valueRange` and `metadataValueOrder` are re-derived from the whole population as each wafer
+  resolves, and each derivation allocates a fresh object, so every card was being rebuilt and
+  redrawn for an identical value. On a progressive load that is quadratic: on 50 wafers × 8,000
+  dies × 50 tests in Chrome the bin-colour map alone was 1,275 pushes and 24 s of a 64 s load,
+  and is now one push.
+- **The gallery's lot Summary panel now settles once, when the last wafer resolves, instead of
+  re-rendering after every one.** A progressive load was re-pooling and redrawing the whole
+  panel on each newly resolved wafer, which is quadratic in wafer count and was the single
+  largest cost on this path: 175 s of a 182 s, 50-card progressive load. The panel still renders
+  once at mount and again whenever a user opens it. Combined with the change above, 50 cards of
+  8,000 dies now load in **7.7 s of non-blocking work with no task over 440 ms**, down from
+  182 s.
+
+### Fixed
+
+- **A large wafer or lot could fail outright with "Maximum call stack size exceeded".**
+  `Math.min(...)`/`Math.max(...)` spread a whole die array into a call, which throws once the
+  array passes roughly 100,000 entries — reachable on a single 400,000-die wafer in aggregated
+  values, inferred wafer geometry, reticle bounds and several chart scales. Every such call now
+  uses the `minOf`/`maxOf` helpers, and `scripts/check-spread-limits.mjs` (wired into
+  `npm run check`) fails the build if one comes back.
+- **A non-finite test value could make a whole test's statistics `NaN`.** `computePerTestStats`
+  sorted and summarised whatever `testValues` held, with no `Number.isFinite` screen, so one
+  `NaN` or `Infinity` from a parser silently turned that test's mean, median, sigma and Cpk into
+  `NaN` rather than being dropped as no data.
+
 ## [0.30.1] — 2026-09-16
 
 ### Security
 
-- **Names from a data file could run script in a tooltip.** The die tooltip and the Insights
-  chart tooltips (correlation, capability, boxplot, trend, histogram, bar and grouped-bar
-  charts), plus the legend-row and toolbar tooltips, built HTML from test names, units, bin
-  names, wafer labels and metadata values without escaping them. A file with a test named
-  `<img src=x onerror=…>` ran that script when a user hovered, in a Tauri, Electron or
-  WebView2 host inside the app's own webview. Every such value is now escaped. The escape
-  helper, formerly private to the reports, is the one copy for the library (`core/utils.ts`),
-  and `tests/htmlEscaping.test.mjs` fails if a tooltip puts a raw label into HTML again.
+- **Fixes a security issue in how names from a data file are displayed.** Earlier versions are
+  affected; update to 0.30.1, particularly if your app opens files from sources you don't
+  control. Names now always display as plain text, so a name that contains markup shows it
+  literally.
 
 ### Changed