@mylasertools/kerfscript 0.0.0-stage → 0.2.0

package/docs/getting-started.md

@@ -0,0 +1,98 @@
+# 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.
+
+## Your first part
+
+Open the playground, clear the editor and type:
+
+```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.
+
+## Holes
+
+`difference()` keeps the first shape and removes the rest from it:
+
+```kerf
+difference() {
+  rect([80, 50], r = 4);
+  translate([10, 25]) circle(d = 5);
+  translate([70, 25]) circle(d = 5);
+}
+```
+
+`translate([x, y])` moves what follows it. The y axis points up, and
+`rect()` starts at `[0, 0]` unless you pass `center = true`.
+
+## Engraving and scoring
+
+Wrap shapes in `engrave()` to engrave their area, or `score()` to mark their
+outline without cutting through:
+
+```kerf
+difference() {
+  rect([80, 50], r = 4);
+  translate([10, 25]) circle(d = 5);
+  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");
+```
+
+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.
+
+## Settings
+
+A top-level variable with a comment in square brackets becomes a slider:
+
+```kerf
+width = 80; // [40:5:200]
+height = 50; // [30:5:120]
+label = "Oak";
+
+difference() {
+  rect([width, height], r = 4);
+  translate([10, height / 2]) circle(d = 5);
+  translate([width - 10, height / 2]) circle(d = 5);
+}
+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.
+
+## 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:
+
+```kerf
+$kerf = 0.15;
+```
+
+Cut the [calibration square](../examples/calibration-square.kerf) once to
+measure yours. [Kerf](kerf.md) explains how.
+
+## 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.
+
+## 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

package/docs/javascript.md

@@ -0,0 +1,98 @@
+# 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.
+
+```sh
+npm install @mylasertools/kerfscript
+```
+
+## render()
+
+```js
+import { render } from '@mylasertools/kerfscript';
+
+const result = render(source, {
+  params: { width: 200 },
+  fonts: { Inter: await (await fetch('/Inter.ttf')).arrayBuffer() },
+  defaultFont: 'Inter',
+  sheet: [600, 400],
+});
+```
+
+### 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                                             |
+
+### Result
+
+| 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                                                                                            |
+
+`paths` is for apps that draw the result themselves. Fill `regions` with the
+even-odd rule on `fill` layers, and stroke `lines`.
+
+## parameters()
+
+```js
+import { parameters } from '@mylasertools/kerfscript';
+
+parameters(source).parameters;
+// [{ name, caption, group, type, initial, min, max, step, options, span }]
+```
+
+`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:
+
+```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]);
+```
+
+## 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.
+
+```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
+  }
+}
+```
+
+## 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.

package/docs/kerf.md

@@ -0,0 +1,70 @@
+# 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.
+
+## Setting it
+
+```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.
+
+Only closed outlines on cut layers are offset. Engraving, scoring and open cut
+lines (like a living hinge) are left as drawn.
+
+You can set the kerf for one material only, together with its thickness:
+
+```kerf
+material(thickness = 4, kerf = 0.12, name = "birch") {
+  part("side", qty = 2) finger_rect([100, 60], "out");
+}
+```
+
+On the command line, `--kerf 0.1` overrides the value for every part.
+
+## 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.
+
+Measure each material you use. Thicker material usually has a wider kerf, and
+the kerf can differ between the top and bottom face.
+
+## 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:
+
+- 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.
+
+Set `$thickness` to the thickness you measured rather than the one on the
+label, and joints follow.
+
+## 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.

package/docs/layers.md

@@ -0,0 +1,74 @@
+# 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`.
+
+## 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  |
+
+```kerf
+difference() {
+  circle(d = 90);
+  circle(d = 6);
+}
+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.
+
+## Areas and lines
+
+Layers hold two kinds of geometry:
+
+- **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.
+
+`stroke(width)` turns lines into areas, for engraving a line of a given
+width. `outline()` turns areas into their outline lines.
+
+## The material
+
+When a part is finished, KerfScript takes the union of everything on the cut
+layer as the **material**. Then:
+
+- 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.
+
+## Your own layers
+
+`layer(name, mode, color)` makes a layer of your own, for example a second
+engraving pass at a different power:
+
+```kerf
+rect([60, 40]);
+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"`.
+
+## 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.
+
+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.

package/docs/openscad.md

