@wafertools/wafermap 0.21.1 → 0.22.0

package/AGENTS.md

@@ -0,0 +1,170 @@
+# wafermap — rules for AI coding agents
+
+Guidance for AI tools (Claude Code, Codex, Copilot, Cursor, …) writing code that
+**uses** `@wafertools/wafermap`. Paste the rules below into your project's own
+agent config so they are loaded whenever the agent works on wafer map code.
+
+This library renders semiconductor wafer maps. Its output drives yield calls, lot
+dispositions and process changes, so a plot that is *plausibly but silently wrong*
+is the expensive failure — worse than one that throws. Most rules here exist
+because the obvious-looking code produces exactly that.
+
+<!-- RULES:START -->
+
+## wafermap — usage rules
+
+`@wafertools/wafermap` renders wafer maps from semiconductor die test data.
+Wrong-but-plausible output drives real yield and lot decisions, so prefer failing
+loudly over guessing.
+
+### Entry points
+
+- `@wafertools/wafermap` — `buildWaferMap()`, geometry, `registerColorScheme()`. Pure, no DOM, server-safe.
+- `@wafertools/wafermap/render` — `renderWaferMap()`, `renderWaferGallery()`, `toCanvas()`. Needs the DOM.
+- `@wafertools/wafermap/stats` — `analyzeWaferMap()`, `analyzeWaferLot()`. Pure analysis.
+- `@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. Reach for `toCanvas()`/`buildView()`
+only when you need the low-level pipeline — they give up the toolbar and every UI
+correctness guarantee that comes with it.
+
+### Traps that produce silently wrong maps
+
+- **Never `die.hbin ?? 0` or `die.sbin ?? 0`.** A missing bin is not bin 0 — it is
+  no-data, and must render grey. Defaulting to 0 invents a bin and changes the
+  yield number. Leave the field absent.
+- **`x` and `y` are prober step positions (integers), not millimetres.** Pass them
+  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]`.
+- **`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
+  only via `getTestPassStatus(die, testNumber, def)`; never read `die.testPass`
+  directly and never interpret a 0/1 in `testValues`. A missing verdict is no-data,
+  never a fail.
+- **Show users `die.x` / `die.y` only.** Never surface internal display or
+  transformed coordinates in tooltips, labels or reports, whatever the rotation or
+  flip state.
+- **A die with test results is always fully on the wafer.** A prober only steps to
+  sites that fit. Never recompute a `partial` flag by testing die corners against
+  the wafer circle — that manufactures fake partial dies which are then greyed out
+  and dropped from yield. A die outside the wafer means the *geometry* is wrong.
+- **Check `result.warnings` and `summary.stats.warnings`.** Both are
+  `WaferWarning[]` — `{ code, message, severity }`. Branch on `code`, never on the
+  prose. Geometry advisories are severity `'error'`: they mean dies may be drawn in
+  the wrong place. The renderers surface these themselves in a toolbar indicator, so
+  do NOT hand-roll a second display — pass
+  `warnings: { display: false, onWarning }` if the app has its own notification UI.
+  (`result.inference.warnings` is a deprecated string mirror; do not use it.)
+- **Container needs a real height.** A zero-height parent renders nothing. This is
+  the most common "it didn't work" report.
+
+### API facts that are easy to guess wrong
+
+- `PlotMode` values are camelCase: `'hardBin'`, `'softBin'`, `'value'`, `'metadata'`,
+  `'stackedValues'`, `'stackedBins'`, `'stackedSoftBins'`. Never snake_case.
+- `retestCount` is the total probe count — `2` means probed twice. Do not add 1.
+- `retestPolicy: 'best'`/`'worst'` is pass/fail-aware via `passBins`; bin number only
+  breaks ties within a category.
+- Hard bins (`hbin`) and soft bins (`sbin`) are independent number spaces. Never merge them.
+- Build once, render many: `buildWaferMap()` handles data + geometry; re-render UI
+  changes through the controller's `setOptions()`, not by rebuilding.
+- `result.view` is internal. Use the promoted fields: `result.plotMode`,
+  `result.metadata`, `result.isLotStack`, `result.hbinDefs`, `result.sbinDefs`,
+  `result.testDefs`.
+- Die keys come from `getDieKey(die)`. A hand-rolled `` `${x},${y}` `` breaks
+  click-to-highlight silently, because findings carry `dieKeys` in that exact format.
+- `stats.warnings` is `WaferWarning[]` (it was `string[]` before 0.22.0). Read
+  `w.message` to display, branch on `w.code`. Code that calls a string method on an
+  entry — `warnings[0].includes('…')` — is the old shape and will throw.
+- **`summary.findings` is the complete list and contains restatements of the same
+  fact.** Building a list for a human to read? Exclude what other findings absorb:
+  `const absorbed = new Set(summary.findings.flatMap(f => f.absorbedIds ?? []))`.
+  Skip that and one edge failure is reported up to three times per region — a hard
+  bin row, its soft-bin twin, and the yield row that restates the pass bin. Do NOT
+  use `relatedIds` for this; it is a different relationship and some ids it names
+  no longer exist in `findings`.
+
+### Scale: do not turn this into a data explorer
+
+The most common performance mistake is treating the library as somewhere to dump
+an entire test program and browse it. It is a *renderer* — it analyses everything
+it is handed, because it has no way to know which tests anyone will look at.
+
+- **Pass only the tests you will actually chart or analyse in `testDefs`.** A real
+  parametric program can carry hundreds of tests while the user ever looks at a
+  handful. Cost scales with test count, and test correlation scales
+  *quadratically*: on a ~1,000-die wafer, `enableTestValueAnalysis` costs ~25 ms at
+  6 tests and ~91 ms at 60, while the correlation matrix goes from 15 pairs to 1,770.
+- **Do not "load everything, filter in the UI".** Filtering after the fact means you
+  already paid for the parse, the transfer and the analysis.
+- **The right shape is pre-scan → select → load.** Scan the source for which test
+  numbers exist (and their names/limits if available), let the user choose, then
+  parse and build only the chosen tests. A scan that reads test identity without
+  reading every value is dramatically cheaper than a full load, and it is what makes
+  a large file feel instant.
+- **Above 250 discovered tests, `analyzeWaferMap` gives up on test-value analysis
+  entirely** — it returns no test findings rather than a trimmed set, and records a
+  `WaferWarning` with code `'test-count-capped'` in `stats.warnings`. Silence is not
+  success here: an empty findings list is indistinguishable from "nothing to report"
+  unless you check. Pass `testNumbers: [...]` to scope the analysis explicitly.
+- **Reach for options deliberately.** Plain `analyzeWaferMap()` is cheap;
+  `computePerTestStats` is modest; `enableTestValueAnalysis` is the expensive one
+  (roughly 10× the base analysis on a large wafer) and exists to find spatial
+  patterns automatically — do not enable it by default just because it sounds good.
+- **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.
+- **In a gallery, pass `perWaferSummaries` to `analyzeWaferLot`** so it reuses the
+  per-wafer analysis you already ran instead of redoing it.
+
+### Removed — do not emit these
+
+| Never | Use instead |
+| --- | --- |
+| `DieResult.values` / `Die.values` | `testValues` (keyed by test number) |
+| `TestDef.index` | `TestDef.testNumber` (required) |
+| `ViewOptions.colorBySpec` | `passFailDisplay: 'spec'` |
+| `ViewOptions.testIndex` | `activeTest` |
+| `mountWaferCanvas` | `renderWaferMap` |
+| `HARD_BIN_COLORS` / `SOFT_BIN_COLORS` | `BIN_PALETTE` |
+| `GalleryItem` | `WaferMapDisplayItem` |
+| `MountOptions` | `RenderOptions` |
+| `WaferCanvasController` | `WaferMapController` |
+| `CanvasHitTarget` | `HitTarget` |
+| `buildScene` / `BuildSceneOptions` / `SceneOptions` | `buildView` / `ViewOptions` |
+| `WaferFlat`, field `flat` | `WaferNotch`, field `notch` |
+| `isInsideWaferWithFlat` | `isInsideWafer` |
+| `DieSample` / `WaferMapPoint` | `DieResult` |
+| `colorScheme: 'color'` | `colorScheme: 'default'` |
+| `plotMode: 'specLimit'` | `passFailDisplay: 'spec'` |
+| standalone `getDieAtPoint` | `hitTarget.getDieAtPoint` from `toCanvas()` |
+| `RenderOptions.tooltipTestLimit` | (was a no-op; nothing replaces it) |
+
+Passing a removed option is a type error, and is ignored at runtime. Do not add
+compatibility shims for them.
+
+### Terminology in user-facing text
+
+- Never write "channel" — use "index", "slot" or "test". "Channel" is tester
+  hardware jargon that confuses the engineers reading these maps.
+- Label what is actually shown. Name the real pass bins rather than assuming bin 1;
+  say "Hard Bin Breakdown" not "Bin Breakdown"; identify an aggregated or filtered
+  population (`N=50`, "6 wafers · mean") so nobody mistakes a lot stack for one wafer.
+
+<!-- RULES:END -->
+
+## Where to look
+
+- [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
+  [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
+user, so this file gets fixed.

package/CHANGELOG.md

@@ -19,15 +19,174 @@ under `### Breaking`.
 
 ---
 
