@mylasertools/kerfscript 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 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. 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
+  arithmetic and matrix products stop at the limit instead of first filling
+  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.
+
 ## 0.2.0 (2026-10-28)
 
 First public release.

package/CLA.md

@@ -7,9 +7,12 @@ Thank you for contributing to KerfScript. This agreement lets MyLaserTools
 commercial licences, including licences we may sell. You keep the copyright in
 your contribution.
 
-By submitting a Contribution (a pull request, patch, issue attachment or any
-other material you intentionally send us for inclusion in KerfScript) you
-("You") agree to the following for that Contribution and every later one.
+This agreement applies to a Contribution when you add the signature
+statement below to the pull request that contains it. A Contribution is
+material you intentionally submit in that signed pull request for inclusion
+in KerfScript. Issue reports, ideas, unsigned pull requests and other
+communications do not grant rights under this agreement. Sign each pull
+request you want us to consider for inclusion.
 
 ## 1. Copyright licence
 
@@ -62,12 +65,12 @@ trademarks.
 
 ## How to sign
 
-Add this line to your first pull request description, using your legal name:
+Add this statement to each pull request description, using your legal name:
 
 ```text
 I have read the KerfScript CLA 1.0 and agree to it for my contributions.
 Name: <your name>  GitHub: <your handle>  Date: <YYYY-MM-DD>
 ```
 
-If You contribute on behalf of a company, contact julia@mylasertools.com for
+If You contribute on behalf of a company, contact hi@mylasertools.com for
 the company version first.

package/COMMERCIAL-LICENSE.md

@@ -1,35 +1,24 @@
 # Licensing
 
-Copyright (c) 2026 MyLaserTools. All rights reserved except as granted below.
+Copyright (c) 2026 MyLaserTools.
+
+**KerfScript is free to use, including for commercial work.** Write programs,
+cut and sell what you make, and sell your `.kerf` designs and the files they
+produce. You don't need to ask us for any of that.
 
 KerfScript is dual licensed. You can use it under **either**:
 
 1. **The GNU Affero General Public License, version 3 only** (`AGPL-3.0-only`,
    full text in [LICENSE](LICENSE)), together with the additional permission
    below, or
-2. **A commercial licence** from MyLaserTools.
-
-## What the AGPL means for you
+2. **A commercial licence** from MyLaserTools, which is **free**.
 
-Free, under the AGPL, when you:
-
-- write KerfScript programs and cut, sell or share what you make with them
-- use the `kerf` command line tool, or the library inside software you only run
-  for yourself
-- build open source software on KerfScript and publish its complete source code
-  under the AGPL
+## Free commercial licence
 
-You need a commercial licence when you:
-
-- ship KerfScript inside a closed source app, plugin, machine or firmware
-- run KerfScript (or a modified copy) behind a website or online service and do
-  not want to publish that service's complete source code under the AGPL
-- want to change KerfScript without sharing your changes
-
-The AGPL treats letting people use the software over a network like
-distributing it: if you modify KerfScript or build it into a service that
-others use, you must offer those users the complete corresponding source code
-of the whole program under the AGPL.
+Want to build KerfScript into a closed-source app, plugin, machine, firmware
+or online service? The commercial licence costs nothing. Just email
+hi@mylasertools.com with your name or company and what you are building, and
+we will send it to you.
 
 ## Additional permission: your designs are yours
 
@@ -45,15 +34,21 @@ that:
 
 This permission covers your programs and their output only. It does not cover
 the KerfScript interpreter, its tools, or modified copies of the standard
-library, which remain under the AGPL.
+library, which remain under the AGPL unless you have the commercial licence.
 
-## Commercial licences
+## What the AGPL means for you
 
-A commercial licence replaces the AGPL obligations with ordinary commercial
-terms: closed source use, use in hosted services, private modifications and
-support options. Terms and pricing are set per agreement.
+Under the AGPL you can:
 
-Contact: julia@mylasertools.com
+- write KerfScript programs and cut, sell or share what you make with them
+- run the interpreter, including a modified copy, privately or in internal
+  tools without publishing those private changes
+- use an unmodified copy on a server
+- distribute software that includes KerfScript, as long as you share its
+  source code under the AGPL
+
+If you would rather not share your source code, ask for the free commercial
+licence.
 
 ## Trademarks
 

package/LANGUAGE.md

@@ -1,15 +1,18 @@
 # KerfScript language reference
 
 Language version 0.1. Copyright (c) 2026 MyLaserTools. This document is
-licensed under [CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/).
+licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
 "KerfScript" is a trademark of MyLaserTools, see [TRADEMARKS.md](TRADEMARKS.md).
 
