API Reference¶

For: developers integrating the library. This is a reference, not a tutorial — if you're new, start with the Quick Start and Developer Guide.

This document describes the public API exposed by wafermap. For the system-level overview and recommended entry points, see Architecture.

How to read this document. §3 is the section map — find your entry point there. §4 (buildWaferMap, the data layer) plus §5 or §6 (the renderers) cover most applications; §7 adds the findings engine. Cross-references use §N.N notation throughout; shared types live in §12.

How much of this do I need?¶

Almost none of it. This is a reference, not a reading list — it documents every option so that the rare one you eventually need is written down, not so that you learn them.

A working map is two calls:

const result = buildWaferMap({ results, waferConfig, dieConfig });
renderWaferMap(document.getElementById('map'), result);

That renders with a full interactive toolbar — plot modes, colour schemes, zoom, export — with no options passed at all. Add analyzeWaferMap when you want the findings and summary panel, and renderWaferGallery in place of renderWaferMap for a lot. That is four functions, and it is the whole story for most integrations.

For scale: tsmap, a complete cross-platform desktop application built on this library, imports 14 of its ~100 exports. RenderOptions has 22 fields; a typical integration sets a handful. Everything else here is depth that stays out of your way until you go looking for it.

New to the library? Start with the Quick Start (a 5-minute tutorial), then the Guide for a feature walkthrough. Come back here when you need a specific option.

1 Coordinate system¶

x and y throughout this API are die grid positions (prober step coordinates) — integers such as −7, 0, 5. They are NOT millimetre values. They must be JavaScript number type — CSV parsers return strings; always cast with Number() or + before passing to buildWaferMap.

This matches what wafer test equipment outputs. The library converts grid positions to physical mm internally using the die size you provide.

prober outputs:  x=-5, y=3   (die grid position)
library computes: x_mm = -5 × 10 = -50 mm   (given die width = 10 mm)

Physical mm positions appear only on the Die output objects (die.physX, die.physY) and in the wafer model. You never need to compute or supply mm values.

2 Quick Start¶

The step-by-step tutorial is Quick Start; this is the condensed call shape as a memory jogger:

import { buildWaferMap } from '@wafertools/wafermap';
import { renderWaferMap } from '@wafertools/wafermap/render';

// x,y are prober step positions (die grid indices), not mm.
const result = buildWaferMap({
  results:   rows.map(r => ({ x: +r.x, y: +r.y, hbin: +r.hbin, testValues: { 1010: +r.testA } })),
  waferConfig: { diameter: 300, notch: { type: 'bottom' } },
  dieConfig:   { width: 10, height: 10 },
  testDefs: [{ testNumber: 1010, name: 'TestA', unit: 'V' }],
});

renderWaferMap(document.getElementById('map'), result);

The map renders with a full built-in toolbar — no extra HTML or JavaScript needed. To add a statistical findings panel, pass the result through analyzeWaferMap — see §7.1.

3 API overview¶

If you want the shortest path to the right entry point before diving into the type details, see Architecture. It explains which layer to use for data construction, rendering, analysis, and worker offloading.

graph TD
    bwm["buildWaferMap()<br/>data layer — no DOM"]
    rwm["renderWaferMap()"]
    rg["renderWaferGallery()"]
    awm["analyzeWaferMap()"]
    awl["analyzeWaferLot()"]
    wk["createWafermapWorker()"]

    bwm --> rwm
    bwm --> rg
    bwm --> awm
    bwm --> awl
    bwm --> wk

Everyday — the four functions almost every integration uses:

Occasional — reach for these when you hit the specific need:

Rarely needed — escape hatches. Skip unless something above can't do it:

4 buildWaferMap(input)¶

The primary entry point. Pass whatever data you have — prober step positions, optional geometry hints, or a pre-built die array. The function infers whatever is missing and returns a fully constructed wafer model.

Inference reads geometry from the extent of the data. When you supply only die positions, the wafer diameter and centre are derived from how far the data reaches. This is correct whenever the data reaches the true wafer edge — a fully-populated wafer, or a sparse one (skip-sampled or randomly sampled positions missing across the whole face). It is wrong for partial data — a contiguous region such as a half wafer, a single quadrant, or an off-centre cluster — because the extent stops short of the true edge, so the region is mistaken for a smaller full wafer and mis-centred. For partial data supply waferConfig.diameter and waferConfig.center — see §4.3 Inference levels. When the library detects likely-partial coverage with no anchor, it adds a structured warning to result.warnings (code 'partial-coverage').

Server-safe: buildWaferMap is a pure function with no DOM access or side effects. It can run in Node.js, Deno, a Web Worker, or any server-side environment.

import { buildWaferMap } from '@wafertools/wafermap';

4.1 Input¶

buildWaferMap accepts either an array of data points or an object. They are equivalent when no extra options are needed — the array form is just shorthand for { results: [...] }:

// Array form — shorthand, equivalent to passing { results }
buildWaferMap(results: DieResult[])

// Object form — use when you need geometry hints or other options.
// WaferMapInput is a union: pass either results OR lotStack, never both.
buildWaferMap(input: WaferMapInput)

WaferMapInput is a discriminated union:

// Shared base (WaferMapInputBase) — all fields are optional:
type WaferMapInputBase = {
  waferConfig?:      WaferConfig,      // physical wafer geometry (diameter, notch, orientation…)
  dieConfig?:        DieConfig,        // die size and coordinate conventions
  dies?:             Die[],            // pre-built die array; skips geometry generation
  reticleConfig?:    ReticleConfig,    // stepper field grid overlay
  passBins?:         number[],         // bins that pass (default [1]) — carried on the result as result.passBins
  ringCount?:        number,           // rings for ring overlays, ring yield and ring findings (default 4) — carried as result.ringCount
  retestPolicy?:     'last' | 'first' | 'best' | 'worst', // how to handle multiple results at the same (x,y); default 'last'
  edgeDieYieldMode?: 'exclude' | 'denominator-only', // default 'exclude'
  testDefs?:         TestDef[],        // named test definitions — one per testValues entry
  hbinDefs?:         BinDef[],         // named hard bin definitions — one per distinct hbin value
  sbinDefs?:         BinDef[],         // named soft bin definitions — one per distinct sbin value
  metadataFields?:   MetadataFieldDef[], // opts a die.metadata key into the 'metadata' plot mode — §4.1.10
}

// Single-wafer variant (WaferMapInputSingle):
type WaferMapInputSingle = WaferMapInputBase & {
  results?:  DieResult[]   // per-die measurements from the prober
  lotStack?: never          // passing both results and lotStack is a type error
}

// Lot-stack variant (WaferMapInputLotStack):
type WaferMapInputLotStack = WaferMapInputBase & {
  lotStack:  LotStackConfig  // collapse multiple wafers into one aggregated map
  results?:  never            // passing both results and lotStack is a type error and runtime error
}

type WaferMapInput = WaferMapInputSingle | WaferMapInputLotStack

All fields are optional. Supply what you know; the library handles the rest. Passing both results and lotStack on the same object is a type error and is rejected at runtime.

4.1.1 DieResult¶

A single die record from wafer test equipment.

{
  x:           number                      // die grid X position (prober step coordinate)
  y:           number                      // die grid Y position (prober step coordinate)
  testValues?: Record<number, number>      // preferred: test measurements keyed by stable test identity
                                           // e.g. { 1050: 1.42e-3, 1060: 0.487, 1070: 8.3e-12 }
                                           // the key is any stable integer per test — for example an STDF TEST_NUM,
                                           // a database test ID, or an application-defined constant
  testPass?:   Record<number, boolean>     // recorded per-test pass/fail verdicts keyed the same way (true = pass)
                                           // parametric tests: value in testValues, optionally the tester's verdict here
                                           // (e.g. STDF PTR TEST_FLG); functional tests (testType 'F'): verdict here ONLY —
                                           // they have no measured value. e.g. { 2001: true, 2002: false }
  hbin?:       number                      // hard bin assignment (physical sort result; STDF V4 range 0–32767)
  sbin?:       number                      // soft bin assignment (test-program failure category; independent 0–32767 space)
  siteNum?:    number                      // STDF site_num — which parallel test site tested this die
                                           // enables test-site analysis in analyzeWaferMap when ��2 distinct
                                           // values each appear on ≥3 dies (indicating a multi-site probe card)
  partId?:     number                      // STDF pir.part_id — tester-assigned identifier for this unit
                                           // at most fabs this encodes probe sequence (the step order across the wafer)
                                           // but the field is semantically neutral — its meaning is fab-specific
                                           // note: STDF part_id is 1-based; camelCase follows the library convention
}

A single test result: testValues: { 1050: 0.95 }

When a die position appears more than once in the results array (a retest), the retestPolicy field on WaferMapInput controls which result is kept. The die.retestCount field always records how many times that position appeared.

4.1.2 WaferConfig¶

