@mylasertools/kerfscript 0.2.1 → 0.3.0

package/dist/lexer.d.cts

@@ -3,7 +3,9 @@ export interface Pos {
     line: number;
     col: number;
     offset: number;
+    file?: string;
 }
+export declare const where: (pos: Pos, col?: boolean) => string;
 export interface Token {
     type: TokenType;
     value: string;
@@ -20,9 +22,10 @@ export declare class KerfError extends Error {
     col?: number;
     echoes: string[];
     missingFonts?: string[];
+    file?: string;
     constructor(message: string, pos?: Pos);
 }
-export declare function tokenize(src: string): {
+export declare function tokenize(src: string, file?: string): {
     tokens: Token[];
     comments: Comment[];
 };

package/dist/lexer.d.ts

@@ -3,7 +3,9 @@ export interface Pos {
     line: number;
     col: number;
     offset: number;
+    file?: string;
 }
+export declare const where: (pos: Pos, col?: boolean) => string;
 export interface Token {
     type: TokenType;
     value: string;
@@ -20,9 +22,10 @@ export declare class KerfError extends Error {
     col?: number;
     echoes: string[];
     missingFonts?: string[];
+    file?: string;
     constructor(message: string, pos?: Pos);
 }
-export declare function tokenize(src: string): {
+export declare function tokenize(src: string, file?: string): {
     tokens: Token[];
     comments: Comment[];
 };

package/dist/parser.d.cts

@@ -1,6 +1,6 @@
 import type { Program } from './ast.cjs';
 import { type Comment } from './lexer.cjs';
-export declare function parse(src: string): {
+export declare function parse(src: string, file?: string): {
     program: Program;
     comments: Comment[];
 };

package/dist/parser.d.ts

@@ -1,6 +1,6 @@
 import type { Program } from './ast.js';
 import { type Comment } from './lexer.js';
-export declare function parse(src: string): {
+export declare function parse(src: string, file?: string): {
     program: Program;
     comments: Comment[];
 };

package/dist/render.d.cts

@@ -2,7 +2,7 @@ import { type LayerDef, type Limits } from './evaluator.cjs';
 import { type LayerPath } from './export/svg.cjs';
 import { type Layer } from './geometry.cjs';
 import { type FontSource } from './text.cjs';
-import type { Value } from './values.cjs';
+import { type Value } from './values.cjs';
 export interface RenderOptions {
     params?: Record<string, Value>;
     fonts?: Record<string, FontSource>;

package/dist/render.d.ts

@@ -2,7 +2,7 @@ import { type LayerDef, type Limits } from './evaluator.js';
 import { type LayerPath } from './export/svg.js';
 import { type Layer } from './geometry.js';
 import { type FontSource } from './text.js';
-import type { Value } from './values.js';
+import { type Value } from './values.js';
 export interface RenderOptions {
     params?: Record<string, Value>;
     fonts?: Record<string, FontSource>;

package/dist/values.d.cts

@@ -16,10 +16,18 @@ export type Value = number | string | boolean | undefined | Value[] | Range | Cl
 export declare const isRange: (v: Value) => v is Range;
 export declare const isFn: (v: Value) => v is Closure;
 export declare const isNum: (v: Value) => v is number;
+export declare const own: <T>(o: Record<string, T> | undefined, key: string) => T | undefined;
+export declare function checkSetting(name: string, v: unknown, depth?: number): void;
 export declare function rangeValues(r: Range, limit: number): number[];
 export declare function truthy(v: Value): boolean;
-export declare function equals(a: Value, b: Value): boolean;
+export declare function equals(a: Value, b: Value, step?: () => void): boolean;
 export declare function typeName(v: Value): string;
+export declare function write(v: Value, max: number, quote?: boolean): {
+    text: string;
+    whole: boolean;
+};
+export declare function joinText(vs: Value[], sep: string, max: number): string | undefined;
 export declare function show(v: Value): string;
-export declare function str(v: Value): string;
+export declare const toText: (v: Value) => string;
+export declare function toNumber(v: Value): number;
 export declare function fmt(n: number): string;

package/dist/values.d.ts

@@ -16,10 +16,18 @@ export type Value = number | string | boolean | undefined | Value[] | Range | Cl
 export declare const isRange: (v: Value) => v is Range;
 export declare const isFn: (v: Value) => v is Closure;
 export declare const isNum: (v: Value) => v is number;
+export declare const own: <T>(o: Record<string, T> | undefined, key: string) => T | undefined;
+export declare function checkSetting(name: string, v: unknown, depth?: number): void;
 export declare function rangeValues(r: Range, limit: number): number[];
 export declare function truthy(v: Value): boolean;
-export declare function equals(a: Value, b: Value): boolean;
+export declare function equals(a: Value, b: Value, step?: () => void): boolean;
 export declare function typeName(v: Value): string;
+export declare function write(v: Value, max: number, quote?: boolean): {
+    text: string;
+    whole: boolean;
+};
+export declare function joinText(vs: Value[], sep: string, max: number): string | undefined;
 export declare function show(v: Value): string;
-export declare function str(v: Value): string;
+export declare const toText: (v: Value) => string;
+export declare function toNumber(v: Value): number;
 export declare function fmt(n: number): string;

package/dist/wasm.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/wasm.d.ts

@@ -0,0 +1 @@
+export {};

package/docs/cli.md

@@ -14,6 +14,30 @@ You can also run it through `npx`:
 npx @mylasertools/kerfscript render box.kerf -o box.svg
 ```
 
+## Without Node.js
+
+The [releases](https://github.com/mylasertools/kerfscript/releases) page has a
+standalone `kerf` for Windows, macOS and Linux (x64 and arm64) that needs no
+Node.js: `kerf-<version>-<os>-<arch>.zip` or `.tar.gz`, and
+`kerfscript-cli-<version>-linux-<arch>.deb` or `.rpm`. It has the
+Atkinson Hyperlegible font built in, like the npm package.
+
+| System           | Install                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| macOS, Linux     | `brew install mylasertools/tap/kerfscript`                                                                    |
+| Windows          | `winget install MyLaserTools.KerfScript.CLI`, or `choco install kerfscript`                                   |
+| Windows (Scoop)  | `scoop bucket add mylasertools https://github.com/mylasertools/scoop-bucket`, then `scoop install kerfscript` |
+| Linux (Snap)     | `sudo snap install kerfscript`; the command is `kerfscript.kerf`                                              |
+| Arch Linux (AUR) | `kerfscript-bin`                                                                                              |
+| macOS (MacPorts) | `sudo port install kerfscript`                                                                                |
+| Docker           | `docker run --rm -v "$PWD:/work" --user "$(id -u):$(id -g)" ghcr.io/mylasertools/kerfscript render box.kerf`  |
+
+Package manager listings follow each release as they are approved. The
+binaries are not signed yet. On macOS, Homebrew and MacPorts install them
+without a warning; a downloaded `kerf` needs
+`xattr -d com.apple.quarantine kerf` once. On Windows, SmartScreen may warn
+the first time.
+
 Save a `.kerf` file from the [models](https://kerfscript.mylasertools.com/models/)
 to try these commands.
 
@@ -31,21 +55,21 @@ reports parts, dimensions, cut lengths, sheets and warnings.
 
 ## Options
 
-| Option | Use |
-| --- | --- |
-| `-o, --out <file>` | Output path ending in `.svg`, `.dxf` or `.json`; defaults to `<file>.svg` |
-| `-D name=value` | Override a parameter; repeat for multiple values |
-| `-p, --params <file>` | Load parameter values from a JSON file |
-| `--font <file.ttf>` | Supply a font file; repeat for multiple fonts |
-| `--kerf <mm>` | Override kerf for every part |
-| `--sheet <W>x<H>` | Set the sheet width and height in millimetres |
-| `--gap <mm>` | Set spacing between parts |
-| `--margin <mm>` | Set spacing at sheet edges; defaults to the gap |
-| `--no-pack` | Keep the positions defined in the program |
-| `--guides` | Include the guide layer |
-| `--split` | Export one file per sheet |
-| `-h, --help` | Show command help |
-| `-v, --version` | Show version numbers |
+| Option                | Use                                                                       |
+| --------------------- | ------------------------------------------------------------------------- |
+| `-o, --out <file>`    | Output path ending in `.svg`, `.dxf` or `.json`; defaults to `<file>.svg` |
+| `-D name=value`       | Override a parameter; repeat for multiple values                          |
+| `-p, --params <file>` | Load parameter values from a JSON file                                    |
+| `--font <file.ttf>`   | Supply a font file; repeat for multiple fonts. `Atkinson` is built in     |
+| `--kerf <mm>`         | Override kerf for every part                                              |
+| `--sheet <W>x<H>`     | Set the sheet width and height in millimetres                             |
+| `--gap <mm>`          | Set spacing between parts                                                 |
+| `--margin <mm>`       | Set spacing at sheet edges; defaults to the gap                           |
+| `--no-pack`           | Keep the positions defined in the program                                 |
+| `--guides`            | Include the guide layer                                                   |
+| `--split`             | Export one file per sheet                                                 |
+| `-h, --help`          | Show command help                                                         |
+| `-v, --version`       | Show version numbers                                                      |
 
 `-D` accepts KerfScript values, including numbers, quoted strings, booleans
 and lists. For example: `-D width=200` or `-D 'name="Ada"'`.
@@ -68,9 +92,11 @@ a non-zero exit code.
 
 ## Fonts
 
-Supply font files with `--font` for designs that use text. The CLI does not
-look up fonts installed on your system.
+The CLI has one font built in, Atkinson Hyperlegible, as `Atkinson`: the same
+font and name as the playground. Text that names no font uses it.
 
-`--font Inter-Bold.ttf` makes the font available as `Inter-Bold`. A design
-can request it with `font = "Inter-Bold"`. The first supplied font is the
-default for text that does not name one.
+Supply other font files with `--font`. The CLI does not look up fonts
+installed on your system. `--font Inter-Bold.ttf` makes the font available
+as `Inter-Bold`. A design can request it with `font = "Inter-Bold"`. The
+first supplied font becomes the default for text that does not name one, and
+`Atkinson` stays available.

package/docs/compatibility.md

@@ -22,9 +22,9 @@ and operation order.
 
 ## Checked
 
-| Program | Version | SVG | DXF | Checks |
-| --- | --- | --- | --- | --- |
-| Inkscape | 1.4.2 | Passed | Passed | Dimensions, layers and SVG fills |
+| Program  | Version | SVG    | DXF    | Checks                           |
+| -------- | ------- | ------ | ------ | -------------------------------- |
+| Inkscape | 1.4.2   | Passed | Passed | Dimensions, layers and SVG fills |
 
 Six reference models passed these import checks on 28 October 2026.
 Drawing dimensions matched within 0.02 mm, including kerf compensation.

package/docs/customizer.md

@@ -38,15 +38,15 @@ do not get their own controls.
 
 Put a range or choice list after the assignment:
 
-| Comment after the value | Control |
-| --- | --- |
-| `// [40:5:400]` | Slider from 40 to 400, in steps of 5 |
-| `// [40:400]` | Slider from 40 to 400 |
-| `// [200]` | Number with an upper limit of 200 |
-| `// [2, 3, 4]` | Choice of 2, 3 or 4 |
-| `// [round:Round, square:Square]` | Menu with a label for each value |
-| No comment on a boolean | Checkbox |
-| No comment on a string | Text field |
+| Comment after the value           | Control                              |
+| --------------------------------- | ------------------------------------ |
+| `// [40:5:400]`                   | Slider from 40 to 400, in steps of 5 |
+| `// [40:400]`                     | Slider from 40 to 400                |
+| `// [200]`                        | Number with an upper limit of 200    |
+| `// [2, 3, 4]`                    | Choice of 2, 3 or 4                  |
+| `// [round:Round, square:Square]` | Menu with a label for each value     |
+| No comment on a boolean           | Checkbox                             |
+| No comment on a string            | Text field                           |
 
 `/* [Size] */` starts a group named Size. `/* [Hidden] */` hides the
 settings that follow it, until another group begins.

package/docs/desktop.md

@@ -0,0 +1,96 @@
+# Desktop app
+
+The KerfScript app is the [playground](https://kerfscript.mylasertools.com/playground/)
+on your computer: the same editor, settings and preview, with your designs
+saved as `.kerf` files. It works offline.
+
+## Install
+
+Download the app for your system from the
+[releases](https://github.com/mylasertools/kerfscript/releases):
+
+| System  | File                                                                         |
+| ------- | ---------------------------------------------------------------------------- |
+| Windows | `kerfscript-desktop-<version>-windows-x64-setup.exe`, or the `.msi`          |
+| macOS   | `kerfscript-desktop-<version>-macos-universal.dmg` (Apple silicon and Intel) |
+| Linux   | `.AppImage`, `.deb` or `.rpm`, for x64 or arm64                              |
+
+Package manager listings (winget, Chocolatey, Flathub and the AUR) follow as
+each one is approved.
+
+The app is not signed with an Apple or Microsoft certificate yet:
+
+- **macOS** says the app cannot be checked for malicious software. Open it
+  once with right click → **Open**, or run
+  `xattr -d com.apple.quarantine /Applications/KerfScript.app`.
+- **Windows** SmartScreen may say it protected your PC. Choose
+  **More info** → **Run anyway**.
+
+## Files
+
+| Action                | Keys                                          |
+| --------------------- | --------------------------------------------- |
+| Open a `.kerf` file   | Ctrl+O (⌘O on a Mac), or the **Open…** button |
+| Save                  | Ctrl+S                                        |
+| Save under a new name | Ctrl+Shift+S, or **Save as…**                 |
+
+Double-click a `.kerf` file to open it in the app. The title bar shows the
+file name, or Untitled, and a dot when there are unsaved changes. The app asks
+before it closes, or opens another design or an example over them, also for a
+design you have not saved yet. A design can be up to 1,000,000 characters
+long, the same as in the playground. Saving writes the whole file before it
+replaces the old one, so a full disk or a crash cannot leave half a design.
+
+SVG, DXF and sheet ZIP exports open a save dialog in the design's folder.
+On Linux, a name typed without `.kerf`, `.svg`, `.dxf` or `.zip` gets it, and
+the app asks before replacing a file of that name.
+
+## LightBurn
+
+**Open in LightBurn** sends the cut file straight to
+[LightBurn](https://lightburnsoftware.com) 2.2 or later, through LightBurn's
+[REST API](https://github.com/LightBurnSoftware/LightBurn-REST). With several
+sheets, each sheet in the cut files list has its own **LightBurn** link.
+
+LightBurn has to be open on the same computer. The first time, LightBurn
+asks whether to allow KerfScript; choose **Allow** within 30 seconds. The
+window may open behind KerfScript. KerfScript asks only to send files: it
+cannot read your projects, change cut settings or start the laser.
+
+The file opens as a new LightBurn project, as if you had used File → Open,
+and LightBurn asks first if your current project has unsaved changes. Check
+the layers and cut settings in LightBurn before you run the job.
+
+To stop KerfScript sending files, remove it in LightBurn under
+Settings → Extensions → Manage API Authorizations.
+
+LightBurn is a trademark of LightBurn Software, Inc. KerfScript is not made,
+endorsed or certified by LightBurn Software.
+
+## Libraries
+
+`use <path>` and `include <path>` find files in the open design's folder and
+the folders below it: with the design at `projects/box.kerf`,
+`use <lib/tabs>` reads `projects/lib/tabs.kerf`. Unlike the
+[command line](cli.md), the app reads only `.kerf` files, and not from folders
+above the design's, such as `use <../shared/tabs>`; keep them next to the
+design or in a folder below it. That way a design you download cannot read
+other files on your computer. Standard library paths such as `use <kerf/box>` work
+everywhere. A design that has not been saved yet can only use the standard
+library.
+
+## Fonts
+
+`text()` uses Atkinson Hyperlegible, as in the playground. The app does not
+read fonts installed on your system yet; use the [command line](cli.md) with
+`--font` for other fonts.
+
+## About and licences
+
+**About** shows the app's version, a link to its source code, and the
+licences of KerfScript and of everything built into the app.
+
+## Sharing
+
+**Copy web link** copies a link that opens your code in the playground on the
+website, so people without the app can see it.

package/docs/javascript.md

@@ -31,20 +31,20 @@ changing the source string.
 
 ### Options
 
-| Option | Value |
-| --- | --- |
-| `params` | Parameter values keyed by name |
-| `fonts` | Font files keyed by name, as `ArrayBuffer` or `Uint8Array` |
-| `defaultFont` | Name to use when `text()` does not specify a font |
-| `resolve` | `(path) => source` callback for libraries outside the standard library |
-| `kerf` | Kerf override for every part, in millimetres |
-| `layout` | `"pack"` or `"none"` |
-| `sheet` | `[width, height]` in millimetres |
-| `gap` | Space between parts, in millimetres |
-| `margin` | Space at sheet edges, in millimetres; defaults to `gap` |
-| `guides` | Whether to include guide geometry |
-| `maxSteps` | Evaluation step limit |
-| `limits` | Memory limits, see below; any you leave out keep their default |
+| Option        | Value                                                                  |
+| ------------- | ---------------------------------------------------------------------- |
+| `params`      | Parameter values keyed by name                                         |
+| `fonts`       | Font files keyed by name, as `ArrayBuffer` or `Uint8Array`             |
+| `defaultFont` | Name to use when `text()` does not specify a font                      |
+| `resolve`     | `(path) => source` callback for libraries outside the standard library |
+| `kerf`        | Kerf override for every part, in millimetres                           |
+| `layout`      | `"pack"` or `"none"`                                                   |
+| `sheet`       | `[width, height]` in millimetres                                       |
+| `gap`         | Space between parts, in millimetres                                    |
+| `margin`      | Space at sheet edges, in millimetres; defaults to `gap`                |
+| `guides`      | Whether to include guide geometry                                      |
+| `maxSteps`    | Evaluation step limit                                                  |
+| `limits`      | Memory limits, see below; any you leave out keep their default         |
 
 Supply a font for programs that use text:
 
@@ -61,16 +61,16 @@ The URL should point to a font file provided by your application.
 
 ### Result
 
-| Field | Contents |
-| --- | --- |
-| `svg` | Combined SVG containing all sheets |
-| `width`, `height` | Combined SVG dimensions in millimetres |
-| `sheets` | Each sheet's dimensions, material, thickness, SVG, DXF, paths and placed items |
-| `parts` | Part names, quantities, dimensions, piece counts, cut lengths and material properties |
-| `paths` | Layer paths with `name`, `mode`, `color`, `d`, `regions` and `lines` |
-| `layers` | Layer definitions in output order |
-| `warnings` | Problems that did not stop the render |
-| `echoes` | Output from the program's `echo()` calls |
+| Field             | Contents                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `svg`             | Combined SVG containing all sheets                                                    |
+| `width`, `height` | Combined SVG dimensions in millimetres                                                |
+| `sheets`          | Each sheet's dimensions, material, thickness, SVG, DXF, paths and placed items        |
+| `parts`           | Part names, quantities, dimensions, piece counts, cut lengths and material properties |
+| `paths`           | Layer paths with `name`, `mode`, `color`, `d`, `regions` and `lines`                  |
+| `layers`          | Layer definitions in output order                                                     |
+| `warnings`        | Problems that did not stop the render                                                 |
+| `echoes`          | Output from the program's `echo()` calls                                              |
 
 Use `result.svg` for a combined preview. Use `result.sheets[i].svg` or
 `.dxf` to export individual sheets, particularly when they use different
@@ -136,9 +136,11 @@ Run browser renders in a web worker so they do not block the page. Set a
 timeout and terminate the worker if it takes too long. Evaluation limits
 bound program steps and recursion, but geometry work also takes time.
 
-Memory limits stop a program before it asks for more memory than a browser
-tab can give: part copies, circle segments, list sizes, text length, shape
-points, exported points and sheets. The defaults are in
+Size limits stop a program before it builds more than a browser tab can
+usually hold: part copies, circle segments, list sizes, text length, shape
+points, exported points and sheets. They bound what a program makes, not
+every byte the renderer uses, so keep the worker's timeout as well, and run
+programs you did not write where the page can end them. The defaults are in
 [Limits](../LANGUAGE.md#limits) and in `DEFAULT_LIMITS`. Lower them with the
 `limits` option if your worker has little memory:
 

package/docs/layers.md

@@ -6,12 +6,12 @@ software. Unassigned shapes go on the `cut` layer.
 
 ## The built-in layers
 
-| Layer | Wrap shapes in | Colour in the file | Intended operation |
-| --- | --- | --- | --- |
-| `engrave` | `engrave()` | black `#000000` | Fill an area |
-| `score` | `score()` | blue `#0000ff` | Mark a line or outline |
-| `cut` | `cut()` | red `#ff0000` | Cut through the material |
-| `guide` | `guide()` | light blue | Show construction geometry |
+| Layer     | Wrap shapes in | Colour in the file | Intended operation         |
+| --------- | -------------- | ------------------ | -------------------------- |
+| `engrave` | `engrave()`    | black `#000000`    | Fill an area               |
+| `score`   | `score()`      | blue `#0000ff`     | Mark a line or outline     |
+| `cut`     | `cut()`        | red `#ff0000`      | Cut through the material   |
+| `guide`   | `guide()`      | light blue         | Show construction geometry |
 
 This coaster has a cut outline and hole, an engraved ring and a scored border:
 

package/docs/openscad.md

@@ -23,15 +23,15 @@ See the [language reference](../LANGUAGE.md) for supported arguments.
 
 ## Different
 
-| Feature | OpenSCAD | KerfScript |
-| --- | --- | --- |
-| Geometry | 3D and 2D | 2D parts for laser cutting |
-| Output | 3D formats and 2D exports | SVG and DXF with operation layers |
-| Assignments | The last assignment in a scope applies throughout that scope | Assignments take effect in order |
-| Type errors | Many produce `undef` and a warning | Stop evaluation with an error |
-| `color()` | Sets a shape's colour | Use `cut()`, `score()`, `engrave()` or `layer()` |
-| Fonts | Looks up system fonts | Uses fonts supplied by the application or CLI |
-| Libraries | Can load local files | Loads the standard library and sources allowed by the host |
+| Feature     | OpenSCAD                                                     | KerfScript                                                 |
+| ----------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| Geometry    | 3D and 2D                                                    | 2D parts for laser cutting                                 |
+| Output      | 3D formats and 2D exports                                    | SVG and DXF with operation layers                          |
+| Assignments | The last assignment in a scope applies throughout that scope | Assignments take effect in order                           |
+| Type errors | Many produce `undef` and a warning                           | Stop evaluation with an error                              |
+| `color()`   | Sets a shape's colour                                        | Use `cut()`, `score()`, `engrave()` or `layer()`           |
+| Fonts       | Looks up system fonts                                        | Uses fonts supplied by the application or CLI              |
+| Libraries   | Can load local files                                         | Loads the standard library and sources allowed by the host |
 
 Assignment order is especially important when adapting a design. A value
 assigned later in a KerfScript program does not change earlier geometry.

package/docs/versions.md

@@ -1,6 +1,6 @@
 # Versions
 
-KerfScript 0.2.0 implements language version 0.1. The package version tracks
+KerfScript 0.3.0 implements language version 0.1. The package version tracks
 the software release; the language version tracks the syntax and behavior
 of `.kerf` programs.
 
@@ -30,4 +30,4 @@ files used with a design. Applications that store designs should retain
 that information and compare the output before upgrading the interpreter.
 
 Pin the npm package to an exact version when your application needs a fixed
-renderer, for example `@mylasertools/kerfscript@0.2.0`.
+renderer, for example `@mylasertools/kerfscript@0.3.0`.

package/docs/webassembly.md

@@ -0,0 +1,131 @@
+# WebAssembly
+
+`kerfscript.wasm` runs KerfScript from any language that can host a
+WebAssembly module: Python, Rust, Go, C#, Java, Ruby and others. It is a
+WASI (preview 1) module built from the same source as the JavaScript package,
+so it makes the same SVG and DXF files, byte for byte.
+
+For JavaScript applications, use the [JavaScript API](javascript.md)
+instead: it is smaller and faster.
+
+## Getting the module
+
+Download `kerfscript-<version>.wasm` from the
+[releases](https://github.com/mylasertools/kerfscript/releases) page and save
+it as `kerfscript.wasm`, or get `kerfscript-wasm-<version>.zip`, which has the
+module with this guide and its licences. You can also build it from the
+repository with [Javy](https://github.com/bytecodealliance/javy):
+
+```sh
+npm run build
+npm run wasm        # writes dist/kerfscript.wasm
+```
+
+Set `JAVY` to the javy binary if it is not on the `PATH`.
+
+## How it works
+
+The module reads one JSON request from standard input, writes one JSON
+response to standard output and exits. Start a fresh instance for each
+request. From a shell, with [Wasmtime](https://wasmtime.dev):
+
+```sh
+echo '{"source": "rect([80, 50]);"}' | wasmtime run kerfscript.wasm
+```
+
+### Request
+
+| Field         | Value                                                                       |
+| ------------- | --------------------------------------------------------------------------- |
+| `command`     | `"render"` (default), `"params"`, `"version"` or `"licenses"`               |
+| `source`      | The program, as a string                                                    |
+| `params`      | Parameter values keyed by name                                              |
+| `files`       | Libraries for `include` and `use`, keyed by path: `{"lib/tab.kerf": "..."}` |
+| `fonts`       | Font files keyed by name, base64 encoded. `Atkinson` is built in            |
+| `defaultFont` | Name to use when `text()` does not specify a font                           |
+| `kerf`        | Kerf override for every part, in millimetres                                |
+| `layout`      | `"pack"` (default) or `"none"`                                              |
+| `sheet`       | Sheet size `[width, height]` in millimetres                                 |
+| `gap`         | Space between packed parts                                                  |
+| `margin`      | Space between the parts and the sheet edge                                  |
+| `guides`      | `true` to include guide layer geometry                                      |
+
+These match the [render() options](javascript.md#options). A path in `files`
+can leave out `.kerf`, as in the program.
+
+### Response
+
+Every response has `ok`. When it is `false`, `error` holds the message and
+`echoes` holds what the program echoed before it stopped. The module never
+exits with an error code for a bad program.
+
+- `render`: `svg` (all sheets, for preview), `width`, `height`, `parts`,
+  `warnings`, `echoes` and `sheets`. Each sheet has `width`, `height`,
+  `material`, `thickness`, `svg` and `dxf`; write one file per sheet to cut.
+- `params`: `parameters`, as from [`parameters()`](javascript.md).
+- `version`: `version` (package) and `language`.
+- `licenses`: `files`, the licence texts of the module and of everything
+  built into it, keyed by file name: `LICENSE`, `COMMERCIAL-LICENSE.md`,
+  `THIRD-PARTY-NOTICES.md`, `THIRD-PARTY-LICENSES.md` (the JavaScript engine
+  and its Rust crates) and `OFL.txt`. The release ZIP has the same files.
+
+## Python
+
+With the [`wasmtime`](https://pypi.org/project/wasmtime/) package:
+
+```python
+import json, os, tempfile
+from wasmtime import Engine, Linker, Module, Store, WasiConfig
+
+engine = Engine()
+module = Module.from_file(engine, "kerfscript.wasm")
+linker = Linker(engine)
+linker.define_wasi()
+
+def kerf(request):
+    with tempfile.TemporaryDirectory() as d:
+        inp, out = os.path.join(d, "in.json"), os.path.join(d, "out.json")
+        with open(inp, "w", encoding="utf-8") as f:
+            json.dump(request, f)
+        wasi = WasiConfig()
+        wasi.stdin_file = inp
+        wasi.stdout_file = out
+        store = Store(engine)
+        store.set_wasi(wasi)
+        linker.instantiate(store, module).exports(store)["_start"](store)
+        with open(out, encoding="utf-8") as f:
+            return json.load(f)
+
+result = kerf({"source": "w = 80; rect([w, 50]);", "params": {"w": 120}})
+for i, sheet in enumerate(result["sheets"]):
+    with open(f"sheet-{i + 1}.svg", "w", encoding="utf-8", newline="") as f:
+        f.write(sheet["svg"])
+```
+
+Compile the module once and reuse it; each request only needs a new `Store`.
+
+## Node.js
+
+The JavaScript package is the better fit in Node.js, but the module also runs
+under `node:wasi`, which is how the test suite checks it:
+
+```js
+import { closeSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { WASI } from 'node:wasi';
+
+const module = await WebAssembly.compile(readFileSync('kerfscript.wasm'));
+writeFileSync('in.json', JSON.stringify({ source: 'rect([80, 50]);' }));
+const stdin = openSync('in.json', 'r');
+const stdout = openSync('out.json', 'w');
+const wasi = new WASI({ version: 'preview1', stdin, stdout, returnOnExit: true });
+wasi.start(await WebAssembly.instantiate(module, wasi.getImportObject()));
+closeSync(stdin);
+closeSync(stdout);
+console.log(JSON.parse(readFileSync('out.json', 'utf8')).svg);
+```
+
+## Performance
+
+The module carries its own JavaScript engine (QuickJS), so it is about 2 MB
+and renders roughly three to five times slower than Node.js. The example
+designs take well under a second.