gds-lens 0.1.0

package/src/wasm-worker.js

@@ -0,0 +1,157 @@
+import { describeLoadFailure } from "./load-errors.js";
+
+// Runs the parse/flatten/triangulate half of loading a layout file (GDSII or
+// OASIS) off the main thread. Either way createGdstkModule is already in
+// scope by the time this file's own code runs, but how it got there depends
+// on the host (see createParseWorker in viewer.js):
+//
+// On an ordinary page the worker is a small blob that importScripts() both
+// gds-lens-engine.js and this file by absolute URL, and the wasm binary is a
+// separate file the module fetches for itself.
+//
+// Some hosts can do neither. A VS Code webview is the worked example: its
+// resource protocol serves `<script src>` tags in the main document fine, but
+// a Worker (even a blob one) can't reach it at all -- importScripts against
+// that URL fails with a NetworkError before it even gets to CSP, and fetch()
+// fails the same way even from the main thread, so the binary can't be
+// fetched either. Such a host uses the inline-wasm build (-sSINGLE_FILE=1,
+// binary embedded in the .js), concatenates its full text with this file's,
+// and returns a Worker built from the result through the ViewerHost's
+// createWorker() hook -- no network involved. See createWorker in
+// hosts/browser.js for the ordinary case this replaces.
+//
+// createGdstkModule() instantiates the *same* wasm module used on the main
+// thread. Its main() calls init_gl(), which fails harmlessly here (no
+// "#glCanvas" -- no DOM at all, same as running under plain Node for
+// headless testing) and returns before touching any DOM/GL state, so this
+// stays a pure computation module in this context: renderer.cpp's
+// parseGdsToLayers() does the parse/flatten/triangulate work and posts
+// 'gdsProgress' messages directly (see report_progress() in renderer.cpp).
+//
+// createGdstkModule() returns a Promise -- a rejection there (or any other
+// async failure below) would otherwise vanish as an unhandled rejection
+// inside this Worker instead of reaching viewer.js's worker.onerror (that
+// only fires for *synchronous* throws), leaving the main thread waiting
+// forever with no error and no progress. Every path below explicitly
+// posts a 'gdsResult' failure instead of letting anything fail silently.
+// Relay console.log/error to the main thread as 'gdsLog' messages -- this
+// worker has no DOM of its own, so viewer.js's on-screen #debugPanel is the
+// only way these are visible without a DevTools window correctly attached to
+// this specific webview (which has proven fiddly to get right). Args are
+// stringified defensively since not everything passed to console.log here
+// (e.g. Error objects, the Module object) is guaranteed structured-cloneable.
+function safeStringify(arg) {
+    if (typeof arg === "string") return arg;
+    if (arg instanceof Error) return arg.stack || arg.message;
+    try {
+        return JSON.stringify(arg);
+    } catch {
+        return String(arg);
+    }
+}
+const originalLog = console.log.bind(console);
+const originalError = console.error.bind(console);
+console.log = (...args) => {
+    originalLog(...args);
+    try {
+        postMessage({type: "gdsLog", level: "log", text: args.map(safeStringify).join(" ")});
+    } catch {
+        // ignore -- best-effort relay only
+    }
+};
+console.error = (...args) => {
+    originalError(...args);
+    try {
+        postMessage({type: "gdsLog", level: "error", text: args.map(safeStringify).join(" ")});
+    } catch {
+        // ignore -- best-effort relay only
+    }
+};
+
+console.log("[GDS worker] script started executing, typeof createGdstkModule:", typeof createGdstkModule);
+
+self.onerror = (msg, url, line, col, err) => {
+    console.error("[GDS worker] self.onerror:", msg, "at", url + ":" + line + ":" + col, err && err.stack);
+};
+self.addEventListener("unhandledrejection", (event) => {
+    console.error("[GDS worker] unhandled promise rejection inside worker:", event.reason);
+});
+
+// Where to fetch gds-lens-engine.wasm from, for the build that keeps it separate.
+// Emscripten would resolve it against this worker's own script URL, which is
+// a blob: with no directory to speak of, so viewer.js passes the real one in.
+// Absent (the inline-wasm build, or a host that assembles the worker itself)
+// there is no binary to locate and the default is left alone.
+function moduleArgs() {
+    const base = self.gdsLensScriptBase;
+    if (!base) return {};
+    return { locateFile: (file) => new URL(file, base).href };
+}
+
+console.log("[GDS worker] registering onmessage handler");
+self.onmessage = (event) => {
+    const message = event.data;
+    console.log("[GDS worker] received message, type:", message.type);
+    if (message.type !== "parse") return;
+
+    console.log("[GDS worker] fileData byteLength:", message.fileData && message.fileData.byteLength);
+    console.log("[GDS worker] calling createGdstkModule()...");
+    createGdstkModule(moduleArgs()).then((Module) => {
+        console.log("[GDS worker] createGdstkModule() resolved, Module keys:", Object.keys(Module).filter(k => typeof Module[k] === "function"));
+        // Extension-less name on purpose: GDSII vs OASIS is decided by the
+        // file's own header inside the wasm (gds_common::detect_format), so
+        // nothing here has to know or plumb through which one this is.
+        console.log("[GDS worker] writing /input.layout to MEMFS...");
+        Module.FS.writeFile("/input.layout", new Uint8Array(message.fileData));
+        console.log("[GDS worker] calling Module.parseGdsToLayers('/input.layout')...");
+        const result = Module.parseGdsToLayers("/input.layout");
+        console.log("[GDS worker] parseGdsToLayers returned, ok:", result.ok, "format:", result.format, "error:", result.error);
+        Module.FS.unlink("/input.layout");
+
+        if (!result.ok) {
+            postMessage({type: "gdsResult", ok: false, error: result.error});
+            return;
+        }
+
+        console.log("[GDS worker] layers:", result.layers.length, "instance groups:", result.instanceGroups.length, "labels:", result.totalLabels, "cells:", result.hierarchy.cellCount, "-- posting gdsResult back to main thread");
+        const transferList = [];
+        for (const layer of result.layers) {
+            transferList.push(layer.outlineVertices.buffer, layer.outlineRanges.buffer,
+                              layer.fillVertices.buffer);
+            // Label text (see attach_labels in renderer.cpp). Only the
+            // top-level layer entries carry it -- an instanced cell's labels
+            // are expanded into world space during the flatten, so the
+            // per-group entries below have no text of their own.
+            transferList.push(layer.textChars.buffer, layer.textLengths.buffer,
+                              layer.textOrigins.buffer, layer.textAnchors.buffer);
+        }
+        for (const group of result.instanceGroups) {
+            transferList.push(group.instances.buffer);
+            for (const layer of group.layers) {
+                transferList.push(layer.outlineVertices.buffer, layer.outlineRanges.buffer,
+                                  layer.fillVertices.buffer);
+            }
+        }
+        // hierarchy (see build_hierarchy in renderer.cpp) is plain objects and
+        // numbers -- one entry per cell in the file -- except for each row's
+        // per-placement transforms, which are Float64Arrays and so worth
+        // transferring rather than cloning. They're capped library-wide
+        // (kMaxHierarchyPlacements), so this walk is bounded and most rows
+        // (single placements) carry none at all.
+        for (const cell of result.hierarchy.cells) {
+            for (const ref of cell.refs) {
+                if (ref.placements) transferList.push(ref.placements.buffer);
+            }
+        }
+        postMessage(
+            {type: "gdsResult", ok: true, layers: result.layers, instanceGroups: result.instanceGroups,
+             hierarchy: result.hierarchy, bbox: result.bbox},
+            transferList
+        );
+        console.log("[GDS worker] postMessage(gdsResult) call returned");
+    }).catch((err) => {
+        console.error("[GDS worker] createGdstkModule() chain rejected:", err, err && err.stack);
+        postMessage({type: "gdsResult", ok: false, error: describeLoadFailure(err, "Layout worker failed")});
+    });
+};
+console.log("[GDS worker] onmessage handler registered, script finished top-level execution");

