gds-lens 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,132 @@ follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
 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.
 
+## [1.3.0] - 2026-09-14
+
+### Added
+
+- **Two layouts in one viewer.** A `<gds-lens>` can hold two layouts at once
+  and draw them through one camera into one canvas, for comparing two
+  revisions of a design:
+
+  ```js
+  await element.load(oldBytes);
+  await element.load(newBytes, { slot: "b", name: "rev-b.gds" });
+  await element.setBlend(0.5);
+  ```
+
+  - `load(source, { slot })` picks which layout to replace -- `"a"` (the
+    default, and the only one a single-layout viewer ever uses) or `"b"`. A
+    second layout arriving does not move the camera off what is already being
+    read, and loading either slot leaves the other alone.
+  - `unload(slot)` drops one again; `setBlend(t)` / `getBlend()` crossfade
+    between them, `0` showing only A, `1` only B, between overlaying them.
+  - With two loaded, the panel grows a **Compare** folder: the blend slider,
+    an optional per-layout tint, and **Highlight differences**, which marks
+    per (layer, datatype) where the two disagree -- one colour where only A
+    has geometry, another where only B does. Both rasterize through the same
+    camera into the same coverage mask in the same frame, so identical
+    geometry cancels exactly. It is a difference of what is drawn at the zoom
+    being viewed, not a geometric XOR, and differences under about half a
+    pixel are ignored; zoom in to resolve a smaller one.
+  - The layer list shows the **union** of both layouts' layers, chipped A or B
+    where only one has it, so an added or removed layer is visible as a row
+    rather than absent. The hierarchy browser roots both cell trees, and cell
+    and label searches run over both with the same chips on the hits.
+  - `getLayers()` entries gain `source` (0 for slot A, 1 for B), and
+    `gds-load`'s detail gains `slot`.
+
+  See [docs/embedding.md](docs/embedding.md#two-layouts-in-one-viewer). The
+  single-layout case is unchanged in every respect: no attribute, no mode
+  flag, and the Compare folder is not built at all until a second layout is
+  loaded.
+
+- **gdsfactory / kfactory ports.** kfactory records each cell's ports as
+  KLayout meta info, which KLayout writes into the layout file itself: a
+  `$$$CONTEXT_INFO$$$` cell in GDSII, `KLAYOUT_CONTEXT` properties in OASIS,
+  each holding strings like `META('kfactory:ports:0')={'name'=>'o1',...}`. The
+  viewer now reads those back (`src/wasm/kfactory_ports.cpp`) -- name, type,
+  position, direction, width and layer, through the named cross-section --
+  and expands them through every placement, so a component's ports are marked
+  wherever it sits in the design: a bar across the port, an arrow the way it
+  faces, and its name once few enough are on screen to read. Optical ports
+  are orange, electrical green, anything else the highlight blue. A **Ports**
+  toggle in Display turns the overlay off; a **Ports** folder lists the top
+  cell's ports and centers the view on one when clicked. Each hierarchy cell
+  entry carries a `ports` array and the hierarchy a `portCount`, the
+  `gds-load` event's detail gains `portCount`, and the element exposes nothing
+  new otherwise -- a file without the metadata looks exactly as before. The
+  expansion stops at 200,000 port placements and says so in the panel.
+
+- **`getCamera()` / `setCamera({zoom, panX, panY})`,
+  `getMeasurements()` / `addMeasurement(x0, y0, x1, y1)` /
+  `clearMeasurements()`, and `getLayers()` / `setLayerVisible(...)`** on the
+  viewer surface and the element, for an app that wants to frame the view,
+  place a ruler or drive layer visibility itself. Thin pass-throughs over
+  behavior that already existed internally; `getLayers()` is also the only way
+  to read a layer's name, group, colors and shape counts.
+
+## [1.2.0] - 2026-09-03
+
+### Added
+
+- `gds-load` and `gds-error` events on the element, dispatched however a load
+  was started -- the `src` attribute, `load()`, or a host pushing bytes through
+  its surface. Until now a load that came from `src` could fail only into the
+  viewer's own error panel, with nothing for the embedding page to observe.
+  `detail` carries `{ layerCount, cellCount }` and `{ message }` respectively.
+  Prefixed rather than `load` / `error`, which every HTML element already has
+  with other types attached.
+- `showLoading(label?)` on the element. The surface had it; a page fetching its
+  own bytes and calling `load(bytes)` could not reach it without `ready`, so it
+  sat on "No layout loaded" for the length of the download.
+- A message when WebGL2 cannot be had: unsupported, disabled, or the page over
+  its limit on live contexts. The renderer's `main()` returns quietly when its
+  context creation fails -- which is what lets the same module run in the parse
+  worker and under Node, where there is no canvas -- and nothing on the other
+  side ever asked, so the result was a canvas that never drew and a `load()`
+  that reported success. The viewer now asks (`isGlReady`) and says so, and a
+  lost context (`webglcontextlost`, after a GPU reset or the browser reclaiming
+  it) is reported the same way rather than left as a black canvas.
+
+### Changed
+
+- `load()` settles on the outcome. It used to resolve as soon as the file had
+  been handed to the parse worker, so it never rejected on a file the parser
+  refused -- contrary to what the React docs claimed of it. It now resolves
+  once the layout is on screen and rejects with the same message the viewer
+  shows. A load superseded by a newer one rejects with an error named
+  `AbortError`, the name `fetch()` uses for the same thing.
+
+- The demo page's layout is served as gzipped OASIS rather than gzipped GDSII:
+  the same design, 4.4 MB down from 8.1 MB. `site/make-demo-assets.py` writes
+  OASIS now.
+
+### Fixed
+
+- The parse worker wrote a dozen lines to the console on every load, into the
+  embedding page's DevTools, whether or not tracing had been asked for. The
+  relay to the on-screen debug panel was always meant to be unconditional; the
+  copy to the real console was not. It is now gated on the same flag as the
+  main thread's breadcrumbs (the `debug` attribute or `?gdsDebug=1`). The test
+  meant to catch this filtered on `[GDS]`, and the worker's prefix is
+  `[GDS worker]`.
+- `destroy()` did not release the viewer. Six listeners on `window` (the
+  keyboard shortcuts and the coordinate menu's dismissal) were never removed,
+  and a listener's closure holds the whole viewer, wasm instance included; the
+  renderer's own `mouseup` and `resize` callbacks on `window` did the same from
+  the other side, and the WebGL context waited on garbage collection. Every
+  listener now carries an abort signal that `dispose()` fires, and the renderer
+  exports a `destroyRenderer()` that unregisters its callbacks and destroys the
+  context outright -- so a page calling `destroy()` because it hit the per-page
+  context cap gets its slot back when it asks, not when the collector gets to
+  it.
+- Two quick changes to `src` (or two `load(url)` calls) could show the older
+  layout: the viewer superseded an in-flight *parse*, but the fetch in front of
+  it was nobody's to cancel, so a slow first file landing after a small second
+  one won. Each `load()` now aborts the fetch before it, and a load parked on
+  gzip expansion notices it has been superseded when it wakes.
+
 ## [1.1.0] - 2026-08-31
 
 ### Added
@@ -389,7 +515,8 @@ 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/v1.1.0...HEAD
+[Unreleased]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.0.3...v1.1.0
 [1.0.3]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/EthanLowenthal/GDS-Lens/compare/v1.0.1...v1.0.2

package/README.md

@@ -15,9 +15,6 @@ a given release does.
 
 ![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**: 1.0. The element's API is stable, and breaking changes wait
-> for a major version. See [the changelog](CHANGELOG.md).
-
 ## Quick start
 
 ```sh
@@ -68,6 +65,14 @@ a streaming WebAssembly compile — see
   and ASCII DRC results.
 - **Navigates hierarchy**. You can search cells and labels, and measure
   distances.
+- **Shows gdsfactory / kfactory ports**. A layout written by gdsfactory 8+
+  carries its ports as KLayout metadata inside the file; the viewer reads them
+  back, draws every port as a bar across its width with an arrow the way it
+  faces (and its name, close in), and lists the top cell's ports in the panel.
+  No Python involved.
+- **Compares two layouts**. One viewer can hold two of them, drawn through one
+  camera, with a crossfade between them and a per-layer highlight of where they
+  differ. See [Two layouts in one viewer](docs/embedding.md#two-layouts-in-one-viewer).
 
 ## Installation
 
@@ -94,8 +99,6 @@ takes one attribute and exposes a handful of methods.
 
 #### Attributes
 
-The element takes one attribute:
-
 | Attribute | Description |
 |---|---|
 | `src` | URL of a layout to fetch and display. Setting it later reloads. |
@@ -106,13 +109,62 @@ 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. |
+| `ready` | `Promise<ViewerSurface>` | 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. `options.slot` is `"a"` (the default) or `"b"`, which loads a second layout alongside the first to compare them — see [Two layouts in one viewer](docs/embedding.md#two-layouts-in-one-viewer). Resolves once the layout is on screen; rejects on a failed fetch, a file the parser refuses, or — with an error named `AbortError` — when a later load into the same slot superseded this one. |
+| `showLoading(label?)` | `Promise<void>` | Shows the loading overlay, for the wait before a `load()` of bytes the page is fetching itself. `load(url)` does this on its own. |
 | `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. |
 | `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). |
+| `getCamera()` | `Promise<{zoom, panX, panY}>` | The current pan/zoom. |
+| `setCamera(camera)` | `Promise<void>` | Sets the pan/zoom. Clamped to the loaded design's bounds (the union of both, with two layouts loaded). |
+| `getLayers()` | `Promise<LayerInfo[]>` | Every layer's name, group, colors, visibility and shape counts, plus the `source` slot it came from. |
+| `setLayerVisible(layer, datatype, visible)` | `Promise<void>` | Shows or hides one layer. |
+| `getMeasurements()` | `Promise<{x0,y0,x1,y1}[]>` | Every ruler on screen, in micron endpoints. |
+| `addMeasurement(x0, y0, x1, y1)` | `Promise<void>` | Places a finished ruler without disturbing measure mode. |
+| `clearMeasurements()` | `Promise<void>` | Removes every ruler. Rulers don't survive a reload either way. |
+| `unload(slot?)` | `Promise<void>` | Drops the second layout, leaving a single-layout viewer. |
+| `setBlend(t)` | `Promise<void>` | Crossfades two loaded layouts: `0` shows only A, `1` only B, between overlays them. |
+| `getBlend()` | `Promise<number>` | The current crossfade. |
+
+Every `load()` cancels the one before it *for the same slot*, so two quick
+changes to `src` show the second layout even when the first is the slower
+download.
+
+#### Events
+
+The element dispatches events on itself. None bubbles.
+
+| Event | `detail` | When |
+|---|---|---|
+| `gds-load` | `{ slot, layerCount, cellCount, portCount }` | A layout finished loading and is on screen, whichever way the load was started — the `src` attribute, `load()`, or a host pushing bytes through its surface. `slot` is which of the two layouts it is. `portCount` is how many ports its kfactory metadata declared, 0 for a plain file. |
+| `gds-error` | `{ message }` | A load failed, or `showError()` was called. `message` is the text the viewer shows. |
+
+```js
+viewer.addEventListener("gds-load", (event) => {
+    console.log(`${event.detail.layerCount} layers, ${event.detail.cellCount} cells`);
+});
+viewer.addEventListener("gds-error", (event) => {
+    reportProblem(event.detail.message);
+});
+```
+
+The names carry a prefix because `load` and `error` already have meanings —
+and types — on every HTML element.
+
+#### Keyboard shortcuts
+
+The keys act on the viewer that was last pointed at, so on a page with several
+they go to the one under the mouse.
+
+| Key | Action |
+|---|---|
+| `[` / `]` | Previous / next marker in the selected marker's category. |
+| `m` | Toggle measure mode. Click two points to place a ruler. |
+| `Esc` | Abandon a ruler being placed; with none in progress, clear the finished ones and return to pan mode. Also closes the coordinate menu. |
+| `h` | Show or hide the cell hierarchy. |
+| `/` | Focus the cell filter box. |
 
 #### Several viewers on one page