-## [Unreleased]
+## [0.22.0] — 2026-08-04
+
+### Breaking
+
+- **`StatsSummary.stats.warnings` is now `WaferWarning[]`, not `string[]`.** The
+  library raised advisories in two incompatible shapes — structured
+  `{ code, message }` on `WaferMapResult.warnings`, raw prose strings on the stats
+  summary — so a host had two vocabularies to handle and no stable key to branch
+  on for half of them. Both are now `WaferWarning`.
+
+  Migration: read `w.message` where you previously read the string, and branch on
+  the new stable `w.code` (`'test-count-capped'` is the one raised today) instead
+  of matching prose. Code that did `warnings[0].includes('…')` is exactly what
+  this replaces — that string was never a contract.
+
+- **`findTestDef`, `resolveTestNumber`, `getUniqueTestNumbers` and
+  `generateTextOverlay` are no longer exported from `/renderer` (or the root).**
+  They are internal helpers of the view pipeline with no documented contract, and
+  nothing outside the library used them. An export nobody can look up is still API
+  surface you cannot change later, so they were withdrawn rather than documented.
+
+  Migration: none expected. If you did depend on one, import it from
+  `@wafertools/wafermap/renderer/buildView.js` and open an issue saying what for —
+  the fix is to give you a supported entry point, not to re-widen the surface.
+
+### Added
+
+- **The library now surfaces its own data warnings.** A ⚠ indicator appears in the
+  toolbar only when there is something to say; clicking it lists each advisory with
+  its code and explanation. It also feeds the Summary panel's banner and a new
+  `onWarning` callback, all from one collected, de-duplicated, severity-ordered set.
+
+  This closes a real gap rather than adding a nicety: **geometry advisories were
+  rendered by no UI at all.** `'partial-coverage'` means the inferred diameter and
+  centre may be wrong and dies may be drawn in the wrong place, and nothing ever
+  told the person looking at the map. Analysis advisories fared little better — they
+  appeared only if the host both passed `statsSummary` and the user opened the
+  Summary panel. The library has the information to know the display may mislead,
+  so showing it is its responsibility, not the caller's.
+
+  Deliberately not a toast: these are persistent conditions about whether the map
+  can be trusted, and a message that dismisses itself leaves the map still wrong
+  with no way back to the explanation.
+
+- **`WarningsOptions` on `renderWaferMap` and `renderWaferGallery`** —
+  `{ display?: boolean; onWarning?: (warnings: WaferWarning[]) => void }`. Hosts
+  with their own notification system pass `{ display: false, onWarning }`: the
+  library still collects, de-duplicates and severity-orders, and the host owns only
+  presentation. `collectWarnings` and `severityOf` are exported from
+  `@wafertools/wafermap/render` so such a host can reproduce exactly the set the
+  built-in UI would have shown rather than re-deriving it from two sources.
+
+- **`WaferWarning.severity`** — `'error' | 'warning' | 'info'`, defaulting to
+  `'warning'`. Geometry advisories are `'error'` (the map may be positionally
+  wrong); the test-count cap is `'warning'` (a feature produced nothing, but what
+  is drawn is correct). Drives the indicator's colour and ordering — and the
+  severity is always in the accessible name too, never colour alone.
+
+- New `--wmap-err-bg` / `--wmap-err-border` / `--wmap-err-text` theme tokens
+  (9.55:1 contrast on their background, clearing WCAG AA on all three surfaces
+  they appear on).
+
+
+- **Downloadable examples package.** `site/wafermap-examples.zip`, built as part of
+  `npm run build:site` and published alongside the docs. Contains every example, the
+  bundled library, the sample datasets, and a `starter/` skeleton to copy as the seed
+  of an application. Unzip, run `sh serve.sh` (or `serve.cmd` on Windows), and it works
+  with no npm install and no network — the offline path matters for locked-down fab
+  networks. The bundled `serve.py` pins the MIME type for `.js` rather than trusting
+  the platform: Python's stdlib server reads MIME types from the Windows registry, and
+  where that mapping has been altered it serves JavaScript as `text/plain`, which
+  browsers refuse to execute as a module — failing every page on Windows while working
+  on Linux.
+- **`AGENTS.md` — usage rules for AI coding agents.** Most consumers now write wafer
+  map code through Claude Code, Codex, Copilot or Cursor, and this library's inputs
+  invite confident wrong guesses: `die.hbin ?? 0` reads as ordinary defensive coding
+  but turns no-data dies into bin 0 and moves the yield number; `activeTest` reads
+  like an index but is a test number. The file's core is a copy-paste block for the
+  consumer's own agent config, surfaced at
+  [/agents/](https://wafertools.github.io/wafermap/agents/), shipped in the npm
+  package (`node_modules/@wafertools/wafermap/AGENTS.md`) and at the root of the
+  examples archive. `scripts/check-agents-guide.mjs` verifies it against
+  `dist/**/*.d.ts` on every `npm run check` and CI run — every recommended symbol
+  must exist, every symbol in the removal table (parsed from the table itself, not a
+  duplicate list) must be absent, and structural claims are checked rather than
+  trusted. An agent guide that names a removed API is worse than none.
+- `llms.txt` now ships in the npm package and the examples archive, with its
+  repo-relative links replaced by absolute ones — they resolved to nothing in both
+  of those locations.
+- `docs/examples/manifest.json` — single source for the examples list, consumed by
+  `demo-nav.js`, the `index.md` generator, the archive builder, and a nav consistency
+  check wired into `npm run check` and the test suite.
 
 ### Changed
 
+- **Findings no longer restate the same fact several times.** One edge failure
+  could produce, per region: a hard-bin row, its soft-bin twin with an identical
+  delta, a pass-bin row, and a yield row saying the same thing as the pass-bin row
+  — up to seven rows for what an engineer would state in one sentence. Two exact
+  redundancies now collapse:
+
+  - A soft-bin finding whose hard-bin twin covers **provably the same dies** is
+    absorbed, and the surviving row says so (`Hard and soft bin 3 (same dies)`).
+    The test is die-set identity computed from the dies, never bin-number
+    equality — hard and soft bins are independent number spaces, and merging on
+    the number would report one population under the other's name.
+  - When exactly one pass bin is configured, that bin's row and the yield row are
+    the same statement by definition, so the bin row is absorbed into the yield
+    row. With several pass bins no single bin equals yield, and the rule correctly
+    does not fire.
+
+  The surviving row names what it absorbed — "Ring 4 (edge) has hard bin 3 and
+  soft bin 3 (same dies) occurrence 8.8 percentage points higher…" — rather than
+  quietly dropping the other half. "(same dies)" is load-bearing: without it the
+  wording could be read as two populations summed.
+
+  This applies at lot level too. `analyzeWaferLot` skips per-wafer findings that
+  were absorbed, so a twin does not reappear as its own lot row — which is where
+  the duplication was most misleading, since every lot row is annotated "seen on
+  N/M wafers" and one fact stated twice reads as two signals corroborating
+  each other.
+
+  Nothing is discarded: absorbed findings remain in `summary.findings` and are
+  still returned by `filterFindings`. Only the Summary panel and the findings
+  report hide them, via the new `StatsFinding.absorbedIds`.
+
+- `StatsFinding.absorbedIds` — IDs of findings another finding restates. Kept
+  separate from `relatedIds`, which already meant two different things (a
+  run-merge's audit trail of constituents it *replaced*, which no longer exist,
+  and a spatial pattern's live supporting detail). Anything in `absorbedIds` is
+  guaranteed still present in `findings`.
+
+- **Examples consolidated from 26 pages to 20.** Several demos differed only by which
+  option was enabled. `findings`, `summary-panel`, `lot-findings`, `gallery` and
+  `lot-stack-analysis` are now one `statistics.html` with a scope selector
+  (single wafer / lot gallery / lot stack) whose banner names the exact calls and
+  options in force; `color-schemes` folded into `display-control.html`, where the
+  existing scheme dropdown already did the same job; `partial-data` folded into
+  `geometry.html` as a second section. Every old URL keeps a redirect stub pointing at
+  the merged page and the anchor that reproduces what it used to show, and the Guide
+  cross-links now target those anchors, so per-topic granularity is unchanged.
+
 - **Package renamed from `@paulrobins/wafermap` to `@wafertools/wafermap`.** The GitHub repo
   moved from `telecasterer/wafermap` to `wafertools/wafermap` along with it — repository,
   homepage, and issue-tracker URLs all point at the new org. `@paulrobins/wafermap` is
   deprecated on npm in favour of this package; no functional changes.
 
+### Fixed
+
+- **The toolbar could overflow across neighbouring content.** It is pinned by its
+  right edge with no width bound, so once wider than its container the excess grew
+  leftward — out of the card and over whatever sat beside it (the next map in a
+  grid, an adjacent gallery card). It had always been wider than a ~400px
+  container. It now wraps within the container, breaking between control groups
+  rather than mid-group, with `wrap-reverse` so the trailing group keeps the top
+  row and Expand keeps its top-right corner.
+
+
+- **Custom colour schemes did not work on the built documentation site.**
+  `scripts/bundle-docs.mjs` built each importmap entry point as an independent esbuild
+  bundle, so `wafermap` and `wafermap/render` each inlined a private copy of the
+  colour-scheme registry. `registerColorScheme` imported from `wafermap` wrote into a
+  registry the renderer never read, and a custom scheme rendered pixel-identical to the
+  default palette — silently, with no error. All entry points are now built in one
+  invocation with code splitting, so shared module state lives in a common chunk. Only
+  ever affected the bundled site build; `npm run dev` serves unbundled modules that
+  resolve to one shared file, which is why it went unnoticed.
+
 ## [0.21.1] — 2026-07-31
 
 ### Added

package/README.md

@@ -1,5 +1,7 @@
 # wafermap
 
+<img src="docs/images/wafermap-readme-header-256.png" width="64" height="64" alt="wafermap icon">
+
 [![CI](https://github.com/wafertools/wafermap/actions/workflows/ci.yml/badge.svg)](https://github.com/wafertools/wafermap/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@wafertools/wafermap.svg)](https://www.npmjs.com/package/@wafertools/wafermap)
 ![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
@@ -14,6 +16,11 @@ Browser-first wafer map visualization for semiconductor test data.
 
 **[Project Portal: Docs & Interactive Demos →](https://wafertools.github.io/wafermap/)**
 
+## Community
+
+Questions, ideas, or want to show off a wafer map you built? Use [GitHub
+Discussions](https://github.com/wafertools/.github/discussions).
+
 ## Overview
 
 wafermap renders interactive wafer maps from semiconductor prober output. Hard bins, soft bins, test values, retest runs, edge exclusion, and spec limits are native inputs.
@@ -56,8 +63,9 @@ and stats layers.
 - [Developer Guide](https://wafertools.github.io/wafermap/guide/)
 - [SvelteKit](https://wafertools.github.io/wafermap/sveltekit/) · [React](https://wafertools.github.io/wafermap/react/) · [Vue 3](https://wafertools.github.io/wafermap/vue/) integration guides
 - [API Reference](https://wafertools.github.io/wafermap/api/)
+- [Using wafermap with an AI coding agent](https://wafertools.github.io/wafermap/agents/) — rules to paste into Claude Code / Codex / Copilot / Cursor, also shipped as `AGENTS.md` in this package
 - [Architecture](https://wafertools.github.io/wafermap/architecture/) · [Performance](https://wafertools.github.io/wafermap/performance/) · [Troubleshooting](https://wafertools.github.io/wafermap/troubleshooting/)
-- [Live examples](https://wafertools.github.io/wafermap/examples/)
+- [Live examples](https://wafertools.github.io/wafermap/examples/) — or [download them](https://wafertools.github.io/wafermap/wafermap-examples.zip) to run and edit locally, offline, with the library bundled in
 
 **Using an app built with wafermap** (test / device / yield engineers):
 

package/dist/packages/canvas-adapter/icons.js

@@ -39,4 +39,4 @@ export const ICONS={aggr:'<svg viewBox="0 0 24 24" width="16" height="16" fill="
   <path d="M4.2 12h15.6"/>
   <path d="M5.8 16h12.4"/>
 
-</svg>`,windowMinimize:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M5 19h14"/></svg>',windowRestore:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="5" width="16" height="14" rx="1.5"/></svg>',xyIndicator:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M5 19 L5 7"/><path d="M5 7 L3 10"/><path d="M5 7 L7 10"/><path d="M5 19 L17 19"/><path d="M17 19 L14 17"/><path d="M17 19 L14 21"/><text x="18" y="8" font-size="6" fill="currentColor" stroke="none">X</text><text x="2" y="6" font-size="6" fill="currentColor" stroke="none">Y</text></svg>',zoomIn:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="11" x2="11" y1="8" y2="14"/><line x1="8" x2="14" y1="11" y2="11"/></svg>',zoomMode:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="m13 13.5 2-2.5-2-2.5"/><path d="m21 21-4.3-4.3"/><path d="M9 8.5 7 11l2 2.5"/><circle cx="11" cy="11" r="8"/></svg>',zoomOut:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="8" x2="14" y1="11" y2="11"/></svg>'};
+</svg>`,warning:'<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>',windowMinimize:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M5 19h14"/></svg>',windowRestore:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="5" width="16" height="14" rx="1.5"/></svg>',xyIndicator:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M5 19 L5 7"/><path d="M5 7 L3 10"/><path d="M5 7 L7 10"/><path d="M5 19 L17 19"/><path d="M17 19 L14 17"/><path d="M17 19 L14 21"/><text x="18" y="8" font-size="6" fill="currentColor" stroke="none">X</text><text x="2" y="6" font-size="6" fill="currentColor" stroke="none">Y</text></svg>',zoomIn:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="11" x2="11" y1="8" y2="14"/><line x1="8" x2="14" y1="11" y2="11"/></svg>',zoomMode:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="m13 13.5 2-2.5-2-2.5"/><path d="m21 21-4.3-4.3"/><path d="M9 8.5 7 11l2 2.5"/><circle cx="11" cy="11" r="8"/></svg>',zoomOut:'<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="8" x2="14" y1="11" y2="11"/></svg>'};

package/dist/packages/canvas-adapter/index.d.ts

@@ -5,6 +5,8 @@ export type { RenderOptions, WaferMapController, WaferViewOptions, WaferPreferen
 export { renderWaferGallery } from './renderWaferGallery.js';
 export type { WaferMapDisplayItem, WaferMapDisplayItemFactory, GalleryOptions, GalleryController } from './renderWaferGallery.js';
 export type { SummaryPanelOptions } from './summaryPanel.js';
+export { collectWarnings, severityOf } from './warnings.js';
+export type { WarningsOptions } from './warnings.js';
 export type { InsightsOptions, InsightsView } from './insightsTab.js';
 export { setDetachWindowOpener } from './toolbar.js';
 export type { DetachWindowOpener } from './toolbar.js';

package/dist/packages/canvas-adapter/index.js

@@ -1 +1 @@
-export{toCanvas}from"./toCanvas.js";export{renderWaferMap}from"./renderWaferMap.js";export{renderWaferGallery}from"./renderWaferGallery.js";export{setDetachWindowOpener}from"./toolbar.js";
+export{toCanvas}from"./toCanvas.js";export{renderWaferMap}from"./renderWaferMap.js";export{renderWaferGallery}from"./renderWaferGallery.js";export{collectWarnings,severityOf}from"./warnings.js";export{setDetachWindowOpener}from"./toolbar.js";

package/dist/packages/canvas-adapter/renderWaferGallery.d.ts

@@ -2,6 +2,7 @@ import { type SaveImageHandler, type SaveTextHandler, type UserGuideExtension }
 import type { Die } from '../core/dies.js';
 import type { WaferViewOptions } from './renderWaferMap.js';
 import type { LotStatsSummary } from '../stats/types.js';
+import { type WarningsOptions } from './warnings.js';
 import type { SummaryPanelOptions } from './summaryPanel.js';
 import { type InsightsOptions } from './insightsTab.js';
 /**
@@ -25,6 +26,13 @@ export interface WaferMapDisplayItem {
     testDefs?: import('../renderer/buildWaferMap.js').TestDef[];
     metadataFields?: import('../renderer/buildWaferMap.js').MetadataFieldDef[];
     reticles?: import('../core/reticle.js').Reticle[];
+    /**
+     * Geometry advisories carried from `buildWaferMap`. Present automatically when
+     * an item is spread from a `WaferMapResult` (the usual `{ ...result, label }`
+     * shape); the gallery collects them across cards and surfaces them once in the
+     * lot bar's warning indicator.
+     */
+    warnings?: import('../renderer/buildWaferMap.js').WaferWarning[];
     isLotStack?: boolean;
     aggrMethod?: string;
     lotSize?: number;
@@ -148,6 +156,12 @@ export interface GalleryOptions {
      * recomputing it — no other host wiring beyond this option.
      */
     insights?: InsightsOptions;
+    /**
+     * Built-in surfacing of the library's own data warnings (see `WarningsOptions`).
+     * Defaults on. The gallery collects across every item and de-duplicates, so a
+     * geometry advisory affecting the whole lot is stated once, not per card.
+     */
+    warnings?: WarningsOptions;
 }
 export interface GalleryController {
     /** Replace all items — destroys existing cards and rebuilds the grid. Accepts pre-built items, factory functions, or a mix. */