package/types/cell-search.d.ts

@@ -0,0 +1,33 @@
+// `gds-lens/cell-search` -- ranking and pathfinding over a design's cell tree.
+//
+// Both work on the hierarchy model the wasm parse hands back.
+
+/** One node of the cell tree. */
+export interface CellNode {
+    name?: string;
+    /** Child placements, by index into the same array. */
+    references?: Array<{ cell: number }>;
+    [key: string]: unknown;
+}
+
+/**
+ * Indices of the cells whose name contains `query`, best first: exact match,
+ * then prefix matches, then substring matches. Case-insensitive. Empty when
+ * the query is blank or nothing matches.
+ */
+export function rankCellMatches(cells: CellNode[], query: string): number[];
+
+/**
+ * One path of cell indices from a top cell down to `target`, root first and
+ * target last -- or `null` if no top cell reaches it.
+ *
+ * Depth-first, so it is *a* path rather than the shortest: a cell placed in
+ * twenty places has twenty paths and none is more correct. Terminates on a
+ * reference cycle, and stops descending at `maxDepth`.
+ */
+export function cellPathToTarget(
+    cells: CellNode[],
+    roots: number[],
+    target: number,
+    maxDepth: number,
+): number[] | null;

package/types/coord-parse.d.ts

@@ -0,0 +1,11 @@
+// `gds-lens/coord-parse` -- reading a coordinate a person typed.
+
+/**
+ * A coordinate pair in microns, or `null` if the text is not one.
+ *
+ * Tolerates the shapes coordinates actually arrive in: bare pairs, wrapped in
+ * brackets, comma- or space-separated, and per-number units (`nm`, `um`, `mm`)
+ * which are converted. Anything left over after the two numbers rejects the
+ * whole string rather than being half-read.
+ */
+export function parseCoordinatePair(text: string): { x: number; y: number } | null;