{
  diameter?:      number         // wafer diameter in mm; inferred from grid extent × pitch if omitted
  center?:        { x: number, y: number }
                  // prober coordinate that lies at the physical wafer centre.
                  // Supply for partial data (a contiguous half/quadrant/slice that
                  // stops short of the wafer edge); anchors placement to the true
                  // centre. Not needed for sparse full-extent data. Does NOT change
                  // die.x/die.y labels.
                  // When omitted, the centre is inferred as the data midpoint (full-wafer assumption).
  notch?:         { type: 'top' | 'bottom' | 'left' | 'right' }
                  // physical orientation mark direction; standard dimensions derived from diameter:
                  //   ≤ 100 mm → 32.5 mm orientation flat  (SEMI M1)
                  //   ≤ 150 mm → 57.5 mm orientation flat  (SEMI M1)
                  //   > 150 mm → V-notch ~3.5 mm wide, 1.25 mm deep  (SEMI M1)
  orientation?:   number         // degrees CW to rotate the die grid on screen; default 0 (see note below)
  edgeExclusion?: number         // exclusion band width in mm measured inward from the wafer edge; dies in this band are dimmed
                                 // how these dies affect yield is controlled by the top-level edgeDieYieldMode option (§4.1.10)
  metadata?:      WaferMetadata  // arbitrary lot/wafer-level data attached to the view (lot ID, date, etc.)
}

orientation note: positive values rotate the die grid clockwise. The notch/flat position is controlled by notch.type and is not affected by orientation — it stays fixed as the physical alignment mark.

4.1.3 DieConfig¶

{
  width?:              number   // die width in mm (= X step pitch); enables physical mm coordinates
  height?:             number   // die height in mm (= Y step pitch); enables physical mm coordinates
  coordinateOrigin?:   {
    // where the prober places coordinate (0,0) on the wafer grid
    type: 'center'           // default — grid already centred; centroid offset applied automatically
        | 'LL'               // (0,0) at lower-left corner (standard STDF/KLA output)
        | 'UL'               // (0,0) at upper-left corner — positive Y runs downward (flips display Y)
        | 'LR'               // (0,0) at lower-right corner — positive X runs leftward (flips display X)
        | 'UR'               // (0,0) at upper-right corner — both axes flipped
        | 'custom'           // manual offset: centre = (0,0) + offset in grid steps
    offset?: { x: number; y: number }   // grid-step offset to the true centre; only used when type is 'custom'
  }
  yAxisDirection?: 'up' | 'down'     // which direction Y increases on the prober; 'down' for row/matrix probers (default 'up')
  xAxisDirection?: 'right' | 'left'  // which direction X increases; 'left' for backside or mirrored probing (default 'right')
}

When width and height are omitted, the library estimates die dimensions from the grid layout using nearest-neighbour step analysis first, falling back to the circular-wafer aspect-ratio constraint.

4.1.4 ReticleConfig¶

{
  width:      number               // stepper field width in number of dies (e.g. 4 means 4 dies wide)
  height:     number               // stepper field height in number of dies
  anchorDie?: { x: number; y: number }
               // die grid index (x, y), in original die coordinates (die.x/die.y),
               // that sits at the reticle field's min-x/min-y corner (bottom-left,
               // since +Y is up) — i.e. it becomes the leftmost, bottom-most die
               // of the field it belongs to. Shifts the entire reticle grid so
               // this die aligns to a field boundary.
               // Default {0,0} — die (0,0) is at a corner.
}

When provided, reticle overlays are shown by default (showReticle defaults to true).

4.1.5 LotStackConfig¶

Collapse data from multiple wafers into a single map before rendering. When lotStack is present the top-level results field is ignored.

{
  results:    DieResult[][]  // input data — one DieResult[] per wafer in the lot
  method:     // aggregation applied per die position across all wafers:
    | 'mean'       // arithmetic mean of values → testValues[0]
    | 'median'     // median of values → testValues[0]
    | 'stddev'     // sample standard deviation of values → testValues[0]
    | 'min'        // minimum value across lot → testValues[0]
    | 'max'        // maximum value across lot → testValues[0]
    | 'count'      // number of wafers that provided a value at this position → testValues[0]
    | 'countBin'   // how many wafers had targetBin at this position → testValues[0]
    | 'mode'       // most frequent bin across wafers → hbin
    | 'percent'    // percentage of wafers that had targetBin → testValues[0] in [0,100]
  targetBin?: number   // bin value to count or measure; required for 'countBin' and 'percent'
}

4.1.6 passBins¶

passBins?: number[]   // default [1]  (industry convention: bin 1 = pass)

Bin values that count as pass for yield calculation. Set to [] to suppress yield.

4.1.7 retestPolicy¶

retestPolicy?: 'last' | 'first' | 'best' | 'worst'   // default 'last'

Controls how the library handles multiple results for the same die position (retests). In wafer test it is common for a die to be tested more than once — for example after a recontact, a temperature retest, or a continuity retest.

Regardless of which policy is active, die.retestCount is always set on any die that appeared more than once in the input. Use it to identify retested dies in your own analysis without needing to re-scan the raw results.

// Last result wins (default — no field needed):
buildWaferMap({ results })

// Explicitly keep first result:
buildWaferMap({ results, retestPolicy: 'first' })

// Check how many retests occurred after the map is built:
result.dies.filter(d => d.retestCount !== undefined)
  .forEach(d => console.log(`Die (${d.x},${d.y}) tested ${d.retestCount} times`));

4.1.8 TestDef¶

Named definition for one test parameter. The toolbar mode dropdown always offers one entry per test — using testNumber as the label when testDefs is absent. When testDefs is provided, tooltips show "Idsat: 1.23 mA" with the test name and SI-scaled unit; without it they fall back to "Test 1050: 1.23 mA".

{
  testNumber:  number  // required: stable test identity matching the key used in DieResult.testValues
                       // e.g. an STDF TEST_NUM, a database test ID, or an application-defined constant
  name:        string  // e.g. "Idsat", "Vth", "Continuity"
  unit?:       string  // SI base unit, e.g. "A", "V", "Ω", "F" — the formatter applies SI prefixes
                       // automatically (0.03 Ω → "30 mΩ"), so always pass the base unit, never a
                       // pre-scaled unit like "mA" or "µV"
  logScale?:   boolean // when true, value normalization and the colorbar use log₁₀ scale for this test
                       // silently falls back to linear when any die value is ≤ 0; default false
  limitLow?:   number  // lower specification limit in the same units as the test value
                       // values below this are out-of-spec; drives out-of-spec coloring and spec yield stats
  limitHigh?:  number  // upper specification limit in the same units as the test value
                       // values above this are out-of-spec
                       // both limits are optional independently — one-sided limits are valid
  testType?:   'P' | 'F'  // 'P' = parametric (continuous measured value, the default),
                       // 'F' = functional (pass/fail outcome ONLY, no measured value —
                       // e.g. an STDF FTR; the verdict lives in DieResult.testPass).
                       // Functional tests stay selectable in value mode but always render
                       // as test pass/fail (solid green/red with a Pass/Fail legend), and
                       // are excluded from all parametric statistics — per-test stats
                       // tables, capability, correlation, distribution charts, value
                       // stacks, and regional value findings (a mean or Cpk of a binary
                       // outcome would be meaningless). They get pass-rate analysis
                       // instead: stats.functionalYield, "Functional Tests" tables, and
                       // regional pass-rate findings (kind 'functionalTest')
}

testNumber must match the key used in DieResult.testValues / DieResult.testPass.

isParametricTest(def) (exported; deprecated — removed in 0.31.0) returns false only for testType: 'F' — an undefined def or undefined testType counts as parametric, so untyped callers are unaffected.

Legacy functional encoding: callers that predate DieResult.testPass encoded a functional outcome as a testValues entry of 1 (pass) / 0 (fail). That data keeps working everywhere — rendering, stats, and findings all read verdicts through getTestPassStatus (§10.1), which documents the fallback. New code should write testPass and leave functional tests out of testValues entirely.

4.1.9 BinDef¶

Named definition for one bin number. Used for both hard bin (hbinDefs) and soft bin (sbinDefs) — the shape is identical but the number spaces are independent.

Per STDF V4, hard bins and soft bins each range 0–32767. Bin 1 in hard bin space and bin 1 in soft bin space are different things and may have different names — always pass them as separate arrays.

{
  bin:    number   // the numeric bin value this defines
  name:   string   // e.g. "Pass", "Contact Open", "Vth - Hi NMOS"
  color?: string   // optional CSS colour, e.g. "#2ecc71" — wins over the bin colour scheme for this bin (§11.19)
}

Hard bins (hbinDefs) are the physical sort result — where the part goes on the handler. Soft bins (sbinDefs) are the logical test-program classification — the failure category as determined by the test algorithm, used for debug and yield analysis. Many soft bins typically map to one hard bin.

4.1.10 edgeDieYieldMode¶

edgeDieYieldMode?: 'exclude' | 'denominator-only'   // default 'exclude'

Controls how dies within the edge exclusion zone (waferConfig.edgeExclusion) are treated in yield calculation.

const result = buildWaferMap({
  results,
  waferConfig:      { diameter: 300, edgeExclusion: 3 },
  dieConfig:        { width: 8, height: 12 },
  edgeDieYieldMode: 'denominator-only',
});

const { yieldPercent, yieldPercentGross } = result.yield;
// yieldPercent      — interior-only yield (edge dies excluded entirely)
// yieldPercentGross — gross die yield (edge dies counted against you)

4.1.11 MetadataFieldDef¶

Named definition for one die.metadata key, opting it into the 'metadata' plot mode — a generic categorical/layout view, distinct from test results and bins. Use this for any per-die classification that isn't a test outcome: which project a die belongs to on a multiproject wafer, vendor/third-party ownership, reserved/shared/unassigned areas, or any other host-defined grouping already carried in die.metadata.

