@mylasertools/kerfscript 0.0.0-stage → 0.2.0

package/dist/joinery.d.cts

@@ -0,0 +1,7 @@
+import { type Poly } from './geometry.cjs';
+export type Edge = 'out' | 'in' | 'flat';
+export declare function fingerCount(length: number, finger: number): number;
+export declare function fingerRect(w: number, h: number, edges: Edge[], t: number, finger: number): Poly[];
+export declare function fingerHoles(length: number, edge: Edge, t: number, finger: number): Poly[];
+export declare function tslot(d: number, length: number, nutW: number, nutH: number, nutAt: number): Poly[];
+export declare function livingHinge(w: number, h: number, spacing: number, bridge: number, cut: number): Poly[];

package/dist/joinery.d.ts

@@ -0,0 +1,7 @@
+import { type Poly } from './geometry.js';
+export type Edge = 'out' | 'in' | 'flat';
+export declare function fingerCount(length: number, finger: number): number;
+export declare function fingerRect(w: number, h: number, edges: Edge[], t: number, finger: number): Poly[];
+export declare function fingerHoles(length: number, edge: Edge, t: number, finger: number): Poly[];
+export declare function tslot(d: number, length: number, nutW: number, nutH: number, nutAt: number): Poly[];
+export declare function livingHinge(w: number, h: number, spacing: number, bridge: number, cut: number): Poly[];

package/dist/lexer.d.cts

@@ -0,0 +1,28 @@
+export type TokenType = 'num' | 'str' | 'id' | 'punct' | 'eof';
+export interface Pos {
+    line: number;
+    col: number;
+    offset: number;
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    pos: Pos;
+}
+export interface Comment {
+    text: string;
+    line: number;
+    block: boolean;
+    own: boolean;
+}
+export declare class KerfError extends Error {
+    line?: number;
+    col?: number;
+    echoes: string[];
+    missingFonts?: string[];
+    constructor(message: string, pos?: Pos);
+}
+export declare function tokenize(src: string): {
+    tokens: Token[];
+    comments: Comment[];
+};

package/dist/lexer.d.ts

@@ -0,0 +1,28 @@
+export type TokenType = 'num' | 'str' | 'id' | 'punct' | 'eof';
+export interface Pos {
+    line: number;
+    col: number;
+    offset: number;
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    pos: Pos;
+}
+export interface Comment {
+    text: string;
+    line: number;
+    block: boolean;
+    own: boolean;
+}
+export declare class KerfError extends Error {
+    line?: number;
+    col?: number;
+    echoes: string[];
+    missingFonts?: string[];
+    constructor(message: string, pos?: Pos);
+}
+export declare function tokenize(src: string): {
+    tokens: Token[];
+    comments: Comment[];
+};

package/dist/parser.d.cts

@@ -0,0 +1,6 @@
+import type { Program } from './ast.cjs';
+import { type Comment } from './lexer.cjs';
+export declare function parse(src: string): {
+    program: Program;
+    comments: Comment[];
+};

package/dist/parser.d.ts

@@ -0,0 +1,6 @@
+import type { Program } from './ast.js';
+import { type Comment } from './lexer.js';
+export declare function parse(src: string): {
+    program: Program;
+    comments: Comment[];
+};

package/dist/paths.d.cts

@@ -0,0 +1,28 @@
+import type { Poly } from './geometry.cjs';
+export type Cmd = {
+    type: 'M' | 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'Q';
+    x1: number;
+    y1: number;
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    type: 'Z';
+};
+export interface Flattened {
+    closed: Poly[];
+    open: Poly[];
+}
+export declare function flatten(cmds: Cmd[], tolerance?: number): Flattened;
+export declare function parseSvgPath(d: string): Cmd[];

package/dist/paths.d.ts

@@ -0,0 +1,28 @@
+import type { Poly } from './geometry.js';
+export type Cmd = {
+    type: 'M' | 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'Q';
+    x1: number;
+    y1: number;
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    type: 'Z';
+};
+export interface Flattened {
+    closed: Poly[];
+    open: Poly[];
+}
+export declare function flatten(cmds: Cmd[], tolerance?: number): Flattened;
+export declare function parseSvgPath(d: string): Cmd[];