package/types/gds-lens.d.ts

@@ -0,0 +1,135 @@
+// Public types for the `gds-lens` entry point: the custom element, the host
+// interface an embedder implements, and the surface the viewer hands back.
+//
+// Hand-written rather than emitted, because these describe a contract that is
+// deliberately looser than the implementation: every ViewerHost method is
+// optional, and the viewer hides the control for anything a host leaves out.
+// That optionality is the interesting part, and it is the part a generated
+// declaration would get wrong.
+
+/** A file a host picked on the viewer's behalf. */
+export interface PickedFile {
+    name: string;
+    text: string;
+}
+
+/** A saved camera position, persisted by the host between sessions. */
+export interface NamedView {
+    name: string;
+    [key: string]: unknown;
+}
+
+/** The result of a `goToPoint`, reported back to the host. */
+export interface GotoResult {
+    ok: boolean;
+    x: number;
+    y: number;
+}
+
+/**
+ * What the viewer can be told to do, handed to the host in `connect`.
+ *
+ * This is the push direction: the host calls these to drive the viewer,
+ * rather than answering questions the viewer asks.
+ */
+export interface ViewerSurface {
+    /**
+     * The element the viewer is mounted in. Bind anything of your own to this
+     * rather than to `window`, so it stays inside the component -- a listener
+     * on `window` reaches the whole embedding page.
+     */
+    element: HTMLElement;
+    load(bytes: Uint8Array | ArrayBuffer, options?: { reload?: boolean }): void;
+    showError(message: string): void;
+    setLyp(name: string, text: string): void;
+    setMarkers(name: string, text: string): void;
+    /** Offer a reload, for when the file changed underneath. */
+    showStale(text: string): void;
+    goToPoint(x: number, y: number): void;
+    toggleDebug(): void;
+    setNamedViews(views: NamedView[]): void;
+    /** Re-ask `isLightTheme()` after a theme change. */
+    applyTheme(): void;
+}
+
+/**
+ * Everything the viewer needs from whatever is embedding it. Install as
+ * `window.gdsLensHost` before the element script runs.
+ *
+ * Every method is optional: a missing one is not an error, it means the
+ * embedder does not offer that service, and the viewer removes the control
+ * for it. A read-only embed can implement almost none of this.
+ */
+export interface ViewerHost {
+    /** `null` means the user cancelled. */
+    pickLyp?(): Promise<PickedFile | null> | PickedFile | null;
+    unloadLyp?(): void;
+    pickMarkers?(): Promise<PickedFile | null> | PickedFile | null;
+    unloadMarkers?(): void;
+    /** Called once at mount, for saved camera positions. */
+    loadViews?(): Promise<NamedView[]> | NamedView[];
+    saveViews?(views: NamedView[]): void;
+    /** `existing` is the names already in use; `null` means cancelled. */
+    promptViewName?(existing: string[]): Promise<string | null> | string | null;
+    requestReload?(): void;
+    setAutoReload?(on: boolean): void;
+    onGotoResult?(result: GotoResult): void;
+    /** Defaults to the OS preference when not implemented. */
+    isLightTheme?(): boolean;
+    /** Override where the payload's scripts cannot be fetched by URL. */
+    createWorker?(): Worker;
+    /** Called at mount, handing over the push-direction surface. */
+    connect?(viewer: ViewerSurface): void;
+}
+
+/** Accepted by `load`: a URL to fetch, or bytes you already have. */
+export type LayoutSource = string | Uint8Array | ArrayBuffer;
+
+/**
+ * The `<gds-lens>` element. Importing `gds-lens` registers it; the engine,
+ * the wasm module and the WebGL context are all deferred until an element
+ * actually connects.
+ *
+ * `display: block` with no intrinsic height, so give it one.
+ */
+export declare class GdsLens extends HTMLElement {
+    /**
+     * Resolves once the engine has mounted. Every method below awaits this,
+     * so it is rarely needed directly. Rejects if the element is not
+     * connected.
+     */
+    readonly ready: Promise<ViewerSurface>;
+
+    /** `options.reload` keeps the current camera and layer visibility. */
+    load(source: LayoutSource, options?: { reload?: boolean }): Promise<void>;
+
+    /**
+     * Centres on a coordinate in microns and flashes a crosshair. Resolves
+     * `true` if the point is inside the layout.
+     */
+    goToPoint(x: number, y: number): Promise<boolean>;
+
+    /** Applies a `.lyp` layer-properties file. Pass `""` to clear. */
+    setLyp(name: string, text: string): Promise<void>;
+
+    /** Applies a marker database; the format is sniffed from the content. */
+    setMarkers(name: string, text: string): Promise<void>;
+
+    /** Replaces the view with an error message. */
+    showError(message: string): Promise<void>;
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "gds-lens": GdsLens;
+    }
+    interface Window {
+        /** Install before the element script runs to replace the default host. */
+        gdsLensHost?: ViewerHost;
+        /**
+         * Published by the default browser host (not by the element), so a
+         * plain page can drive the viewer from a script tag or the console.
+         */
+        gdsLens?: ViewerSurface;
+    }
+}

