# wafermap examples

Offline examples package for [@wafertools/wafermap](https://wafertools.github.io/wafermap/)
**v0.23.1**.

The library is bundled in `dist/`. Nothing to install, no network needed —
unzip, start the server, and every page works.

## Start it

The pages **must be served over HTTP**. Opening `index.html` from your file
manager will not work: browsers block ES modules and `fetch` on `file://`
URLs, so you will get a blank page and a console full of CORS errors.

| Platform | Command |
|---|---|
| Windows | `serve.cmd` (double-click, or run it from a terminal) |
| macOS / Linux | `sh serve.sh` |

Both take an optional port: `sh serve.sh 9000`. Then open:

- **<http://localhost:8080/examples/index.html>** — the 20 examples
- **<http://localhost:8080/starter/>** — a minimal skeleton to copy

Requires Python 3, which ships with macOS and most Linux distributions. On
Windows, install it from [python.org](https://python.org) if `serve.cmd`
reports it missing.

### No Python?

```
npx http-server -p 8080 .
```

Do **not** use `npx serve` — it returns 404 for the `.js` files under
`dist/`, which breaks every page.

> The bundled `serve.py` is not just a convenience wrapper: it pins the MIME
> type for `.js`. Python's built-in server reads MIME types from the Windows
> registry, and on machines where that mapping has been altered it serves
> JavaScript as `text/plain`, which browsers refuse to execute as a module.
> Any substitute server needs to get `text/javascript` right.

## What's inside

| Path | |
|---|---|
| `examples/` | 20 worked examples, one topic each. Start at `examples/index.html`. |
| `starter/` | Minimal app skeleton — copy this folder to begin your own. See `starter/README.md`. |
| `dist/` | The bundled library. Do not edit. |
| `data/` | Sample CSVs used by the examples and the Developer Guide. |
| `AGENTS.md` | Usage rules to paste into your AI coding agent's config before it writes wafer map code. |
| `llms.txt` | Machine-readable map of the docs and package entry points. |

Edit any example in place and reload — there is no build step.

**One exception to "works offline":** `examples/comparison.html` benchmarks
wafermap against Plotly.js, which it fetches from a CDN. Without a connection
that page explains itself and stops; everything else is unaffected.

The larger synthetic datasets (`showcase-*.csv`) are omitted to keep the
download small; regenerate them with `scripts/gen-showcase-csvs.mjs` from the
[repository](https://github.com/wafertools/wafermap) if you want them.

## Using it in a real project

The examples resolve the library through an importmap in each page's `<head>`:

```html
<script type="importmap">{ "imports": {
  "wafermap":        "../dist/index.js",
  "wafermap/render": "../dist/packages/canvas-adapter/index.js"
} }</script>
```

When you move to a bundler (Vite, webpack, esbuild), delete that block and:

```
npm install @wafertools/wafermap
```

The `import` statements themselves do not change.

## Documentation

- [Quick start](https://wafertools.github.io/wafermap/quickstart/)
- [Developer guide](https://wafertools.github.io/wafermap/guide/)
- [API reference](https://wafertools.github.io/wafermap/api/)

MIT licensed.