-KerfScript describes flat parts for laser cutting. A program is a list of
-statements that build 2D shapes, put them on **layers** (cut, score, engrave),
-group them into **parts**, and the renderer compensates for the **kerf**, packs
-parts onto **sheets** and writes SVG or DXF.
+This reference covers KerfScript syntax, built-in modules and functions.
+For a first project, follow [Getting started](docs/getting-started.md).
 
-Units are millimetres and degrees. The y axis points up.
+Programs build 2D shapes, assign them to cut, score or engrave layers, and
+group them into parts. Rendering applies kerf compensation, arranges the
+parts on sheets and produces SVG or DXF files.
+
+Lengths are in millimetres and angles are in degrees. Positive x points
+right; positive y points up.
 
 ```kerf
 // A coaster with a hole, an engraved ring and a scored border.
@@ -49,7 +52,8 @@ Points are lists `[x, y]`. `p.x` and `p.y` read the first two items.
 
 ## Expressions
 
-From lowest to highest precedence:
+Operators are listed from lowest to highest precedence. Use parentheses
+to change the order of evaluation.
 
 | Operator            | Meaning                                                                                                        |
 | ------------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -64,14 +68,19 @@ From lowest to highest precedence:
 | `a ^ b`             | power, right associative and tighter than unary minus                                                          |
 | `f(x)` `a[i]` `a.x` | call, index, member                                                                                            |
 
-Mixing types an operator can't handle (a list plus a number, `undef + 1`)
-stops the program with an error naming the line. Truthiness: `false`, `0`,
-`""`, `[]` and `undef` are false.
+Unsupported combinations, such as a list plus a number or `undef + 1`,
+produce an error at the source line.
+
+In conditions, `false`, `0`, `""`, `[]` and `undef` count as false.
 
-`let (a = 1, b = a + 1) expr` binds names for one expression.
+Use `let (a = 1, b = a + 1) expr` to define names for one expression.
+Each binding can use the ones before it.
 
 ### List comprehensions
 
+Build a list with `for`, filter items with `if`, or insert the contents of
+another list with `each`:
+
 ```kerf
 squares = [for (i = [1:5]) i * i];
 odd = [for (i = [1:9]) if (i % 2) i];
@@ -81,6 +90,10 @@ flat = [each [1, 2], 3];
 
 ## Statements
 
+Assignments and function definitions end with a semicolon. Modules create
+geometry and can receive child statements. In the syntax below, `...`
+stands for the body of a statement:
+
 ```kerf
 name = expr;                          // assignment
 function name(a, b = 2) = expr;       // function
@@ -111,13 +124,15 @@ Arguments can be positional or named: `rect([20, 10], r = 2)`.
 
 ### Modifiers
 
-Put before a module call: `*` disables it, `#` and `%` move it to the guide
-layer so you can see it without cutting it.
+Place `*` before a module call to disable it. Use `#` or `%` to move its
+geometry to the guide layer. Guides are included only when requested in
+the render options.
 
 ### children()
 
-Inside a module, `children()` renders the statements the module was called
-with, `children(i)` renders only the i-th one, and `$children` is their count.
+Inside a module, `children()` renders all child statements passed by the
+caller. `children(i)` selects one child, using a zero-based index.
+`$children` is the number of children.
 
 ```kerf
 module hang_hole(d = 5) {
@@ -142,7 +157,7 @@ module hang_hole(d = 5) {
 
 Every shape is on a layer. Shapes not wrapped in a layer module are on `cut`.
 
-| Layer     | Mode  | Colour    | What happens                                         |
+| Layer     | Mode  | Colour    | Intended operation                                   |
 | --------- | ----- | --------- | ---------------------------------------------------- |
 | `engrave` | fill  | `#000000` | the area is engraved                                 |
 | `score`   | line  | `#0000ff` | lines and shape outlines are marked, not cut through |
