@mylasertools/kerfscript 0.0.0-stage → 0.2.1

package/docs/getting-started.md

@@ -0,0 +1,115 @@
+# Getting started
+
+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
+
+Clear the playground editor and enter:
+
+```kerf
+rect([80, 50], r = 4);
+```
+
+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
+
+Replace the rectangle with this code:
+
+```kerf
+difference() {
+  rect([80, 50], r = 4);
+  translate([10, 25]) circle(d = 5);
+  translate([70, 25]) circle(d = 5);
+}
+```
+
+`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
+
+Add a scored border and engraved text:
+
+```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");
+```
+
+`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
+
+Give dimensions names so you can change them without editing every shape:
+
+```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");
+```
+
+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 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;
+```
+
+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
+
+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): 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

@@ -0,0 +1,153 @@
+# JavaScript API
+
+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
+```
+
+## 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: 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 | 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:
+
+```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.
+
+### Result
+
+| 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';
+
+const source = 'width = 80; // [40:5:200]\nrect([width, 50]);';
+const settings = parameters(source).parameters;
+```
+
+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 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
+
+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('rect([80, 50]);');
+} catch (error) {
+  if (error instanceof KerfError) {
+    console.error(error.message, error.line, error.col);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Running untrusted code
+
+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.
+
+Memory limits stop a program before it asks for more memory than a browser
+tab can give: part copies, circle segments, list sizes, text length, shape
+points, exported points and sheets. 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

@@ -0,0 +1,67 @@
+# Kerf
+
+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;
+```
+
+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 cut outlines receive the offset. Engraving, scoring and open
+cuts such as living hinges keep their original paths.
+
+To use a value for a particular material, set it inside `material()`:
+
+```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. 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`. 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.
+
+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
+
+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.
+
+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.
+
+Both kerf and sheet thickness affect the fit. A tight or loose slot alone
+does not tell you which value needs adjusting.
+
+## Limits
+
+- 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

@@ -0,0 +1,108 @@
+# Layers
+
+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 | 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() {
+  circle(d = 90);
+  circle(d = 6);
+}
+engrave() difference() { circle(d = 74); circle(d = 68); }
+score() circle(d = 84);
+```
+
+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
+
+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:
+
+```kerf
+circle(d = 60);
+score() {
+  outline() circle(d = 50);
+  outline() circle(d = 40);
+}
+```
+
+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
+
+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.
+
+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
+
+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]);
+engrave() translate([40, 20]) circle(d = 12);
+```
+
+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
+
+KerfScript writes layers in this order: engrave, custom layers, score, cut,
+then guide. Within a cut layer, inner paths precede outer outlines.
+
+Laser software may reorder these paths. Check its job preview so engraving
+runs before cutting and holes are cut before the surrounding part.

package/docs/openscad.md

@@ -0,0 +1,71 @@
+# Coming from OpenSCAD
+
+KerfScript uses syntax familiar to OpenSCAD users, with features for laser
+cutting. Existing OpenSCAD files may need changes to run in KerfScript.
+This guide covers the shared syntax and the differences that affect a port.
+
+## The same
+
+You can use familiar building blocks:
+
+- Modules, functions, `for`, `if`, `let`, `each`, list comprehensions,
+  ranges and function literals.
+- `children()`, `children(i)` and `$children`.
+- Dynamically scoped `$` variables, plus `$fn`, `$fa` and `$fs` for curve
+  resolution.
+- 2D shapes: `square()` or `rect()`, `circle()`, `polygon()` and `text()`.
+- Transforms: `translate`, `rotate`, `scale`, `mirror` and `multmatrix`.
+- Shape operations: `union`, `difference`, `intersection`, `hull` and `offset`.
+- `echo()`, `assert()`, `use <...>` and `include <...>`.
+- Customizer comments for ranges, choices, groups and captions.
+
+See the [language reference](../LANGUAGE.md) for supported arguments.
+
+## Different
+
+| Feature | OpenSCAD | KerfScript |
+| --- | --- | --- |
+| Geometry | 3D and 2D | 2D parts for laser cutting |
+| Output | 3D formats and 2D exports | SVG and DXF with operation layers |
+| Assignments | The last assignment in a scope applies throughout that scope | Assignments take effect in order |
+| Type errors | Many produce `undef` and a warning | Stop evaluation with an error |
+| `color()` | Sets a shape's colour | Use `cut()`, `score()`, `engrave()` or `layer()` |
+| Fonts | Looks up system fonts | Uses fonts supplied by the application or CLI |
+| Libraries | Can load local files | Loads the standard library and sources allowed by the host |
+
+Assignment order is especially important when adapting a design. A value
+assigned later in a KerfScript program does not change earlier geometry.
+
+## Not in KerfScript
+
+KerfScript does not support `cube`, `sphere`, `cylinder`, `polyhedron`,
+`linear_extrude`, `rotate_extrude` or `projection`. It also does not support
+`minkowski`, `resize`, `color`, `import`, `surface` or `render`.
+
+Calls to these modules produce an error. For a design based on an extruded
+2D outline, start with that outline and remove the extrusion.
+
+## Only in KerfScript
+
+- **Operations:** `cut()`, `score()`, `engrave()`, `guide()` and `layer()`.
+- **Material settings:** `$kerf` for cut compensation and `$thickness` for
+  material-dependent joints.
+- **Parts and layout:** `part()`, `material()`, quantities, `$sheet` and `$gap`.
+- **Joinery:** `finger_rect`, `finger_holes`, `tslot` and `living_hinge`.
+- **Paths:** `line`, `polyline`, `arc`, `path`, `stroke` and `outline`.
+- **Additional shapes:** `ellipse`, `regular_polygon`, `star` and rounded
+  rectangles with `rect(r = ...)`.
+- **Text measurement:** `text_width()` and `text_metrics()`.
+
+## Porting a 2D design
+
+1. Keep the 2D geometry and remove extrusion or other 3D operations.
+2. Assign shapes to cut, score or engrave layers.
+3. Check repeated assignments and put each value before the code that uses it.
+4. Supply the fonts used by `text()`.
+5. Set the measured material thickness and kerf. Use the joinery modules
+   where they suit the design.
+
+Render the result and check the dimensions and layers before exporting.
+The [layers](layers.md), [kerf](kerf.md) and
+[parts and sheets](parts-and-sheets.md) guides cover those steps.

package/docs/parts-and-sheets.md

@@ -0,0 +1,82 @@
+# Parts and sheets
+
+Use parts to name the pieces in a design, set quantities and assign
+materials. KerfScript lays them out on sheets, grouping parts that use the
+same material and thickness.
+
+## Parts
+
+```kerf
+part("side", qty = 2) rect([100, 60]);
+part("base") rect([100, 100]);
+```
+
+This creates two side panels and one base. Each `part()` has its own layers
+and appears in the parts list with dimensions and cut length. The default
+quantity is one.
+
+Shapes outside a `part()` are collected into a part named `part`.
+
+Transforms and operations such as `translate()`, `difference()` and
+`offset()` can wrap a part and change all of it. Layer wrappers such as
+`score()` and `engrave()` go inside the part instead, since a whole part on
+the score layer would have nothing to cut:
+
+```kerf
+part("tag") {
+  rect([60, 30], r = 3);
+  score() translate([5, 5]) rect([50, 20]);
+}
+```
+
+## Materials
+
+`material()` sets the thickness, kerf and material name for its parts:
+
+```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]);
+}
+```
+
+The two plywood panels share a sheet. The acrylic window goes on a separate
+sheet. Each part records the `$thickness`, `$kerf` and `$material` values in
+effect where it is defined.
+
+## Sheets
+
+Set the available sheet size and spacing in millimetres:
+
+```kerf
+$sheet = [300, 200];
+$gap = 4;
+```
+
+With the default `$layout = "pack"`, KerfScript arranges copies of each part
+in rows, leaving the specified gap. It rotates a part 90° if that lets it
+fit the sheet. The default sheet is 600 × 400 mm, with a 3 mm gap between
+parts and at the sheet edges.
+
+A part larger than the sheet produces a warning. Set `$layout = "none"`
+to keep the positions from your code instead of packing the parts.
+
+The CLI `--margin` option and API `margin` option let you set the edge
+spacing separately from the gap between parts.
+
+## One file per sheet
+
+A combined SVG stacks all sheets in one preview. For the material example
+above, export the plywood and acrylic sheets separately and cut each with
+the matching material settings.
+
+- On the command line, add `--split` to write `design-1.svg`,
+  `design-2.svg` and so on. `kerf check` lists each sheet's material and
+  thickness.
+- In JavaScript, `result.sheets` provides the SVG, DXF, material and
+  thickness for each sheet.
+
+DXF exports contain one sheet per file.

package/docs/versions.md

@@ -0,0 +1,33 @@
+# Versions
+
+KerfScript 0.2.0 implements language version 0.1. The package version tracks
+the software release; the language version tracks the syntax and behavior
+of `.kerf` programs.
+
+Package updates can include bug fixes, export options and JavaScript API
+changes without changing the language version. Use `kerf --version` to see
+both numbers, or read the `VERSION` and `LANGUAGE_VERSION` exports in JavaScript.
+
+## Before 1.0
+
+The language may change before 1.0. Release notes identify changes that
+affect existing programs or their output, including geometry and text layout
+fixes. Removing or renaming a language feature requires a new language version.
+
+Check the changelog when upgrading a tool that renders saved designs.
+
+## From 1.0
+
+The compatibility policy for language version 1.x is to keep existing
+programs working throughout that series. New features will be added without
+changing existing syntax. Bug fixes that affect output will be listed in
+the changelog; other breaking changes will require language version 2.0.
+
+## Pinning a version
+
+For repeatable exports, record the interpreter version, settings and font
+files used with a design. Applications that store designs should retain
+that information and compare the output before upgrading the interpreter.
+
+Pin the npm package to an exact version when your application needs a fixed
+renderer, for example `@mylasertools/kerfscript@0.2.0`.