gds-lens 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ 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

package/README.md

@@ -65,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
 
@@ -91,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. |
@@ -104,26 +110,35 @@ The element exposes the following members:
 | Member | Returns | Description |
 |---|---|---|
 | `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. 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 superseded this one. |
+| `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). |
-
-Every `load()` cancels the one before it, so two quick changes to `src` show
-the second layout even when the first is the slower download.
+| `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 two events on itself, whichever way a load was started
-— the `src` attribute, `load()`, or a host pushing bytes through its surface.
-Neither bubbles.
+The element dispatches events on itself. None bubbles.
 
 | Event | `detail` | When |
 |---|---|---|
-| `gds-load` | `{ layerCount, cellCount }` | A layout finished loading and is on screen. |
+| `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