package/types/hosts-browser.d.ts

@@ -0,0 +1,13 @@
+// `gds-lens/hosts/browser` -- the default ViewerHost, for a plain web page.
+
+import type { ViewerHost } from "./gds-lens.js";
+
+/**
+ * A host implemented for an ordinary page: `<input type=file>` for the
+ * pickers, `localStorage` for saved views, `prompt()` for a name, and three
+ * ways in for a layout -- `?src=`, drag-and-drop on the element, and a direct
+ * call through `window.gdsLens`.
+ *
+ * Installs itself as `window.gdsLensHost` on import if nothing else has.
+ */
+export function createBrowserHost(): ViewerHost;

package/types/layout-bytes.d.ts

@@ -0,0 +1,49 @@
+// `gds-lens/layout-bytes` -- gzip in front of the parser.
+//
+// The result is a discriminated union rather than a throw: "too large for
+// this machine" and "the file is broken" need different things said about
+// them, and the caller is the one with the wording.
+
+export interface DecodedLayout {
+    ok: true;
+    bytes: Uint8Array;
+    gzipped: boolean;
+    /** gzip's ISIZE trailer, or `null` when the input was too short. */
+    storedSize: number | null;
+}
+
+export interface FailedLayout {
+    ok: false;
+    /** `"too-large"` is this machine's limit; `"corrupt"` is the file's. */
+    reason: "too-large" | "corrupt";
+    storedSize: number | null;
+    /** The cap that was enforced, so a message can quote it. */
+    limit: number;
+    detail: string;
+}
+
+/** gzip's magic number (RFC 1952 ID1/ID2). Content, not extension. */
+export function looksGzipped(bytes: Uint8Array | null | undefined): boolean;
+
+/**
+ * The uncompressed size gzip records in its trailer, or `null` if the input is
+ * too short to hold one.
+ *
+ * A hint about the file rather than a fact about it: it is stored modulo 2^32,
+ * and for a multi-member file it describes only the last member. Never use it
+ * to enforce a limit -- `decodeLayoutBytes` counts actual output instead.
+ */
+export function gzipStoredSize(bytes: Uint8Array | null | undefined): number | null;
+
+/**
+ * Uncompressed layout bytes, whatever the input was. Non-gzipped input is
+ * passed straight back, untouched and uncopied.
+ *
+ * `maxBytes` caps what a compressed file is allowed to expand to, enforced
+ * against the running output total rather than the trailer's claim, so a
+ * decompression bomb stops at the cap. Pass a non-finite value for no cap.
+ */
+export function decodeLayoutBytes(
+    bytes: Uint8Array,
+    maxBytes?: number,
+): Promise<DecodedLayout | FailedLayout>;

