@mylasertools/kerfscript 0.0.0-stage → 0.2.1

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,58 @@
+import { type LayerDef, type Limits } 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;
+    limits?: Partial<Limits>;
+}
+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,58 @@
+import { type LayerDef, type Limits } 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;
+    limits?: Partial<Limits>;
+}
+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,76 @@
+# Command line
+
+Use the `kerf` command to export designs, change parameters and inspect
+parts from your terminal. Install the package with Node.js 20 or newer:
+
+```sh
+npm install --global @mylasertools/kerfscript
+kerf render box.kerf -o box.svg
+```
+
+You can also run it through `npx`:
+
+```sh
+npx @mylasertools/kerfscript render box.kerf -o box.svg
+```
+
+Save a `.kerf` file from the [models](https://kerfscript.mylasertools.com/models/)
+to try these commands.
+
+## Commands
+
+```sh
+kerf render <file.kerf> [-o out.svg] [options]
+kerf params <file.kerf>
+kerf check <file.kerf>
+```
+
+`render` exports SVG, DXF or JSON, using the output file's extension to
+choose the format. `params` lists the editable settings as JSON. `check`
+reports parts, dimensions, cut lengths, sheets and warnings.
+
+## Options
+
+| Option | Use |
+| --- | --- |
+| `-o, --out <file>` | Output path ending in `.svg`, `.dxf` or `.json`; defaults to `<file>.svg` |
+| `-D name=value` | Override a parameter; repeat for multiple values |
+| `-p, --params <file>` | Load parameter values from a JSON file |
+| `--font <file.ttf>` | Supply a font file; repeat for multiple fonts |
+| `--kerf <mm>` | Override kerf for every part |
+| `--sheet <W>x<H>` | Set the sheet width and height in millimetres |
+| `--gap <mm>` | Set spacing between parts |
+| `--margin <mm>` | Set spacing at sheet edges; defaults to the gap |
+| `--no-pack` | Keep the positions defined in the program |
+| `--guides` | Include the guide layer |
+| `--split` | Export one file per sheet |
+| `-h, --help` | Show command help |
+| `-v, --version` | Show version numbers |
+
+`-D` accepts KerfScript values, including numbers, quoted strings, booleans
+and lists. For example: `-D width=200` or `-D 'name="Ada"'`.
+
+## Examples
+
+```sh
+kerf render name-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
+```
+
+For multiple sheets, `--split` creates numbered files such as `box-1.svg`
+and `box-2.svg`. Use it for DXF exports of a design with several sheets.
+
+Warnings are written to standard error and allow rendering to continue.
+An error stops the command, reports its location when available and returns
+a non-zero exit code.
+
+## Fonts
+
+Supply font files with `--font` for designs that use text. The CLI does not
+look up fonts installed on your system.
+
+`--font Inter-Bold.ttf` makes the font available as `Inter-Bold`. A design
+can request it with `font = "Inter-Bold"`. The first supplied font is the
+default for text that does not name one.

package/docs/compatibility.md

@@ -0,0 +1,64 @@
+# Laser software
+
+Export SVG or DXF from KerfScript, then set up the cutting job in your laser
+software. Check the imported size and layers before assigning power, speed
+and operation order.
+
+## What is in the files
+
+**SVG**
+
+- Millimetre dimensions with a matching `viewBox`.
+- Named layer groups for engraving, scoring, cutting and any custom layers.
+- Red cut paths, blue score paths and black filled engraving.
+- Inner cut paths before outer outlines in the file.
+
+**DXF**
+
+- R12 polylines with millimetre units.
+- Named layers such as `CUT`, `SCORE` and `ENGRAVE`.
+- Engraving as outlines. Set the engraving layer to fill in your laser software.
+- One sheet per file. Use the CLI's `--split` option for several sheets.
+
+## Checked
+
+| Program | Version | SVG | DXF | Checks |
+| --- | --- | --- | --- | --- |
+| Inkscape | 1.4.2 | Passed | Passed | Dimensions, layers and SVG fills |
+
+Six reference models passed these import checks on 28 October 2026.
+Drawing dimensions matched within 0.02 mm, including kerf compensation.
+These results cover file imports; they do not establish a fit for a
+particular machine or material.
+
+## Not checked yet
+
+LightBurn, xTool Studio, xTool Creative Space, RDWorks and LaserGRBL have
+not yet been verified with the reference models. Import handling can differ
+between programs, especially for units, layer colours and fills.
+
+## Checklist for a new program
+
+Download the calibration square and box from the
+[models](https://kerfscript.mylasertools.com/models/) and check their imports:
+
+1. **Size:** the calibration square's cut path is 100.15 mm wide with
+   `$kerf = 0.15`, allowing for a finished 100 mm square. If the imported
+   size differs, check the unit and DPI settings.
+2. **Layers:** cutting, scoring and engraving can be assigned separate operations.
+3. **Fill:** engraved text has filled letters. For DXF, select fill in the
+   engraving layer's settings.
+4. **Holes:** cut holes remain open and contain no engraving.
+5. **Order:** the job preview cuts inner paths before outer outlines.
+6. **Parts:** the box contains all six panels without overlaps.
+
+## What the file does not decide
+
+Set power, speed, passes and focus for your machine and material. Check the
+job preview for engraving before cutting and holes before outer outlines;
+laser software can reorder the paths in a file.
+
+For multiple sheets, use a separate file and matching material settings for
+each sheet. If KerfScript has already applied kerf compensation, leave the
+laser software's kerf offset at zero. Test the job on scrap before cutting
+the final material.

package/docs/customizer.md

@@ -0,0 +1,74 @@
+# Settings
+
+Expose dimensions, text and other choices as controls beside your design.
+Comments define sliders and menus, while the variable values provide their
+defaults. KerfScript uses OpenSCAD's customizer comment format.
+
+```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]);
+```
+
+This example defines several control types. The rectangle uses `width`
+and `depth`; the other variables illustrate settings you can use elsewhere
+in a design.
+
+## What becomes a setting
+
+A variable declared at the top level becomes a setting when its value is a
+number, string, boolean or list of numbers. Variables defined by expressions,
+such as `half_width = width / 2`, are calculated from the other values and
+do not get their own controls.
+
+## Comments
+
+Put a range or choice list after the assignment:
+
+| Comment after the value | Control |
+| --- | --- |
+| `// [40:5:400]` | Slider from 40 to 400, in steps of 5 |
+| `// [40:400]` | Slider from 40 to 400 |
+| `// [200]` | Number with an upper limit of 200 |
+| `// [2, 3, 4]` | Choice of 2, 3 or 4 |
+| `// [round:Round, square:Square]` | Menu with a label for each value |
+| No comment on a boolean | Checkbox |
+| No comment on a string | Text field |
+
+`/* [Size] */` starts a group named Size. `/* [Hidden] */` hides the
+settings that follow it, until another group begins.
+
+A `//` comment immediately above a variable supplies its caption. Keep the
+file's introductory comment separate with a blank line so it does not
+become the first setting's caption.
+
+## Changing settings without editing the file
+
+The CLI accepts values with `-D` or a JSON file with `--params`:
+
+```sh
+kerf render box.kerf -D width=200
+kerf render box.kerf --params box-settings.json
+kerf params box.kerf
+```
+
+`box-settings.json` can contain `{"width": 200, "lid": false}`.
+Use `kerf params` to list a design's settings as JSON.
+
+String values need quotes, for example `-D 'label="Oak"'` for a design
+with a `label` setting. In JavaScript, pass values through `render()`'s
+`params` option and read the settings with `parameters()`. See the
+[JavaScript API](javascript.md).