{
  key:     string    // the die.metadata key this definition applies to
  label?:  string     // display name for the toolbar entry and map title — default: Title Case of key
  values?: Array<{ value: string; label?: string; color?: string }>  // optional per-value overrides
}

A key is only offered in the toolbar's "Metadata" mode-menu section when it appears in metadataFields and at least one die actually has that key set — presence in metadataFields is an explicit opt-in, never auto-detected. values is optional per field: distinct values with no override are still shown, auto-labeled with the raw (stringified) value and auto-colored from an ordered qualitative palette (assigned in natural alphanumeric order by value — so D2 precedes D10 rather than following it — making colors stable across reloads and the legend order predictable — not the pass/fail-flavored palette hardBinColor uses, since an arbitrary metadata field has no universal "good/bad" meaning).

const result = buildWaferMap({
  results: [
    { x: 4, y: -2, hbin: 1, metadata: { project: 'Project A', device: 'Device 12' } },
    { x: 5, y: -2, metadata: { project: 'vendor' } }, // vendor die — no test/bin data at all
  ],
  waferConfig: { diameter: 300 },
  dieConfig:   { width: 10, height: 10 },
  metadataFields: [
    { key: 'project', label: 'Project', values: [
      { value: 'Project A', color: '#4e79a7' },
      { value: 'vendor',    label: 'Third-party vendor', color: '#bab0ac' },
    ] },
  ],
});

renderWaferMap(container, result, { viewOptions: { plotMode: 'metadata', activeMetadataKey: 'project' } });

Key properties of this mode:

• Coexists with test/bin data — a die can carry hbin/testValues and a metadata classification at the same time; 'metadata' is just another selectable toolbar view of the same underlying die, the same way hardBin/softBin/value already are. die.metadata already renders in every tooltip regardless of plot mode, so switching into 'metadata' mode changes the map's colour/legend without changing what the tooltip shows.
• No lot-stacking. 'metadata' is deliberately excluded from the stacked/lot-aggregation modes (stackedValues/stackedBins/stackedSoftBins) — a die's layout classification is a constant of the design, not a per-wafer measurement, so there is nothing meaningful to aggregate across a lot.
• Never affects yield. die.metadata was never part of the yield-eligibility pipeline, so a 'metadata'-classified die's yield/pass-fail status (if it has one) is entirely unaffected by this mode.
• Click-to-highlight in the legend, exactly like hardBin/softBin: clicking a legend swatch dims every die except that value (highlightMetadataValue, the string-keyed analogue of highlightBin); clicking the same swatch again clears it.
• Reuses wafer geometry, tooltip, selection, zoom, and PNG export unchanged — none of those are plot-mode-aware. The one thing genuinely new is the colour fill, the legend, and the toolbar entry.

4.1.12 standardDiameters¶

standardDiameters?: number[]   // default [100, 125, 150, 200, 300]

The wafer diameters (mm) treated as standard when sanity-checking an inferred diameter. A diameter you supply is never second-guessed; this is consulted only when the library had to size the wafer from the die extent, and it is what decides whether the non-standard-diameter advisory (§4.2.2) fires.

It replaces the default rather than adding to it, so spread it to extend:

import { buildWaferMap } from '@wafertools/wafermap';

// a line that also runs 3-inch
buildWaferMap({ results, standardDiameters: [100, 125, 150, 200, 300, 76.2] });

// genuinely non-standard substrate — panels, reclaim, odd R&D shapes
buildWaferMap({ results, standardDiameters: [] });

[] disables the check entirely, and is the intended opt-out for a substrate that is not on the ladder — better than suppressing every geometry advisory to silence one that does not apply to your line.

STANDARD_WAFER_DIAMETERS_MM (deprecated — removed in 0.31.0) is exported from the root entry point as a readonly number[], so host code can read, extend or compare against the SEMI M1 ladder without restating it.

4.2 Return value¶

{
  wafer:         Wafer          // resolved wafer model (diameter, radius, center, notch, orientation)
  dies:          Die[]          // all dies inside the wafer boundary, with testValues/hbin/sbin attached
  plotMode:      PlotMode       // the plot mode chosen by buildWaferMap ('hardBin', 'value', etc.)
  metadata:      WaferMetadata | null  // wafer metadata from waferConfig.metadata
  isLotStack:    boolean        // true when built from lotStack input
  aggrMethod?:   string         // lot-stack aggregation method ('mean', 'median', 'countBin', …); undefined for single wafers
  lotSize?:      number         // number of wafers aggregated when built from lotStack; undefined for single wafers
  hbinDefs?:     BinDef[]       // named hard bin definitions passed to buildWaferMap
  sbinDefs?:     BinDef[]       // named soft bin definitions passed to buildWaferMap
  testDefs?:     TestDef[]      // named test definitions passed to buildWaferMap
  metadataFields?: MetadataFieldDef[]  // named metadata-field definitions passed to buildWaferMap — §4.1.11
  reticles:      Reticle[]      // generated reticle geometry — wired automatically when passed as a WaferMapDisplayItem
  reticleConfig: ReticleConfig | undefined  // the reticle config that was used; passed through to analyzeWaferMap automatically
  units:   'mm' | 'normalized'   // coordinate space of die.physX/die.physY and wafer dimensions
  warnings: WaferWarning[]       // structured geometry-inference advisories — always present (may be empty).
                                  // Surfaced automatically by renderWaferMap/renderWaferGallery in the
                                  // toolbar's warning indicator; read here for programmatic use. §4.2.2
                                  // { code: string; message: string;
                                  //   severity?: 'error' | 'warning' | 'info'; confidence?: number }
                                  // The first three geometry codes below are severity 'error': they mean
                                  // die positions may be wrong, not that a feature is missing.
                                  // Codes:
                                  //   'partial-coverage'  — data does not span a full wafer; inferred
                                  //     diameter/centre may be wrong. Supply waferConfig.center + .diameter.
                                  //   'geometry-conflict' — waferConfig.diameter AND dieConfig.width/
                                  //     height were BOTH supplied, and are too small to contain the
                                  //     probed dies. A die with results is a real prober position and is
                                  //     always fully on the wafer, so the two supplied values contradict
                                  //     each other; check them against the real device.
                                  //   'non-standard-diameter' — pitch supplied without a diameter, and the
                                  //     wafer sized from the die extent landed off the standard ladder
                                  //     (100/150/200/300 mm) — evidence the probed grid did not reach the
                                  //     edge. Supply waferConfig.diameter. NOTE: an inferred PITCH raises
                                  //     nothing: it is derived to fit the diameter, so it is always
                                  //     self-consistent. And 'geometry-conflict' is never raised for an
                                  //     inferred pitch — pitch is a free scaling parameter, so with
                                  //     no supplied pitch there is always one that "fits", and a fit
                                  //     check would otherwise fire on perfectly good full-wafer data.
                                  //   'edge-exclusion-exceeds-radius' — severity 'warning', not 'error':
                                  //     waferConfig.edgeExclusion is larger than the resolved wafer radius
                                  //     (most likely when the diameter was itself inferred from sparse
                                  //     data). The excluded band is clamped to the whole wafer rather than
                                  //     silently producing a smaller, wrong ring.
  inference: {
    wafer:    { confidence: number; method: string }   // how diameter was resolved; confidence 0–1.
                                                        // method is 'inferred-partial' when partial data was detected
    diePitch: { confidence: number; units: 'mm' | 'normalized' }  // how die size was resolved
    grid:     { confidence: number }                   // quality of the grid index assignment
  }
  dataCoverage: {
    filledDies:       number   // dies with at least one value or bin attached
    totalDies:        number   // POSITIONED dies inside the wafer boundary (including partial) — 0 for a
                                // fully coordinate-less wafer; see unpositionedDies below, not this, for
                                // "how many dies does this wafer actually have"
    edgeExcludedDies: number   // dies whose centres fall within the edge exclusion band
    ratio:            number   // filledDies / totalDies ∈ [0, 1] — undefined/misleading when totalDies is 0
    unpositionedDies: number   // dies with no reported x/y at all (see §12.1's coordinate-less note) —
                                // always present, 0 when every die has a position
  }
  passBins: number[]    // the pass bins given to buildWaferMap. renderWaferMap, renderWaferGallery (per wafer)
                         // and analyzeWaferMap read these — never repeat them in a render or analysis call
  ringCount: number     // the ring count given to buildWaferMap (default 4) — read by the renderers, analysis and reports
  yield: YieldSummary   // pass/fail statistics computed against passBins — NOT scoped to positioned dies,
                         // unlike dataCoverage above; a coordinate-less die with bin data still counts
}

4.2.1 YieldSummary¶

{
  passDies:          number          // dies with a bin in passBins
  failDies:          number          // full dies inside wafer with a bin not in passBins
  edgeExcludedDies:  number          // dies within the edge exclusion zone
  partialDies:       number          // dies straddling the wafer boundary — always 0 for a
                                     // `results`-based map (§12.1)
  totalDies:         number          // passDies + failDies (edge-excluded not included)
  yieldPercent:      number | null   // (passDies / totalDies) × 100 ∈ [0, 100]; null when no bin data
  yieldPercentGross: number | null   // (passDies / (passDies + failDies + edgeExcludedDies)) × 100 ∈ [0, 100];
                                     // only set when edgeDieYieldMode: 'denominator-only'; otherwise null
}

Partial dies are excluded from both numerator and denominator. Edge-excluded dies are excluded by default (edgeDieYieldMode: 'exclude'); set edgeDieYieldMode: 'denominator-only' to include them in the denominator for gross die yield.

