@wafertools/wafermap 0.21.1 → 0.22.0

package/dist/packages/stats/renderFindingsReport.js

@@ -1,11 +1,11 @@
-import{formatFindingDelta as g,formatFindingCoverage as h,formatFindingTooltip as b,escHtml as a,buildMetadataRows as d,renderDefinitionList as c,renderSection as p,renderSeverityBadge as w,reportStyles as v}from"./reportHtml.js";import{buildFindingsNarrative as y}from"./findingsNarrative.js";import{plainBinTerms as f}from"../renderer/fmt.js";function $(t,n){if(t.level==="lot"){const o=t,l=o.perWafer.map(r=>r.summary.wafer?.wafer??r.summary.wafer?.waferId).filter(r=>r!=null).map(String).join(", ");return c([...d(o.perWafer.map(r=>({metadata:r.summary.wafer}))),...l?[{label:"Wafers",value:l}]:[],{label:"Wafer count",value:String(o.stats.waferCount)},{label:"Generated",value:n}])}const e=t,i=e.stats.yieldPercent!==null?`${e.stats.yieldPercent.toFixed(1)}%`:"N/A";return c([...d([{metadata:e.wafer}]),{label:"Total dies",value:String(e.stats.totalDies)},{label:"Analysed dies",value:String(e.stats.analyzedDies)},{label:"Yield",value:i},{label:"Generated",value:n}])}function R(t,n){return t.length?t.map(e=>`<tr title="${a(b(e))}">
-      <td class="tight">${w(e.severity)}</td>
-      <td class="tight">${a(e.comparison.left)}</td>
-      <td>${a(f(e.variable.label))}</td>
-      <td class="numeric">${a(g(e))}</td>
-      <td class="numeric">${a(h(e,n))}</td>
+import{formatFindingDelta as b,formatFindingCoverage as w,formatFindingTooltip as v,escHtml as r,buildMetadataRows as c,renderDefinitionList as f,renderSection as p,renderSeverityBadge as $,reportStyles as y}from"./reportHtml.js";import{buildFindingsNarrative as R}from"./findingsNarrative.js";import{plainBinTerms as u}from"../renderer/fmt.js";function S(t,n){if(t.level==="lot"){const o=t,l=o.perWafer.map(a=>a.summary.wafer?.wafer??a.summary.wafer?.waferId).filter(a=>a!=null).map(String).join(", ");return f([...c(o.perWafer.map(a=>({metadata:a.summary.wafer}))),...l?[{label:"Wafers",value:l}]:[],{label:"Wafer count",value:String(o.stats.waferCount)},{label:"Generated",value:n}])}const e=t,i=e.stats.yieldPercent!==null?`${e.stats.yieldPercent.toFixed(1)}%`:"N/A";return f([...c([{metadata:e.wafer}]),{label:"Total dies",value:String(e.stats.totalDies)},{label:"Analysed dies",value:String(e.stats.analyzedDies)},{label:"Yield",value:i},{label:"Generated",value:n}])}function F(t,n){return t.length?t.map(e=>`<tr title="${r(v(e))}">
+      <td class="tight">${$(e.severity)}</td>
+      <td class="tight">${r(e.comparison.left)}</td>
+      <td>${r(u(e.variable.label))}</td>
+      <td class="numeric">${r(b(e))}</td>
+      <td class="numeric">${r(w(e,n))}</td>
     </tr>`).join(`
-`):'<tr><td colspan="5" class="no-data">No significant findings</td></tr>'}function F(t,n){return`<table class="report-table findings-table compact">
+`):'<tr><td colspan="5" class="no-data">No significant findings</td></tr>'}function H(t,n){return`<table class="report-table findings-table compact">
   <thead>
     <tr>
       <th>Severity</th>
@@ -16,26 +16,26 @@ import{formatFindingDelta as g,formatFindingCoverage as h,formatFindingTooltip a
     </tr>
   </thead>
   <tbody>
-    ${R(t,n)}
+    ${F(t,n)}
   </tbody>
-</table>`}export function renderFindingsReportHtml(t,n={}){const e=t.level==="lot",i=n.title??(e?"Lot Findings Report":"Wafer Findings Report"),o=new Date().toLocaleString(),l=t.findings,r=t.level==="lot"?t.stats.waferCount:void 0,s=f(y(l)??""),u=s?`<p class="findings-narrative">${a(s)}</p>
-`:"",m=[p("Summary",$(t,o)),p("Findings",u+F(l,r))].join(`
+</table>`}export function renderFindingsReportHtml(t,n={}){const e=t.level==="lot",i=n.title??(e?"Lot Findings Report":"Wafer Findings Report"),o=new Date().toLocaleString(),l=new Set(t.findings.flatMap(s=>s.absorbedIds??[])),a=t.findings.filter(s=>!l.has(s.id)),m=t.level==="lot"?t.stats.waferCount:void 0,d=u(R(a)??""),g=d?`<p class="findings-narrative">${r(d)}</p>
+`:"",h=[p("Summary",S(t,o)),p("Findings",g+H(a,m))].join(`
 `);return`<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
-<title>${a(i)}</title>
+<title>${r(i)}</title>
 <style>
-${v()}
+${y()}
 </style>
 </head>
 <body>
 <main class="report">
   <header class="report-header">
-    <h1>${a(i)}</h1>
-    <p class="report-subtitle">Generated ${a(o)}</p>
+    <h1>${r(i)}</h1>
+    <p class="report-subtitle">Generated ${r(o)}</p>
   </header>
-  ${m}
+  ${h}
 </main>
 </body>
 </html>`}export function openHtmlReport(t){if(typeof window.__openHtmlReport=="function"){window.__openHtmlReport(t);return}const n=window.open("","_blank");n&&(n.document.write(t),n.document.close())}export function setReportOpener(t){window.__openHtmlReport=t}

package/dist/packages/stats/types.d.ts

@@ -1,4 +1,5 @@
-import type { WaferMapInput, WaferMapResult } from '../renderer/buildWaferMap.js';
+import type { WaferMapInput, WaferMapResult, WaferWarning } from '../renderer/buildWaferMap.js';
+export type { WaferWarning };
 export type StatsSeverity = 'info' | 'notable' | 'unusual';
 export type StatsLevel = 'wafer' | 'lot' | 'inter-wafer';
 export type StatsVariableKind = 'yield' | 'hardBin' | 'softBin' | 'test' | 'functionalTest' | 'spatialPattern';
@@ -65,8 +66,25 @@ export interface StatsFinding {
     };
     summary: string;
     highlight: HighlightTarget;
-    /** IDs of other findings that describe the same signal at a finer level of detail. */
+    /**
+     * IDs of other findings that describe the same signal at a finer level of
+     * detail. Note these do NOT all resolve to entries in `findings`: when a run
+     * of per-region findings is merged into one (e.g. `Rings 3–4`), this is the
+     * audit trail of the constituents it REPLACED, and those no longer exist.
+     */
     relatedIds?: string[];
+    /**
+     * IDs of findings that state exactly the same fact as this one and are
+     * therefore hidden from reading surfaces (the Summary panel, the findings
+     * report) in favour of it.
+     *
+     * Distinct from `relatedIds` deliberately: everything named here IS still
+     * present in `findings` and can be read programmatically — nothing is
+     * discarded, it is only de-duplicated for display. Two cases are collapsed:
+     * a soft-bin finding whose hard-bin twin covers provably the same dies, and
+     * the single pass bin's row against the yield row that restates it.
+     */
+    absorbedIds?: string[];
 }
 export interface StatsSummary {
     level: 'wafer';
@@ -96,8 +114,20 @@ export interface StatsSummary {
          */
         hardBinCounts?: Record<number, number>;
         softBinCounts?: Record<number, number>;
-        /** Structured warnings emitted during analysis (e.g. test-count cap exceeded). */
-        warnings?: string[];
+        /**
+         * Structured advisories raised during analysis — the same `WaferWarning`
+         * shape used by `WaferMapResult.warnings`, so a host has one warning
+         * vocabulary to handle rather than two. Branch on `warning.code`.
+         *
+         * The one raised today is `'test-count-capped'`: more tests were found than
+         * the analysis cap allows, so test-value analysis was skipped and no test
+         * findings exist. That is a silent absence — nothing throws — so check this
+         * rather than assuming an empty findings list means "nothing to report".
+         *
+         * `renderWaferMap`/`renderWaferGallery` surface these automatically in the
+         * toolbar's warning indicator; a host does not have to render them itself.
+         */
+        warnings?: WaferWarning[];
         /** True when this summary was produced from lot-aggregated data (lotStack). */
         isLotStack?: boolean;
         /** Aggregation method used to produce the lot-stack (e.g. 'mean', 'countBin'). Present only when isLotStack is true. */

package/llms.txt

@@ -0,0 +1,39 @@
+# wafermap
+
+Browser-first wafer map visualization toolkit for semiconductor test data.
+Primary entry point: build wafer models with `buildWaferMap()`, then render with a canvas.
+
+## Core docs
+Absolute URLs: this file ships inside the npm package and the examples archive,
+where repo-relative paths do not resolve.
+- [Agent rules](https://wafertools.github.io/wafermap/agents/) - the traps that produce silently wrong maps. Read this first.
+- [Developer Guide](https://wafertools.github.io/wafermap/guide/) - end-to-end usage, CSV loading, display controls, stats, galleries, and worker usage.
+- [API Reference](https://wafertools.github.io/wafermap/api/) - public API, input types, coordinate system rules, and configuration details.
+- [Quick start](https://wafertools.github.io/wafermap/quickstart/) - install and first map.
+- [Troubleshooting](https://wafertools.github.io/wafermap/troubleshooting/) - common failure modes.
+- [Examples](https://wafertools.github.io/wafermap/examples/) - 20 runnable demo pages, also downloadable at https://wafertools.github.io/wafermap/wafermap-examples.zip to run offline.
+
+## Public package entry points
+- `@wafertools/wafermap`
+- `@wafertools/wafermap/render`
+- `@wafertools/wafermap/stats`
+- `@wafertools/wafermap/worker`
+- `@wafertools/wafermap/worker-script`
+
+## Important notes
+- `x` and `y` in `DieResult` are die grid positions (prober step integers), not millimetres.
+- Use `testValues: Record<number, number>` (keyed by stable test number) rather than the deprecated `values: number[]` (positional array). Example: `testValues: { 1050: 0.95 }`.
+- Hard bins go in `hbin`; soft bins go in `sbin`. Their number spaces are independent. Never merge them, and never fall back to `?? 0` — a missing bin is not bin 0.
+- All coordinates shown to the user (axis ticks, tooltips) must be original die grid positions (`die.x` / `die.y`), not post-transform display coordinates.
+- `buildWaferMap()` is pure and server-safe; renderers require the DOM.
+- Recommended path for most users: `buildWaferMap()` + `renderWaferMap()`.
+- `passBins` sets both the yield number and the wording of its label — do not assume `[1]`.
+- `activeTest` takes a test number (e.g. `1050`), not a positional index.
+- Functional tests (`testType: 'F'`) have no value; read verdicts only via `getTestPassStatus()`. A missing verdict is no-data, never a fail.
+- `PlotMode` values are camelCase (`'hardBin'`, `'stackedValues'`), never snake_case.
+- Full rules, including the removed-API table: see AGENTS.md, shipped alongside this file.
+
+## Development
+- Build: `npm run build`
+- Test: `npm test`
+- Typecheck: `npm run check`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wafertools/wafermap",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Interactive wafer map visualization and yield analysis for semiconductor test data. Hard bins, soft bins, test values, retests, edge exclusion, reticle overlays, spatial statistics, failure clustering, and lot-level trend analysis — pure ES modules, no runtime dependencies, no server required.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,9 @@
     "!dist/**/*.map",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "llms.txt"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -72,10 +74,12 @@
     "build": "node scripts/build-user-guide.mjs && node scripts/sync-icons.mjs && node scripts/sync-version.mjs && rm -rf dist && tsc -p tsconfig.build.json",
     "build:guide": "node scripts/build-user-guide.mjs",
     "clean": "rm -rf dist",
-    "check": "node scripts/sync-version.mjs && tsc --noEmit -p tsconfig.json",
+    "check": "node scripts/sync-version.mjs && tsc --noEmit -p tsconfig.json && node scripts/check-examples-manifest.mjs && node scripts/build-agents-page.mjs --check && node scripts/check-agents-guide.mjs && node scripts/check-toolbar-docs.mjs",
+    "build:examples-index": "node scripts/build-examples-index.mjs",
+    "check:drift": "node scripts/check-drift.mjs",
     "dev": "rm -rf docs/dist && cp -r dist docs/dist && ./.venv/bin/zensical serve --dev-addr localhost:8001",
     "test": "npm run build && node --test tests/*.test.mjs",
-    "build:site": "rm -rf docs/dist && cp -r dist docs/ && ${ZENSICAL:-.venv/bin/zensical} build --clean && cp -r docs/data site/data && rm -rf docs/dist && node scripts/bundle-docs.mjs",
+    "build:site": "rm -rf docs/dist && cp -r dist docs/ && ${ZENSICAL:-.venv/bin/zensical} build --clean && cp -r docs/data site/data && rm -rf docs/dist && node scripts/bundle-docs.mjs && node scripts/build-examples-archive.mjs",
     "preview:site": "npm run build:site && echo \"\\nServing bundled site at http://localhost:8002/examples/ — Ctrl-C to stop\\n\" && cd site && python3 -m http.server 8002",
     "prepack": "npm run build && node scripts/minify-dist.mjs",
     "pack:check": "npm pack --dry-run",
@@ -83,7 +87,8 @@
     "postpublish": "echo \"\\ndist/ was minified for publish — run 'npm run build' to restore the readable dev build.\\n\"",
     "screenshots": "node scripts/capture-screenshots.mjs",
     "screenshots:list": "node scripts/capture-screenshots.mjs --list",
-    "build:images": "npm run build && node scripts/capture-screenshots.mjs"
+    "build:images": "npm run build && node scripts/capture-screenshots.mjs",
+    "build:agents-page": "node scripts/build-agents-page.mjs"
   },
   "keywords": [
     "wafer-map",
@@ -110,11 +115,10 @@
   "devDependencies": {
     "esbuild": "^0.28.1",
     "jsdom": "^29.1.1",
-    "marked": "^18.0.3",
+    "marked": "^18.0.7",
     "playwright": "^1.60.0",
-    "semble": "^0.1.1",
     "serve": "^14.2.0",
-    "typescript": "^5.6.3"
+    "typescript": "^5.9.3"
   },
   "allowScripts": {
     "esbuild@0.28.1": true