@mylasertools/kerfscript 0.2.0 → 0.2.1

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,144 @@ 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.
+
+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

@@ -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.

package/docs/openscad.md

@@ -1,67 +1,71 @@
 # 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.
+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
 
-- Statements, modules, functions, `for`, `if`, `let`, `each`, list
-  comprehensions, ranges like `[0:2:10]`, function literals.
+You can use familiar building blocks:
+
+- Modules, functions, `for`, `if`, `let`, `each`, list comprehensions,
+  ranges and 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)`.
+- 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: `// [40:5:400]`, `/* [Group] */`, `/* [Hidden] */`,
-  and captions on the line above. Tools that read OpenSCAD settings read
-  these.
+- Customizer comments for ranges, choices, groups and captions.
+
+See the [language reference](../LANGUAGE.md) for supported arguments.
 
 ## 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               |
+| 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
 
-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.
+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
 
-- 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.
+- **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. 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.
+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.