package/dist/render.d.cts

@@ -0,0 +1,57 @@
+import { type LayerDef } from './evaluator.cjs';
+import { type LayerPath } from './export/svg.cjs';
+import { type Layer } from './geometry.cjs';
+import { type FontSource } from './text.cjs';
+import type { Value } from './values.cjs';
+export interface RenderOptions {
+    params?: Record<string, Value>;
+    fonts?: Record<string, FontSource>;
+    defaultFont?: string;
+    resolve?: (path: string) => string | undefined;
+    kerf?: number;
+    layout?: 'pack' | 'none';
+    sheet?: [number, number];
+    gap?: number;
+    margin?: number;
+    guides?: boolean;
+    maxSteps?: number;
+}
+export interface PartInfo {
+    name: string;
+    qty: number;
+    width: number;
+    height: number;
+    pieces: number;
+    cutLength: number;
+    thickness: number;
+    kerf: number;
+    material: string;
+}
+export interface Placed {
+    part: string;
+    copy: number;
+    layers: Map<string, Layer>;
+    rotated: boolean;
+}
+export interface Sheet {
+    width: number;
+    height: number;
+    material: string;
+    thickness: number;
+    items: Placed[];
+    paths: LayerPath[];
+    svg: string;
+    dxf: string;
+}
+export interface RenderResult {
+    sheets: Sheet[];
+    width: number;
+    height: number;
+    paths: LayerPath[];
+    svg: string;
+    parts: PartInfo[];
+    layers: LayerDef[];
+    warnings: string[];
+    echoes: string[];
+}
+export declare function render(source: string, options?: RenderOptions): RenderResult;

package/dist/render.d.ts

@@ -0,0 +1,57 @@
+import { type LayerDef } from './evaluator.js';
+import { type LayerPath } from './export/svg.js';
+import { type Layer } from './geometry.js';
+import { type FontSource } from './text.js';
+import type { Value } from './values.js';
+export interface RenderOptions {
+    params?: Record<string, Value>;
+    fonts?: Record<string, FontSource>;
+    defaultFont?: string;
+    resolve?: (path: string) => string | undefined;
+    kerf?: number;
+    layout?: 'pack' | 'none';
+    sheet?: [number, number];
+    gap?: number;
+    margin?: number;
+    guides?: boolean;
+    maxSteps?: number;
+}
+export interface PartInfo {
+    name: string;
+    qty: number;
+    width: number;
+    height: number;
+    pieces: number;
+    cutLength: number;
+    thickness: number;
+    kerf: number;
+    material: string;
+}
+export interface Placed {
+    part: string;
+    copy: number;
+    layers: Map<string, Layer>;
+    rotated: boolean;
+}
+export interface Sheet {
+    width: number;
+    height: number;
+    material: string;
+    thickness: number;
+    items: Placed[];
+    paths: LayerPath[];
+    svg: string;
+    dxf: string;
+}
+export interface RenderResult {
+    sheets: Sheet[];
+    width: number;
+    height: number;
+    paths: LayerPath[];
+    svg: string;
+    parts: PartInfo[];
+    layers: LayerDef[];
+    warnings: string[];
+    echoes: string[];
+}
+export declare function render(source: string, options?: RenderOptions): RenderResult;

package/dist/stdlib.d.cts

@@ -0,0 +1 @@
+export declare const LIBRARIES: Record<string, string>;

package/dist/stdlib.d.ts

@@ -0,0 +1 @@
+export declare const LIBRARIES: Record<string, string>;

package/dist/text.d.cts

