Metadata-Version: 2.4
Name: kwasm
Version: 0.2.20
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

Standalone wasm-based client-only layout viewer for semiconductor designs, powered by
[KLayout](https://www.klayout.org).

kwasm compiles KLayout's layout rendering engine to WebAssembly via Emscripten, wrapped
in a Rust FFI layer. The result is an interactive GDS2/OASIS viewer that runs entirely
in the browser — no install required.

## Features

- View GDS2 and OASIS layout files in the browser
- Pan, zoom, select, measure, and draw annotations
- Layer panel with per-layer visibility toggling and color display
- Toolbar with switchable interaction modes
- Dark and light theme
- Load layouts via drag & drop or `?url=` query parameter
- Configurable toolbar via `?tools=` query parameter
- Python package with embeddable Jupyter viewer
- CLI for bundling layouts into self-contained HTML files

## Quick Start

```bash
# Build all WASM artifacts
just build

# Build docs site and serve at http://localhost:8080
just serve
```

## Available Commands

| Command                    | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `just build [mode]`        | Build WASM artifacts (`all` by default)                |
| `just dev [mode]`          | Copy bundled HTML from `dist/` into the Python package |
| `just wheel`               | Build Python wheel                                     |
| `just dist`                | Build everything (WASM + wheel)                        |
| `just check [mode]`        | Check WASM compilation (no link)                       |
| `just docs [mode]`         | Build versioned documentation pages in `site/`         |
| `just serve [mode] [port]` | Build docs and serve                                   |
| `just clean`               | Clean build artifacts                                  |

## Query Parameters

| Parameter  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `?url=`    | Load a layout file from a URL (e.g. `?url=https://example.com/chip.gds`)       |
| `?tools=`  | Comma-separated list of toolbar tools to show. All tools are shown by default. |
| `?lyp=`    | Load a .lyp layer properties file from a URL (e.g. `?lyp=layers.lyp`)          |
| `?drop=`   | Enable/disable drag & drop (`true`/`false`). Default: `true`.                  |
| `?layers=` | Show/hide the layer panel (`true`/`false`). Default: `true`.                   |

Available tool names for `?tools=`:

| Name             | Description                   |
| ---------------- | ----------------------------- |
| `select`         | Pointer/select mode           |
| `move`           | Pan mode                      |
| `ruler`          | Ruler/measure mode            |
| `draw-polyline`  | Draw polyline annotations     |
| `draw-manhattan` | Draw manhattan route          |
| `draw-freehand`  | Draw freehand annotations     |
| `clear-all`      | Erase all annotations         |
| `fit-all`        | Zoom to fit layout            |
| `reload`         | Reload layout                 |
| `top-ports`      | Toggle top-level port markers |
| `instance-ports` | Toggle instance port markers  |
| `dangling-ports` | Toggle dangling port markers  |
| `text`           | Toggle text labels            |
| `theme`          | Light/dark mode toggle        |

Example: `?tools=ruler,top-ports,instance-ports` shows only the ruler, top-level ports, and instance ports buttons.

## Python Package

kwasm is available as a Python package that bundles the WASM viewer:

```bash
pip install kwasm
```

### Jupyter Notebook

```python
import kwasm

kwasm.show("my_chip.gds")
kwasm.show("my_chip.gds", lyp="layers.lyp", tools=("ruler", "fit-all"))
```

When used with [gdsfactory](https://github.com/gdsfactory/gdsfactory), you can pass components directly:

```python
import gdsfactory as gf
import kwasm

c = gf.components.mzi()
kwasm.show(c)
```

### CLI

```bash
# Bundle a GDS into a self-contained HTML file
kwasm bundle my_chip.gds --output viewer.html --lyp layers.lyp

# Bundle and open in the default browser
kwasm view my_chip.gds
```

## License

[GPL-3.0](LICENSE)

## JavaScript Workspace (`@gdsfactory/kwasm` npm package)

The repo is an npm workspace; the publishable React library lives under `packages/kwasm/` and the example Vite app under `packages/example/`.

### Engines

- Node `>=22.14`
- npm `>=11.5.1`

### Layout

```
packages/
  kwasm/         # @gdsfactory/kwasm — publishable Vite library
  example/       # Vite example app (private, not published)
```

### Common commands

| Command          | What it does                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `npm install`    | Install root + workspace dev dependencies; refresh `package-lock.json`                                                     |
| `npm run dev`    | Start the example app's Vite dev server (HMR; library changes reflect via workspace symlink — Phase 5 wires the full demo) |
| `npm run build`  | Run `vite build` in every workspace package that defines a `build` script                                                  |
| `npm test`       | Run Vitest in every workspace package that defines `test`                                                                  |
| `npm run lint`   | ESLint over `packages/**/*.{ts,tsx}`                                                                                       |
| `npm run format` | Prettier over the workspace                                                                                                |
| `npm run ci`     | Lint + format check + build + test (used by `.github/workflows/ci.yml`)                                                    |

### WASM artifacts

The `packages/kwasm/wasm/` directory holds the modular ESM glue + gzipped WASM bytes consumed by the lib at consumer build time. It is **populated by** `just build js-lib` (added in Phase 1). The bundled-HTML pipeline (`just build all`) is unchanged.

### Tooling

- TypeScript strict; `target: ES2022`, `jsx: react-jsx`; no `paths` aliases in `packages/kwasm/src/` (would leak into emitted `.d.ts`).
- ESLint 10 flat config (`typescript-eslint`, `react-hooks`, `jsx-a11y`, `eslint-config-prettier`).
- Prettier 3.
- Pre-commit via `prek` (project convention — never `pre-commit`).
- Vitest 4 with `unit` (happy-dom) and `browser` (Playwright + Chromium) projects.

### Supported consumer bundlers (v1)

**Vite only.** Next.js / Webpack / Rspack / esbuild are explicitly out of scope for v1 (locked in Phase 1 discussion, 2026-04-25). Other bundlers may work but are not validated in CI.
