@mylasertools/kerfscript 0.3.0 → 0.4.0

package/dist/render.d.cts

@@ -1,3 +1,4 @@
+import { type AssemblyPart } from './assembly.cjs';
 import { type LayerDef, type Limits } from './evaluator.cjs';
 import { type LayerPath } from './export/svg.cjs';
 import { type Layer } from './geometry.cjs';
@@ -51,6 +52,7 @@ export interface RenderResult {
     paths: LayerPath[];
     svg: string;
     parts: PartInfo[];
+    assembly: AssemblyPart[];
     layers: LayerDef[];
     warnings: string[];
     echoes: string[];

package/dist/render.d.ts

@@ -1,3 +1,4 @@
+import { type AssemblyPart } from './assembly.js';
 import { type LayerDef, type Limits } from './evaluator.js';
 import { type LayerPath } from './export/svg.js';
 import { type Layer } from './geometry.js';
@@ -51,6 +52,7 @@ export interface RenderResult {
     paths: LayerPath[];
     svg: string;
     parts: PartInfo[];
+    assembly: AssemblyPart[];
     layers: LayerDef[];
     warnings: string[];
     echoes: string[];

package/docs/javascript.md

@@ -61,16 +61,17 @@ 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                                              |
+| 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                                                                                                             |
+| `assembly`        | One entry per copy of a part with `name`, `copy`, `thickness`, `outline`, a 4 × 4 `matrix` and `placed`, for showing the design put together. Parts without `at` or `rotate` have `placed: false` |
+| `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

package/docs/parts-and-sheets.md

@@ -29,6 +29,38 @@ part("tag") {
 }
 ```
 
+## Assembly
+
+Give a part a place in 3D and apps can show the design put together.
+`rotate` turns the part and `at` moves it. The turn happens first, the same
+as OpenSCAD's `translate(at) rotate(r)`. Each part is drawn flat with its
+thickness standing up along +Z.
+
+```kerf
+material(thickness = 3) {
+  part("base", at = [0, 0, 0]) rect([100, 60]);
+  part("wall", at = [0, 3, 3], rotate = [90, 0, 0]) rect([100, 40]);
+}
+```
+
+A part with copies takes one placement for all of them, or a list with one
+for each copy:
+
+```kerf
+part("leg", qty = 4, at = [[0, 0, 0], [80, 0, 0], [0, 40, 0], [80, 40, 0]],
+     rotate = [90, 0, 0]) rect([20, 60]);
+```
+
+`box()` from `kerf/box` places its panels itself, so every box assembles.
+Parts without `at` or `rotate` lie flat beside the assembled view, each copy
+in rows to its right, and the render names them in a warning. When placed
+parts run into each other, the render warns which two collide. That is what
+a finger edge set to `"out"` where it should be `"in"` looks like, or a part
+placed one thickness off. Joints that interlock exactly do not count, and
+neither does an overlap smaller than about a cubic millimetre, the kind of
+nick a laser kerf or a press fit takes up. A tab half a millimetre out of its
+slot is well over that and gets a warning.
+
 ## Materials
 
 `material()` sets the thickness, kerf and material name for its parts:

package/docs/versions.md

@@ -1,6 +1,6 @@
 # Versions
 
-KerfScript 0.3.0 implements language version 0.1. The package version tracks
+KerfScript 0.4.0 implements language version 0.1. The package version tracks
 the software release; the language version tracks the syntax and behavior
 of `.kerf` programs.
 
@@ -30,4 +30,4 @@ 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.3.0`.
+renderer, for example `@mylasertools/kerfscript@0.4.0`.

package/docs/webassembly.md

@@ -60,7 +60,9 @@ Every response has `ok`. When it is `false`, `error` holds the message and
 exits with an error code for a bad program.
 
 - `render`: `svg` (all sheets, for preview), `width`, `height`, `parts`,
-  `warnings`, `echoes` and `sheets`. Each sheet has `width`, `height`,
+  `assembly`, `warnings`, `echoes` and `sheets`. `assembly` is the same as
+  from [`render()`](javascript.md): one entry per copy of a part, with its
+  outline, thickness and placement. Each sheet has `width`, `height`,
   `material`, `thickness`, `svg` and `dxf`; write one file per sheet to cut.
 - `params`: `parameters`, as from [`parameters()`](javascript.md).
 - `version`: `version` (package) and `language`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mylasertools/kerfscript",
-  "version": "0.3.0",
+  "version": "0.4.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",