@@ -0,0 +1,36 @@
+import { type Poly } from './geometry.cjs';
+import { type Cmd } from './paths.cjs';
+export type FontSource = ArrayBuffer | Uint8Array;
+interface OtFont {
+    getPath(text: string, x: number, y: number, size: number, options?: object): {
+        commands: Cmd[];
+    };
+    getAdvanceWidth(text: string, size: number, options?: object): number;
+    ascender: number;
+    descender: number;
+    unitsPerEm: number;
+}
+export declare class FontBook {
+    private sources;
+    private fallback?;
+    private parsed;
+    readonly missing: Set<string>;
+    constructor(sources: Record<string, FontSource>, fallback?: string | undefined);
+    names(): string[];
+    get(name: string): OtFont;
+}
+export interface TextOptions {
+    size: number;
+    font: string;
+    halign: string;
+    valign: string;
+    spacing: number;
+}
+export declare function textRegions(book: FontBook, text: string, o: TextOptions): Poly[];
+export declare function textMetrics(book: FontBook, text: string, o: TextOptions): {
+    advance: number;
+    bounds: number[][];
+    ascent: number;
+    descent: number;
+};
+export {};

package/dist/text.d.ts

@@ -0,0 +1,36 @@
+import { type Poly } from './geometry.js';
+import { type Cmd } from './paths.js';
+export type FontSource = ArrayBuffer | Uint8Array;
+interface OtFont {
+    getPath(text: string, x: number, y: number, size: number, options?: object): {
+        commands: Cmd[];
+    };
+    getAdvanceWidth(text: string, size: number, options?: object): number;
+    ascender: number;
+    descender: number;
+    unitsPerEm: number;
+}
+export declare class FontBook {
+    private sources;
+    private fallback?;
+    private parsed;
+    readonly missing: Set<string>;
+    constructor(sources: Record<string, FontSource>, fallback?: string | undefined);
+    names(): string[];
+    get(name: string): OtFont;
+}
+export interface TextOptions {
+    size: number;
+    font: string;
+    halign: string;
+    valign: string;
+    spacing: number;
+}
+export declare function textRegions(book: FontBook, text: string, o: TextOptions): Poly[];
+export declare function textMetrics(book: FontBook, text: string, o: TextOptions): {
+    advance: number;
+    bounds: number[][];
+    ascent: number;
+    descent: number;
+};
+export {};

package/dist/values.d.cts

@@ -0,0 +1,25 @@
+import type { Expr, Param } from './ast.cjs';
+export interface Range {
+    type: 'range';
+    start: number;
+    step: number;
+    end: number;
+}
+export interface Closure {
+    type: 'function';
+    params: Param[];
+    body: Expr;
+    scope: unknown;
+    name?: string;
+}
+export type Value = number | string | boolean | undefined | Value[] | Range | Closure;
+export declare const isRange: (v: Value) => v is Range;
+export declare const isFn: (v: Value) => v is Closure;
+export declare const isNum: (v: Value) => v is number;
+export declare function rangeValues(r: Range, limit: number): number[];
+export declare function truthy(v: Value): boolean;
+export declare function equals(a: Value, b: Value): boolean;
+export declare function typeName(v: Value): string;
+export declare function show(v: Value): string;
+export declare function str(v: Value): string;
+export declare function fmt(n: number): string;

package/dist/values.d.ts

@@ -0,0 +1,25 @@
+import type { Expr, Param } from './ast.js';
+export interface Range {
+    type: 'range';
+    start: number;
+    step: number;
+    end: number;
+}
+export interface Closure {
+    type: 'function';
+    params: Param[];
+    body: Expr;
+    scope: unknown;
+    name?: string;
+}
+export type Value = number | string | boolean | undefined | Value[] | Range | Closure;
+export declare const isRange: (v: Value) => v is Range;
+export declare const isFn: (v: Value) => v is Closure;
+export declare const isNum: (v: Value) => v is number;
+export declare function rangeValues(r: Range, limit: number): number[];
+export declare function truthy(v: Value): boolean;
+export declare function equals(a: Value, b: Value): boolean;
+export declare function typeName(v: Value): string;
+export declare function show(v: Value): string;
+export declare function str(v: Value): string;
+export declare function fmt(n: number): string;

package/docs/cli.md

