gds-lens 0.1.0

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "gds-lens",
+  "version": "0.1.0",
+  "description": "GDSII & OASIS layout parsing and WebGL2 rendering for the browser",
+  "license": "MIT",
+  "author": "Ethan Lowenthal",
+  "keywords": [
+    "gdsii",
+    "gds",
+    "oasis",
+    "oas",
+    "layout",
+    "layout-viewer",
+    "webgl",
+    "wasm",
+    "lyp",
+    "vlsi",
+    "eda",
+    "ic-layout",
+    "chip-design",
+    "semiconductor",
+    "photonics",
+    "drc",
+    "lvs",
+    "lyrdb"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EthanLowenthal/GDS-Lens"
+  },
+  "homepage": "https://github.com/EthanLowenthal/GDS-Lens#readme",
+  "bugs": {
+    "url": "https://github.com/EthanLowenthal/GDS-Lens/issues"
+  },
+  "scripts": {
+    "build:wasm": "npm run build:wasm:web && npm run build:wasm:inline && npm run build:wasm:esm",
+    "build:wasm:web": "emcmake cmake -S src/wasm -B src/wasm/build/web -DGDS_LENS_INLINE_WASM=OFF && cmake --build src/wasm/build/web",
+    "build:wasm:inline": "emcmake cmake -S src/wasm -B src/wasm/build/inline -DGDS_LENS_INLINE_WASM=ON && cmake --build src/wasm/build/inline",
+    "build": "node scripts/build-webview.mjs",
+    "watch": "node scripts/build-webview.mjs --watch",
+    "test": "node --test test/*.test.js",
+    "lint": "eslint .",
+    "check:dist": "node scripts/check-dist.mjs",
+    "check:types": "tsc --noEmit -p test/types/tsconfig.json",
+    "prepublishOnly": "npm run lint && npm test && npm run check:dist && npm run check:package",
+    "check:package": "node scripts/check-package.mjs",
+    "build:wasm:esm": "emcmake cmake -S src/wasm -B src/wasm/build/esm -DGDS_LENS_ESM=ON && cmake --build src/wasm/build/esm"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@xmldom/xmldom": "^0.9.10",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.5.0",
+    "globals": "^17.11.0",
+    "lil-gui": "^0.21.0",
+    "playwright": "^1.62.1",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "types/",
+    "dist/",
+    "src/",
+    "!src/wasm",
+    "LICENCE.md",
+    "THIRD-PARTY-LICENSES.md",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "types": "./types/gds-lens.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/gds-lens.d.ts",
+      "default": "./dist/esm/gds-lens.js"
+    },
+    "./parsers": {
+      "types": "./types/parsers.d.ts",
+      "default": "./src/marker-parsers.js"
+    },
+    "./cell-search": {
+      "types": "./types/cell-search.d.ts",
+      "default": "./src/cell-search.js"
+    },
+    "./coord-parse": {
+      "types": "./types/coord-parse.d.ts",
+      "default": "./src/coord-parse.js"
+    },
+    "./layout-bytes": {
+      "types": "./types/layout-bytes.d.ts",
+      "default": "./src/layout-bytes.js"
+    },
+    "./load-errors": {
+      "types": "./types/load-errors.d.ts",
+      "default": "./src/load-errors.js"
+    },
+    "./hosts/browser": {
+      "types": "./types/hosts-browser.d.ts",
+      "default": "./src/hosts/browser.js"
+    },
+    "./web/*": "./dist/web/*",
+    "./inline-wasm/*": "./dist/inline-wasm/*",
+    "./package.json": "./package.json",
+    "./esm/*": "./dist/esm/*"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": [
+    "./dist/esm/gds-lens.js",
+    "./src/gds-lens.js",
+    "./dist/**"
+  ]
+}

package/src/cell-search.js