result.yield.yieldPercent vs summary.stats.yieldPercent — both are in [0, 100] and can differ when you pass custom options to analyzeWaferMap (e.g. a different edgeDieYieldMode or passBins). Use result.yield for rendering and quick checks; use summary.stats.yieldPercent when you need the yield that is consistent with the findings analysis.

units tells you the coordinate space of the physical coordinates (die.physX, die.physY) and wafer dimensions; die.x/die.y remain die grid positions (prober step coordinates):

• 'mm' — at least one physical dimension was known (die size or wafer diameter); physical coordinates (die.physX/die.physY and wafer dimensions) are expressed in millimetres.
• 'normalized' — only grid positions were supplied; physical coordinates are in normalized units (aspect ratio preserved) with pitchX = 1 normalized unit by convention.

4.3 Inference levels¶

The library adapts to whatever geometry context you provide. Four distinct levels:

All four levels assume the data spans a full, roughly symmetric wafer centred near the prober origin. The diameter and centre are derived from the extent of the data you pass. See "Minimum geometry for partial data" below before relying on inference for anything less than a full wafer.

Diameter snapping: inferred diameters snap to industry-standard sizes. 100 mm, 150 mm, 200 mm, and 300 mm are preferred (±10% tolerance); other SEMI standard sizes (25 / 50 / 75 / 450 mm) are tried next (±20%); remaining values are rounded to the nearest 10 mm.

Origin: defaults to 'center' (centroid offset applied automatically). Set coordinateOrigin: { type: 'LL' } explicitly for standard STDF/KLA output where (0,0) is at the lower-left corner.

4.2.2 WaferWarning¶

The library's one warning vocabulary. Raised by geometry inference on WaferMapResult.warnings, and by analysis on StatsSummary.stats.warnings.

{
  code:      string   // stable machine-readable key — BRANCH ON THIS, not on message
  message:   string   // human-readable, suitable for direct display
  severity?: 'error' | 'warning' | 'info'   // default 'warning' when absent
  confidence?: number // inference confidence 0–1, when one applies
}

Codes

severity is about trust in what is on screen, not about how loud the message is: 'error' means the map may be positionally wrong; 'warning' means something expected is missing or degraded but what is drawn is correct. The union of code is deliberately open to string so new advisories are not a breaking change — switch with a default branch.

These are surfaced automatically — see WarningsOptions.

Minimum geometry for partial data¶

Inference works backwards from the data's bounding extent. What matters is whether the data reaches the true wafer edge:

• Sparse data — positions missing across the whole wafer (systematic skip-sampling, e.g. 1-in-4, or random sampling). The extent still reaches the edge, so diameter and centre infer correctly. No geometry hints required.
• Partial data — a contiguous region that stops short of the edge: a half wafer, a single quadrant, a slice, or an off-centre cluster. The extent understates the wafer, so the region is mistaken for a smaller full wafer and re-centred on its own midpoint. Inference is wrong here.

An edge ring / annulus is a middle case: only outer dies are present, but they reach the true edge, so the diameter is right — only the empty interior is "missing", which is harmless.

For partial data, supply both:

waferConfig.center anchors placement to the real centre. It does not change the public die.x / die.y labels — those remain the original prober coordinates. (Supplying dieConfig.width/height for the pitch is recommended too, so coordinates are in real mm.)

Detection is heuristic: the library flags likely-partial coverage by how far the data centroid sits from its bounding-box centre. Contiguous partial regions are caught; an off-centre cluster small enough to look like a tiny full wafer, and an edge ring (centroid-symmetric), are not flagged — when in doubt, set waferConfig.center explicitly rather than relying on the warning.

// Right half of a 300 mm wafer; prober (0,0) is the wafer centre.
const result = buildWaferMap({
  results,                                   // prober x ∈ [0..15], y ∈ [-15..15]
  waferConfig: { diameter: 300, center: { x: 0, y: 0 } },
  dieConfig:   { width: 10, height: 10 },
});

When the library detects likely-partial data and no center was supplied, it adds a structured warning to result.warnings (code 'partial-coverage') and sets result.inference.wafer.method to 'inferred-partial' — check these programmatically rather than relying on console output.

4.4 Examples¶

Minimal — grid positions only (normalized units):

const result = buildWaferMap([
  { x: 0, y:  0, testValues: { 1050: 0.95 } },
  { x: 1, y:  0, testValues: { 1050: 0.87 } },
  { x: 0, y: -1, testValues: { 1050: 0.91 } },
]);
// result.units === 'normalized'

With die size — physical mm coordinates:

const result = buildWaferMap({
  results:   data,
  dieConfig: { width: 10, height: 10 },
});
// result.units === 'mm'

Fully specified with notch:

const result = buildWaferMap({
  results:     data,
  waferConfig: { diameter: 300, notch: { type: 'bottom' }, orientation: 90 },
  dieConfig:   { width: 10, height: 10 },
});

With bin data and edge exclusion:

const result = buildWaferMap({
  results:     csvRows.map(r => ({ x: Number(r.x), y: Number(r.y), hbin: Number(r.hbin) })),
  waferConfig: { diameter: 200, edgeExclusion: 3 },
  dieConfig:   { width: 8, height: 8 },
});
console.log(result.yield.yieldPercent);

Multiple tests and bins in a single pass:

const result = buildWaferMap({
  results: rows.map(r => ({
    x: +r.x, y: +r.y,
    testValues: { 1010: +r.testA, 1020: +r.testB, 1030: +r.testC },
    hbin: +r.hbin,
    sbin: +r.sbin,
  })),
  testDefs: [
    { testNumber: 1010, name: 'Idsat', unit: 'A' },
    { testNumber: 1020, name: 'Vth',   unit: 'V' },
    { testNumber: 1030, name: 'Ioff',  unit: 'A' },
  ],
  dieConfig: { width: 10, height: 10 },
});

Reticle overlay phased to die (2, 1):

const result = buildWaferMap({
  results:   data,
  dieConfig: { width: 10, height: 10 },
  reticleConfig: { width: 4, height: 2, anchorDie: { x: 2, y: 1 } },
});

Multi-wafer lot stack — count bin 2 failures across six wafers:

const result = buildWaferMap({
  waferConfig: { diameter: 300 },
  dieConfig:   { width: 10, height: 10 },
  lotStack: {
    results:   [wafer1, wafer2, wafer3, wafer4, wafer5, wafer6],
    method:    'countBin',
    targetBin: 2,
  },
});

Row-based prober (y increases downward, origin at upper-left):

const result = buildWaferMap({
  results:   data,
  dieConfig: { width: 10, height: 10, coordinateOrigin: { type: 'UL' } },
});

Retests — keep first result, surface retest count in tooltip:

// Raw results may include the same (x, y) more than once.
// 'first' keeps the initial test; 'last' (default) keeps the most recent.
const result = buildWaferMap({
  results:      rawResults,
  retestPolicy: 'first',
  waferConfig:  { diameter: 300, notch: { type: 'bottom' } },
  dieConfig:    { width: 10, height: 10 },
});

// die.retestCount is set (to the total count) whenever a position was retested.
const retested = result.dies.filter(d => d.retestCount !== undefined);
console.log(`${retested.length} die positions were retested`);
// e.g. → "47 die positions were retested"
// The built-in tooltip automatically shows "Retests: N" for retested dies.

4.5 Post-enrichment¶

When you need to attach additional values after the map is built, use getDieKey for stable lookups:

import { buildWaferMap, getDieKey } from '@wafertools/wafermap';

const result = buildWaferMap({ results: primaryData, waferConfig, dieConfig });

const rowMap = new Map(rows.map(r => [getDieKey({ x: +r.x, y: +r.y }), r]));
const enrichedDies = result.dies.map(d => {
  const row = rowMap.get(getDieKey(d));
  if (!row) return d;
  return {
    ...d,
    testValues: { 1010: +row.testA, 1020: +row.testB, 1030: +row.testC },
    hbin:       +row.hbin,
    sbin:       +row.sbin,
  };
});

getDieKey always use this for stable die lookups rather than ad-hoc template literals — it guarantees a consistent "x,y" format across grid offset corrections.

5 renderWaferMap(container, result, options?)¶

A fully self-contained interactive wafermap. Accepts a WaferMapResult directly, owns view building internally, and provides a built-in toolbar that appears on hover — wafermap-specific controls always in the same place.

renderWaferMap(container: HTMLElement, result: RenderableWaferMap, options?: RenderOptions): WaferMapController

options is optional, and mostly stays that way. RenderOptions has 22 top-level fields and this section documents all of them, but the call above works with none: you get the toolbar, plot modes, colour schemes, zoom and pan, tooltips, die selection and PNG export by default.

For calibration, tsmap — a full desktop application on this library — passes 7: viewOptions (initial plot mode and colour scheme), summaryPanel, insights, downloadFilename, userGuideExtension and showHelpButton. Those six, plus onSaveImage/onSaveText if you want exports routed through your own save dialog, cover the overwhelming majority of integrations.

Everything else in this section exists for a specific need — a host that draws its own chrome, an embedded map that must follow a host theme, a wafer with no position data. Search for the problem you have; don't read forward.