@@ -0,0 +1,61 @@
+# Command line
+
+The `kerf` command renders `.kerf` files to SVG, DXF or JSON. It needs
+Node.js 20 or newer and comes with the `@mylasertools/kerfscript` npm
+package.
+
+```sh
+npm install --global @mylasertools/kerfscript
+kerf render box.kerf -o box.svg
+```
+
+Or without installing:
+
+```sh
+npx @mylasertools/kerfscript render box.kerf -o box.svg
+```
+
+## Commands
+
+```sh
+kerf render <file.kerf> [-o out.svg] [options]
+kerf params <file.kerf>     # settings as JSON
+kerf check <file.kerf>      # parts, sizes, cut length, sheets and warnings
+```
+
+## Options
+
+| Option                | What it does                                                           |
+| --------------------- | ---------------------------------------------------------------------- |
+| `-o, --out <file>`    | output file, `.svg`, `.dxf` or `.json`; default `<file>.svg`           |
+| `-D name=value`       | set a setting; the value is KerfScript: `40`, `"Oak"`, `true`, `[1,2]` |
+| `-p, --params <file>` | JSON file of setting values                                            |
+| `--font <file.ttf>`   | font for `text()`; repeat for more fonts. The name is the file name    |
+| `--kerf <mm>`         | override kerf compensation for every part                              |
+| `--sheet <W>x<H>`     | sheet size for packing, in mm                                          |
+| `--gap <mm>`          | space between packed parts                                             |
+| `--margin <mm>`       | space between the parts and the sheet edge (default: the gap)          |
+| `--no-pack`           | keep parts where the program placed them                               |
+| `--guides`            | include guide layer geometry                                           |
+| `--split`             | write one file per sheet (`out-1.svg`, `out-2.svg`, ...)               |
+| `-h, --help`          | show help                                                              |
+| `-v, --version`       | show the version                                                       |
+
+## Examples
+
+```sh
+kerf render sign.kerf -D 'name="Ada"' --font Inter-Bold.ttf -o ada.svg
+kerf render box.kerf --sheet 400x300 --kerf 0.12 --split -o box.svg
+kerf render box.kerf -o box.dxf
+kerf check box.kerf
+```
+
+Warnings go to standard error and do not stop the render. Errors stop it with
+the line and column, and a non-zero exit code.
+
+## Fonts
+
+KerfScript does not ship fonts and never reads system fonts, so a file
+renders the same everywhere. Pass the fonts a design uses with `--font`. A
+design that asks for `font = "Inter-Bold"` needs `--font Inter-Bold.ttf`; the
+first font given is the default.

package/docs/compatibility.md