package/types/load-errors.d.ts

@@ -0,0 +1,27 @@
+// `gds-lens/load-errors` -- turning engine-level failures into text a layout
+// engineer can act on.
+
+/**
+ * A human-readable explanation of a load failure.
+ *
+ * Running out of room in the 32-bit wasm heap surfaces as one of a handful of
+ * unhelpful strings depending on which allocation happened to fail; they all
+ * mean the same thing, and all get the same explanation. `prefix` labels
+ * anything else with where it came from, and is ignored for out-of-memory,
+ * since that is about the layout rather than the component that noticed.
+ */
+export function describeLoadFailure(err: unknown, prefix?: string): string;
+
+/** Whether a failure is the wasm heap running out, however it surfaced. */
+export function isOutOfMemory(err: unknown): boolean;
+
+/**
+ * Wording for a failed gzip expansion -- the `{ ok: false }` result from
+ * `decodeLayoutBytes`. Returns `""` for a successful one.
+ *
+ * The two reasons get different prose: `"too-large"` is about this machine's
+ * limit, `"corrupt"` about the file being truncated or half-written.
+ */
+export function describeDecodeFailure(
+    result: { ok: boolean; reason?: string; storedSize?: number | null; limit?: number; detail?: string },
+): string;

package/types/parsers.d.ts

@@ -0,0 +1,84 @@
+// `gds-lens/parsers` -- DRC/LVS marker databases, normalized.
+//
+// Pure JavaScript: no DOM, no WebAssembly. The XML parser is passed in as a
+// constructor argument rather than imported, so this runs in Node (with
+// @xmldom/xmldom) and in a browser (with the built-in DOMParser) unchanged.
+
+/** A `DOMParser` constructor -- the platform's, or @xmldom/xmldom's. */
+export type DOMParserConstructor = new () => {
+    parseFromString(text: string, type: string): Document;
+};
+
+export interface MarkerBBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+
+/**
+ * One marker. Coordinates are in µm, y-up world space.
+ *
+ * Items with no geometry (float or text values) keep the raw value in `note`,
+ * have `bbox === null`, and draw nothing.
+ */
+export interface MarkerItem {
+    /** Globally unique; equals the index in category-major order. */
+    id: number;
+    /** Short label for the list row. */
+    label: string;
+    /** Non-geometry values, multiplicity, cell reference. */
+    note: string;
+    /** One packed `(x, y, ...)` array per ring. */
+    polygons: Float64Array[];
+    /** Packed segments: `(x0, y0, x1, y1, ...)`. */
+    edges: Float64Array;
+    /** `null` when the item has no geometry. */
+    bbox: MarkerBBox | null;
+    /** True for a `WE<n>` waiver record. */
+    waived: boolean;
+}
+
+export interface MarkerCategory {
+    /** Full path; `.`-joined for lyrdb nesting. */
+    name: string;
+    description: string;
+    items: MarkerItem[];
+}
+
+/** The normalized model both parsers emit. */
+export interface MarkerModel {
+    /** `""` when the file does not say. */
+    topCell: string;
+    warnings: string[];
+    categories: MarkerCategory[];
+}
+
+/** Geometry repacked per item id, ready to hand to the renderer. */
+export interface FlatMarkerModel {
+    categories: MarkerCategory[];
+    itemCategory: Int32Array;
+    itemBBoxes: Float64Array;
+    polyVerts: Float64Array;
+    polyVertCounts: Int32Array;
+    polyItemIds: Int32Array;
+    edgeVerts: Float64Array;
+    edgeItemIds: Int32Array;
+}
+
+/** Decided by content, not by extension. `null` when unrecognized. */
+export function sniffMarkerFormat(text: string): "lyrdb" | "drc" | null;
+
+/** Parses a whitespace-separated coordinate list into a packed array. */
+export function parsePointList(text: string): Float64Array;
+
+/** Parses a KLayout `.lyrdb` report database. Throws if it is not one. */
+export function parseLyrdb(text: string, DOMParserCtor: DOMParserConstructor): MarkerModel;
+
+/** Parses an ASCII DRC results database. */
+export function parseDrcAscii(text: string): MarkerModel;
+
+/** Dispatches on `sniffMarkerFormat`. Throws on an unrecognized format. */
+export function parseMarkerFile(text: string, DOMParserCtor: DOMParserConstructor): MarkerModel;
+
+export function flattenMarkerModel(model: MarkerModel): FlatMarkerModel;