gds-lens 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -4,10 +4,103 @@ 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.
+From 1.0.0 on, a breaking change to the element's API waits for a major
+version. Before that, `0.x` releases changed it freely.
 
-## [Unreleased]
+## [1.0.0] - 2026-08-25
+
+### Added
+
+- Several `<gds-lens>` elements can now be live on one page. Each drives its
+  own viewer, with its own WebAssembly instance and WebGL2 context, so a `.lyp`
+  or marker database applied to one leaves the others alone. A second element
+  used to refuse visibly rather than contend for the renderer's state.
+- `destroy()` on the element, releasing a viewer's WebAssembly instance and GL
+  context for good. Rarely needed -- an ordinary unmount parks the viewer
+  instead, which is what makes a framework remount free.
+- `docs/react.md`: a wrapper component, the JSX type declaration for React 18
+  and 19, server rendering, and what remounting does. The examples are covered
+  by `test/react.test.js`, and the type declaration by
+  `test/types/jsx-smoke.tsx`.
+- `showLoading(label?)` on the viewer surface, for the wait before `load()`:
+  a host that is fetching bytes can say so instead of leaving the viewer
+  looking idle. The element calls it itself when `load()` is given a URL.
+- `examples/multi-view.html`: six viewers on one page -- three loading a layout
+  from `src`, three waiting for a button -- including applying a `.lyp` and a
+  marker database to one viewer alone, and creating and releasing a viewer to
+  keep a WebGL context free.
+- `docs/embedding.md`, which is where the `ViewerHost` interface, the three
+  builds, the subpath exports and the WebAssembly limits moved to. The README
+  keeps the quick start and the element's own API and is a third of its previous
+  length.
+
+### Fixed
+
+- Saved views were shared by every viewer on the page. Each read the whole set
+  at mount and wrote the whole set back on save, so two viewers that both saved
+  a view overwrote each other and the last one won. The default host now keeps a
+  bucket per viewer, keyed by the element's `id`, else its `src`, else -- for a
+  page with a single viewer and neither -- the key it has always used. `loadViews`
+  and `saveViews` are handed the viewer asking, which is what a host serving
+  several needs to tell them apart. A viewer with no `id` and no `src` on a page
+  with others has nothing stable to key on: its views last for the life of the
+  page. Views previously saved on a page whose element carries a `src` are not
+  carried into the new per-layout bucket.
+- The renderer sized its drawing buffer to the window rather than to the canvas
+  element, which was only ever right for a viewer filling the page. In an
+  embedded `<gds-lens>` the browser stretched a window-sized buffer over the
+  element's box, so the layout was drawn distorted; every coordinate the mouse
+  produced -- the readout, the ruler, the right-click "Copy coordinate",
+  zoom-at-cursor -- answered for a pixel the pointer was not on; and each viewer
+  allocated a window-sized buffer and mask texture however small it was on
+  screen. It now sizes from the element, and a `ResizeObserver` on the canvas
+  keeps it in step with a box that changes without the window changing.
+- The canvas right-click menu passed viewport coordinates to the renderer and
+  clamped itself against the window, so in an embedded viewer it opened in the
+  wrong place and reported the coordinate of a different pixel.
+- A viewer that had not been asked for a layout showed "Loading layout..." over
+  an empty progress bar, which read as a load that had hung. It now says "No
+  layout loaded" until something actually asks for one.
+- `import "gds-lens"` shipped no default host. `sideEffects` in package.json
+  did not list `src/hosts/browser.js`, whose whole purpose is the side effect
+  of installing `window.gdsLensHost`, so every bundler dropped it -- including
+  the one that builds `dist/esm`. The documented entry point therefore came up
+  with no `.lyp` or marker pickers, no saved views, no drag-and-drop, no
+  `window.gdsLens`, and a console error claiming no layout would ever appear on
+  pages whose layout had loaded perfectly well. The served payloads were never
+  affected, since they load `gds-lens-host.js` as a separate script.
+
+  The `esm-bundle` test that was meant to catch this asserted on the string
+  `gdsLensHost`, which viewer.js contains anyway; it now looks for the host's
+  own implementation.
+- A viewer adopted while its WebAssembly module was still starting failed to
+  come up at all, reporting `Cannot set properties of null (setting 'width')`.
+  `ready` resolves as soon as the viewer is built, which is well before `main()`
+  creates the GL context, so an element could be removed and its viewer adopted
+  inside that window -- and `adopt` re-pointed the module's DOM root on the next
+  turn of the module promise, which is after `main()` has already read it. It
+  now writes through the object Emscripten uses *as* the Module, so the new root
+  is in place immediately.
+- An element whose parked viewer had been adopted by another element went on
+  driving it, so a stray `load()` or `src` change on a detached element wrote
+  into whatever was on screen. Such an element now rejects instead.
+- Removing a `<gds-lens>` before its engine finished loading raised an unhandled
+  promise rejection, which reached the embedding app's error reporting.
+- An element removed and re-added before its engine arrived built two viewers,
+  orphaning the first one's WebAssembly instance and WebGL context behind the
+  second's shadow tree.
+- The viewer no longer assigns `window.onerror`, which clobbered the embedding
+  page's handler. Page-level failures are reported through an added listener
+  and fanned out to whichever debug panels are open.
+
+### Changed
+
+- `src/viewer.js` exports `createViewer(element)` instead of doing its work in
+  its module body, which is what allows more than one viewer. `window.gdsLensHost`
+  is consequently read when each viewer mounts rather than once at import, so an
+  app can install a host any time before its first `<gds-lens>` renders.
+- `src/mount-target.js` is gone. It existed only to hand an element to
+  viewer.js's module body, which is now a parameter.
 
 ## [0.1.1] - 2026-08-25
 