RenderableWaferMap is { wafer, dies } plus every other WaferMapResult field as optional. A WaferMapResult satisfies it, so the usual buildWaferMap → renderWaferMap path is unchanged; the wider type exists because renderWaferGallery renders each card through this same function, and a card is a WaferMapDisplayItem that carries no dataCoverage, viewport, legendBox, binLegendRows or reticleConfig. Supply what you have — anything absent is derived or skipped rather than assumed.

renderWaferMap accepts any block HTMLElement as container — the function creates and manages its own <canvas> inside it, sized to fill the container (width: 100%; height: 100%). Width comes from document flow, but the canvas can only fill a resolved height. A plain block <div> in normal flow works (it grows to the map), but a flex or grid child whose ancestors never resolve a height collapses to zero — the map is then invisible and the library logs a warning. Give the container a height with any of:

<!-- Fixed size: -->
<div id="map" style="width: 600px; height: 600px;"></div>

<!-- Responsive square (height follows width): -->
<div id="map" style="width: 100%; aspect-ratio: 1;"></div>

// Or let the library size it — no container CSS needed:
renderWaferMap(container, result, { height: 600 }); // px, or '70vh', etc.

See Troubleshooting → Map is blank, invisible, or the wrong height for all four valid sizing patterns. The toolbar gives users direct access to every display option without any app-level chrome: plot mode, colour scheme, ring and quadrant overlays, die labels, rotate, flip, zoom, box-select, and PNG download. An expand button (⛶) in the toolbar opens the map in an enlarged modal overlay using canvas reparenting — no second controller is created. A maximise button inside the modal grows it to fill the window.

import { buildWaferMap } from '@wafertools/wafermap';
import { renderWaferMap } from '@wafertools/wafermap/render';

const result = buildWaferMap({ results, passBins });
const ctrl = renderWaferMap(document.getElementById('map'), result, { showToolbar: true });

5.1 WaferViewOptions¶

viewOptions controls the initial display state of the map — which plot mode to show, the colour scheme, overlays, orientation, and so on. Every field is optional; the toolbar lets users change all of them at runtime. Pass viewOptions inside RenderOptions:

renderWaferMap(container, result, {
  viewOptions: {
    plotMode:      'value',
    activeTest:    1060,       // testNumber to show (must match a testDef.testNumber)
    valueColorScheme: 'mako',
    showDieLabels: true,
  },
});

To read or update options programmatically after mount, use the controller:

const ctrl = renderWaferMap(container, result, options);

ctrl.getOptions();                         // → current WaferViewOptions snapshot
ctrl.setOptions({ plotMode: 'softBin' });  // merge — only listed keys change

Field reference¶

Persisting user preferences¶

WaferViewOptions is the intersection of two named sub-types: - WaferPreferences — stable settings worth saving (bin and value colour schemes, the bin-definition colour toggle, rotation, overlays, legend position, log scale, colorbar range mode) - WaferDisplayState — transient session state (plot mode, active test, active metadata key, value range, highlight bin)

The onViewOptionsChange callback receives a category hint ('preference' | 'state' | 'mixed') so you can decide what to persist without filtering keys manually:

renderWaferMap(container, result, {
  onViewOptionsChange: (opts, changed, category) => {
    if (category === 'preference') saveToLocalStorage(opts);
  },
});

Use === 'preference' (not !== 'state') so that 'mixed' events — which may include transient fields like plotMode or activeTest — do not get written to storage.

5.2 Hover tooltip content by mode¶

The aggregationMethod and lotSize fields on ViewOptions (§11, buildView) populate the method label and percentage denominator respectively. renderWaferMap and renderWaferGallery set both for you — a map built with lotStack carries its own lotSize.

5.3 Axis labels¶

When showAxes: true, tick labels show die grid indices (integer i/j values). renderWaferMap derives diePitchMm automatically from the view geometry, so axes always show grid indices. Only when calling toCanvas directly without supplying diePitchMm do axes fall back to mm values.

5.4 RenderOptions¶

These ToCanvasOptions fields (§9.1) are accepted: padding, background, showColorbar, colorbarWidth, showAxes, showTitle, legendOffset, diePitchMm and metadataFields. Plus:

{
  height?:                 number | string    // intrinsic map height. renderWaferMap fills its container, which must
                                            // therefore have a resolved height; set this and the library sizes its own
                                            // wrapper, so the map renders with no container CSS. Number = px, or any CSS
                                            // length ('600px', '70vh'). Omit when the container already has a height.
  showAxes?:               boolean            // draw axis tick marks and die grid index labels (default false)
  viewOptions?:           WaferViewOptions  // initial display state; plotMode, testDefs, and reticles are pre-seeded from the result automatically
  onHover?:                (die: Die | null, event: MouseEvent) => void
  onClick?:                (die: Die, event: MouseEvent) => void
  onSelect?:               (dies: Die[]) => void     // fires after box-select drag or click-select
  onViewOptionsChange?:   (opts: WaferViewOptions, changed: (keyof WaferViewOptions)[], category: 'preference' | 'state' | 'mixed') => void
                          // mirrors toolbar changes; changed lists the keys that were modified;
                          // category is 'preference' when all changed keys are WaferPreferences,
                          // 'state' when all are WaferDisplayState, 'mixed' when both
  showTooltip?:            boolean   // default true
  showToolbar?:            boolean   // default true
  showIdentity?:      boolean   // default true — the wafer's identity (lot, wafer ID, product, test
                                            // program, temperature, etc.) in the chrome row above the canvas, beside
                                            // the toolbar. Independent of showToolbar/Insights, and a CONTENT switch
                                            // only: the chrome row exists whenever there is a toolbar, so turning this
                                            // off costs the identity text and nothing else. Short metadata renders
                                            // inline when it fits; otherwise it collapses to one identifying line that
                                            // expands over the canvas on click/Enter/Space. Renders nothing when the
                                            // result has no metadata/lot-stack context.
  dieList?:                DieListDisplayOptions  // display preferences for the built-in die-list table (the
                                            // coordinate-less map replacement, and the "+N dies without position" footer)
                                            // — column selection, maxRows. See §5.4.1.
  showExpandButton?:       boolean   // show the expand button in the toolbar and enable the E-key shortcut
                                            // (default true). Independent of showIdentity — expand is a view control,
                                            // not part of the wafer's identity. Set false when the host already renders
                                            // the map inside its own expanded/modal context, where wmap's built-in
                                            // expand modal would be redundant
  statsSummary?:           StatsSummary  // precomputed wafer-level stats — adds a Summary toggle button to the toolbar
  summaryPanel?:           SummaryPanelOptions  // Summary panel placement and open/closed initial state
  insights?:               InsightsOptions  // adds an Insights toolbar button that swaps the map for this wafer's own
                                            // chart suite (Overview, Distributions, Correlation) — default disabled. See §5.9.
  warnings?:               WarningsOptions  // built-in surfacing of the library's own advisories — ON by default.
                                            // { display?: boolean; onWarning?: (w: WaferWarning[]) => void }
                                            // See §4.2.2 and the note below.
  showHelpButton?:         boolean   // show a help button in the toolbar that opens the built-in end-user guide
                                            // (default false); enable in applications that want to surface the guide
                                            // without linking externally. Opens as a real, separate window when
                                            // `window.open` is available, falling back to an in-page non-modal
                                            // floating window when it's blocked (some embedded WebViews — Tauri,
                                            // Electron, WebView2 — silently return null)
  userGuideExtension?:     UserGuideExtension  // insert a host app's own documentation into the guide window
                                            // (see "User guide extension" below) — only relevant when showHelpButton is true
  downloadFilename?:       string    // stem for the PNG download filename (default 'wafermap') — '.png' is appended automatically
  onSaveImage?:            (blob: Blob, suggestedName: string) => void | Promise<void>
                                            // host hook for persisting the rendered PNG. When provided, the toolbar's save
                                            // button calls it instead of triggering a browser <a download>, letting
                                            // embedded hosts (Tauri, Electron, WebView2) route the image through a native
                                            // dialog. When omitted, the default download behaviour is unchanged.
  onSaveText?:             (text: string, suggestedName: string, mimeType: string) => void | Promise<void>
                                            // host hook for every built-in "Export CSV" button — Summary/Insights test-values
                                            // and functional-tests tables, and the die-list table (§5.4.1). Mirrors
                                            // onSaveImage — when provided, called instead of a browser <a download> (a
                                            // silent no-op in Tauri/Electron/WebView2). When omitted, the default
                                            // download behaviour is unchanged.
  zIndex?:                 number    // base z-index for wmap's transient overlays (menus, tooltip, expand/help modals).
                                            // Omit for a safe high default (above typical app modal layers); set it to
                                            // embed the map inside your own modal/overlay. See "Overlay z-index" below.
}

Sizing. renderWaferMap fills its container, so the container must have a resolved height (width comes from document flow). A plain block <div> grows to fit the map; a flex/grid child needs a height-resolved parent or it collapses to zero — the library logs a warning when it detects this. Pass height to have the library size the container for you. See Troubleshooting → Map is blank, invisible, or the wrong height.

The box-select toolbar button is always shown. Providing onSelect lets your app react to selection changes; without it the selection is purely visual.

When statsSummary is provided, a summary panel toggle button (notebook icon) appears in the toolbar. The panel opens hidden by default; clicking the button shows or hides it. Clicking a finding in the panel highlights the affected die zone on the map.