@@ -154,11 +169,14 @@ cut() ...        engrave() ...        score() ...        guide() ...
 layer("pocket", mode = "fill", color = "#00aa00") ...
 ```
 
-`layer(name, mode, color)` defines a layer. Modes are `"cut"`, `"line"`,
-`"fill"` and `"guide"`. Output lists layers as engrave, custom layers, score,
-cut, guide, so machines engrave before cutting.
+Use `layer(name, mode, color)` to define a custom layer. Its mode is
+`"cut"`, `"line"`, `"fill"` or `"guide"`.
 
-Rules applied when a part is finished:
+Files list layers in this order: engrave, custom layers, score, cut, guide.
+Set the actual operation order, power and speed in your laser software.
+See [Laser software](docs/compatibility.md) for import details.
+
+When a part is rendered:
 
 - The part's **material** is the union of its cut layer shapes.
 - Engrave, score and custom layers are clipped to the material, so nothing is
@@ -170,6 +188,9 @@ Rules applied when a part is finished:
 
 ## Parts and sheets
 
+Use `part()` to name a component and set its quantity. Wrap parts in
+`material()` when they share a thickness, kerf and material name:
+
 ```kerf
 material(thickness = 4, kerf = 0.12, name = "birch") {
   part("side", qty = 2) finger_rect([100, 60], "out");
@@ -182,9 +203,12 @@ material(thickness = 4, kerf = 0.12, name = "birch") {
 - Shapes outside any part form one part named `part`.
 - `material(thickness, kerf, name) { ... }` sets those special variables for
   its children.
-- With `$layout = "pack"` parts are grouped by material and thickness, copied
-  `qty` times, rotated 90° if that makes them fit, and shelf-packed onto
-  sheets of `$sheet`. Parts larger than the sheet are reported.
+- With `$layout = "pack"`, parts are grouped by material and thickness and
+  repeated `qty` times. They are arranged in rows on sheets of `$sheet` and
+  may be rotated 90° to fit. Parts larger than the sheet produce a warning.
+
+See [Parts and sheets](docs/parts-and-sheets.md) for spacing, layout and
+export examples.
 
 ## Built-in modules
 
@@ -204,11 +228,22 @@ material(thickness = 4, kerf = 0.12, name = "birch") {
 | `polyline(points, closed = false)`                         |                                                                              |
 | `arc(r, start = 0, end = 90)`                              | arc line, angles in degrees                                                  |
 
+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). The
+playground, the command line and `kerfscript.wasm` have `Atkinson`
+(Atkinson Hyperlegible) built in.
+
 ### Transforms
 
-`translate([x, y])`, `rotate(a, center = [x, y])`, `scale(s)` or
-`scale([sx, sy])`, `mirror([nx, ny])` (mirror across the line through the
-origin with that normal), `multmatrix(m)` with a 2x3 matrix.
+| 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(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
 
@@ -217,7 +252,7 @@ origin with that normal), `multmatrix(m)` with a 2x3 matrix.
 | `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                                       |
@@ -233,48 +268,115 @@ origin with that normal), `multmatrix(m)` with a 2x3 matrix.
 
 ### Other
 
-`echo(...)` prints values, `assert(cond, message)` stops with the message when
-`cond` is false, `children(i)`.
+| 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
 
-Math (degrees): `abs sign floor ceil round sqrt pow exp ln log sin cos tan
-asin acos atan atan2 min max clamp lerp norm cross`.
-
-Lists and strings: `len concat reverse sum slice str chr ord upper lower split
-join search contains lookup`.
-
-Types: `is_num is_string is_bool is_list is_undef is_function type_of`.
-
-Random: `rands(min, max, count, seed)` is repeatable for the same seed.
-
-Text: `text_width(text, size, font)` returns the advance width;
-`text_metrics(text, size, font)` returns `[advance, [[x0, y0], [x1, y1]], ascent, descent]`.
-
-Joinery: `finger_count(length, finger)` returns the finger count
-`finger_rect` uses for that edge.
+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(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 |
+
+### Types
+
+`is_num(value)`, `is_string(value)`, `is_bool(value)`, `is_list(value)`,
+`is_undef(value)` and `is_function(value)` return a boolean.
+`type_of(value)` returns the type name as a string.
+
+### Random values
+
+`rands(min, max, count, seed = 1)` returns a list of numbers between the
+bounds. The same seed gives the same sequence.
+
+### Text measurements
+
+`text_width(text, size, font)` returns the advance width, including glyph
+spacing. `text_metrics(text, size, font)` returns
+`[advance, [[x0, y0], [x1, y1]], ascent, descent]`.
+
+Both require the font to be available to the renderer, just like `text()`.
+
+### Joint dimensions
+
+`finger_count(length, finger)` returns the odd finger count used by
+`finger_rect()` for an edge of that length.
 
 ## Customizer comments
 
-Top-level assignments with a plain value (number, string, boolean or list of
-numbers) are listed as parameters by `kerf params` and by editors:
+Top-level assignments with a literal number, string, boolean or numeric
+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;
 ```
 
-The format matches OpenSCAD customizer comments, so existing editors can show
-KerfScript parameters.
+- `/* [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.
 
 ## Standard library
 
-`use <kerf/box>`:
+Load the box modules with `use <kerf/box>`:
 
 - `box([w, d, h], lid = false, finger)` makes the six (or five) panels of a
   finger-jointed box as parts `bottom`, `lid`, `front`, `back`, `left`,
@@ -286,10 +388,42 @@ KerfScript parameters.
 - **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
 
-Renderers stop programs that recurse deeper than about a thousand calls, loop
-over more than a million items, or run more than five million steps, with an
-error instead of hanging.
+The interpreter limits call depth to 1,000 for modules and 2,000 for
+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`. 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 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).