@@ -194,6 +287,7 @@ web page rather than for a webview.
   worker-loading route and shipped unsubstituted. The `createWorker` host hook
   replaces it.
 
-[Unreleased]: https://github.com/EthanLowenthal/GDS-Lens/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/EthanLowenthal/GDS-Lens/compare/v0.1.1...v1.0.0
 [0.1.1]: https://github.com/EthanLowenthal/GDS-Lens/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/EthanLowenthal/GDS-Lens/releases/tag/v0.1.0

package/README.md

@@ -1,11 +1,15 @@
 # GDS Lens
 
+[![npm](https://img.shields.io/npm/v/gds-lens.svg?style=flat-square&color=0f1720&label=NPM)](https://www.npmjs.com/package/gds-lens)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENCE.md)
+
 GDSII and OASIS chip layouts, parsed and rendered in the browser. A drop-in
 custom element compiled to pure JS+WASM with a WebGL2 renderer.
 
 ![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.
+> **Status**: 1.0. The element's API is stable, and breaking changes wait
+> for a major version. See [the changelog](CHANGELOG.md).
 
 ## Quick start
 
@@ -39,41 +43,9 @@ 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.
+If you would rather serve a payload than bundle one — for a smaller download and
+a streaming WebAssembly compile — see
+[Embedding GDS Lens](docs/embedding.md#serve-the-files-instead-of-bundling).
 
 ## What it does
 
@@ -100,15 +72,18 @@ 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 following sections describe the element's own API. The rest lives beside
+it:
+
+| Page | What is in it |
+|---|---|
+| [React integration](docs/react.md) | A wrapper component, the JSX type declaration, server rendering, remounts. |
+| [Embed the viewer](docs/embedding.md) | The `ViewerHost` interface, the three builds, the 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.
+takes one attribute and exposes a handful of methods.
 
 #### Attributes
 
@@ -130,188 +105,47 @@ The element exposes the following members:
 | `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. |
+| `destroy()` | `Promise<void>` | Releases the viewer's WebAssembly instance and WebGL context for good. Rarely needed — see [Removal parks the viewer](#removal-parks-the-viewer). |
 
-#### Only one live element at a time
+#### Several viewers on one page
 
-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.
+Each `<gds-lens>` drives its own viewer, with its own shadow tree, its own
+WebAssembly instance, and its own WebGL2 context. Put as many on a page as you
+like; they share nothing, so a `.lyp` or a marker database applied to one leaves
+the others alone.
 
-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.
+Each one costs a WebGL2 context, though, and browsers cap live contexts per page
+at roughly 8 to 16 — past that the browser starts dropping the oldest. A page
+showing a dozen layouts at once wants one viewer swapping layouts rather than a
+dozen elements.
 
-### The `ViewerHost` interface
+[`examples/multi-view.html`](examples/multi-view.html) is a working page of six:
+three loading a layout from `src`, three waiting for a button, one of them
+created and released on demand to keep a context free.
 
-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.
+#### Removal parks the viewer
 
-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.
+An element leaving the DOM *parks* its viewer rather than tearing it down, and
+the next `<gds-lens>` to mount without one of its own adopts it. That is what
+makes a framework remount free: the element is new, the viewer is not, and the
+parsed design, the camera and the GL context all survive.
 
-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:
+An element mounted *alongside* a live one finds nothing parked and builds its
+own, which is why the preceding section is true.
 
-| 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"
-```
+Nothing frees a parked viewer on its own. A page that creates viewers it will
+never show again, and is hitting the context limit, can call `destroy()`; an
+ordinary unmount should let it park. See
+[Remounts and StrictMode](docs/react.md#remounts-and-strictmode) for what this
+means in a framework.
 
 ### 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.
+The parser and renderer run in a 32-bit WebAssembly address space, so a layout
+has to fit — file plus geometry — inside it. See
+[Limits](docs/embedding.md#limits) for the numbers and
+[Compressed layouts](docs/embedding.md#compressed-layouts) for what that means
+for gzipped files.
 
 ## Build from source