Metadata-Version: 2.4
Name: kwasm
Version: 0.3.1
Summary: Standalone web-based layout viewer using KLayout
License-Expression: GPL-3.0
Requires-Python: ~=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Dynamic: license-file

# kwasm

A standalone KLayout-powered GDS viewer with 2D and 3D views.

The product is one self-contained JavaScript file: UI, styles, icons, Three.js,
and one Rust/KLayout WebAssembly runtime. Mount it in a DOM element or an iframe;
interact through versioned JSON messages. No React implementation is included.
The protocol can export the edited in-memory design back to base64 GDS.
Use `resetProject: true` on `loadGds` when replacing it with an unrelated design;
ordinary same-project reloads retain companion configuration and camera state.

This checkout contains an unreleased breaking refactor. The examples below describe
the new interface, not necessarily the currently deployed CDN/PyPI release.

## Browser

Build or download the matching `kwasm-VERSION.js` and serve it locally or on a CDN:

```html
<div id="viewer" style="height:600px"></div>
<script src="./kwasm-0.2.26.js"></script>
<script>
  const viewer = Kwasm.mount(document.getElementById("viewer"), { viewerId: "layout" });
  viewer.ready.then(() => {
    window.postMessage(
      {
        type: "kwasm:request",
        version: 2,
        viewerId: "layout",
        requestId: "load-1",
        action: "loadGds",
        gds: "YOUR_BASE64_GDS",
      },
      window.origin === "null" ? "*" : window.origin,
    );
  });
  // Call viewer.destroy() when removing it.
</script>
```

Initial data can also be embedded with `mount(element,{gds,lyp,layerstack})`.
3D requires a layerstack and uses the same loaded design, active cell and layer
visibility as 2D. One viewer per page is supported.

The native runtime runs in one embedded worker so long KLayout operations do not
block the surrounding page. No extra runtime file is fetched. A restrictive CSP
must permit `worker-src data:` as well as WebAssembly compilation; see the public
interface for a complete policy example.

[Complete public interface and examples](specs/protocol.md): all mount options,
messages, responses, events, origins, drawing/routing flow, Python APIs, and limits.
There are no viewer URL parameters.

## Python

```python
import kwasm

kwasm.bundle("design.gds", output="design.html", layerstack="stack.json")
kwasm.show("design.gds", interactive=True, layerstack="stack.json")
```

The wheel ships the same JS file. Offline HTML is the default reference integration.
Pass `script_url=kwasm.CDN_URL` to fetch the versioned viewer at runtime after the
corresponding release is deployed, or use your own hosting URL.

```sh
kwasm bundle design.gds --lyp layers.lyp --layerstack stack.json --output design.html
kwasm view design.gds
kwasm export-layerstack your_pdk.module --output stack.json
```

## Development

Install Rust (pinned toolchain), Emscripten **6.0.4**, Node 22+, uv and just.
Initialize the KLayout/Expat submodules and activate Emscripten on PATH.

```sh
git submodule update --init --recursive
npm ci
just build             # one Rust binary + dist/kwasm-VERSION.js
just dev               # copy identical JS into Python package
just test              # Python, pure Rust and JS unit tests
npx playwright install chromium
just test-js-browser   # actual built artifact, both views and embedding modes
just wheel
```

[Developing and architecture](DEVELOPING.md) ·
[Feature boundaries and invariants](specs/architecture.md) ·
[Refactor decisions and acceptance](specs/refactor.md)

## License

GPL-3.0; see [LICENSE](LICENSE). KLayout is not replaced or relicensed by this
refactor. Bundled third-party components retain their own licenses, including
Three.js (MIT) and Font Awesome Free. A CDN or postMessage transport does not
itself determine the license obligations of a consuming application.
