wafermap AGENTS.md

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.

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 carry WaferWarning — { code, message, severity }. Branch on code, never on the prose. The two differ in shape and the difference throws: result.warnings is required and always an array ([] when clean), but summary.stats.warnings is optional and is undefined when there is nothing to report. Write summary.stats.warnings?.length — a bare summary.stats.warnings.length is a TypeError on every clean wafer, which is most of them, so it will pass your testing and fail in production. 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.)
• Give the container a resolved height. renderWaferMap fills its container. A bare block-flow <div> is fine — it grows to the canvas. The real failure is a flex/grid child whose ancestors never resolve a height: it stays 0-tall and the map is invisible. The library detects exactly that case after layout settles and console.warns with the fix, so read the console before debugging further. Either give the container a real CSS height, or pass { height: 600 } in the render options and the library will size it for you.