@mylasertools/kerfscript 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,13 +1,64 @@
 # Changelog
 
-## 0.2.1
+## 0.3.0 (2026-10-30)
 
+- `kerfscript.wasm`: a WASI module that runs KerfScript from Python, Rust,
+  Go, C# and other languages. It takes a JSON request on standard input and
+  writes SVG, DXF, parts and warnings as JSON. `"command": "licenses"`
+  returns the licence texts of the module and of the JavaScript engine built
+  into it. Build it with `npm run wasm`; see
+  [docs/webassembly.md](docs/webassembly.md).
+- A desktop app for Windows, macOS and Linux: the playground with `.kerf`
+  files on disk (Open, Save, Save as, double-click to open; Save as adds
+  `.kerf` to a name without it and asks before replacing a file of that
+  name), exports through a save dialog, `use`/`include` libraries read from
+  the design's folder and the folders below it (`.kerf` files only), and an
+  About window with the source link and the licences of everything in the
+  app. Saving writes the whole file before it replaces the old one, and the
+  app asks about unsaved changes before it closes, also on ⌘Q.
+  Installers: Windows setup and MSI, a universal macOS dmg, and an AppImage,
+  `.deb` and `.rpm` for Linux x64 and arm64; Flathub, winget, Chocolatey and
+  AUR manifests. See [docs/desktop.md](docs/desktop.md).
+- Open in LightBurn in the desktop app: sends the cut file (or one sheet) to
+  LightBurn 2.2 or later through its REST API. KerfScript asks LightBurn only
+  for permission to send files, and talks to it directly, past any proxy
+  set on the computer.
+- Chocolatey and MacPorts manifests for the command line.
+- The playground does not load a shared link, draft or file longer than
+  1,000,000 characters, and stops unpacking a compressed link at that size.
+  Any code the editor runs fits in a link, whatever its script, and a link
+  that cannot be opened says why in the console. Code over the limit is not
+  coloured or read for settings, and Copy link refuses it. A link to an
+  empty design opens it, instead of the draft.
+- Settings for a list, such as `size = [10, 20]`, keep numbers changed in the
+  code since the settings were drawn, instead of putting the old ones back.
+  An empty or half-typed number box leaves the code as it is.
+- The playground renders the newest code after fast edits to a slow design,
+  instead of stopping with "Stopped after 15 seconds", and keeps working
+  when the number of sheets drops to one in the laser file view. Edits after
+  opening a shared link or moving a slider on an example are kept on reload.
+- The website's licence page, and `assets/THIRD-PARTY-NOTICES.md` next to
+  `kerfscript.js`, have the notices of the libraries bundled in its
+  JavaScript.
+- Standalone `kerf` binaries for Windows, macOS and Linux that need no
+  Node.js, with the licences of the Deno runtime built into them,
+  `kerfscript-cli` `.deb` and `.rpm` packages (which install next to the
+  desktop app), a Docker image, a snap, and Homebrew,
+  Scoop, winget and AUR manifests, all built by the release workflow with
+  SHA-256, SHA-512 and GPG signatures. Nightly builds go to a rolling
+  `nightly` prerelease. See RELEASING.md.
+- A `kerf(1)` man page and a `text/x-kerfscript` MIME type for `*.kerf` files
+  in the Linux packages.
+- The command line and `kerfscript.wasm` have a font built in, Atkinson
+  Hyperlegible as `Atkinson` (the playground's font), so `text()` works
+  without `--font`. The JavaScript library still takes fonts from the host.
 - Memory limits, so a program cannot make a browser tab run out of memory:
   part copies, circle segments and polygon corners, list and string sizes,
   all list items together, `text()` length, shape points, exported points
   and sheets. Each stops the program with an error that says what to change.
   Defaults are in `DEFAULT_LIMITS` and the `limits` render option changes
-  them. Every example stays well under them.
+  them. Every example stays well under them. Ranges in loops and built-in
+  functions stop at `maxListLength` items, not at a fixed million.
 - A list or string that grows past what JavaScript can hold now gives a
   KerfScript error instead of a `RangeError`.
 - Lists are checked while they are built, so `each` in a long loop, list
@@ -15,6 +66,34 @@
   memory. Strings joined with `+`, strings from functions and `echo()` text
   count toward `maxListItems` too, and a repeated unknown argument warning
   is shown once.
+- `echo()`, `str()`, `join()` and `==` on lists that hold the same list many
+  times stop at the limits instead of running out of memory: text stops at
+  `maxListLength` characters while it is written, and comparing lists does
+  not compare the same pair of lists twice. Error messages, part names and
+  other settings show only the start of a long list.
+- Comparing lists, dot products and built-in functions that go through a list
+  or string, such as `search()`, `contains()`, `max()` and `sum()`, take a
+  step for each item, so a loop over a long list stops at `maxSteps` instead
+  of running for minutes.
+- `hull()` around named parts makes the hull of each part, the same as
+  `hull()` inside the part. It left the parts unchanged before.
+- DXF layers whose names come out the same in DXF, such as `a b` and `a_b`,
+  stay separate layers: the later ones get `_2`, `_3` and so on. The
+  built-in layers keep `CUT`, `SCORE`, `ENGRAVE` and `GUIDE`.
+- Built-in functions take named arguments, such as `sin(x = 30)` and
+  `pow(x = 2, y = 10)`; an unknown name gives a warning, and so does an
+  argument given both by position and by name. They were ignored before.
+- Errors and warnings in a library name it, as in
+  `(line 3, column 5 in <lib/tabs>)`. The playground marks the line only for
+  errors in the program itself.
+- `toString()`, `constructor()` and other names every JavaScript object has
+  are unknown functions and libraries, instead of a crash or a wrong value.
+- `text_width()` and `text_metrics()` take a step per character, have the
+  same length limit as `text()`, and are much faster for long text.
+- A list times a matrix of the wrong size, and `params` values that are not
+  numbers, strings, booleans or lists, are errors instead of a crash.
+- A list times a list whose items multiply to lists is an error instead of
+  text.
 - The commercial licence for closed-source apps and services is free: email
   hi@mylasertools.com.
 

package/LANGUAGE.md

@@ -230,18 +230,20 @@ export examples.
 
 Supply geometry as children of a shape-processing module, for example
 `translate([10, 0]) circle(d = 5);`. Fonts used by `text()` must be supplied
-by the application or through the [command line](docs/cli.md).
+by the application or through the [command line](docs/cli.md). The
+playground, the command line and `kerfscript.wasm` have `Atkinson`
+(Atkinson Hyperlegible) built in.
 
 ### Transforms
 
-| Module | Effect |
-| --- | --- |
-| `translate([x, y])` | Move geometry by x and y |
+| Module                       | Effect                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `translate([x, y])`          | Move geometry by x and y                                               |
 | `rotate(a, center = [x, y])` | Rotate by `a` degrees around a point; the default centre is the origin |
-| `scale(s)` | Scale both axes by the same factor |
-| `scale([sx, sy])` | Scale each axis separately |
-| `mirror([nx, ny])` | Reflect across a line through the origin, perpendicular to this vector |
-| `multmatrix(m)` | Apply a 2 × 3 transformation matrix |
+| `scale(v)`                   | Scale both axes by the number `v`                                      |
+| `scale([sx, sy])`            | Scale each axis separately                                             |
+| `mirror([nx, ny])`           | Reflect across a line through the origin, perpendicular to this vector |
+| `multmatrix(m)`              | Apply a 2 × 3 transformation matrix                                    |
 
 ### Combining
 
@@ -250,7 +252,7 @@ by the application or through the [command line](docs/cli.md).
 | `union()` / `group()`                          | joins children                                                             |
 | `difference()`                                 | removes every later child's area from every layer of the first child       |
 | `intersection()`                               | keeps only the area common to all children, layers of the first child kept |
-| `hull()`                                       | convex hull                                                                |
+| `hull()`                                       | convex hull; each named part inside gets its own hull                      |
 | `offset(r)` / `offset(delta, chamfer = false)` | grow (positive) or shrink areas; `r` rounds corners                        |
 | `stroke(width)`                                | turns lines into areas of that width, for cutting single line art          |
 | `outline()`                                    | turns areas into their outline lines                                       |
@@ -266,50 +268,53 @@ by the application or through the [command line](docs/cli.md).
 
 ### Other
 
-| Module | Effect |
-| --- | --- |
-| `echo(...)` | Report values without creating geometry |
-| `assert(cond, message)` | Stop with `message` when `cond` is false |
-| `children(i)` | Render a child passed to the current module; omit `i` to render all children |
+| Module                       | Effect                                                                           |
+| ---------------------------- | -------------------------------------------------------------------------------- |
+| `echo(...)`                  | Report values without creating geometry                                          |
+| `assert(condition, message)` | Stop with `message` when `condition` is false                                    |
+| `children(index)`            | Render a child passed to the current module; omit `index` to render all children |
 
 ## Built-in functions
 
-Functions return values. The examples below use positional arguments.
+Functions return values. Arguments can be positional or named with the
+parameter names below, as in `pow(x = 2, y = 10)` or `log(8, base = 2)`. An
+unknown name gives a warning. `concat`, `str` and `chr` take only positional
+arguments.
 
 ### Numbers and vectors
 
-| Function | Result |
-| --- | --- |
-| `abs(x)`, `sign(x)` | Absolute value, or sign as -1, 0 or 1 |
-| `floor(x)`, `ceil(x)`, `round(x)` | Round down, up or to the nearest integer |
-| `sqrt(x)`, `pow(x, y)` | Square root, or x raised to y |
-| `exp(x)`, `ln(x)` | Exponential with base e, or natural logarithm |
-| `log(x)`, `log(base, x)` | Base-10 logarithm, or logarithm with a chosen base |
-| `sin(a)`, `cos(a)`, `tan(a)` | Trigonometric functions with angles in degrees |
-| `asin(x)`, `acos(x)`, `atan(x)`, `atan2(y, x)` | Inverse trigonometric functions, returning degrees |
-| `min(values)`, `max(values)` | Minimum or maximum of a list; also accept separate values |
-| `clamp(x, low, high)` | Limit x to the given interval |
-| `lerp(a, b, t)` | Interpolate between numbers or vectors; t = 0 gives a, t = 1 gives b |
-| `norm(v)` | Length of a vector |
-| `cross(a, b)` | Cross product; a scalar for 2D vectors or a vector for 3D vectors |
+| Function                                       | Result                                                               |
+| ---------------------------------------------- | -------------------------------------------------------------------- |
+| `abs(x)`, `sign(x)`                            | Absolute value, or sign as -1, 0 or 1                                |
+| `floor(x)`, `ceil(x)`, `round(x)`              | Round down, up or to the nearest integer                             |
+| `sqrt(x)`, `pow(x, y)`                         | Square root, or x raised to y                                        |
+| `exp(x)`, `ln(x)`                              | Exponential with base e, or natural logarithm                        |
+| `log(x)`, `log(base, x)`                       | Base-10 logarithm, or logarithm with a chosen base                   |
+| `sin(x)`, `cos(x)`, `tan(x)`                   | Trigonometric functions with angles in degrees                       |
+| `asin(x)`, `acos(x)`, `atan(x)`, `atan2(y, x)` | Inverse trigonometric functions, returning degrees                   |
+| `min(values)`, `max(values)`                   | Minimum or maximum of a list; also accept separate values            |
+| `clamp(x, low, high)`                          | Limit x to the given interval                                        |
+| `lerp(a, b, t)`                                | Interpolate between numbers or vectors; t = 0 gives a, t = 1 gives b |
+| `norm(v)`                                      | Length of a vector                                                   |
+| `cross(a, b)`                                  | Cross product; a scalar for 2D vectors or a vector for 3D vectors    |
 
 ### Lists and strings
 
-| Function | Result |
-| --- | --- |
-| `len(value)` | Number of items in a list or characters in a string |
-| `concat(...)` | Join lists and individual values into one list |
-| `reverse(value)` | Reverse a list or string |
-| `sum(values)` | Sum a list of numbers |
-| `slice(value, start = 0, end)` | Extract part of a list or string; `end` is exclusive and defaults to its length |
-| `str(...)` | Convert values to text and join them |
-| `chr(...)`, `ord(text)` | Convert Unicode code points to text, or read the first character's code point |
-| `upper(text)`, `lower(text)` | Change letter case |
-| `split(text, separator = " ")` | Split text into a list of strings |
-| `join(values, separator = "")` | Join values into a string |
-| `search(value, list)` | Index of the first equal item, or `undef` if absent; also searches characters in strings |
-| `contains(value, item)` | Whether a list contains an item or a string contains a substring |
-| `lookup(x, table)` | Interpolate in a table of `[x, y]` pairs; use the nearest endpoint outside the table's range |
+| Function                       | Result                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `len(value)`                   | Number of items in a list or characters in a string                                          |
+| `concat(...)`                  | Join lists and individual values into one list                                               |
+| `reverse(value)`               | Reverse a list or string                                                                     |
+| `sum(values)`                  | Sum a list of numbers                                                                        |
+| `slice(value, start = 0, end)` | Extract part of a list or string; `end` is exclusive and defaults to its length              |
+| `str(...)`                     | Convert values to text and join them                                                         |
+| `chr(...)`, `ord(text)`        | Convert Unicode code points to text, or read the first character's code point                |
+| `upper(text)`, `lower(text)`   | Change letter case                                                                           |
+| `split(text, separator = " ")` | Split text into a list of strings                                                            |
+| `join(values, separator = "")` | Join values into a string                                                                    |
+| `search(value, list)`          | Index of the first equal item, or `undef` if absent; also searches characters in strings     |
+| `contains(value, item)`        | Whether a list contains an item or a string contains a substring                             |
+| `lookup(x, table)`             | Interpolate in a table of `[x, y]` pairs; use the nearest endpoint outside the table's range |
 
 ### Types
 
@@ -342,15 +347,29 @@ list can appear as editable settings. Comments supply captions, ranges,
 choices and groups:
 
 ```kerf
-/* [Size] */             // group for the following parameters
-// Outer width           <- caption: the comment line above
-width = 120; // [40:5:400]   min:step:max
-depth = 80;  // [200]        max
-shape = "round"; // [round:Round, square:Square]   choices with labels
-count = 3; // [2, 3, 4]      choices
-/* [Hidden] */           // not listed
+/* [Size] */
+// Outer width
+width = 120; // [40:5:400]
+depth = 80; // [200]
+shape = "round"; // [round:Round, square:Square]
+count = 3; // [2, 3, 4]
+/* [Hidden] */
+seed = 7;
 ```
 
+- `/* [Size] */` starts a group; the settings below it are listed under
+  _Size_.
+- `// Outer width`, the comment line just above an assignment, is its caption.
+- `[40:5:400]` is a slider from 40 to 400 in steps of 5; `[200]` is a slider
+  up to 200.
+- `[round:Round, square:Square]` is a menu of values with labels; `[2, 3, 4]`
+  is a menu of values.
+- Settings after `/* [Hidden] */` are not listed.
+
+Nothing else may follow the brackets on the same line: with
+`// [40:5:400] min:step:max` the setting is a plain number field, not a
+slider.
+
 These comments follow OpenSCAD's customizer format. Read
 [Settings](docs/customizer.md) for supported controls, or use `kerf params`
 to inspect the settings in a file.
@@ -369,30 +388,42 @@ Load the box modules with `use <kerf/box>`:
 - **SVG**: millimetre units, one Inkscape layer group per KerfScript layer,
   colours as above, 0.1 mm hairline strokes, `data-part` on every path.
 - **DXF**: R12 (AC1009) polylines on layers named after KerfScript layers,
-  with matching AutoCAD colours.
+  with matching AutoCAD colours. Names are upper case with characters other
+  than letters, digits, `_` and `-` as `_`; when two layers come out the
+  same, the later one gets `_2`, `_3` and so on. The built-in layers keep
+  `CUT`, `SCORE`, `ENGRAVE` and `GUIDE`, so a layer of your own named `Cut`
+  becomes `CUT_2`.
 
 ## Limits
 
 The interpreter limits call depth to 1,000 for modules and 2,000 for
-functions. Expanded ranges are limited to 1,000,000 items. The default
+functions. A range a loop or built-in function goes through is limited to
+`maxListLength` items (below). The default
 evaluation limit is 5,000,000 steps; applications can change it with
-`maxSteps`. Exceeding a limit stops evaluation with an error.
+`maxSteps`. Comparing lists with `==`, multiplying two lists, and built-in
+functions that go through a list or string take a step for each item;
+`len()` of a list, `ord()`, `type_of()` and the `is_` functions take one.
+Exceeding a limit stops evaluation with an error.
 
 Programs are also limited in how much memory they can ask for:
 
-| Limit | Default | What it counts |
-| --- | --- | --- |
-| `maxParts` | 10,000 | copies of all parts, adding up every `qty` |
-| `maxSegments` | 10,000 | segments in one circle, ellipse or arc, and corners in one polygon |
-| `maxListLength` | 1,000,000 | items in one list, or characters in one string |
-| `maxListItems` | 3,000,000 | items in all lists the program builds, plus 4 for each list, one for every 8 characters of the strings it builds or echoes |
-| `maxTextLength` | 2,000 | characters in one `text()` |
-| `maxPoints` | 2,000,000 | points in all shapes the modules make, plus 100 for each shape |
-| `maxOutputPoints` | 1,000,000 | points in the exported files, counting every copy |
-| `maxSheets` | 200 | sheets in the layout |
+| Limit             | Default   | What it counts                                                                                                             |
+| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `maxParts`        | 10,000    | copies of all parts, adding up every `qty`                                                                                 |
+| `maxSegments`     | 10,000    | segments in one circle, ellipse or arc, and corners in one polygon                                                         |
+| `maxListLength`   | 1,000,000 | items in one list or range, or characters in one string, including the text `echo()` writes in one call                    |
+| `maxListItems`    | 3,000,000 | items in all lists the program builds, plus 4 for each list, one for every 8 characters of the strings it builds or echoes |
+| `maxTextLength`   | 2,000     | characters in one `text()`                                                                                                 |
+| `maxPoints`       | 2,000,000 | points in all shapes the modules make, plus 100 for each shape                                                             |
+| `maxOutputPoints` | 1,000,000 | points in the exported files, counting every copy                                                                          |
+| `maxSheets`       | 200       | sheets in the layout                                                                                                       |
 
 Applications can change them with the `limits` render option.
 
+A list can hold the same list many times, as in `b = [a, a]`. `echo()`,
+`str()` and `join()` write every copy out, so their text can be far longer
+than the list; they stop with an error once it passes `maxListLength`.
+
 Geometry operations also take time. Applications that render user programs
 should run them in a worker with a timeout; see the
 [JavaScript API](docs/javascript.md#running-untrusted-code).

package/README.md

@@ -101,17 +101,20 @@ it as the start of your own design.
   cuts come before outer ones, and the whole part is offset by half the kerf.
 - **Parts, not just shapes.** `part("lid", qty = 2)` names a piece; the
   renderer packs parts by material and thickness onto sheets.
-- **Joinery that fits.** `finger_rect`, `finger_holes`, `tslot` and
-  `living_hinge` use `$thickness`, so changing the material keeps joints
-  tight.
-- **Familiar syntax.** If you know OpenSCAD, you can read KerfScript. The
-  customizer comments are the same, so editors that understand OpenSCAD
-  parameters understand KerfScript ones.
+- **Joinery that follows the material.** `finger_rect`, `finger_holes`,
+  `tslot` and `living_hinge` use `$thickness`, so the joints resize when the
+  material changes. Measure your kerf and cut a test piece for a snug fit.
+- **Readable code.** Variables, modules, functions, loops and transforms like
+  `translate()` and `rotate()`. Settings come from comments such as
+  `// [10:1:100]`, which the playground turns into sliders. If you have used
+  OpenSCAD, [Coming from OpenSCAD](docs/openscad.md) lists what differs.
 - **Runs anywhere.** Pure TypeScript with no native code: the same interpreter
   runs in browsers, Node, workers and the command line.
-- **Safe to run.** Programs read libraries only through the resolver you
-  provide. Step and recursion limits stop runaway programs, and errors name
-  the line.
+- **Contained.** Programs read libraries only through the resolver you
+  provide and have no other access to files or the network. Step, recursion
+  and size limits stop runaway programs, and errors name the line. Run
+  programs you did not write in a worker or process you can stop; see
+  [Running untrusted code](docs/javascript.md#running-untrusted-code).
 
 ## Install
 
@@ -119,6 +122,12 @@ it as the start of your own design.
 npm install @mylasertools/kerfscript
 ```
 
+The `kerf` command line also comes as a standalone binary that needs no
+Node.js, and through Homebrew, winget, Chocolatey, Scoop, Snap, the AUR,
+MacPorts and Docker: see [Command line](docs/cli.md#without-nodejs). The
+desktop app is in [Desktop app](docs/desktop.md), and the WebAssembly module
+in [WebAssembly](docs/webassembly.md).
+
 ## Command line
 
 ```sh
@@ -156,7 +165,9 @@ Errors are thrown as `KerfError` with `line` and `col`.
 - [Getting started](docs/getting-started.md), then the guides on
   [layers](docs/layers.md), [kerf](docs/kerf.md),
   [parts and sheets](docs/parts-and-sheets.md), [settings](docs/customizer.md),
-  the [command line](docs/cli.md) and the [JavaScript API](docs/javascript.md)
+  the [desktop app](docs/desktop.md), the [command line](docs/cli.md), the
+  [JavaScript API](docs/javascript.md)
+  and [WebAssembly](docs/webassembly.md) for other languages
 - [Coming from OpenSCAD](docs/openscad.md): what is the same and what is not
 - [LANGUAGE.md](LANGUAGE.md): the full language reference
 - [Versions](docs/versions.md): language and package versions, and what stays

package/THIRD-PARTY-NOTICES.md

@@ -117,8 +117,17 @@ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
-## Atkinson Hyperlegible (test fixture only, not published to npm)
+## Desktop app
 
-`test/fixtures/AtkinsonHyperlegible-Regular.ttf`, Copyright 2020 Braille
-Institute of America, Inc., licensed under the SIL Open Font License 1.1. See
-`test/fixtures/OFL.txt`.
+The desktop app is also built from Rust crates (Tauri and its dependencies)
+under MIT, Apache-2.0, MPL-2.0, BSD, ISC, Zlib, Unicode and similar licences.
+`desktop/THIRD-PARTY-LICENSES.md` lists each one with its licence text, and
+the installers place it next to the app.
+
+## Atkinson Hyperlegible (built into the command line and kerfscript.wasm)
+
+`fonts/AtkinsonHyperlegible-Regular.ttf`, Copyright 2020 Braille Institute
+of America, Inc., licensed under the SIL Open Font License 1.1. See
+`fonts/OFL.txt`. It is embedded unmodified in `dist/cli.js` and
+`kerfscript.wasm`, and the playground serves it; `dist/index.js` does not
+include it.