@@ -0,0 +1,67 @@
+# Coming from OpenSCAD
+
+KerfScript borrows OpenSCAD's syntax on purpose: if you have written
+OpenSCAD, you can read KerfScript and write it within minutes. It is not a
+drop-in replacement. It only makes flat parts, and a few rules are different.
+OpenSCAD files do not run unchanged.
+
+## The same
+
+- Statements, modules, functions, `for`, `if`, `let`, `each`, list
+  comprehensions, ranges like `[0:2:10]`, function literals.
+- `children()`, `children(i)` and `$children`.
+- Special variables that start with `$` are dynamically scoped, and `$fn`,
+  `$fa` and `$fs` set curve resolution.
+- 2D shapes: `square()` (also called `rect()`), `circle(r)` or `circle(d =)`,
+  `polygon(points, paths)`, `text()`.
+- Transforms: `translate`, `rotate`, `scale`, `mirror`, `multmatrix`.
+- Combining: `union`, `difference`, `intersection`, `hull`, `offset(r)`,
+  `offset(delta, chamfer)`.
+- `echo()`, `assert()`, `use <...>` and `include <...>`.
+- Customizer comments: `// [40:5:400]`, `/* [Group] */`, `/* [Hidden] */`,
+  and captions on the line above. Tools that read OpenSCAD settings read
+  these.
+
+## Different
+
+|             | OpenSCAD                                      | KerfScript                                                      |
+| ----------- | --------------------------------------------- | --------------------------------------------------------------- |
+| Output      | a solid, as STL, 3MF and more                 | a cut file, as SVG or DXF                                       |
+| Dimensions  | 3D, and 2D for export                         | 2D only                                                         |
+| Assignments | the last one in a scope wins everywhere in it | run in order; a later one takes effect from that line           |
+| Errors      | many mistakes give `undef` and a warning      | type mistakes stop the program, naming the line                 |
+| `color()`   | colours a shape                               | not available; use `cut()`, `score()`, `engrave()` or `layer()` |
+| Fonts       | system fonts                                  | only fonts you pass in, so a file renders the same everywhere   |
+| Libraries   | any file on disk                              | the standard library and whatever the host allows               |
+
+## Not in KerfScript
+
+3D modules (`cube`, `sphere`, `cylinder`, `polyhedron`,
+`linear_extrude`, `rotate_extrude`, `projection`), `minkowski`, `resize`,
+`color`, `import`, `surface` and `render`. Each stops with an error that
+names it, so you find out at once.
+
+## Only in KerfScript
+
+- Layers: `cut()`, `score()`, `engrave()`, `guide()` and `layer()`.
+  See [Layers](layers.md).
+- Kerf compensation with `$kerf`. See [Kerf](kerf.md).
+- Parts, quantities, materials and sheet packing: `part()`, `material()`,
+  `$sheet`, `$gap`. See [Parts and sheets](parts-and-sheets.md).
+- Joinery that reads `$thickness`: `finger_rect`, `finger_holes`, `tslot`,
+  `living_hinge`.
+- Lines as well as areas: `line()`, `polyline()`, `arc()`, `path()`,
+  `stroke()` and `outline()`.
+- Shapes OpenSCAD lacks: `ellipse`, `regular_polygon`, `star`, rounded
+  `rect(r =)`.
+- `text_width()` and `text_metrics()`, to size a part to its text.
+
+## Porting a 2D design
+
+1. Drop `linear_extrude()` and any 3D parts.
+2. Replace `color()` with the layer the shape belongs on.
+3. Check assignments: code that relied on a later assignment overriding an
+   earlier one should assign once.
+4. Pass the fonts your `text()` calls use.
+5. Add `$kerf` and `$thickness`, and replace hand-made finger joints with
+   `finger_rect()` if you want them to follow the material.

package/docs/parts-and-sheets.md

