@mylasertools/kerfscript 0.2.0 → 0.2.1

package/dist/render.d.cts

@@ -1,4 +1,4 @@
-import { type LayerDef } from './evaluator.cjs';
+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';
@@ -15,6 +15,7 @@ export interface RenderOptions {
     margin?: number;
     guides?: boolean;
     maxSteps?: number;
+    limits?: Partial<Limits>;
 }
 export interface PartInfo {
     name: string;

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import { type LayerDef } from './evaluator.js';
+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';
@@ -15,6 +15,7 @@ export interface RenderOptions {
     margin?: number;
     guides?: boolean;
     maxSteps?: number;
+    limits?: Partial<Limits>;
 }
 export interface PartInfo {
     name: string;

package/docs/cli.md

@@ -1,61 +1,76 @@
 # Command line
 
-The `kerf` command renders `.kerf` files to SVG, DXF or JSON. It needs
-Node.js 20 or newer and comes with the `@mylasertools/kerfscript` npm
-package.
+Use the `kerf` command to export designs, change parameters and inspect
+parts from your terminal. Install the package with Node.js 20 or newer:
 
 ```sh
 npm install --global @mylasertools/kerfscript
 kerf render box.kerf -o box.svg
 ```
 
-Or without installing:
+You can also run it through `npx`:
 
 ```sh
 npx @mylasertools/kerfscript render box.kerf -o box.svg
 ```
 
+Save a `.kerf` file from the [models](https://kerfscript.mylasertools.com/models/)
+to try these commands.
+
 ## Commands
 
 ```sh
 kerf render <file.kerf> [-o out.svg] [options]
-kerf params <file.kerf>     # settings as JSON
-kerf check <file.kerf>      # parts, sizes, cut length, sheets and warnings
+kerf params <file.kerf>
+kerf check <file.kerf>
 ```
 
+`render` exports SVG, DXF or JSON, using the output file's extension to
+choose the format. `params` lists the editable settings as JSON. `check`
+reports parts, dimensions, cut lengths, sheets and warnings.
+
 ## Options
 
-| Option                | What it does                                                           |
-| --------------------- | ---------------------------------------------------------------------- |
-| `-o, --out <file>`    | output file, `.svg`, `.dxf` or `.json`; default `<file>.svg`           |
-| `-D name=value`       | set a setting; the value is KerfScript: `40`, `"Oak"`, `true`, `[1,2]` |
-| `-p, --params <file>` | JSON file of setting values                                            |
-| `--font <file.ttf>`   | font for `text()`; repeat for more fonts. The name is the file name    |
-| `--kerf <mm>`         | override kerf compensation for every part                              |
-| `--sheet <W>x<H>`     | sheet size for packing, in mm                                          |
-| `--gap <mm>`          | space between packed parts                                             |
-| `--margin <mm>`       | space between the parts and the sheet edge (default: the gap)          |
-| `--no-pack`           | keep parts where the program placed them                               |
-| `--guides`            | include guide layer geometry                                           |
-| `--split`             | write one file per sheet (`out-1.svg`, `out-2.svg`, ...)               |
-| `-h, --help`          | show help                                                              |
-| `-v, --version`       | show the version                                                       |
+| 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 |
+
+`-D` accepts KerfScript values, including numbers, quoted strings, booleans
+and lists. For example: `-D width=200` or `-D 'name="Ada"'`.
 
 ## Examples
 
 ```sh
-kerf render sign.kerf -D 'name="Ada"' --font Inter-Bold.ttf -o ada.svg
+kerf render name-sign.kerf -D 'name="Ada"' --font Inter-Bold.ttf -o ada.svg
 kerf render box.kerf --sheet 400x300 --kerf 0.12 --split -o box.svg
 kerf render box.kerf -o box.dxf
 kerf check box.kerf
 ```
 
-Warnings go to standard error and do not stop the render. Errors stop it with
-the line and column, and a non-zero exit code.
+For multiple sheets, `--split` creates numbered files such as `box-1.svg`
+and `box-2.svg`. Use it for DXF exports of a design with several sheets.
+
+Warnings are written to standard error and allow rendering to continue.
+An error stops the command, reports its location when available and returns
+a non-zero exit code.
 
 ## Fonts
 
-KerfScript does not ship fonts and never reads system fonts, so a file
-renders the same everywhere. Pass the fonts a design uses with `--font`. A
-design that asks for `font = "Inter-Bold"` needs `--font Inter-Bold.ttf`; the
-first font given is the default.
+Supply font files with `--font` for designs that use text. 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 is the
+default for text that does not name one.

package/docs/compatibility.md

@@ -1,89 +1,64 @@
 # Laser software
 
-KerfScript writes ordinary SVG and DXF files, so any program that reads
-those can open them. This page says what we have actually checked, in which
-version, and what you still need to set up yourself.
+Export SVG or DXF from KerfScript, then set up the cutting job in your laser
+software. Check the imported size and layers before assigning power, speed
+and operation order.
 
 ## What is in the files
 
 **SVG**
 
-- Size in millimetres (`width="100mm"`), with a matching `viewBox`, so one
-  unit is one millimetre.
-- One group per layer, marked as an Inkscape layer and named after it:
-  `engrave`, your own layers, `score`, `cut`, `guide`.
-- Cut lines red `#ff0000`, score lines blue `#0000ff`, 0.1 mm hairline
-  strokes. Engraved areas are filled black `#000000` with the even-odd rule.
-- Holes and inner cuts come before outer outlines.
+- Millimetre dimensions with a matching `viewBox`.
+- Named layer groups for engraving, scoring, cutting and any custom layers.
+- Red cut paths, blue score paths and black filled engraving.
+- Inner cut paths before outer outlines in the file.
 
 **DXF**
 
-- R12 (AC1009) polylines, units set to millimetres.
-- One DXF layer per KerfScript layer, in capitals (`CUT`, `SCORE`,
-  `ENGRAVE`), with matching AutoCAD colours.
-- DXF R12 has no fills. Engraved areas arrive as outlines; set that layer to
-  fill in your laser software.
-- A DXF holds one sheet. Use `--split` for designs with several sheets.
+- R12 polylines with millimetre units.
+- Named layers such as `CUT`, `SCORE` and `ENGRAVE`.
+- Engraving as outlines. Set the engraving layer to fill in your laser software.
+- One sheet per file. Use the CLI's `--split` option for several sheets.
 
 ## Checked
 
-| Program  | Version | SVG | DXF | How                         |
-| -------- | ------- | --- | --- | --------------------------- |
-| Inkscape | 1.4.2   | yes | yes | automatic, `npm run compat` |
+| Program | Version | SVG | DXF | Checks |
+| --- | --- | --- | --- | --- |
+| Inkscape | 1.4.2 | Passed | Passed | Dimensions, layers and SVG fills |
 
-`npm run compat` renders six reference models (the calibration square, the
-kerf test, a six-panel finger-jointed box, a living hinge card, a coaster
-with an engraved ring, and a jigsaw puzzle), opens every SVG and DXF in
-Inkscape from the command line, and checks that:
-
-- the size of the drawing matches KerfScript's geometry within 0.02 mm,
-  kerf compensation included;
-- every layer arrives as a layer with the right name;
-- engraved layers are filled in the SVG.
-
-All six passed in both formats on 28 October 2026.
+Six reference models passed these import checks on 28 October 2026.
+Drawing dimensions matched within 0.02 mm, including kerf compensation.
+These results cover file imports; they do not establish a fit for a
+particular machine or material.
 
 ## Not checked yet
 
-We have not yet run the reference set through **LightBurn**, **xTool
-Studio** or **xTool Creative Space**, **RDWorks** or **LaserGRBL**, and we
-have not cut it on machines outside MyLaserTools. Until we have, treat them as
-untested: they read standard SVG and DXF, but each imports colours, layers
-and fills its own way.
-
-If you try one, we would like to hear what happened. The checklist below is
-what we look at.
+LightBurn, xTool Studio, xTool Creative Space, RDWorks and LaserGRBL have
+not yet been verified with the reference models. Import handling can differ
+between programs, especially for units, layer colours and fills.
 
 ## Checklist for a new program
 
-Open `calibration-square.svg` and `box.svg` from the
-[models](https://kerfscript.mylasertools.com/models/) and check:
-
-1. **Size.** The square is 100.15 mm wide with the default 0.15 mm kerf
-   (100 mm plus compensation), not 26.4 mm or 377.95 mm. If it is wrong, the
-   program ignored the millimetre units; look for an import DPI or unit
-   setting.
-2. **Layers.** Cut, score and engrave arrive as separate layers or colours,
-   so each can get its own power and speed.
-3. **Fill.** The engraved text on the square is filled, not just outlined.
-4. **Holes.** The hole in the square is cut, and engraving does not appear
-   inside it.
-5. **Order.** The program's cut order cuts holes before outlines. Most
-   programs have an "inner shapes first" option; turn it on.
-6. **Parts.** All six box panels arrive, none overlapping.
+Download the calibration square and box from the
+[models](https://kerfscript.mylasertools.com/models/) and check their imports:
 
-## What the file does not decide
+1. **Size:** the calibration square's cut path is 100.15 mm wide with
+   `$kerf = 0.15`, allowing for a finished 100 mm square. If the imported
+   size differs, check the unit and DPI settings.
+2. **Layers:** cutting, scoring and engraving can be assigned separate operations.
+3. **Fill:** engraved text has filled letters. For DXF, select fill in the
+   engraving layer's settings.
+4. **Holes:** cut holes remain open and contain no engraving.
+5. **Order:** the job preview cuts inner paths before outer outlines.
+6. **Parts:** the box contains all six panels without overlaps.
 
-The file describes geometry and layers. Your laser software decides how the
-machine runs it:
+## What the file does not decide
 
-- **Order of operations.** Layer order in an SVG is a hint. Most programs
-  sort operations themselves; check that engraving runs before cutting and
-  inner cuts before outer ones.
-- **Power, speed, passes and focus** for each layer and material.
-- **Material and thickness.** KerfScript records them per sheet; make sure
-  the file you send matches the sheet in the machine.
-- **Kerf.** If your laser software also applies kerf offset, turn one of them
-  off, or parts will be compensated twice.
+Set power, speed, passes and focus for your machine and material. Check the
+job preview for engraving before cutting and holes before outer outlines;
+laser software can reorder the paths in a file.
 
-Always run a test on scrap before cutting good material.
+For multiple sheets, use a separate file and matching material settings for
+each sheet. If KerfScript has already applied kerf compensation, leave the
+laser software's kerf offset at zero. Test the job on scrap before cutting
+the final material.

package/docs/customizer.md

@@ -1,9 +1,8 @@
 # Settings
 
-Top-level variables with a plain value become **settings**: sliders, menus,
-checkboxes and text boxes in the playground, on MyLaserTools, and in any tool
-that reads OpenSCAD customizer comments. The format is the same as
-OpenSCAD's.
+Expose dimensions, text and other choices as controls beside your design.
+Comments define sliders and menus, while the variable values provide their
+defaults. KerfScript uses OpenSCAD's customizer comment format.
 
 ```kerf
 /* [Size] */
@@ -24,39 +23,52 @@ wall = 3;
 rect([width, depth]);
 ```
 
+This example defines several control types. The rectangle uses `width`
+and `depth`; the other variables illustrate settings you can use elsewhere
+in a design.
+
 ## What becomes a setting
 
-A top-level assignment whose value is a number, a string, `true` or `false`,
-or a list of numbers. An expression like `width / 2` is not a setting; it is
-worked out from the others.
+A variable declared at the top level becomes a setting when its value is a
+number, string, boolean or list of numbers. Variables defined by expressions,
+such as `half_width = width / 2`, are calculated from the other values and
+do not get their own controls.
 
 ## Comments
 
-| Comment after the value           | Control                       |
-| --------------------------------- | ----------------------------- |
-| `// [40:5:400]`                   | slider from 40 to 400, step 5 |
-| `// [40:400]`                     | slider from 40 to 400         |
-| `// [200]`                        | number up to 200              |
-| `// [2, 3, 4]`                    | menu of those values          |
-| `// [round:Round, square:Square]` | menu with labels              |
-| none, on `true` or `false`        | checkbox                      |
-| none, on a string                 | text box                      |
-
-- `/* [Group name] */` starts a group for the settings below it.
-  `/* [Hidden] */` hides the ones that follow.
-- A `//` comment on its own line just above a setting is its caption.
-  A comment at the end of the line before does not count.
-- Put a blank line between a file's opening comment and its first setting,
-  so the opening comment is not taken as that setting's caption.
+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 |
+
+`/* [Size] */` starts a group named Size. `/* [Hidden] */` hides the
+settings that follow it, until another group begins.
+
+A `//` comment immediately above a variable supplies its caption. Keep the
+file's introductory comment separate with a blank line so it does not
+become the first setting's caption.
 
 ## Changing settings without editing the file
 
+The CLI accepts values with `-D` or a JSON file with `--params`:
+
 ```sh
-kerf render box.kerf -D width=200 -D 'label="Oak"'
-kerf render box.kerf --params oak.json
+kerf render box.kerf -D width=200
+kerf render box.kerf --params box-settings.json
 kerf params box.kerf
 ```
 
-`-D` values are KerfScript values, so strings need their quotes. `kerf params`
-prints the settings as JSON. From JavaScript, pass `params` to `render()` and
-read them with `parameters()`; see [JavaScript API](javascript.md).
+`box-settings.json` can contain `{"width": 200, "lid": false}`.
+Use `kerf params` to list a design's settings as JSON.
+
+String values need quotes, for example `-D 'label="Oak"'` for a design
+with a `label` setting. In JavaScript, pass values through `render()`'s
+`params` option and read the settings with `parameters()`. See the
+[JavaScript API](javascript.md).

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.