@mylasertools/kerfscript 0.2.0 → 0.3.0

package/docs/getting-started.md

@@ -1,24 +1,24 @@
 # Getting started
 
-This guide takes you from an empty file to a cut file in about ten minutes.
-You need nothing installed: the [playground](https://kerfscript.mylasertools.com/playground/)
-runs KerfScript in your browser.
+Make a small sign with two hanging holes and engraved text. You can follow
+this guide in the [playground](https://kerfscript.mylasertools.com/playground/)
+without installing anything.
 
 ## Your first part
 
-Open the playground, clear the editor and type:
+Clear the playground editor and enter:
 
 ```kerf
 rect([80, 50], r = 4);
 ```
 
-That is a rounded rectangle, 80 by 50 mm. Units are always millimetres. A
-shape that is not on any other layer is **cut**, so this is a part you could
-cut out now.
+This draws an 80 × 50 mm rectangle with 4 mm corner radii. KerfScript uses
+millimetres for lengths and degrees for angles. Shapes go on the cut layer
+unless you assign another layer.
 
 ## Holes
 
-`difference()` keeps the first shape and removes the rest from it:
+Replace the rectangle with this code:
 
 ```kerf
 difference() {
@@ -28,13 +28,16 @@ difference() {
 }
 ```
 
-`translate([x, y])` moves what follows it. The y axis points up, and
-`rect()` starts at `[0, 0]` unless you pass `center = true`.
+`difference()` subtracts the two circles from the rectangle. Each hole is
+5 mm across, centred 10 mm from a side and halfway up the sign.
+
+`translate([x, y])` moves a shape. The x axis points right and the y axis
+points up. A rectangle starts at `[0, 0]`; use `center = true` to centre it
+on that point.
 
 ## Engraving and scoring
 
-Wrap shapes in `engrave()` to engrave their area, or `score()` to mark their
-outline without cutting through:
+Add a scored border and engraved text:
 
 ```kerf
 difference() {
@@ -43,15 +46,19 @@ difference() {
   translate([70, 25]) circle(d = 5);
 }
 score() translate([20, 10]) rect([40, 30], r = 2);
-engrave() translate([40, 25]) text("Oak", size = 10, halign = "center", valign = "center");
+engrave() translate([40, 25])
+  text("Oak", size = 10, halign = "center", valign = "center");
 ```
 
-Engraving and scoring are clipped to the material, so nothing is marked over
-a hole or off the edge. [Layers](layers.md) explains the rest.
+`score()` marks the border's outline. `engrave()` fills the letters. Both
+stay within the sign's cut outline, excluding the holes. The playground
+supplies a font for this example.
+
+See [Layers](layers.md) for custom layers and guide lines.
 
 ## Settings
 
-A top-level variable with a comment in square brackets becomes a slider:
+Give dimensions names so you can change them without editing every shape:
 
 ```kerf
 width = 80; // [40:5:200]
@@ -67,32 +74,42 @@ engrave() translate([width / 2, height / 2])
   text(label, size = 10, halign = "center", valign = "center");
 ```
 
-Move a slider in the playground and the number in the code changes with it.
-[Settings](customizer.md) covers groups, captions and menus.
+The comments create sliders for width and height. `[40:5:200]` means a
+minimum of 40, a step of 5 and a maximum of 200. `label` becomes a text
+field. The text and holes stay centred as the dimensions change.
+
+In the playground, changing a control also updates its value in the code.
+See [Settings](customizer.md) for menus, groups and captions.
 
 ## Kerf
 
-The laser burns away a thin line of material, the **kerf**. Tell KerfScript
-how wide it is and parts come out the size you typed:
+The beam removes some material along each cut. To account for that width,
+add your measured kerf near the top of the program:
 
 ```kerf
 $kerf = 0.15;
 ```
 
-Cut the [calibration square](../examples/calibration-square.kerf) once to
-measure yours. [Kerf](kerf.md) explains how.
+Here, `0.15` is an example in millimetres. Use the
+[calibration square](../examples/calibration-square.kerf) to measure a value
+for your machine and material. [Kerf](kerf.md) explains the measurement and
+how it affects the exported outlines.
 
 ## Getting the file
 
-In the playground, press **SVG** or **DXF**. Open the SVG in your laser
-software: cut lines are red, score lines blue and engraving black, each on its
-own layer. Set power, speed and the order of operations there, as you would
-for any other file. [Laser software](compatibility.md) has notes for the
-programs we have checked.
+Choose **SVG** or **DXF** in the playground, then open the file in your laser
+software. Assign the cut, score and engrave layers their power, speed and
+operation order. In DXF, set engraved areas to fill.
+
+If you used `$kerf`, leave kerf compensation off in the laser software to
+avoid applying it twice. The [import guide](compatibility.md) covers sizes,
+layers and tested programs.
+
+Download **.kerf** to keep an editable copy of the design.
 
 ## Next
 
-- [Layers](layers.md): cut, score, engrave and your own layers
-- [Parts and sheets](parts-and-sheets.md): several pieces, quantities, materials
-- [Coming from OpenSCAD](openscad.md): what is the same and what is not
-- [Language reference](../LANGUAGE.md): everything in one page
+- [Layers](layers.md): separate cutting, scoring and engraving.
+- [Parts and sheets](parts-and-sheets.md): arrange several parts by material.
+- [Coming from OpenSCAD](openscad.md): adapt an existing 2D design.
+- [Language reference](../LANGUAGE.md): look up syntax and functions.

package/docs/javascript.md

@@ -1,8 +1,8 @@
 # JavaScript API
 
-The same interpreter that runs the command line and the playground is a
-TypeScript library with no native code. It runs in browsers, web workers,
-Node.js and edge runtimes.
+Add KerfScript rendering to a JavaScript application with the
+`@mylasertools/kerfscript` package. The library runs in browsers and Node.js
+and includes TypeScript definitions.
 
 ```sh
 npm install @mylasertools/kerfscript
@@ -10,89 +10,146 @@ npm install @mylasertools/kerfscript
 
 ## render()
 
+Pass a program as a string. The result contains its geometry, files, parts
+and warnings:
+
 ```js
 import { render } from '@mylasertools/kerfscript';
 
+const source = 'width = 80; rect([width, 50]);';
 const result = render(source, {
-  params: { width: 200 },
-  fonts: { Inter: await (await fetch('/Inter.ttf')).arrayBuffer() },
-  defaultFont: 'Inter',
+  params: { width: 120 },
   sheet: [600, 400],
+  margin: 0,
 });
+
+console.log(result.svg);
 ```
 
+This exports a 120 × 50 mm rectangle. `params` overrides `width` without
+changing the source string.
+
 ### Options
 
-| Option        | Meaning                                                                              |
-| ------------- | ------------------------------------------------------------------------------------ |
-| `params`      | setting values by name, overriding the top-level assignments                         |
-| `fonts`       | font files by name, as `ArrayBuffer` or `Uint8Array`                                 |
-| `defaultFont` | font used when `text()` names none                                                   |
-| `resolve`     | `(path) => source` for `use <path>` and `include <path>` beyond the standard library |
-| `kerf`        | override kerf compensation for every part                                            |
-| `layout`      | `"pack"` or `"none"`                                                                 |
-| `sheet`       | `[width, height]` in mm                                                              |
-| `gap`         | space between packed parts                                                           |
-| `margin`      | space around the sheet edge (default: `gap`)                                         |
-| `guides`      | include guide layer geometry                                                         |
-| `maxSteps`    | step limit before the program is stopped                                             |
+| 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:
 
-### Result
+```js
+const response = await fetch('/fonts/Inter.ttf');
+const font = await response.arrayBuffer();
+const result = render(source, {
+  fonts: { Inter: font },
+  defaultFont: 'Inter',
+});
+```
+
+The URL should point to a font file provided by your application.
 
-| Field             | Contents                                                                                                   |
-| ----------------- | ---------------------------------------------------------------------------------------------------------- |
-| `svg`             | every sheet in one SVG, for previews                                                                       |
-| `width`, `height` | size of that combined SVG in mm                                                                            |
-| `sheets`          | one entry per sheet: `width`, `height`, `material`, `thickness`, `svg`, `dxf`, `paths`, `items`            |
-| `parts`           | `name`, `qty`, `width`, `height`, `pieces`, `cutLength`, `thickness`, `kerf`, `material`                   |
-| `paths`           | per layer: `name`, `mode`, `color`, `d` (all path data), `regions` (closed outlines), `lines` (open lines) |
-| `layers`          | the layer definitions in output order                                                                      |
-| `warnings`        | problems that did not stop the render                                                                      |
-| `echoes`          | `echo()` output                                                                                            |
+### Result
 
-`paths` is for apps that draw the result themselves. Fill `regions` with the
-even-odd rule on `fill` layers, and stroke `lines`.
+| 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
+materials.
+
+For a custom preview, `d` contains all paths in a layer. `regions` contains
+closed outlines and `lines` contains open paths. On a `fill` layer, draw
+regions with the even-odd fill rule and draw open paths as strokes.
 
 ## parameters()
 
+Read a program's editable settings without rendering its geometry:
+
 ```js
 import { parameters } from '@mylasertools/kerfscript';
 
-parameters(source).parameters;
-// [{ name, caption, group, type, initial, min, max, step, options, span }]
+const source = 'width = 80; // [40:5:200]\nrect([width, 50]);';
+const settings = parameters(source).parameters;
 ```
 
-`type` is `"number"`, `"string"` or `"boolean"`; a list of numbers is
-`"number"` with a list `initial`, as in OpenSCAD's parameter JSON. `span` is
-`[start, end]`, the offsets of the value in the source, so an editor can change
-a value without touching anything else:
+Each setting includes `name`, `caption`, `group`, `type`, `initial` and
+`span`. Ranges add `min`, `max` and `step`; menus add `options`.
+
+`type` is `"number"`, `"string"` or `"boolean"`. A numeric vector has
+type `"number"` and an array as its `initial` value.
+
+`span` gives the source offsets `[start, end]` of the value. An editor can
+use them to update one setting:
 
 ```js
-const p = parameters(source).parameters.find((p) => p.name === 'width');
-const next = source.slice(0, p.span[0]) + '200' + source.slice(p.span[1]);
+const width = settings.find((p) => p.name === 'width');
+if (width) {
+  const next = source.slice(0, width.span[0]) + '120' + source.slice(width.span[1]);
+}
 ```
 
+Read the settings again after editing the source; the offsets refer to the
+string passed to `parameters()`.
+
 ## Errors
 
-Errors are thrown as `KerfError` with `line` and `col`. They also carry
-`echoes`, the `echo()` output up to the error, and `missingFonts` when a font
-was not supplied, so an app can load those fonts and render again.
+Language errors use `KerfError`. Its `line` and `col` identify the source
+location when available, and `echoes` contains output produced before the
+error. `missingFonts` lists fonts the application needs to supply.
 
 ```js
 import { KerfError, render } from '@mylasertools/kerfscript';
 
 try {
-  render(source, { fonts });
-} catch (e) {
-  if (e instanceof KerfError && e.missingFonts) {
-    // load e.missingFonts, then render again
+  render('rect([80, 50]);');
+} catch (error) {
+  if (error instanceof KerfError) {
+    console.error(error.message, error.line, error.col);
+  } else {
+    throw error;
   }
 }
 ```
 
 ## Running untrusted code
 
-Programs cannot read files or the network: `use` and `include` reach only the
-standard library and whatever your `resolve` returns. Step and recursion limits
-stop runaway programs. A render is still ordinary synchronous work, so run
-it in a web worker, and stop the worker if it takes too long.
+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.
+
+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:
+
+```js
+import { render, DEFAULT_LIMITS } from '@mylasertools/kerfscript';
+
+render(source, { limits: { maxPoints: DEFAULT_LIMITS.maxPoints / 2 } });
+```
+
+KerfScript programs have no direct file or network access. `use` and
+`include` can load the standard library and sources returned by your
+`resolve` callback. Restrict that callback to libraries you intend to expose.

package/docs/kerf.md

@@ -1,27 +1,25 @@
 # Kerf
 
-The laser beam burns away a thin line of material as it cuts. That width is
-the **kerf**, usually somewhere between 0.05 and 0.3 mm depending on the
-machine, the lens, the material and its thickness. Without compensation every
-part comes out smaller than drawn by about one kerf, and every hole bigger.
-For a sign that hardly matters. For finger joints and press fits it decides
-whether the box holds together.
+Kerf is the width of material removed by a laser cut. Allowing for it helps
+parts finish at the intended size and joints fit together. Measure it for
+the material and cutting settings you use.
 
 ## Setting it
 
+Set `$kerf` in millimetres:
+
 ```kerf
 $kerf = 0.15;
 ```
 
-KerfScript offsets every cut outline outward by half the kerf when it writes
-the file. The beam then runs half a kerf outside the part and burns away
-material that was never part of it, so the part ends up the size you typed.
-Holes are offset inward the same way, so they end up the size you typed too.
+With this value, KerfScript moves an outer cut path outward by 0.075 mm and
+a hole's path inward by the same amount. The offset compensates for material
+removed on either side of the beam.
 
-Only closed outlines on cut layers are offset. Engraving, scoring and open cut
-lines (like a living hinge) are left as drawn.
+Only closed cut outlines receive the offset. Engraving, scoring and open
+cuts such as living hinges keep their original paths.
 
-You can set the kerf for one material only, together with its thickness:
+To use a value for a particular material, set it inside `material()`:
 
 ```kerf
 material(thickness = 4, kerf = 0.12, name = "birch") {
@@ -29,42 +27,41 @@ material(thickness = 4, kerf = 0.12, name = "birch") {
 }
 ```
 
-On the command line, `--kerf 0.1` overrides the value for every part.
+On the command line, `--kerf 0.1` overrides the value for every part. Apply
+kerf compensation in either KerfScript or your laser software, once per job.
 
 ## Measuring your kerf
 
 1. Cut the [calibration square](../examples/calibration-square.kerf) with
-   `$kerf = 0`.
-2. Measure the outside of the square with calipers, across the middle.
-3. Your kerf is `100 - measured`. If the square measures 99.82 mm, use
-   `$kerf = 0.18`.
-4. Cut it again with that value. The square should now be 100 mm and the hole
-   20 mm. If the square is still small and the hole big, raise `$kerf` a
-   little; if the square is big, lower it.
+   `$kerf = 0`. Leave any offset in your laser software at zero too.
+2. Measure the square across the middle with calipers.
+3. Subtract that measurement from 100 mm. A square measuring 99.82 mm gives
+   a kerf of 0.18 mm.
+4. Set `$kerf = 0.18` and cut another sample. Check the outside against
+   100 mm and the hole against 20 mm, then adjust the value if needed.
 
-Measure each material you use. Thicker material usually has a wider kerf, and
-the kerf can differ between the top and bottom face.
+Repeat the measurement when the material or cutting settings change. Thick
+material can have a different cut width at its top and bottom faces.
 
 ## Checking a fit
 
-For joints, the [kerf and fit test](../examples/kerf-test.kerf) cuts a row of
-slots from slightly narrower to slightly wider than `$thickness`. Push a scrap
-of the same sheet into each slot:
+After calibrating kerf, measure your sheet's thickness and set `$thickness`
+to that measurement. The nominal thickness on a material label can differ
+from the sheet itself.
 
-- if the slot marked `0` is snug, your kerf and thickness are right;
-- if a `+` slot fits best, the sheet is thicker than `$thickness` says
-  (plywood often is);
-- if a `-` slot fits best, it is thinner.
+The [kerf and fit test](../examples/kerf-test.kerf) cuts slots slightly
+narrower and wider than `$thickness`. Try a scrap from the same sheet in each
+slot. A positive label means a wider slot; a negative label means a narrower
+one. Choose the fit you need and use the result to refine your dimensions.
 
-Set `$thickness` to the thickness you measured rather than the one on the
-label, and joints follow.
+Both kerf and sheet thickness affect the fit. A tight or loose slot alone
+does not tell you which value needs adjusting.
 
 ## Limits
 
-- A hole, slot or notch narrower than the kerf cannot be cut: the beam is
-  wider than the gap, so compensation closes it. KerfScript warns when that
-  happens to a hole.
-- Thin bridges and fingers come out the right size but are fragile, and can
-  char in thin material. Keep them several times wider than the kerf.
-- The beam is not perfectly straight in thick material, so cut faces taper a
-  little. Compensation works on the average width.
+- Compensation can close a hole or notch narrower than the kerf. KerfScript
+  warns when a hole disappears.
+- Narrow bridges and fingers may be fragile or char during cutting even
+  when their dimensions are correct. Test small features in your material.
+- Compensation adjusts the 2D outline. It does not remove taper from the
+  cut face in thick material.

package/docs/layers.md

@@ -1,17 +1,19 @@
 # Layers
 
-Every shape in KerfScript is on a layer, and the layer decides what the
-laser does with it. Shapes that are not wrapped in a layer module are on
-`cut`.
+Layers separate cutting, scoring and engraving in the exported file. Use
+them to give different parts of a design different operations in your laser
+software. Unassigned shapes go on the `cut` layer.
 
 ## The built-in layers
 
-| Layer     | Wrap shapes in | Colour in the file | What the laser does                               |
-| --------- | -------------- | ------------------ | ------------------------------------------------- |
-| `engrave` | `engrave()`    | black `#000000`    | engraves the area of the shapes                   |
-| `score`   | `score()`      | blue `#0000ff`     | marks lines and outlines without cutting through  |
-| `cut`     | `cut()`        | red `#ff0000`      | cuts the outlines through, with kerf compensation |
-| `guide`   | `guide()`      | light blue         | nothing; shown only when you ask for guide lines  |
+| 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:
 
 ```kerf
 difference() {
@@ -22,53 +24,85 @@ engrave() difference() { circle(d = 74); circle(d = 68); }
 score() circle(d = 84);
 ```
 
-`#` and `%` in front of a module call move it to the guide layer, which is
-handy for checking where something is without cutting it.
+The layer describes the operation. Set its power, speed and passes in your
+laser software.
+
+Place `#` or `%` before a module call to move it to the guide layer.
+Guides are excluded from the output unless you request them with
+`--guides` on the command line or `guides: true` in the API.
 
 ## Areas and lines
 
-Layers hold two kinds of geometry:
+Shapes such as `rect()`, `circle()` and `text()` define areas. On an
+engrave layer, those areas are filled. On cut and score layers, their
+outlines become paths.
+
+`line()`, `polyline()`, `arc()` and `living_hinge()` produce lines. They
+remain lines on every layer. A living hinge, for example, is a pattern of
+open cuts within a part.
+
+Use `stroke(width)` to turn a line into an area of a specified width. Use
+`outline()` to turn an area's boundary into lines.
+
+### Overlapping shapes merge
+
+The areas inside one `score()` are merged first, like a `union()`, and
+only the outline of the result is scored. Two nested circles become one
+disc, so this scores a single ring:
+
+```kerf
+circle(d = 60);
+score() {
+  circle(d = 50);
+  circle(d = 40); // inside the first circle: merged away
+}
+```
+
+To score every shape's own outline, turn each one into lines first with
+`outline()`. Lines are never merged, so this scores both rings:
 
-- **Areas** come from shapes like `rect()`, `circle()` and `text()`. On
-  `engrave` the area is filled; on `cut` and `score` its outline is followed.
-- **Lines** come from `line()`, `polyline()`, `arc()` and `living_hinge()`.
-  They are followed as they are, on any layer. On `cut` they are cut through,
-  which is how a living hinge is made.
+```kerf
+circle(d = 60);
+score() {
+  outline() circle(d = 50);
+  outline() circle(d = 40);
+}
+```
 
-`stroke(width)` turns lines into areas, for engraving a line of a given
-width. `outline()` turns areas into their outline lines.
+One `outline()` around both circles would not help: it merges them before
+it traces them. The same rule holds on the cut layer and on custom
+layers. Use `difference()` when you want the area between two outlines,
+such as a ring to engrave.
 
 ## The material
 
-When a part is finished, KerfScript takes the union of everything on the cut
-layer as the **material**. Then:
+Closed shapes on a part's cut layer define its material. KerfScript clips
+engraving, scoring and open cut lines to that area, excluding holes. Start
+with a cut shape when adding marks to a part.
 
-- engraving and scoring are clipped to the material, so nothing is marked
-  inside a hole or off the part;
-- cut lines are clipped to the material too;
-- if the material falls apart into separate pieces, you get a warning,
-  because that usually means a missing bridge.
+If the cut shapes form separate pieces, KerfScript reports a warning. Check
+for a missing connection or define the pieces as separate parts.
 
 ## Your own layers
 
-`layer(name, mode, color)` makes a layer of your own, for example a second
-engraving pass at a different power:
+Use `layer(name, mode, color)` when you need another operation, such as a
+second engraving depth:
 
 ```kerf
 rect([60, 40]);
-layer("deep", mode = "fill", color = "#00aa00") translate([10, 10]) rect([20, 20]);
+layer("deep", mode = "fill", color = "#00aa00")
+  translate([10, 10]) rect([20, 20]);
 engrave() translate([40, 20]) circle(d = 12);
 ```
 
-Modes are `"cut"`, `"line"` (score), `"fill"` (engrave) and `"guide"`.
+The rectangle and circle use separate engraving layers. You can assign each
+a different power in your laser software. Supported modes are `"cut"`,
+`"line"`, `"fill"` and `"guide"`.
 
 ## Order in the file
 
-Layers are written in this order: engrave, your own layers, score, cut,
-guide. Within the cut layer, holes and inner cuts come before outer outlines,
-so a part does not drop out before its holes are cut.
+KerfScript writes layers in this order: engrave, custom layers, score, cut,
+then guide. Within a cut layer, inner paths precede outer outlines.
 
-That order is a good default, but it does not control your machine. Most
-laser software sorts and orders operations itself. Check the cut order, and
-set power, speed and passes for each layer, in your laser software before you
-run the job.
+Laser software may reorder these paths. Check its job preview so engraving
+runs before cutting and holes are cut before the surrounding part.