Overlay z-index (zIndex / --wmap-z). Every transient overlay wmap creates in the host page — toolbar menus and dropdowns, the die hover tooltip, the expand modal, and the (non-modal) user-guide window — uses position: fixed. By default they stack at a high base value (6000), so they appear above typical app modal layers with no configuration. wmap layers its own overlays from the base upward: the modal backdrop and a component's own persistent chrome (e.g. a gallery card's toolbar) at the base, the tooltip and the modal box (over its own backdrop) at base + 1, every menu/dropdown/cascade-submenu at base + 2, and content that must clear a maximized modal box at base + 3. The user-guide window uses its own incrementing band above that, so it's never hidden behind a still-open modal. A gallery card detached into its own window (§6.6) is a separate OS window, not an in-page overlay, so none of this stacking applies to it — it's positioned and raised by the OS window manager instead.

Menus specifically render into one dedicated layer per overlay root (see "Menus opened from inside..." below) rather than at the same tier as ordinary persistent chrome — a persistent, host-page-pinned element (your own sticky header, a docked panel) can sit anywhere in your stacking order without ever being able to outrank a wmap menu, because menus don't compete on the general base/tooltip/modal scale at all.

To embed a wmap render inside your own modal or overlay, pass zIndex so wmap's menus and tooltips land above it:

// Host modal at z-index 5000; put wmap's overlays above it:
renderWaferMap(container, result, { zIndex: 5100 });

zIndex is applied for the lifetime of the render and restored on controller.destroy(). Internally it writes the --wmap-z CSS custom property on document.documentElement (overlays that append to document.body inherit it from there, and every tier above — including the menu layer — is itself calc(var(--wmap-z, 6000) + N), so raising zIndex shifts the whole stack together); you can set --wmap-z yourself instead of passing zIndex if you prefer to control stacking via CSS. Menus opened from inside the expand modal or the user-guide window are appended to that box's own menu layer rather than document.body's, so they always appear above its content regardless of the host page's stacking context.

Native <dialog> host modals need no configuration at all. If your own modal is built on the native <dialog> element and shown via .showModal(), it's promoted into the browser's top layer — a rendering layer that sits above the entire normal stacking order unconditionally, regardless of any z-index (no zIndex value, however high, can make a document.body-level element paint above it). wmap detects this automatically: every overlay it creates (tooltip, menus, the expand modal, the user-guide window's in-page fallback) checks whether its trigger lives inside a <dialog> currently shown modally (element.matches(':modal')) and, if so, roots itself inside that dialog instead of document.body — so it lands correctly in the same top-layer subtree with no zIndex or other configuration needed. This is unrelated to the zIndex mechanism above, which only matters for ordinary (non-<dialog>) modal implementations — a plain fixed/absolute overlay div, whatever library built it.

5.4.1 Theming (--wmap-* custom properties)¶

wmap's chrome — the toolbar, summary panel, menus, the die tooltip, and the wafer canvas itself (background, axis labels, grid) — is themed entirely through CSS custom properties. Set them on any ancestor of the render container and everything wmap draws follows. Every token has a light default baked in, so if you set nothing you get the default light appearance; override only what you want.

This is the same mechanism --wmap-z uses for stacking. It is theme-agnostic: wmap defines the tokens and their defaults, the host supplies the values. (The data palette — the bin/value colours of the dies — is separate and controlled by colorScheme, not these tokens; it does not follow the chrome accent.)

Type size (--wmap-font-size)¶

wmap's chrome is sized from one token. Set --wmap-font-size and every tier moves with it, so an embedded map follows the host's own type scale instead of pinning wmap's:

:root { --wmap-font-size: 14px; }   /* default 12px */

The tiers are derived, not individually settable — deliberately, so a host cannot produce an incoherent scale (headings smaller than body, meta larger than headings):

Canvas text follows too, but resolves the token at paint time from the document root — canvas cannot read a CSS variable. Set --wmap-font-size on :root (as with the colour tokens) rather than scoping it to a container, or chart and axis labels will keep the default while the DOM chrome moves.

Density (--wmap-density)¶

The companion lever to --wmap-font-size. It scales every step of the spacing scale, so an embedded map can tighten into a narrow column or breathe in a roomy host:

:root { --wmap-density: 0.85; }   /* default 1 */

Type is deliberately not affected. Density is the space between things; shrinking type to fit a column is what produced a segmented toggle that rendered smaller than the buttons beside it. Corner radius is likewise unaffected — it is three fixed roles (control 4px, container 6px, pill full).

Typeface (--wmap-font-family)¶

The third sizing lever. It defaults to inherit, so an embedded map picks up the host's own typeface without being told; set it only when the map should differ from its container:

:root { --wmap-font-family: "IBM Plex Sans", system-ui, sans-serif; }  /* default: inherit */

Like --wmap-font-size, canvas text cannot read the variable, so it reaches DOM chrome only — set a stack the canvas defaults sit comfortably beside rather than a display face.

Token reference (default in parentheses):

--wmap-err-* and --wmap-warn-* are visually distinct on purpose — a warning says something is missing or degraded, an error says the map may be positionally wrong (geometry advisories), and flattening the two into one colour hides the difference that matters. Every token that pairs a background with text on it — warn-*, err-*, text-strong against panel-bg/surface — needs its own AA-contrasting pair when you theme it. Overriding only the surfaces and leaving these unset does not make them invisible; it makes them fall back to the light-theme defaults above, which is how a dark theme silently ends up with near-black text on a near-black panel. §5.4.1's dark/Nord examples below set all of them for exactly this reason.

Canvas colours are resolved from these variables at draw time and re-resolved on a theme change or OS light/dark flip, so the wafer repaints to match.

Following the OS light/dark preference — put the light values on :root and override in a media query:

:root {
  --wmap-surface: #fff;
  --wmap-text: #333;
  /* …other light values… */
}
@media (prefers-color-scheme: dark) {
  :root {
    --wmap-canvas-bg: #242426;
    --wmap-surface:   #2a2a2d;
    --wmap-panel-bg:  #202022;
    --wmap-border:    #3a3a3a;
    --wmap-text:      #ccc;
    --wmap-text-muted:#888;
    --wmap-icon:      #aaa;
    --wmap-icon-hover:#6af;
    --wmap-icon-active:#6af;
    /* …etc… */
  }
}

Example — a dark theme (drop-in; overrides only what differs from the light defaults):

.wmap-dark {
  --wmap-canvas-bg:   #242426;
  --wmap-surface:     #2a2a2d;
  --wmap-panel-bg:    #202022;
  --wmap-border:      #3a3a3a;
  --wmap-text:        #ccc;
  --wmap-text-muted:  #888;
  --wmap-text-strong: #f2f2f2;
  --wmap-icon:        #aaa;
  --wmap-icon-hover:  #6af;
  --wmap-icon-active: #6af;
  --wmap-bg-hover:    #343438;
  --wmap-bg-active:   #2b3a4f;
  --wmap-menu-hover:  #343438;
  --wmap-menu-active: #2b3a4f;
  --wmap-separator:   #2a2a2a;
  --wmap-warn-bg:     #3a2f0f;
  --wmap-warn-border: #7a6222;
  --wmap-warn-text:   #f0c04d;
  --wmap-err-bg:      #3a1414;
  --wmap-err-border:  #7a3030;
  --wmap-err-text:    #ff8a8a;
  --wmap-info-bg:     #1a2b3d;
  --wmap-info-text:   #8ecbff;
  --wmap-selected:    #6af;
  --wmap-finding-indicator: #ffa057;
}

Every one of these matters: the six tokens that used to be left unset here — --wmap-text-strong plus the warn-*/err-*/info-*/finding-indicator group — do not go unstyled when omitted. They fall back to wmap's light-theme defaults, and --wmap-text-strong (the Summary panel's heading/big-number colour) defaults to #1f2f43, near-black. Near-black text on the #202022 panel above is under 1.1:1 contrast — invisible, not merely dim. Omitting any of this block's tokens reproduces that bug for whichever surface reads the one you left out.

Example — Nord (a branded palette; shows the same structure with a different accent):

.wmap-nord {
  --wmap-canvas-bg:   #2e3440;
  --wmap-surface:     #323846;
  --wmap-panel-bg:    #2b303b;
  --wmap-border:      #434c5e;
  --wmap-text:        #e5e9f0;
  --wmap-text-muted:  #a6adbb;
  --wmap-text-strong: #eceff4;
  --wmap-icon:        #d8dee9;
  --wmap-icon-hover:  #88c0d0;
  --wmap-icon-active: #88c0d0;
  --wmap-bg-hover:    #3b4252;
  --wmap-bg-active:   #3b4a58;
  --wmap-menu-hover:  #3b4252;
  --wmap-menu-active: #3b4a58;
  --wmap-separator:   #3b4252;
  --wmap-warn-bg:     #3b3220;
  --wmap-warn-border: #7a6a3a;
  --wmap-warn-text:   #ebcb8b;
  --wmap-err-bg:      #3b2020;
  --wmap-err-border:  #7a4040;
  --wmap-err-text:    #f39a9a;
  --wmap-info-bg:     #20303a;
  --wmap-info-text:   #88c0d0;
  --wmap-selected:    #88c0d0;
  --wmap-finding-indicator: #dc9a80;
}

The reference host tsmap implements a full theme picker (light, dark, Nord, Solarized, a brand green, high-contrast) this way — its index.html :root blocks are a worked example of the complete token set across multiple themes.

5.4.2 SummaryPanelOptions¶

