gds-lens 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+Notable changes to this project. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+While the version is `0.x` the public API may change in any release. See the
+status note at the top of the README.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-25
+
+First release as a library.
+
+GDS Lens was previously a VS Code extension, released under the tags `v1.0.0`
+through `v1.6.3` and never published to npm. Those tags remain in the
+repository as history; this is a different thing with a different API, so the
+version starts again rather than continuing from `1.6.3`. The extension host
+has been replaced by the `ViewerHost` interface, the viewer mounts as a
+`<gds-lens>` custom element in a shadow root, and the payload is built for any
+web page rather than for a webview.
+
+### Added
+
+- `<gds-lens>` custom element: `src`, `load`, `goToPoint`, `setLyp`,
+  `setMarkers`, `showError`, `ready`.
+- **`dist/esm/`, a single importable module.** `import "gds-lens"` now resolves
+  to one file with the markup, styles, lil-gui, the default host, the
+  WebAssembly binary and the parse worker's script all inside it -- no bundler
+  configuration and no sibling files to serve. Built from a new
+  `GDS_LENS_ESM` wasm variant (`-sEXPORT_ES6`). The binary is inlined once and
+  shared with the worker through a `blob:` URL rather than inlined twice, which
+  is why this build needs `blob:` in `script-src`; 252 KB gzipped. The module
+  imports without a DOM, so a server render of a page that uses the element
+  does not throw -- the element registers itself on the client, where
+  `customElements` exists.
+- `describeDecodeFailure` on `gds-lens/load-errors`, and `limit` on the failure
+  result from `decodeLayoutBytes`.
+- The `ViewerHost` interface, with every method optional -- the viewer removes
+  the control for anything a host does not implement. A default host handles a
+  plain page.
+- Hand-written TypeScript declarations for the element, the host contract and
+  every pure subpath export.
+- Subpath exports for the parsers, which have no DOM and no WebAssembly:
+  `gds-lens/parsers`, `/cell-search`, `/coord-parse`, `/layout-bytes`,
+  `/load-errors`, `/hosts/browser`.
+- Two prebuilt payloads, `gds-lens/web/*` and `gds-lens/inline-wasm/*`,
+  differing only in whether the wasm binary is a separate file.
+- `debug` attribute and `?gdsDebug=1` for trace output.
+- Continuous integration: lint and the pure tests on every push, plus a lane
+  that builds both wasm payloads and runs the browser suite against them.
+  Publishing runs from a `v*` tag in the same way -- built and tested in the
+  job that publishes it, so the tarball on the registry is one a green run
+  produced rather than whatever a laptop had on disk. It authenticates with
+  npm trusted publishing rather than a stored token, which also means the
+  published tarball carries provenance: a signed statement of the commit and
+  workflow that built it, verifiable with `npm audit signatures`.
+
+### Changed
+
+- **Every file in the served payloads carries the package prefix.** They get
+  copied into someone else's web root, where `host.js`, `wasm-worker.js` and
+  `gdstk_wasm.js` are collisions waiting to happen:
+
+  | was | is |
+  |---|---|
+  | `host.js` | `gds-lens-host.js` |
+  | `wasm-worker.js` | `gds-lens-worker.js` |
+  | `gdstk_wasm.js` | `gds-lens-engine.js` |
+  | `gdstk_wasm.wasm` | `gds-lens-engine.wasm` |
+  | `viewer.html` | `gds-lens.html` |
+
+  The `createGdstkModule` global is unchanged: it is distinctive enough not to
+  clash, and it says what the module actually is.
+- Lint runs `eslint:recommended` as errors rather than seven rules as
+  warnings, so it can actually fail.
+- `prepublishOnly` gates a publish on lint, tests and two checks:
+  `scripts/check-dist.mjs`, which refuses a `dist/` that is missing, older than
+  the sources it was built from, or still carrying a template placeholder; and
+  `scripts/check-package.mjs`, which reads the file list npm would actually
+  publish and refuses build output, object files, CMake artifacts, the wasm
+  sources, or anything containing the build machine's home directory.
+- Third-party notices now cover the whole payload, not only what is linked
+  into the WebAssembly: zlib and Emscripten (in `gdstk_wasm.js`) and lil-gui
+  (bundled into `gds-lens.js`) have been added.
+
+### Fixed
+
+- **`import "gds-lens"` works.** The main entry pointed at `src/gds-lens.js`,
+  which pulls in `viewer.js` -- needing `.html`/`.css` text imports, a
+  `lil-gui-css` alias that existed only inside this repo's build, and the wasm
+  factory already present as a global. Nothing could load it: not Node, not any
+  bundler. It now resolves to the bundled module above.
+- **Gzipped layouts open.** `decodeLayoutBytes` was fully implemented and unit
+  tested but had no caller anywhere in `src/`, so `.gds.gz` and `.oas.gz`
+  failed with "Could not open this layout" despite the README advertising
+  them. It is wired into the load path, which every entry point goes through.
+  Bytes handed in as an `ArrayBuffer` are normalized too, so a compressed file
+  arriving in that shape is detected rather than sailing past the sniff.
+- **A removed `<gds-lens>` can be replaced.** The one-per-page guard was never
+  cleared, so after the first element left the DOM every later one refused
+  permanently -- which is what a framework re-render or an SPA route change
+  does. The element now releases its claim on disconnect and the next one has
+  the running engine moved into it, keeping the WebGL context, the parsed
+  design and the camera.
+- **An error message is no longer treated as markup.** A load failure's text
+  can carry a filename, a gdstk string, or -- through the default host's
+  `?src=` handling -- text straight from the URL, and it was concatenated into
+  `innerHTML` for the debug readout. A crafted link could inject into the page.
+  It is built as a text node now. Pages using the payload's own `viewer.html`
+  were protected by its CSP; an embedder with a laxer policy was not.
+- **The host page's `console` is no longer replaced.** The viewer overwrote
+  `console.log` and `console.error` to feed its on-screen debug panel, so a
+  host application's own logging appended to a detached `<div>` for the life of
+  the page. Trace output now goes through an internal logger and reaches the
+  console only when asked for.
+- **Drag-and-drop no longer covers the whole page.** The default host bound
+  `dragover`/`drop` to `window` and called `preventDefault`, which silently
+  disabled the embedding application's own drop targets. Both are bound to the
+  `<gds-lens>` element.
+- **Neither the Emscripten build tree nor the C++ ships.** `files` in
+  `package.json` is an allowlist that overrides `.gitignore`, so listing `src/`
+  published the whole build directory: 211 object files and CMake caches,
+  2.0 MB, with absolute paths from the build machine inside them. The wasm
+  sources went with them, which is no better a use of an install -- a consumer
+  gets the compiled payload and has no toolchain to rebuild it from
+  `renderer.cpp`. A `!src/wasm` negation excludes both, and `check:package`
+  fails on either coming back. The tarball is 39 files, 812 KB packed.
+- **Absolute build paths no longer end up in the WebAssembly.** With no
+  `CMAKE_BUILD_TYPE`, `NDEBUG` was never defined, so `assert()` stayed live in
+  gdstk, earcut and libcxxabi -- each embedding `__FILE__` as the full path of
+  the machine that compiled it, six of which shipped inside `gdstk_wasm.wasm`
+  and the inline payload. `-ffile-prefix-map` rewrites the prefix, which also
+  makes the binary reproducible across checkouts. The asserts are deliberately
+  kept: this module parses untrusted layouts, and an assert turns a violated
+  invariant into a clean abort the viewer already explains.
+- Saved views coming back from `localStorage` are checked for being an array,
+  not merely for parsing.
+- The debug panel drops old lines past a cap instead of growing without bound.
+
+### Accessibility
+
+- Controls that were `<span>`s with click handlers are real buttons, so they
+  can be reached and operated from the keyboard.
+- The canvas is focusable and named; the hierarchy is a proper `tree` with
+  per-row expanded state and depth.
+- Load progress, load errors and the stale-file banner are announced;
+  disclosures report `aria-expanded` and the search scope pair
+  `aria-pressed`.
+- The progress bars respect `prefers-reduced-motion`.
+
+### Removed
+
+- The `gds-lens/viewer` export. It pointed at `src/viewer.js`, which cannot be
+  imported by anything -- it needs the wasm factory as a pre-loaded global and
+  text imports for its markup and styles -- so it was a promise nothing could
+  keep. The same surface is reachable through `element.ready`.
+- `bindings.cpp` and its `parseGds` export, a second parse path with no
+  caller, compiled into every build.
+- The `loadAndRenderGds` export, also unused.
+- The `#workerBundle` placeholder element, left over from the extension's
+  worker-loading route and shipped unsubstituted. The `createWorker` host hook
+  replaces it.
+
+[Unreleased]: https://github.com/EthanLowenthal/GDS-Lens/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/EthanLowenthal/GDS-Lens/releases/tag/v0.1.0

