wafermap: Instructions file for Codex

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(), registerBinColorScheme() / registerValueColorScheme(). Pure, no DOM, server-safe.
• @wafertools/wafermap/render — renderWaferMap(), renderWaferGallery(). 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.

There is no low-level drawing pipeline, chart-data builder or region builder to reach for. The library draws through the renderers, and every figure it shows (yield, bin counts, region yield, per-test statistics, capability) comes back from analyzeWaferMap() / analyzeWaferLot().

If the only way to do something is to rebuild one of those pieces, that is a library gap worth reporting, not a pattern to build on.

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.
• 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. buildWaferMap never converts them: each is treated as missing and reported as input-values-not-numbers (severity 'error'), so those dies have no bin or no value and a build that "works" can be mostly empty — read the warnings. Convert with Number() at parse time.
• 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 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.
• 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.