@@ -0,0 +1,88 @@
+// Searching the cell hierarchy: which cells a typed name matches, and how the
+// tree gets down to one of them. This is a standalone script (no imports)
+// loaded two ways, following the same pattern as marker-parsers.js and
+// load-errors.js: the webview pulls it in via a <script> tag, and Node unit
+// tests require() it via the module.exports tail.
+//
+// Both functions work on the hierarchy model parseGdsToLayers hands back (see
+// build_hierarchy in wasm/renderer.cpp): a flat `cells` array of
+// {name, polygons, labels, bbox, refs} where each ref is {cell, count, ...},
+// plus the indices of the top-level cells. Nothing here touches the DOM or the
+// wasm module -- the panel work is in viewer.js.
+
+// Indices of every cell whose name contains `query`, case-insensitively, best
+// match first: the exact name, then names that start with the query, then the
+// rest. Ordering matters because the panel only builds the first couple of
+// hundred rows -- typing a cell's full name should not leave it below thirty
+// cells that merely contain it.
+function rankCellMatches(cells, query) {
+    const needle = String(query).trim().toLowerCase();
+    if (!needle) return [];
+
+    const exact = [];
+    const prefix = [];
+    const rest = [];
+    for (let i = 0; i < cells.length; i++) {
+        const name = cells[i] && typeof cells[i].name === "string" ? cells[i].name : "";
+        const at = name.toLowerCase().indexOf(needle);
+        if (at < 0) continue;
+        // at >= 0 with equal lengths *is* an exact match -- the needle can only
+        // have been found at 0.
+        if (name.length === needle.length) exact.push(i);
+        else if (at === 0) prefix.push(i);
+        else rest.push(i);
+    }
+    return exact.concat(prefix, rest);
+}
+
+// One path of cell indices from a top cell down to `target`, starting at the
+// root and ending at the target itself -- or null if no top cell reaches it
+// (a reference cycle among non-top cells, or a cell the tree's own caps left
+// out of `roots`).
+//
+// Depth-first, so it's *a* path rather than the shortest one: a cell placed in
+// twenty places has twenty paths to it and none is more correct than another,
+// so the first one found is as good an answer as any -- and it's the one the
+// tree reads down to in the order the file placed things.
+//
+// `failed` is what keeps this cheap on a real library. References form a DAG,
+// so without remembering the subtrees that turned out not to contain the
+// target, a design that shares cells widely would re-walk the same ones once
+// per path leading into them. `maxDepth` bounds the recursion, which is what
+// makes a malformed file that closes a reference loop terminate: a cycle's
+// cells are pushed until the limit, then unwound and marked failed.
+function cellPathToTarget(cells, roots, target, maxDepth) {
+    if (!cells || !cells[target]) return null;
+    const limit = maxDepth > 0 ? maxDepth : 1;
+    const failed = new Set();
+    const path = [];
+
+    function walk(index, depth) {
+        path.push(index);
+        if (index === target) return true;
+        // Not "already on the path": `failed` also covers it, since a cell is
+        // only marked once its own walk has come back empty.
+        if (depth + 1 < limit && !failed.has(index)) {
+            const refs = (cells[index] && cells[index].refs) || [];
+            for (const ref of refs) {
+                if (!cells[ref.cell]) continue;
+                if (walk(ref.cell, depth + 1)) return true;
+            }
+        }
+        path.pop();
+        failed.add(index);
+        return false;
+    }
+
+    for (const root of (roots || [])) {
+        if (!cells[root]) continue;
+        if (walk(root, 0)) return path;
+        // walk() unwinds its own pushes on failure, but a root that failed at
+        // depth 0 leaves nothing to unwind -- clear anyway rather than trusting
+        // that from out here.
+        path.length = 0;
+    }
+    return null;
+}
+
+export { rankCellMatches, cellPathToTarget };

package/src/coord-parse.js

