@mylasertools/kerfscript 0.2.0 → 0.2.1

package/docs/parts-and-sheets.md

@@ -1,7 +1,8 @@
 # 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.
+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
 
@@ -10,16 +11,27 @@ 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`.
+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.
 
-Parts show up in the part list with their size and cut length, which the
-playground and `kerf check` print.
+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
 
-Each part records `$thickness`, `$kerf` and `$material` where it is made.
-`material()` sets all three for the parts inside it:
+`material()` sets the thickness, kerf and material name for its parts:
 
 ```kerf
 material(thickness = 3, kerf = 0.15, name = "plywood") {
@@ -31,38 +43,40 @@ material(thickness = 2, kerf = 0.1, name = "acrylic") {
 }
 ```
 
-## Sheets
-
-With the default `$layout = "pack"`, KerfScript:
+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.
 
-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.
+## Sheets
 
-A part bigger than the sheet gives a warning. With `$layout = "none"` parts
-stay where your program put them.
+Set the available sheet size and spacing in millimetres:
 
 ```kerf
 $sheet = [300, 200];
 $gap = 4;
 ```
 
-## One file per sheet
+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.
 
-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.
+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
 
-Cut each sheet as its own job:
+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, `--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`.
+- 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.
 
-Before cutting, check that each file's material and thickness match the
-sheet in your machine.
+DXF exports contain one sheet per file.

package/docs/versions.md

@@ -1,43 +1,33 @@
 # Versions
 
-KerfScript has two version numbers.
+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.
 
-- 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.
+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
 
-KerfScript is young, and the language may still change before 1.0. What we
-promise in the meantime:
+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.
 
-- **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.
+Check the changelog when upgrading a tool that renders saved designs.
 
 ## 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.
+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
 
-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.
+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`.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@mylasertools/kerfscript",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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"
+    "url": "git+https://github.com/mylasertools/kerfscript.git"
   },
-  "bugs": "https://github.com/mylasertools-com/kerfscript/issues",
+  "bugs": "https://github.com/mylasertools/kerfscript/issues",
   "keywords": [
     "kerfscript",
     "laser-cutting",
@@ -72,7 +72,8 @@
     "prepack": "npm run check",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "compat": "node scripts/compat.mjs"
+    "compat": "node scripts/compat.mjs",
+    "readme-images": "npm run build && cd site && node ../scripts/readme-images.mjs"
   },
   "devDependencies": {
     "@types/node": "20.19.43",