package/LICENCE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Lowenthal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,372 @@
+# GDS Lens
+
+GDSII and OASIS chip layouts, parsed and rendered in the browser. A drop-in
+custom element wrapping [gdstk](https://github.com/heitzmann/gdstk) compiled to
+WebAssembly and a WebGL2 renderer.
+
+Reading and rendering only. Writing layouts is deliberately out of scope.
+
+![The viewer: a cell hierarchy tree, a rendered photonic layout, and the layer and display controls](https://raw.githubusercontent.com/EthanLowenthal/GDS-Lens/main/images/example.png)
+
+> **Status**: pre-1.0. The API is unstable and will change.
+
+## Quick start
+
+```sh
+npm install gds-lens
+```
+
+```js
+import "gds-lens";   // registers <gds-lens>
+```
+
+```html
+<gds-lens src="chip.gds" style="width: 100%; height: 600px"></gds-lens>
+```
+
+That's the whole thing. Pan with the mouse, zoom with the wheel. The import
+pulls in one self-contained module — the parser, the renderer, the WebAssembly
+binary, and the control panel — so there is nothing to copy and nothing
+else to serve.
+
+Or drive it from JavaScript:
+
+```js
+import "gds-lens";
+
+const viewer = document.createElement("gds-lens");
+viewer.style.cssText = "width: 100%; height: 600px";
+document.body.append(viewer);
+
+await viewer.load("chip.gds");        // a URL, or bytes you already have
+await viewer.goToPoint(120.5, -40);   // center on a coordinate, in microns
+```
+
+### Serve the files instead of bundling
+
+If you would rather serve a payload than bundle one — for a smaller download
+and a streaming WebAssembly compile — copy `dist/web/` and load its scripts in
+order. The order matters: both must precede `gds-lens.js`, which reads them as
+it starts.
+
+```html
+<script src="gds-lens-engine.js"></script>  <!-- the wasm module -->
+<script src="gds-lens-host.js"></script>    <!-- the default ViewerHost -->
+<script src="gds-lens.js"></script>         <!-- the element -->
+
+<gds-lens src="chip.gds" style="width: 100%; height: 600px"></gds-lens>
+```
+
+#### What each file is
+
+The payload is six files, four of which are required:
+
+| File | Status | What it is |
+|---|---|---|
+| `gds-lens.js` | required | The element, the viewer, and the control panel. This is the package. Load it last. |
+| `gds-lens-engine.js` | required | gdstk's GDSII and OASIS reader and the WebGL2 renderer, compiled to WebAssembly. Defines the `createGdstkModule` global `gds-lens.js` looks for, which is why it goes first. The parse worker loads it too. |
+| `gds-lens-engine.wasm` | required | The binary, fetched by `gds-lens-engine.js` from beside it. `inline-wasm` embeds it instead. |
+| `gds-lens-worker.js` | required | The parse worker: reads and triangulates off the main thread so the canvas stays responsive. Fetched by the worker, never by your page. |
+| `gds-lens-host.js` | optional | The default `ViewerHost`, described in [The ViewerHost interface](#the-viewerhost-interface). If you set `window.gdsLensHost` yourself before `gds-lens.js` runs, omit it. |
+| `gds-lens.html` | optional | A working reference page. For the script order, read this file; there is no need to deploy it. |
+
+Every name carries the package prefix because these get copied into someone
+else's web root, where a bare `host.js` or `wasm-worker.js` is a likely
+collision. Serve them from one directory, in the preceding order.
+
+`dist/web/gds-lens.html` is a working page doing exactly this. Everything in the
+payload must be on the same origin as the page: the WebAssembly binary and the
+parse worker are both fetched relative to the scripts.
+
+## What it does
+
+- **Parses GDSII and OASIS**. Format and gzip are both detected from the
+  leading bytes rather than the filename. The reader is gdstk itself, which is
+  what other implementations validate against.
+- **Renders with WebGL2**. Layer-batched vertex buffers, GPU instancing for
+  repeated cells, and a stroke font all live in C++ compiled alongside the
+  parser.
+- **Reads layer properties**. A `.lyp` file supplies colors, fill styles, and
+  layer names.
+- **Browses DRC and LVS markers**. The viewer reads `.lyrdb` report databases
+  and ASCII DRC results.
+- **Navigates hierarchy**. You can search cells and labels, and measure
+  distances.
+
+## Installation
+
+The package ships prebuilt: no Emscripten toolchain is required to consume it.
+Installing straight from a git URL does not work, because `dist/` is built in
+CI rather than committed.
+
+---
+
+## Reference
+
+The following sections describe the element, the `ViewerHost` interface an
+embedder implements, the package's subpath exports, and the limits of the
+WebAssembly module.
+
+### The `<gds-lens>` element
+
+The element is `display: block` with no intrinsic height, so give it one. It
+takes one attribute, exposes a handful of methods, and only one instance can be
+live at a time.
+
+#### Attributes
+
+The element takes one attribute:
+
+| Attribute | Description |
+|---|---|
+| `src` | URL of a layout to fetch and display. Setting it later reloads. |
+
+#### Properties and methods
+
+The element exposes the following members:
+
+| Member | Returns | Description |
+|---|---|---|
+| `ready` | `Promise<Viewer>` | Resolves once the engine has mounted. Every method in the following table awaits this, so you rarely need it directly. |
+| `load(source, options?)` | `Promise<void>` | `source` is a URL string, a `Uint8Array`, or an `ArrayBuffer`. `options.reload` keeps the current camera and layer visibility instead of framing the design. |
+| `goToPoint(x, y)` | `Promise<boolean>` | Centers on a coordinate in microns and flashes a crosshair. Resolves `true` if the point is inside the layout. |
+| `setLyp(name, text)` | `Promise<void>` | Applies a `.lyp` layer-properties file. Pass `""` to clear. |
+| `setMarkers(name, text)` | `Promise<void>` | Applies a marker database. The viewer detects the format from the content. |
+| `showError(message)` | `Promise<void>` | Replaces the view with an error message. |
+
+#### Only one live element at a time
+
+The renderer keeps its state in module-scope globals, so only one `<gds-lens>`
+can be *live* at a time. A second one alongside the first refuses visibly
+rather than contending for the same WebGL context.
+
+Removing one and adding another is fine, though, which is what matters in a
+framework: React and friends recreate the node on re-render, and an SPA route
+change destroys and rebuilds it. The engine is not torn down when the element
+leaves the DOM — the next `<gds-lens>` to connect has it moved into it, keeping
+the WebGL context, the parsed design, and the camera. Nothing reloads.
+
+### The `ViewerHost` interface
+
+The viewer never touches the environment directly. Anything only an embedder
+can do goes through a host object, which you install as `window.gdsLensHost`
+before the element script runs. Leave it unset and a default host handles a
+plain web page: `<input type=file>` for the pickers, `localStorage` for saved
+views, `prompt()` for a name, plus `?src=` and drag-and-drop for loading.
+
+Two things the default host does to the page, both of which a replacement host
+inherits responsibility for and neither of which the element itself does: it
+publishes the viewer surface as `window.gdsLens`, so a plain page can drive it
+from a script tag or the console; and it binds drag-and-drop to the
+`<gds-lens>` element rather than to `window`, which leaves the rest of the
+page's own drop targets alone.
+
+Every method is optional. The viewer hides the control for anything a host
+does not implement, so a read-only embed can supply almost none of it. A host
+can implement any of the following methods:
+
+| Method | Returns | Called when |
+|---|---|---|
+| `pickLyp()` | `Promise<{name, text} \| null>` | The user asks for a `.lyp`. `null` means cancelled. |
+| `unloadLyp()` | `void` | The loaded `.lyp` is dismissed. |
+| `pickMarkers()` | `Promise<{name, text} \| null>` | The user asks for a marker database. |
+| `unloadMarkers()` | `void` | The loaded marker database is dismissed. |
+| `loadViews()` | `Promise<View[]>` | Once at mount, for saved camera positions. |
+| `saveViews(views)` | `void` | The saved-view set changed. Persist it. |
+| `promptViewName(existing)` | `Promise<string \| null>` | A view is being saved. `existing` is the names already used. |
+| `requestReload()` | `void` | The user asks to re-read the layout. |
+| `setAutoReload(on)` | `void` | The user asks to always reload on change. |
+| `onGotoResult({ok, x, y})` | `void` | A `goToPoint` call finished, reporting whether it landed inside. |
+| `isLightTheme()` | `boolean` | The viewer needs to know the theme. Defaults to the OS preference. |
+| `createWorker()` | `Worker` | The parse Worker is needed. Where the scripts cannot be fetched by URL, override this. |
+| `connect(viewer)` | `void` | At mount, handing you the surface described in the following section. |
+
+#### The viewer surface
+
+`connect(viewer)` gives you the other direction, for pushing into the viewer
+rather than answering it:
+
+| Method | Description |
+|---|---|
+| `load(bytes, {reload})` | Display a layout from bytes. |
+| `showError(message)` | Show a fatal error. |
+| `setLyp(name, text)` | Apply layer properties. |
+| `setMarkers(name, text)` | Apply a marker database. |
+| `showStale(text)` | Offer a reload, for when the file changed underneath. |
+| `goToPoint(x, y)` | Center on a coordinate. |
+| `toggleDebug()` | Show or hide the debug panel. |
+| `setNamedViews(views)` | Replace the saved-view set. |
+| `applyTheme()` | Re-ask `isLightTheme()` after a theme change. |
+| `element` | The `<gds-lens>` the viewer is mounted in. Bind anything of your own to this rather than to `window`, so it stays inside the component. |
+
+#### Example: a custom host
+
+```js
+window.gdsLensHost = {
+    async pickLyp() {
+        const text = await fetch("/pdk/layers.lyp").then((r) => r.text());
+        return { name: "layers.lyp", text };
+    },
+    isLightTheme: () => document.documentElement.dataset.theme === "light",
+    connect(viewer) {
+        myApp.on("layout", (bytes) => viewer.load(bytes));
+    }
+};
+```
+
+### Subpath exports
+
+The parsers are pure JavaScript with no DOM and no WebAssembly, so they import
+cleanly into Node, a worker, or an extension host. The package exposes the
+following entry points:
+
+| Import | Exports |
+|---|---|
+| `gds-lens` | `GdsLens`, and registers `<gds-lens>`. The bundled module — everything inlined |
+| `gds-lens/parsers` | `parseMarkerFile`, `parseLyrdb`, `parseDrcAscii`, `sniffMarkerFormat`, `parsePointList`, `flattenMarkerModel` |
+| `gds-lens/layout-bytes` | `decodeLayoutBytes`, `looksGzipped`, `gzipStoredSize` |
+| `gds-lens/coord-parse` | `parseCoordinatePair` |
+| `gds-lens/cell-search` | `rankCellMatches`, `cellPathToTarget` |
+| `gds-lens/load-errors` | `describeLoadFailure`, `isOutOfMemory`, `describeDecodeFailure` |
+| `gds-lens/hosts/browser` | `createBrowserHost` |
+| `gds-lens/web/*` | The prebuilt payload, for hosts that serve files rather than bundle |
+| `gds-lens/inline-wasm/*` | The same payload with the binary embedded, for hosts that cannot fetch |
+| `gds-lens/esm/*` | The bundled module by path, if you would rather not rely on `.` |
+
+TypeScript declarations ship for all of these.
+
+#### The three builds
+
+`import "gds-lens"` gets you `dist/esm/`, and that is the right default. The
+other two are there for cases it cannot cover. The following table compares
+them:
+
+| Property | `esm` | `web` | `inline-wasm` |
+|---|---|---|---|
+| How it arrives | `import "gds-lens"` | scripts you serve | scripts you serve |
+| Files to serve | none | 4 (+2 optional) | 3 (+2 optional) |
+| Bundler configuration | none | N/A | N/A |
+| Total transfer, gzipped | 252 KB | 235 KB | 243 KB |
+| Streaming WebAssembly compile | no | yes | no |
+| Binary cached separately from the JS | no | yes | no |
+| Sensitive to the page's encoding | no | no | yes |
+| Needs `blob:` in `script-src` | yes | no | no |
+
+**`esm`** is one file with everything inside it: the markup, the styles,
+lil-gui, the default host, the WebAssembly binary, and the parse worker's whole
+script. Nothing is fetched, so nothing has to be served or copied, and no
+bundler needs configuring. It costs the streaming compile and about 17 KB over
+the payload.
+
+Both the main thread and the parse worker need Emscripten's module, and a
+worker cannot share the main thread's copy. Rather than inline it twice —
+which would add about 190 KB gzipped for nothing — it is inlined once as text
+and loaded from a `blob:` URL by both. That is the one thing this build asks
+of a page's CSP that the others do not: `blob:` in `script-src`, on top of
+the `worker-src blob:` all three need.
+
+**`web`** is the payload to serve if you can. `gds-lens-engine.js` fetches
+`gds-lens-engine.wasm` from beside it, so serve the two together; the binary
+compiles as it streams and is cached on its own.
+
+**`inline-wasm`** is `web` with the binary embedded in `gds-lens-engine.js`, for
+hosts that cannot fetch a file next to their own scripts — a VS Code webview
+cannot, from a Worker or from the main thread. Nothing else differs.
+
+On that last row: `inline-wasm` embeds the binary as a raw string, so
+`gds-lens-engine.js` has to be *decoded* as UTF-8 or it is corrupted, and the module
+then fails with a `WebAssembly.instantiate()` error about section lengths that
+says nothing about the cause. Either `Content-Type: text/javascript;
+charset=utf-8` or `<meta charset="UTF-8">` on the page satisfies it; only the
+absence of both breaks. That payload warns in the console when the document is
+not UTF-8. `esm` escapes its non-ASCII, so it does not care.
+
+#### Compressed layouts
+
+Gzip is handled for you: `<gds-lens src="chip.gds.gz">` works, and so does a
+plain `.gds` that is secretly gzipped, because the format is decided by magic
+number rather than by filename. Expansion happens in JavaScript rather than
+inside the WebAssembly heap, which is where a second copy of the
+file is most expensive, and it is capped at 2 GB.
+
+The same decoder is exported if you want it separately — to check a file before
+handing it over, say:
+
+```js
+import { decodeLayoutBytes } from "gds-lens/layout-bytes";
+
+const result = await decodeLayoutBytes(new Uint8Array(await file.arrayBuffer()));
+if (result.ok) await viewer.load(result.bytes);
+else console.error(result.reason);   // "too-large" | "corrupt"
+```
+
+### Limits
+
+Parsing, flattening, and triangulating all happen inside a 32-bit WebAssembly
+module, so everything has to fit in one 4 GB address space. Two cases bound
+what fits:
+
+- **Flat geometry is the expensive case**. It costs roughly 1 KB per polygon
+  end to end, so a couple of million top-level polygons is the practical
+  ceiling.
+- **Hierarchy is nearly free**. A cell placed eight or more times becomes a GPU
+  instance batch: 24 bytes per placement rather than a full geometry copy. A
+  design that flattens to 115 million polygons loads in about 2 GB.
+
+Past that the module aborts, and the viewer turns the error into an explanation
+rather than an engine string.
+
+## Build from source
+
+Building from source requires the
+[Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html)
+(`emcc`/`emcmake` on `PATH`) and Python 3.10 or later for its driver scripts.
+macOS's system `python3` is 3.9 and fails with a `TypeError` on
+`list[str] | None`; with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv python install 3.13
+export EMSDK_PYTHON="$(uv python find 3.13)"
+```
+
+Then build the payloads and run the tests:
+
+```sh
+git submodule update --init --recursive
+npm install
+npm run build:wasm     # all three -> src/wasm/build/{web,inline,esm}/
+npm run build          # -> dist/{web,inline-wasm,esm}/
+npm test
+```
+
+`npm run build:wasm:web`, `:inline`, and `:esm` build one variant each; `npm run
+build` then produces whichever outputs it finds the wasm for, and says which it
+skipped. The three differ only in link flags, but CMake caches those, so each
+gets its own build tree.
+
+`npm test` includes browser tests that need Chromium
+(`npx playwright install chromium`); they skip if it is missing. The end-to-end
+load test runs once per built payload.
+
+Before publishing, `npm run check:dist` and `npm run check:package` verify that
+the payloads are present and no newer than their sources, and that the tarball
+carries nothing it should not. `prepublishOnly` runs both.
+
+## License
+
+MIT, see [`LICENCE.md`](LICENCE.md).
+
+The payload carries third-party code in two places. Statically linked into the
+WebAssembly: [gdstk](https://github.com/heitzmann/gdstk) (BSL-1.0), Clipper
+(BSL-1.0), [Qhull](http://www.qhull.org) (Qhull license),
+[earcut.hpp](https://github.com/mapbox/earcut.hpp) (ISC), and
+[zlib](https://github.com/madler/zlib) (zlib license) — and `gds-lens-engine.js` is
+itself [Emscripten](https://github.com/emscripten-core/emscripten)'s output
+(MIT/NCSA). Bundled into the JavaScript beside it:
+[lil-gui](https://github.com/georgealways/lil-gui) (MIT).
+
+Every notice is reproduced in
+[`THIRD-PARTY-LICENSES.md`](THIRD-PARTY-LICENSES.md). Qhull's license in
+particular requires its notice to accompany any distribution that includes it,
+and its original source can be obtained from
+[the Qhull website](http://www.qhull.org).