@@ -0,0 +1,50 @@
+// Reads a coordinate pair out of whatever text a layout engineer happens to
+// have on the clipboard. Coordinates arrive from outside the viewer all day --
+// a DRC report, a colleague's message, a generator's log -- and each source
+// wraps them differently.
+//
+// This is a standalone script (no imports) following the same pattern as
+// load-errors.js and marker-parsers.js, so it can be require()d from both the
+// extension host (the "Go to Coordinate" command's input box validates with it)
+// and Node unit tests. The webview doesn't need it: the host sends the parsed
+// numbers, not the typed string.
+//
+// The accepted forms are whatever those sources actually produce, which is
+// "x, y" with any of the usual decorations: parentheses, a semicolon or bare
+// whitespace as the separator, and an optional per-number unit. Microns are the
+// default because that's what the readout, the ruler and the .lyrdb files all
+// speak.
+const COORD_UNITS = {
+    nm: 1e-3,
+    um: 1,
+    "µm": 1,  // MICRO SIGN
+    "μm": 1,  // GREEK SMALL LETTER MU -- both are in the wild
+    mm: 1e3
+};
+// One number plus an optional unit; the parse takes the first two matches and
+// requires the rest of the string to be separators, so "1 2 3" is rejected
+// rather than silently read as "1 2".
+const COORD_TOKEN = /(-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*(nm|um|µm|μm|mm)?/gi;
+// What may surround the two numbers -- punctuation, plus a bare x/y label,
+// since "x=12.5, y=40" is a shape real reports print. Anything else means the
+// string wasn't a coordinate pair, so it's rejected rather than half-read.
+const COORD_FILLER = /^[\s(),;:=xy]*$/i;
+
+// Returns {x, y} in microns, or null if the text isn't a coordinate pair.
+function parseCoordinatePair(text) {
+    const numbers = [];
+    let start = 0;
+    let end = 0;
+    COORD_TOKEN.lastIndex = 0;
+    for (let match = COORD_TOKEN.exec(text); match; match = COORD_TOKEN.exec(text)) {
+        numbers.push(parseFloat(match[1]) * (match[2] ? COORD_UNITS[match[2].toLowerCase()] : 1));
+        if (numbers.length === 1) start = match.index;
+        end = COORD_TOKEN.lastIndex;
+        if (numbers.length === 2) break;
+    }
+    if (numbers.length !== 2 || !numbers.every(Number.isFinite)) return null;
+    if (!COORD_FILLER.test(text.slice(0, start)) || !COORD_FILLER.test(text.slice(end))) return null;
+    return { x: numbers[0], y: numbers[1] };
+}
+
+export { parseCoordinatePair };

package/src/engine-source.esm.js

@@ -0,0 +1,49 @@
+// The bundled ESM build's answer to "where does the engine come from": inlined
+// text, because there is nothing beside a bundled module to fetch.
+//
+// Both the main thread and the parse Worker need Emscripten's module, and a
+// Worker cannot share the main thread's copy -- it is a separate script
+// context. Inlining it twice would put the ~400KB binary in the bundle twice,
+// so it is inlined *once* as text and turned into a blob: URL that both sides
+// load. That is why the main thread imports through a blob rather than
+// importing gds-lens-engine.mjs directly.
+//
+// Both loads therefore need `blob:` in the page's CSP -- script-src for the
+// main thread, worker-src for the Worker. The served payloads do not (only
+// worker-src), which is the one thing this build asks for that they do not.
+//
+// The text import is aliased by scripts/build-webview.mjs to the built
+// gds-lens-engine.mjs; the worker half arrives as a define.
+import gdstkSource from "gds-lens:gdstk-source";
+
+// Substituted by scripts/build-webview.mjs: the bundled wasm-worker.js as a
+// string. A define rather than an import because it is built in an earlier
+// pass and never written to disk.
+const workerSource = __GDS_LENS_WORKER_SOURCE__;
+
+// One object URL, made on first use and kept: revoking it would break the
+// Worker, which loads from the same URL, and a second blob would be a second
+// copy of half a megabyte in memory.
+let moduleUrl = null;
+function gdstkModuleUrl() {
+    if (!moduleUrl) {
+        moduleUrl = URL.createObjectURL(new Blob([gdstkSource], { type: "text/javascript" }));
+    }
+    return moduleUrl;
+}
+
+export async function loadGdstkFactory() {
+    // A dynamic import, not an eval: no 'unsafe-eval' is needed, which is what
+    // keeps -sDYNAMIC_EXECUTION=0 worth having.
+    const module = await import(/* @vite-ignore */ gdstkModuleUrl());
+    return module.default;
+}
+
+// Emscripten's ES module output uses import.meta.url, so this has to be loaded
+// as a *module* Worker -- a classic one fails to parse. The factory is a
+// top-level declaration in gdstkSource, so the worker half below simply sees
+// it in scope once the two are concatenated.
+export const workerBundle = {
+    type: "module",
+    text: () => `${gdstkSource}\n${workerSource}`,
+};

package/src/engine-source.js

@@ -0,0 +1,20 @@
+// Where the wasm factory and the parse Worker's script come from.
+//
+// This is the default: the served payloads (dist/web, dist/inline-wasm) load
+// Emscripten's output as a classic <script> before the bundle, so the factory
+// is already a global (from gds-lens-engine.js) and the Worker can fetch the
+// same scripts by URL.
+//
+// The bundled ESM build swaps this file for engine-source.esm.js, which
+// carries both as inlined text instead (see scripts/build-webview.mjs). Every
+// difference between "a payload you serve" and "a module you import" is in
+// these two files, so nothing else has to know which one it is running in.
+
+// Emscripten's MODULARIZE output defines this on the global object.
+export function loadGdstkFactory() {
+    return Promise.resolve(globalThis.createGdstkModule);
+}
+
+// Null means "no inlined script": viewer.js builds the Worker from
+// document-relative URLs instead. See createParseWorker.
+export const workerBundle = null;

package/src/gds-lens.js

@@ -0,0 +1,175 @@
+// The <gds-lens> custom element: the package's entry point.
+//
+// Kept apart from viewer.js so that importing this module only *registers* the
+// element. The engine, the wasm module and the WebGL context are all deferred
+// until an element actually connects, which is what makes this a component
+// someone can import into an app rather than a script that takes over the page
+// on load.
+
+import { setMountTarget } from "./mount-target.js";
+
+// True only in the inline-wasm payload, where gds-lens-engine.js carries the ~400KB
+// wasm binary inline as a raw string -- 66,000-odd non-ASCII bytes. A <script
+// src> with no charset of its own is decoded using the *document's* encoding,
+// so on a page that does not declare UTF-8 those bytes are mangled and the
+// module fails with "WebAssembly.instantiate(): section was shorter than
+// expected size" -- an error that says nothing whatsoever about the encoding
+// that caused it. Say so plainly instead of letting someone lose an afternoon
+// to it.
+//
+// esbuild substitutes this per payload (see scripts/build-webview.mjs), so the
+// warning stays silent in the default build, where the binary is a separate
+// file and the page's encoding is nobody's business. The typeof guard is for
+// running from source through the package's exports map, where nothing has
+// defined it and it should warn.
+const INLINE_WASM = typeof __GDS_LENS_INLINE_WASM__ === "undefined" || __GDS_LENS_INLINE_WASM__;
+
+function warnIfNotUtf8() {
+    if (!INLINE_WASM) return;
+    const encoding = document.characterSet || document.charset;
+    if (encoding && encoding.toUpperCase() !== "UTF-8") {
+        console.error(
+            `[GDS] this document is ${encoding}, not UTF-8. This build of gds-lens ` +
+            "embeds its WebAssembly binary in a script that must be decoded as " +
+            'UTF-8; it will fail to load. Add <meta charset="UTF-8"> to the page, ' +
+            "serve the scripts as text/javascript; charset=utf-8, or use the " +
+            "default build, which keeps the binary in a separate file."
+        );
+    }
+}
+
+// One viewer at a time. renderer.cpp holds its state (GL program, VAO, uniform
+// locations, camera, layer table) in file-scope globals, so two live elements
+// cannot share the module and would silently fight over the same state.
+// Refusing the second with a visible message is the honest failure until that
+// state is threaded through a context.
+//
+// "At a time" rather than "per page load", though: the element that holds the
+// claim gives it up when it leaves the DOM, and the next one to connect gets
+// the existing engine moved into it. Without that, a framework re-render or an
+// SPA route change -- anything that recreates the node -- left every
+// subsequent <gds-lens> permanently refusing, since the engine's module body
+// had already run and could not run again.
+let mounted = null;
+
+// The loaded engine module, kept across mounts. Populated on the first mount
+// and never torn down: it owns the wasm instance and the GL context, and a
+// module body cannot be re-run.
+let engine = null;
+
+// Importing this module must not need a DOM. `import "gds-lens"` is the
+// documented entry point, and every SSR framework -- Next, Nuxt, Astro,
+// SvelteKit -- evaluates that import on the server first, where there is no
+// HTMLElement. A class declaration is evaluated at import time, so extending
+// it directly threw a ReferenceError before anything had even tried to use the
+// component. Extending a stub instead moves the failure to the only place it
+// can matter -- constructing an element, which nothing but a browser does --
+// and leaves the import a no-op on the server, which is what a consumer's
+// bundler and framework both expect of a custom element.
+const ElementBase = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
+
+export class GdsLens extends ElementBase {
+    #ready = null;
+
+    connectedCallback() {
+        if (mounted && mounted !== this) {
+            this.#refuse();
+            return;
+        }
+        // Moved in the DOM rather than recreated: this element still owns its
+        // own shadow tree, so there is nothing to redo.
+        if (this.#ready) {
+            mounted = this;
+            return;
+        }
+        mounted = this;
+        warnIfNotUtf8();
+        this.#ready = this.#mount();
+
+        // Deliberately after #ready is assigned, and deliberately not awaited
+        // inside #mount: load() waits on this.ready, so loading from within
+        // the promise that resolves it would wait on itself forever.
+        const src = this.getAttribute("src");
+        if (src) this.#ready.then(() => this.load(src));
+    }
+
+    async #mount() {
+        // Already running from an earlier element: move it here rather than
+        // building a second engine, which is not possible.
+        if (engine) {
+            engine.adopt(this);
+            return engine.viewer;
+        }
+        setMountTarget(this);
+        // Deferred on purpose: this is what pulls in the engine, instantiates
+        // the wasm module and creates the GL context.
+        engine = await import("./viewer.js");
+        return engine.viewer;
+    }
+
+    #refuse() {
+        console.error(
+            "[GDS] only one <gds-lens> can be active at a time: the renderer keeps " +
+            "its state in module-scope globals, so a second one would fight the first. " +
+            "Remove the first from the DOM and this one will take over its engine."
+        );
+        this.textContent = "Only one <gds-lens> is supported at a time.";
+    }
+
+    // Resolves once the engine has mounted, so callers can await readiness
+    // without racing the dynamic import.
+    get ready() {
+        return this.#ready || Promise.reject(new Error("<gds-lens> is not connected"));
+    }
+
+    // Accepts what a caller is likely to already have: a URL to fetch, or the
+    // bytes themselves in either of the two shapes they usually arrive in.
+    async load(source, options) {
+        const viewer = await this.ready;
+        if (typeof source === "string") {
+            const response = await fetch(source);
+            if (!response.ok) throw new Error(`${source}: HTTP ${response.status}`);
+            return viewer.load(new Uint8Array(await response.arrayBuffer()), options);
+        }
+        return viewer.load(source, options);
+    }
+
+    async goToPoint(x, y) {
+        return (await this.ready).goToPoint(x, y);
+    }
+
+    async setLyp(name, text) {
+        return (await this.ready).setLyp(name, text);
+    }
+
+    async setMarkers(name, text) {
+        return (await this.ready).setMarkers(name, text);
+    }
+
+    async showError(message) {
+        return (await this.ready).showError(message);
+    }
+
+    // Releases the claim without tearing anything down. The element is very
+    // often coming straight back -- React and friends recreate the node on
+    // re-render -- and discarding the wasm instance and GL context only to
+    // rebuild them a tick later would be far worse than holding them. The
+    // engine stays up; the next element to connect adopts it.
+    disconnectedCallback() {
+        if (mounted === this) mounted = null;
+    }
+
+    static get observedAttributes() {
+        return ["src"];
+    }
+
+    attributeChangedCallback(name, previous, current) {
+        if (name === "src" && current && current !== previous && this.#ready) {
+            this.load(current);
+        }
+    }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("gds-lens")) {
+    customElements.define("gds-lens", GdsLens);
+}