@@ -0,0 +1,89 @@
+# Laser software
+
+KerfScript writes ordinary SVG and DXF files, so any program that reads
+those can open them. This page says what we have actually checked, in which
+version, and what you still need to set up yourself.
+
+## What is in the files
+
+**SVG**
+
+- Size in millimetres (`width="100mm"`), with a matching `viewBox`, so one
+  unit is one millimetre.
+- One group per layer, marked as an Inkscape layer and named after it:
+  `engrave`, your own layers, `score`, `cut`, `guide`.
+- Cut lines red `#ff0000`, score lines blue `#0000ff`, 0.1 mm hairline
+  strokes. Engraved areas are filled black `#000000` with the even-odd rule.
+- Holes and inner cuts come before outer outlines.
+
+**DXF**
+
+- R12 (AC1009) polylines, units set to millimetres.
+- One DXF layer per KerfScript layer, in capitals (`CUT`, `SCORE`,
+  `ENGRAVE`), with matching AutoCAD colours.
+- DXF R12 has no fills. Engraved areas arrive as outlines; set that layer to
+  fill in your laser software.
+- A DXF holds one sheet. Use `--split` for designs with several sheets.
+
+## Checked
+
+| Program  | Version | SVG | DXF | How                         |
+| -------- | ------- | --- | --- | --------------------------- |
+| Inkscape | 1.4.2   | yes | yes | automatic, `npm run compat` |
+
+`npm run compat` renders six reference models (the calibration square, the
+kerf test, a six-panel finger-jointed box, a living hinge card, a coaster
+with an engraved ring, and a jigsaw puzzle), opens every SVG and DXF in
+Inkscape from the command line, and checks that:
+
+- the size of the drawing matches KerfScript's geometry within 0.02 mm,
+  kerf compensation included;
+- every layer arrives as a layer with the right name;
+- engraved layers are filled in the SVG.
+
+All six passed in both formats on 28 October 2026.
+
+## Not checked yet
+
+We have not yet run the reference set through **LightBurn**, **xTool
+Studio** or **xTool Creative Space**, **RDWorks** or **LaserGRBL**, and we
+have not cut it on machines outside MyLaserTools. Until we have, treat them as
+untested: they read standard SVG and DXF, but each imports colours, layers
+and fills its own way.
+
+If you try one, we would like to hear what happened. The checklist below is
+what we look at.
+
+## Checklist for a new program
+
+Open `calibration-square.svg` and `box.svg` from the
+[models](https://kerfscript.mylasertools.com/models/) and check:
+
+1. **Size.** The square is 100.15 mm wide with the default 0.15 mm kerf
+   (100 mm plus compensation), not 26.4 mm or 377.95 mm. If it is wrong, the
+   program ignored the millimetre units; look for an import DPI or unit
+   setting.
+2. **Layers.** Cut, score and engrave arrive as separate layers or colours,
+   so each can get its own power and speed.
+3. **Fill.** The engraved text on the square is filled, not just outlined.
+4. **Holes.** The hole in the square is cut, and engraving does not appear
+   inside it.
+5. **Order.** The program's cut order cuts holes before outlines. Most
+   programs have an "inner shapes first" option; turn it on.
+6. **Parts.** All six box panels arrive, none overlapping.
+
+## What the file does not decide
+
+The file describes geometry and layers. Your laser software decides how the
+machine runs it:
+
+- **Order of operations.** Layer order in an SVG is a hint. Most programs
+  sort operations themselves; check that engraving runs before cutting and
+  inner cuts before outer ones.
+- **Power, speed, passes and focus** for each layer and material.
+- **Material and thickness.** KerfScript records them per sheet; make sure
+  the file you send matches the sheet in the machine.
+- **Kerf.** If your laser software also applies kerf offset, turn one of them
+  off, or parts will be compensated twice.
+
+Always run a test on scrap before cutting good material.

package/docs/customizer.md

@@ -0,0 +1,62 @@
+# Settings
+
+Top-level variables with a plain value become **settings**: sliders, menus,
+checkboxes and text boxes in the playground, on MyLaserTools, and in any tool
+that reads OpenSCAD customizer comments. The format is the same as
+OpenSCAD's.
+
+```kerf
+/* [Size] */
+// Outer width
+width = 120; // [40:5:400]
+// Outer depth
+depth = 80; // [200]
+
+/* [Style] */
+shape = "round"; // [round:Round, square:Square]
+holes = 3; // [2, 3, 4]
+lid = true;
+label = "Tools";
+
+/* [Hidden] */
+wall = 3;
+
+rect([width, depth]);
+```
+
+## What becomes a setting
+
+A top-level assignment whose value is a number, a string, `true` or `false`,
+or a list of numbers. An expression like `width / 2` is not a setting; it is
+worked out from the others.
+
+## Comments
+
+| Comment after the value           | Control                       |
+| --------------------------------- | ----------------------------- |
+| `// [40:5:400]`                   | slider from 40 to 400, step 5 |
+| `// [40:400]`                     | slider from 40 to 400         |
+| `// [200]`                        | number up to 200              |
+| `// [2, 3, 4]`                    | menu of those values          |
+| `// [round:Round, square:Square]` | menu with labels              |
+| none, on `true` or `false`        | checkbox                      |
+| none, on a string                 | text box                      |
+
+- `/* [Group name] */` starts a group for the settings below it.
+  `/* [Hidden] */` hides the ones that follow.
+- A `//` comment on its own line just above a setting is its caption.
+  A comment at the end of the line before does not count.
+- Put a blank line between a file's opening comment and its first setting,
+  so the opening comment is not taken as that setting's caption.
+
+## Changing settings without editing the file
+
+```sh
+kerf render box.kerf -D width=200 -D 'label="Oak"'
+kerf render box.kerf --params oak.json
+kerf params box.kerf
+```
+
+`-D` values are KerfScript values, so strings need their quotes. `kerf params`
+prints the settings as JSON. From JavaScript, pass `params` to `render()` and
+read them with `parameters()`; see [JavaScript API](javascript.md).