{
  placement?:   'right' | 'left' | 'top' | 'bottom'  // panel side; default 'right'
  defaultOpen?: boolean                               // open on mount; default false
}

The Summary panel is a docked panel — metadata, yield, detected anomalies (StatsSummary.findings, with severity chips wired to filterFindings, §7.x; the Kind/Region dropdowns appear once there are at least 8 findings), bin breakdown, region yield, test values, and functional tests — plus one combined "Summary report" button that opens the full HTML report (renderSummaryReportHtml/renderLotSummaryReportHtml, which already includes findings) in an in-app modal (openReportModal, §10.3) — no host wiring required. Always co-visible with the map so a clicked finding can highlight the affected dies right there — see §5.9 for why this is a separate surface from Insights. Its bin/region/test-value numbers and Insights' Overview sub-tab read the same underlying computation (StatsSummary.stats.*, buildRegionYieldData, buildCapabilityData), so the two surfaces can show overlapping numbers without ever disagreeing.

Findings render directly beneath the headline stats, above the bin/region/test detail. Every section collapses from its header, and the collapsed set is remembered per panel element across re-renders.

The gallery's panel has no tabs. It previously opened on a Lot/Findings pair in which both tabs carried findings — lot-level ones under "Lot", and none at all under "Findings", which actually listed wafers — and in which two identical-looking per-wafer lists did different things on click. There is now one list: the Wafer Yield section, with each row badged by its own findings count and opening that wafer when clicked. Every wafer appears in it, including those with no findings, which the old subset list structurally could not show. A Findings report button beside the other report buttons covers every wafer's findings in one document.

On the single-wafer panel the metadata section is suppressed when the caller already renders that metadata — renderWaferMap does so whenever its identity header is mounted (showIdentity, default true), since the header's expandable panel is built from the same helpers. Set showIdentity: false and the panel's own "Wafer Info" section returns.

Three sections carry a header selector, and each derives its default rather than starting neutral:

Bin bars are ordered pass-bins-first, then failing bins by descending count — matching buildBinParetoData's count-descending ordering in the Insights bin chart — and are labelled "% of dies (N=…)" to distinguish them from the lot card's "Mean wafer yield", which is an unweighted mean of per-wafer yields. The two are different statistics over different denominators and agree only when die counts are even across the lot.

The on-screen test table carries Test / Mean / Ppk / Spec yield only; the full descriptive statistics (min, quartiles, median, max, σ, both limits) stay in the CSV export and the summary report. Ppk rather than Cpk because Cp/Cpk use the pooled within-wafer stddev — on a single-wafer panel there is exactly one subgroup, so cpk === ppk identically and the "Cpk" label would name an index the data does not contain; across a lot, Cpk excludes the wafer-to-wafer shift that Ppk includes. The Cpk/Ppk pair is a drift diagnostic and lives in the summary report, which prints all four indices. A test's N is hoisted into the section title when every test shares it.

5.4.3 InsightsOptions¶

{
  enabled?:     boolean                                          // show the Insights toolbar button; default false
  defaultView?: 'overview' | 'distributions' | 'correlation'      // sub-tab shown first; default 'overview'
  defaultOpen?: boolean                                          // open Insights on mount instead of the map; default false
}

defaultOpen is for an analysis-first surface, where the charts are the point and the map is the secondary view — symmetric with summaryPanel.defaultOpen. Note that the chart suite is a lazily-imported chunk, so opening it on mount also pulls that chunk on load rather than on first click; leave it off for a map-first page. See the Insights example, which uses it because the charts are its whole subject.

5.4.4 Die list & CSV export¶

Calling buildDieListSection directly is deprecated — removed in 0.31.0. The maps show the die list themselves (the dieList option).

buildDieListSection (@wafertools/wafermap/render) is the general "show me the raw dies" table — one row per die, with an Export CSV button. It backs three built-in surfaces — the coordinate-less map replacement, the "+N dies without position" footer, and the "View die list" Summary panel link, below — and is also exported for standalone use.

"View die list" is a link inside the always-available Summary panel (§5.4.2/§6.5), not a new toolbar button — deliberately, since the toolbar already carries a dozen buttons and this reuses an existing entry point the same way "Summary report" opens the HTML report without one either. On by default whenever a Summary panel is reachable at all — set enabled: false to hide it:

renderWaferMap(container, result, {
  summaryPanel: {},   // the panel this link lives inside — "View die list" appears automatically
});

renderWaferMap(container, result, {
  summaryPanel: {},
  dieList: { enabled: false },   // …unless you don't want it
});

On renderWaferMap it opens this wafer's own dies. On renderWaferGallery (§6.5) the equivalent GalleryOptions.dieList opens every wafer in the lot, pooled, with a leading Wafer column (one per die, resolved from each card's own label) and wafer-metadata columns computed via commonMetadata — a field common to every wafer appears once; a field that varies across the lot (a mixed-lot pool) does not appear at all, rather than printing one wafer's value as if it applied to the whole export. Both open the same resizable modal wmap's toolbar already uses elsewhere (chart drilldown, wafer expand), with buildDieListSection mounted inside it — same metadata columns, same maxRows, same CSV export as every other die-list surface, all driven by the one shared DieListDisplayOptions object.

import { buildDieListSection } from '@wafertools/wafermap/render';

buildDieListSection(dies, testDefs, options?);   // → HTMLDivElement | null

Columns, in order: [extraColumn?] → X, Y [→ Ring, Quadrant] [→ Edge excluded] → Site, Hard bin, Soft bin → one column per test → die metadata → wafer metadata.

X/Y are separate numeric columns, not a single "(x, y)" cell — a bracketed pair reads fine on screen but forces an extra parsing step (or breaks outright) when the CSV is opened in Excel, pandas, or any other tool expecting one number per cell. Blank for an unpositioned die.

Ring/Quadrant appear only when getWafer resolves at least one die to a Wafer — omitted entirely otherwise, not shown empty. Values match classifyDie (§7) exactly, using the same ringCount as the rest of this wafer/lot's analysis, so "Ring 2" here always names the same region a Ring finding does. Reached through renderWaferMap/renderWaferGallery, this is wired up automatically — a direct buildDieListSection call supplies getWafer itself.

Edge excluded appears only when at least one die in the export has edgeExcluded: true — buildWaferMap's edge exclusion (waferConfig.edgeExclusion) is opt-in and only ever stamps true on the dies it excludes, never false on the ones it doesn't, so "no die is excluded" and "the feature was never configured" are indistinguishable from Die[] alone; omitting the column in that case is the closest available approximation. When shown, Yes/No is unambiguous for every row, since at least one exclusion is known to have happened somewhere in the export.

Metadata columns are on by default (metadataColumns: 'auto') — every key found on any die's DieMetadata, deterministically ordered (metadataFields declaration order first, then the rest naturally sorted). Unlike the 'metadata' plot mode, where metadataFields gates which keys are offered (a legend has a cardinality limit), a table column has none — an export silently dropping host data would be worse than a wide one. Pass an explicit string[] to pin the set and order, or 'none' to omit die metadata entirely.

Wafer metadata (lot, waferId, product, …) is CSV-only by default (waferMetadataColumns: 'csv') — constant down every row, so it is noise on screen next to the always-visible metadata badge (§5.4), but it is exactly what makes a detached CSV self-describing enough to concatenate several exports and still know which wafer each row came from. Set 'both' to also show it in the table, or 'none' to omit it.

A key present on both the wafer and a die produces exactly one column, scope die, carrying the die's value — the same shadowing rule the hover tooltip (§12.4) applies.

Column labels resolve metadataFields[].label → prettyKey(key) → the raw key, matching every other column's human-readable header. A metadata key that collides with a built-in column name (e.g. a key literally called Site) is never dropped — it becomes "Site (metadata)", or falls back further to "Site (site)" and then a numbered suffix in the (rare) case that also collides.

maxRows (default 50_000) caps how many rows are built as real DOM — this table has no virtualisation, so an uncapped multi-hundred-thousand-die lot is a genuinely slow, heavy build. The CSV export is never capped; it always contains every die, and a footer states the truncation explicitly ("Showing the first 50,000 of 266,412 dies. The CSV export contains all 266,412.") whenever it applies. Set maxRows: 0 to skip the table and offer only the CSV export.

export interface DieListDisplayOptions {
  metadataColumns?:      'auto' | 'none' | string[];   // default 'auto'
  waferMetadataColumns?: 'csv' | 'both' | 'none';        // default 'csv'
  maxRows?:               number;                        // default 50_000; CSV is never capped
  maxHeight?:             string;
}

export interface DieListOptions extends DieListDisplayOptions {
  title?:          string;
  note?:           string;
  onSaveText?:     SaveTextHandler;
  extraColumn?:    { label: string; get: (die: Die) => string | undefined };
  getWafer?:       (die: Die) => Wafer | undefined;  // per-die wafer for Ring/Quadrant — see below
  ringCount?:      number;              // default 4 — must match this wafer/lot's own ringCount
  waferMetadata?:  WaferMetadata;       // e.g. WaferMapResult.metadata
  metadataFields?: MetadataFieldDef[];  // e.g. WaferMapResult.metadataFields
  ownerDocument?:  Document;            // default `document` — see below
}

When reached through renderWaferMap's RenderOptions.dieList, waferMetadata and metadataFields are always supplied by the library from the current build result — never from the host option — so a standalone-caller mistake can't substitute the wrong identity data into an export. A direct buildDieListSection call supplies both itself.