@@ -0,0 +1,68 @@
+# Parts and sheets
+
+A design often has more than one piece. KerfScript lets you name each piece,
+say how many you need and what it is cut from, and lays them out on sheets.
+
+## Parts
+
+```kerf
+part("side", qty = 2) rect([100, 60]);
+part("base") rect([100, 100]);
+```
+
+`part(name, qty = 1)` makes a named part. Everything inside it is one piece
+with its own layers. Shapes outside any part form one part called `part`.
+
+Parts show up in the part list with their size and cut length, which the
+playground and `kerf check` print.
+
+## Materials
+
+Each part records `$thickness`, `$kerf` and `$material` where it is made.
+`material()` sets all three for the parts inside it:
+
+```kerf
+material(thickness = 3, kerf = 0.15, name = "plywood") {
+  part("front") rect([100, 60]);
+  part("back") rect([100, 60]);
+}
+material(thickness = 2, kerf = 0.1, name = "acrylic") {
+  part("window") rect([80, 40]);
+}
+```
+
+## Sheets
+
+With the default `$layout = "pack"`, KerfScript:
+
+1. groups parts by material and thickness,
+2. copies each part `qty` times,
+3. turns a part 90° when that makes it fit,
+4. packs them in rows onto sheets of `$sheet` (600 by 400 mm by default),
+   with `$gap` millimetres between parts and around the edge.
+
+A part bigger than the sheet gives a warning. With `$layout = "none"` parts
+stay where your program put them.
+
+```kerf
+$sheet = [300, 200];
+$gap = 4;
+```
+
+## One file per sheet
+
+The design above makes two sheets: one of plywood and one of acrylic. The
+combined SVG shows every sheet stacked one above the other, which is useful
+for a preview but is **not** a cutting job: the sheets are different
+materials.
+
+Cut each sheet as its own job:
+
+- On the command line, `--split` writes one file per sheet
+  (`design-1.svg`, `design-2.svg`, ...). `kerf check` lists the sheets with
+  their material and thickness.
+- From JavaScript, `result.sheets` has an SVG and a DXF for each sheet, with
+  its `material` and `thickness`.
+
+Before cutting, check that each file's material and thickness match the
+sheet in your machine.

package/docs/versions.md

@@ -0,0 +1,43 @@
+# Versions
+
+KerfScript has two version numbers.
+
+- The **language version** (now 0.1) covers what `.kerf` files mean: the
+  syntax, the built-in modules and functions, and the rules for layers, kerf
+  and parts. The [language reference](../LANGUAGE.md) describes one language
+  version.
+- The **package version** (now 0.2.0) is the version of the interpreter, the
+  `kerf` command and the JavaScript API. It changes more often: bug fixes,
+  new output options and API additions do not change the language.
+
+The site footer, `kerf --version` and the `VERSION` and `LANGUAGE_VERSION`
+exports show both.
+
+## Before 1.0
+
+KerfScript is young, and the language may still change before 1.0. What we
+promise in the meantime:
+
+- **Changes are written down.** Every change that can alter what a file
+  produces is listed in the changelog under the version that made it.
+- **Files keep running where we can manage it.** A program that worked keeps
+  working, or stops with an error that says what to change. It does not
+  silently start cutting something different.
+- **Geometry changes are called out.** If the same file starts producing
+  different geometry, for example after a packing or text layout fix, the
+  changelog says which designs are affected.
+- **Breaking changes raise the language version.** Package releases within
+  one language version do not remove or rename anything in the language.
+
+## From 1.0
+
+From language version 1.0, `.kerf` files written for 1.x keep producing the
+same parts in every later 1.x interpreter, apart from bug fixes listed in the
+changelog. New features are additions. Anything that would change existing
+files waits for 2.0.
+
+## Pinning a version
+
+Hosts that store designs, like MyLaserTools, record which interpreter
+version a design was published with, so a stored design can be checked
+against later versions before it is upgraded.

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@mylasertools/kerfscript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "KerfScript: a programming language for laser cutting. Write parametric 2D parts with cut, score and engrave layers, kerf compensation and joinery, and export SVG or DXF.",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "author": "MyLaserTools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mylasertools-com/kerfscript.git"
+  },
+  "bugs": "https://github.com/mylasertools-com/kerfscript/issues",
+  "keywords": [
+    "kerfscript",
+    "laser-cutting",
+    "parametric",
+    "cad",
+    "programming-language",
+    "svg",
+    "dxf",
+    "finger-joints",
+    "living-hinge",
+    "kerf"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./cli": "./dist/cli.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "kerf": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "LANGUAGE.md",
+    "LICENSE",
+    "COMMERCIAL-LICENSE.md",
+    "THIRD-PARTY-NOTICES.md",
+    "CHANGELOG.md",
+    "TRADEMARKS.md",
+    "CLA.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/stdlib.mjs && tsc -p tsconfig.json && node scripts/build.mjs",
+    "test": "node --test",
+    "check": "npm run build && npm test",
+    "examples": "node scripts/examples.mjs",
+    "site": "npm run build && npm --prefix site run build",
+    "site:serve": "npm --prefix site run preview",
+    "prepack": "npm run check",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "compat": "node scripts/compat.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "clipper2-ts": "2.0.1-18",
+    "esbuild": "0.25.12",
+    "marked": "15.0.12",
+    "opentype.js": "1.3.4",
+    "prettier": "3.6.2",
+    "typescript": "5.9.3"
+  },
+  "homepage": "https://kerfscript.mylasertools.com"
+}