package/src/hosts/browser.js

@@ -0,0 +1,156 @@
+// The default ViewerHost: the services the viewer needs from whatever is
+// embedding it, implemented for a plain web page.
+//
+// The viewer itself knows nothing about VS Code, or about any other host. It
+// asks for a file, asks for a name, asks to be reloaded, and hands back state
+// to persist. Everything host-specific lives behind this interface, so a
+// second embedder only has to supply these methods rather than fork the
+// viewer.
+//
+// A host sets `window.gdsLensHost` before viewer.js runs to replace this one.
+// Every method here is optional: the viewer hides the control for anything a
+// host leaves out (a host with no pickLyp gets no "Load .lyp" row), so a
+// read-only embed can implement almost none of it.
+//
+//   pickLyp()            -> Promise<{name, text} | null>   null = cancelled
+//   unloadLyp()          -> void
+//   pickMarkers()        -> Promise<{name, text} | null>
+//   unloadMarkers()      -> void
+//   loadViews()          -> Promise<view[]>
+//   saveViews(views)     -> void
+//   promptViewName(existingNames) -> Promise<string | null>
+//   requestReload()      -> void
+//   setAutoReload(on)    -> void
+//   onGotoResult({ok, x, y}) -> void
+//   connect(viewer)      -> void   the viewer's own surface, for pushing in
+//
+// `connect` is how a host drives the viewer rather than answering it:
+//
+//   viewer.load(bytes, { reload })   viewer.showError(message)
+//   viewer.setLyp(name, text)        viewer.setMarkers(name, text)
+//   viewer.showStale(text)           viewer.goToPoint(x, y)
+//   viewer.toggleDebug()             viewer.element  (the mounted element)
+
+export function createBrowserHost() {
+    // Views are per-layout everywhere else; a plain page has no document
+    // identity to key on, so everything in one page shares a bucket. Wrapped
+    // because storage throws outright in some privacy modes rather than
+    // merely coming back empty.
+    const VIEWS_KEY = "gds-lens:named-views";
+    const readViews = () => {
+        try {
+            // Array-checked, not just parse-guarded: the catch only covers a
+            // throw, and `null` or `5` parse perfectly well while being
+            // nothing the caller can iterate.
+            const parsed = JSON.parse(localStorage.getItem(VIEWS_KEY) || "[]");
+            return Array.isArray(parsed) ? parsed : [];
+        } catch {
+            return [];
+        }
+    };
+
+    // One <input type=file> reused for both pickers: creating it lazily and
+    // leaving it detached keeps it out of the layout, and the click has to
+    // happen inside the user gesture that opened the picker or the browser
+    // discards it.
+    const pickText = (accept) => new Promise((resolve) => {
+        const input = document.createElement("input");
+        input.type = "file";
+        input.accept = accept;
+        input.addEventListener("change", () => {
+            const file = input.files && input.files[0];
+            if (!file) return resolve(null);
+            file.text().then(
+                (text) => resolve({ name: file.name, text }),
+                () => resolve(null)
+            );
+        });
+        // No "cancel" event fires reliably across browsers, so a dismissed
+        // dialog simply never resolves. That is fine here: the viewer treats
+        // a pick as pending until it answers, and nothing is blocked on it.
+        input.click();
+    });
+
+    return {
+        pickLyp: () => pickText(".lyp"),
+        pickMarkers: () => pickText(".lyrdb,.txt,.db"),
+        loadViews: async () => readViews(),
+        saveViews: (views) => {
+            try {
+                localStorage.setItem(VIEWS_KEY, JSON.stringify(views));
+            } catch {
+                // Full or blocked storage: the views stay live in this page,
+                // they just will not outlive it. Not worth interrupting for.
+            }
+        },
+        // A plain page has to be told which layout to show. Three ways in,
+        // covering the three situations a page is actually in: a URL for an
+        // embed, a drop for a scratch look at a local file, and a direct call
+        // for a page driving the viewer itself (or a test).
+        connect: (viewer) => {
+            // Published for a plain page (and the test suite) to drive the
+            // viewer from the console or a script tag. This is the default
+            // host's doing, not the element's: an embedder that replaces
+            // gds-lens-host.js gets no such global unless it sets one.
+            window.gdsLens = viewer;
+
+            const loadBytes = (bytes) => viewer.load(bytes, { reload: false });
+
+            const src = new URLSearchParams(location.search).get("src");
+            if (src) {
+                fetch(src)
+                    .then((response) => {
+                        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+                        return response.arrayBuffer();
+                    })
+                    .then((buffer) => loadBytes(new Uint8Array(buffer)))
+                    .catch((err) => viewer.showError(`Could not fetch ${src}: ${err.message || err}`));
+            }
+
+            // Bound to the viewer's own element, not to window. On window,
+            // the preventDefault below fires for every drag anywhere in the
+            // embedding page, which silently disables the host application's
+            // own drop targets -- a component has no business doing that. The
+            // fallback keeps a plain page working if the surface predates
+            // `element`.
+            // Both handlers are required: without preventDefault on dragover
+            // the browser navigates away to the dropped file instead of
+            // handing it over.
+            const bindDrop = (target) => {
+                if (!target) return;
+                target.addEventListener("dragover", (event) => event.preventDefault());
+                target.addEventListener("drop", (event) => {
+                    event.preventDefault();
+                    const file = event.dataTransfer && event.dataTransfer.files[0];
+                    if (!file) return;
+                    file.arrayBuffer().then(
+                        (buffer) => loadBytes(new Uint8Array(buffer)),
+                        (err) => viewer.showError(`Could not read ${file.name}: ${err.message || err}`)
+                    );
+                });
+            };
+
+            bindDrop(viewer.element || document.querySelector("gds-lens"));
+            // The viewer can move to a different element (a framework
+            // re-render recreates the node), which leaves the listeners above
+            // on something detached. Rebind on the new one.
+            if (typeof viewer.onAdopt === "function") viewer.onAdopt(bindDrop);
+        },
+
+        promptViewName: async (existingNames) => {
+            const name = window.prompt(
+                existingNames.length
+                    ? `Name this view (reusing a name replaces it):\n${existingNames.join(", ")}`
+                    : "Name this view:"
+            );
+            return name && name.trim() ? name.trim() : null;
+        }
+        // No requestReload / setAutoReload / onGotoResult: a plain page has no
+        // file on disk to watch and no command palette to answer. The viewer
+        // hides the stale-file banner when requestReload is missing.
+    };
+}
+
+if (typeof window !== "undefined" && !window.gdsLensHost) {
+    window.gdsLensHost = createBrowserHost();
+}