ownerDocument only matters for a host that might mount the table into a document other than the bare global — e.g. a popup window it opened itself. It's irrelevant for ordinary in-page use, including everywhere the library reaches this internally (the Summary panel's "View die list" link, the coordinate-less-wafer map replacement).

5.5 WaferMapController¶

Choose the right update method: - setResult — new wafer loaded (different geometry, dies, and/or test data). Re-seeds bin defs, testDefs, and reticles from the new result automatically. - setOptions — display-only change: plot mode, colour scheme, zoom, etc. No data reload.

{
  setResult(result: WaferMapResult): void            // replace wafer geometry and die data
  setOptions(opts: Partial<WaferViewOptions>): void // merge options, rebuild view
  getOptions(): WaferViewOptions                    // current options snapshot
  setSelection(dies: Die[]): void                    // programmatically highlight dies
  clearSelection(): void
  resetZoom(): void                                  // return to fitted view
  setStatsSummary(summary: StatsSummary | undefined): void  // update the Summary panel at runtime

  setInsightsOpen(open: boolean): void  // programmatically open/close the Insights tab; no-op if `insights.enabled` was not set

  openUserGuide(): void   // opens the end-user guide window directly — the same action the help toolbar button
                                  // performs, but callable regardless of showHelpButton, so a host
                                  // that hides wmap's own help button (e.g. folding it into its own combined help menu)
                                  // can still trigger the guide without a DOM query

  destroy(): void                                    // remove all listeners and DOM elements
}

5.6 Toolbar buttons (full mode)¶

Expand opens the map in an enlarged modal overlay; the map box is reparented — no view rebuild. A maximise button in the modal grows it to fill the window (F). Close with Esc, the × button, or the backdrop. Keyboard shortcut: E. It works in the Insights view too, where it expands the whole chart suite into a wide modal — those charts interact, and reading them side by side is the case the modal exists for; individual chart panels keep their own expand button for enlarging just one. Hidden inside gallery cards (which have their own non-modal expand, see §6) and inside an already-open modal or window.

While the Insights tab is open, every control above except Insights and User guide is hidden — Camera/Zoom/Pan/Box select, Mode/Palette/Log scale/Colorbar range/Rings/Quadrants/Labels/Reticle/XY indicator/Legend style/Rotate/Flip, and Summary all apply only to the map view, which the chart suite has replaced; Summary's panel specifically would have nothing to highlight against with the map hidden behind Insights. Expand is likewise hidden while Insights is open, for the same reason. They reappear as soon as Insights is closed.

5.7 Interactions¶

Note: zoom/rotate/flip are visual-only transforms — they never mutate the underlying Die data. Selection stability is guaranteed: die.x and die.y remain unchanged regardless of display orientation.

5.8 Example usage¶

import { buildWaferMap } from '@wafertools/wafermap';
import { renderWaferMap } from '@wafertools/wafermap/render';

const result = buildWaferMap({ results, waferConfig, dieConfig });

const ctrl = renderWaferMap(document.getElementById('map'), result, {
  viewOptions: { plotMode: 'hardBin', binColorScheme: 'accessible' },
  onClick:  (die)  => console.log(die.x, die.y, die.hbin, die.sbin),
  onSelect: (dies) => console.log(`Selected ${dies.length} dies`),
  onViewOptionsChange: (opts, changed, category) => {
    if (category === 'preference') savePreferences(opts);
    syncExternalUI(opts, changed);
  },
});

// Replace wafer geometry and die data after a full data reload:
ctrl.setResult(newResult);

// Programmatically change display mode:
ctrl.setOptions({ plotMode: 'value', valueColorScheme: 'plasma' });

// Clean up:
ctrl.destroy();

5.9 Insights tab¶

Passing insights: { enabled: true } adds an Insights toolbar button. Clicking it swaps the map for a chart suite computed from this wafer's own dies — the same panels a gallery's Insights tab shows (§6.10), scoped to one wafer. Clicking the button again (or the toolbar's Insights button) returns to the map view; the toolbar itself stays visible and usable the whole time so the Insights button is always reachable to close the tab.

Separate from the Summary panel (§5.4.2) on purpose. A finding's entire value is click-to-highlight-on-map, which can't work inside a full takeover of the map — so the Summary panel (which includes findings) stays docked, always co-visible with the map, while Insights takes over the full view for chart-heavy content that doesn't reference specific dies. The two toggle independently; opening one never hides the other's toolbar button. Insights' Overview numbers and the Summary panel's compact bin/ring/quadrant/test-value rows read the same underlying computation, so they never disagree even though both can be on screen in principle.

Insights has three sub-tabs:

• Overview — a per-test pass rate chart (worst test first, clustered by group when "Group by" is active), headline tiles naming the population (wafer count, dies analysed and excluded, and for a lot the mean wafer yield, labelled unweighted, per wafer to distinguish it from the die-weighted figure), a yield bar (labelled with the actual passBins in use, e.g. "Yield by wafer (pass: bin 1)", with a dashed median reference line), a hard/soft bin pareto, and a details card with ring/quadrant regional yield and the full per-test statistics table. The pass-rate chart has three modes (buildTestPassRateData, @wafertools/wafermap/stats), because a parametric test carries two independent pass/fail notions and a functional test only one:

The two parametric modes can legitimately disagree — guard bands, dynamic or per-site limits, criteria the exported limits do not describe, or a limits/data mismatch. They are therefore kept as separate views rather than collapsed into one "parametric pass rate", and TestPassRateData.disagreementDies counts the dies the two sources judge differently (null, distinct from 0, when only one source is present). The chart surfaces that count rather than resolving it, since only the reader can tell an expected guard band from a real mismatch.

Only the modes the data supports are offered; hasJudgeableTests(testDefs, kind, dies) takes the dies for 'testFlag', since every parametric test could carry a verdict and a definition-only check would offer a mode that renders empty. Bars are rates on a fixed 0–100% axis rather than counts, so splits with different wafer counts compare fairly. A parametric test with neither limits nor a recorded verdict is genuinely unjudgeable and is omitted rather than reported as 100%. - Distributions — process capability (Cp/Cpk/Pp/Ppk, normalized per test — see §7.16's buildCapabilityData for how tests without full spec limits are handled), a test-value boxplot, a value histogram, and a wafer-to-wafer trend (per-wafer mean with ±1σ whiskers, the die-weighted lot mean as a dashed centre line, and spec limits). The trend is always in slot order and has no sort control: a drift or a bad cassette position is only visible in the physical sequence, so sorting it would remove the only signal it carries. - Correlation — a Pearson-r correlation matrix (stating the median pairwise n, with the exact per-pair n in each cell's tooltip) and a die-level X/Y scatter that reports r and n for the pair it is showing, recomputed when the legend filters the points. Clicking a capability box drives the boxplot, histogram and trend onto that same test in place; clicking a correlation matrix cell drives the scatter panel's X/Y in place.

For a single wafer there is no "Group by" control (grouping needs more than one wafer to be meaningful — see §6.10) and no click-to-open-wafer action (the map you're looking at already is the only wafer there is to open). Everything else — the wafer picker on histogram/correlation/scatter, the capability↔boxplot/histogram cross-link, the correlation↔scatter cross-link — behaves the same as the gallery version.

insights.enabled only changes what the toolbar exposes; it needs no other options.

The chart suite is loaded on demand. It is a separate chunk (~25 KB gzipped), fetched the first time Insights is opened and never downloaded by a page that only renders maps — the same treatment the in-app user guide gets. Two consequences worth knowing:

• WaferMapController.setInsightsOpen(true) returns before the tab's DOM exists. The toolbar responds immediately, but code that asserts on the chart DOM straight after the call must wait for it to appear — polling for button[role="tab"] is the cheapest reliable signal. Closing is synchronous, and toggling back to the map while the chunk is still in flight is honoured rather than overridden.
• A host that bundles wmap itself needs a bundler that supports dynamic import() code-splitting (Vite, Rollup, webpack, esbuild with splitting: true — all of them by default). One that inlines dynamic imports still works; it simply loses the saving. insights.defaultView picks which sub-tab shows first (default 'overview'). Panels that read parametric test data (capability, boxplot, histogram, trend, correlation, scatter, and the pass-rate chart's spec/testFlag modes) need testDefs passed to buildWaferMap to have anything to plot — yield and bin pareto only need die.hbin/die.sbin.

const result = buildWaferMap({ results, waferConfig, dieConfig, testDefs, passBins: [1] });
renderWaferMap(document.getElementById('map'), result, { insights: { enabled: true } });

5.10 Warnings¶

renderWaferMap and renderWaferGallery surface the library's own advisories themselves. A ⚠ indicator appears in the toolbar only when there is something to say; clicking it lists each advisory with its code and explanation. The same set feeds the Summary panel's banner.

This is on by default and needs no wiring. The reasoning: the library raises advisories that mean the map may be positionally wrong (partial-coverage and friends — §4.2.2), and it is the only party that knows. Leaving it to the caller to notice and display them means, in practice, that nobody is told.

It is 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.

interface WarningsOptions {
  display?:   boolean                              // default true
  onWarning?: (warnings: WaferWarning[]) => void   // collected, de-duplicated, severity-ordered
}

Hosts with their own notification system should pass both:

renderWaferMap(el, result, {
  warnings: {
    display: false,                    // suppress the built-in indicator
    onWarning: (warnings) => myToastSystem.show(warnings),
  },
});