@mylasertools/kerfscript 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# KerfScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A programming language for laser cutting.**
+
+[Website](https://kerfscript.mylasertools.com) ·
+[Playground](https://kerfscript.mylasertools.com/playground/) ·
+[Models](https://kerfscript.mylasertools.com/models/) ·
+[Docs](https://kerfscript.mylasertools.com/docs/)
+
+Write a part once as code, change a number, and get a new cut file. KerfScript
+is to laser cutters what OpenSCAD is to 3D printers, except it was designed for
+flat parts from the start: cut, score and engrave layers, kerf compensation,
+finger joints, living hinges, parts and sheets are part of the language.
+
+```kerf
+use <kerf/box>
+
+/* [Size] */
+width = 120; // [40:5:400]
+depth = 80; // [40:5:400]
+height = 50; // [20:5:300]
+lid = true;
+
+/* [Material] */
+$thickness = 3; // [1.5:0.5:10]
+$kerf = 0.15; // [0:0.01:0.5]
+
+box([width, depth, height], lid = lid);
+```
+
+```sh
+npx @mylasertools/kerfscript render box.kerf -o box.svg -D width=200
+```
+
+That writes all six panels packed on a sheet, kerf compensated, as a
+millimetre SVG with one layer per operation. Output is checked automatically
+in Inkscape; see [docs/compatibility.md](docs/compatibility.md) for what has
+and has not been tested in other laser software.
+
+## Why a new language
+
+- **Laser concepts are built in.** `engrave()`, `score()` and `cut()` put
+  geometry on machine layers. Engraving is clipped to the material, inner
+  cuts come before outer ones, and the whole part is offset by half the kerf.
+- **Parts, not just shapes.** `part("lid", qty = 2)` names a piece; the
+  renderer packs parts by material and thickness onto sheets.
+- **Joinery that fits.** `finger_rect`, `finger_holes`, `tslot` and
+  `living_hinge` use `$thickness`, so changing the material keeps joints
+  tight.
+- **Familiar syntax.** If you know OpenSCAD, you can read KerfScript. The
+  customizer comments are the same, so editors that understand OpenSCAD
+  parameters understand KerfScript ones.
+- **Runs anywhere.** Pure TypeScript with no native code: the same interpreter
+  runs in browsers, Node, workers and the command line.
+- **Safe to run.** Programs read libraries only through the resolver you
+  provide. Step and recursion limits stop runaway programs, and errors name
+  the line.
+
+## Install
+
+```sh
+npm install @mylasertools/kerfscript
+```
+
+## Command line
+
+```sh
+kerf render design.kerf -o design.svg      # or .dxf / .json
+kerf render design.kerf -D width=200 -D 'label="Oak"' --font Inter.ttf
+kerf render design.kerf --sheet 400x300 --kerf 0.1 --split
+kerf params design.kerf                    # customizer parameters as JSON
+kerf check design.kerf                     # parts, sizes, cut length, warnings
+```
+
+## Library
+
+```js
+import { render, parameters } from '@mylasertools/kerfscript';
+
+const result = render(source, {
+  params: { width: 200 },
+  fonts: { inter: await (await fetch('/Inter.ttf')).arrayBuffer() },
+  sheet: [600, 400],
+});
+
+result.svg; // all sheets in one SVG
+result.sheets; // [{ width, height, material, thickness, svg, dxf, items }]
+result.parts; // [{ name, qty, width, height, pieces, cutLength, thickness, kerf, material }]
+result.warnings; // e.g. a part that falls apart, or one bigger than the sheet
+result.echoes; // echo() output
+
+parameters(source).parameters; // [{ name, caption, group, type, initial, min, max, step, options, span }]
+```
+
+Errors are thrown as `KerfError` with `line` and `col`.
+
+## Learn the language
+
+- [Getting started](docs/getting-started.md), then the guides on
+  [layers](docs/layers.md), [kerf](docs/kerf.md),
+  [parts and sheets](docs/parts-and-sheets.md), [settings](docs/customizer.md),
+  the [command line](docs/cli.md) and the [JavaScript API](docs/javascript.md)
+- [Coming from OpenSCAD](docs/openscad.md): what is the same and what is not
+- [LANGUAGE.md](LANGUAGE.md): the full language reference
+- [Versions](docs/versions.md): language and package versions, and what stays
+  stable before 1.0
+- [examples/](examples): every model on the website, including a
+  calibration square and a kerf test
+
+## Website
+
+kerfscript.mylasertools.com is an Astro site in [site/](site), deployed to
+Cloudflare as a static assets Worker. Every model picture and the guides are
+built from [examples/](examples), [docs/](docs) and LANGUAGE.md by this
+version of KerfScript.
+
+```sh
+npm --prefix site install
+npm run site          # build KerfScript, then the site into site/dist
+npm run site:serve    # preview on http://localhost:4321
+npm --prefix site run deploy
+```
+
+## Checking output
+
+`npm run compat` renders a reference set of models and opens every SVG and
+DXF in Inkscape to check sizes, layers and fills.
+
+## Community
+
+Bug reports, cut reports and ideas are welcome; see
+[CONTRIBUTING.md](CONTRIBUTING.md), the [roadmap](ROADMAP.md),
+[SECURITY.md](SECURITY.md) and the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Licence
+
+Copyright (c) 2026 MyLaserTools.
+
+KerfScript is free software under the
+[GNU AGPL 3.0](LICENSE), with an [additional permission](COMMERCIAL-LICENSE.md#additional-permission-your-designs-are-yours)
+that makes **your `.kerf` designs and the files KerfScript generates yours to
+license and sell however you like**.
+
+Using KerfScript in a closed source product or hosted service without
+publishing your source requires a [commercial licence](COMMERCIAL-LICENSE.md).
+
+"KerfScript" is a trademark of MyLaserTools; see [TRADEMARKS.md](TRADEMARKS.md).
+Contributions need the [CLA](CLA.md); see [CONTRIBUTING.md](CONTRIBUTING.md).
+Bundled third-party code is listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+KerfScript bundles the following software in `dist/`. Their licences apply to
+those parts only.
+
+## Clipper2 / clipper2-ts 2.0.1-18 (bundled)
+
+Original Clipper2: Copyright Angus Johnson 2010–2025.
+TypeScript port by Jeremy Tribby (countertype).
+Source: https://github.com/countertype/clipper2-ts
+
+```text
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+```
+
+## opentype.js 1.3.4 (bundled)
+
+Source: https://github.com/opentypejs/opentype.js
+
+```text
+The MIT License (MIT)
+
+Copyright (c) 2020 Frederik De Bleser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## Atkinson Hyperlegible (test fixture only, not published to npm)
+
+`test/fixtures/AtkinsonHyperlegible-Regular.ttf`, Copyright 2020 Braille
+Institute of America, Inc., licensed under the SIL Open Font License 1.1. See
+`test/fixtures/OFL.txt`.

package/TRADEMARKS.md

@@ -0,0 +1,39 @@
+# Trademark policy
+
+"KerfScript", the `.kerf` file format name used as a product name, and the
+KerfScript logo are trademarks of MyLaserTools. The software licences
+(AGPL-3.0-only and commercial) cover the code. They do not grant rights to the
+name or logo.
+
+This policy keeps "KerfScript" meaning one well defined language, so a `.kerf`
+file written for one KerfScript tool works in every tool that uses the name.
+
+## You may, without asking
+
+- say your design, tutorial, course, video or library is written **in**
+  KerfScript or works **with** KerfScript
+- use the `.kerf` file extension for KerfScript programs
+- use the name to refer to this project and to unmodified copies of it
+- publish a fork for development, as long as it is clearly marked as a fork
+  and does not use the name or logo as its own product name
+
+## You need written permission to
+
+- name a product, service, company, domain or package "KerfScript" or anything
+  confusingly similar (for example "KerfScript Pro", "kerfscript-cloud")
+- call your own implementation, editor or service "KerfScript compatible" or
+  "official". Compatibility claims require passing the KerfScript conformance
+  tests for the language version you claim
+- use the logo, other than to link to this project
+- distribute a modified interpreter under the KerfScript name
+
+## Language specification
+
+The language reference ([LANGUAGE.md](LANGUAGE.md)) is published under
+Creative Commons Attribution-NoDerivatives 4.0 (CC BY-ND 4.0). You may copy and
+share it unchanged with attribution. Changes to the language are made by
+MyLaserTools through this repository, so there is one KerfScript.
+
+## Contact
+
+julia@mylasertools.com

package/dist/ast.d.cts

@@ -0,0 +1,160 @@
+import type { Pos } from './lexer.cjs';
+export type Expr = {
+    kind: 'num';
+    value: number;
+    pos: Pos;
+} | {
+    kind: 'str';
+    value: string;
+    pos: Pos;
+} | {
+    kind: 'bool';
+    value: boolean;
+    pos: Pos;
+} | {
+    kind: 'undef';
+    pos: Pos;
+} | {
+    kind: 'var';
+    name: string;
+    pos: Pos;
+} | {
+    kind: 'list';
+    items: ListItem[];
+    pos: Pos;
+} | {
+    kind: 'range';
+    start: Expr;
+    step: Expr | null;
+    end: Expr;
+    pos: Pos;
+} | {
+    kind: 'unary';
+    op: string;
+    arg: Expr;
+    pos: Pos;
+} | {
+    kind: 'binary';
+    op: string;
+    left: Expr;
+    right: Expr;
+    pos: Pos;
+} | {
+    kind: 'ternary';
+    cond: Expr;
+    then: Expr;
+    else: Expr;
+    pos: Pos;
+} | {
+    kind: 'index';
+    target: Expr;
+    index: Expr;
+    pos: Pos;
+} | {
+    kind: 'member';
+    target: Expr;
+    name: string;
+    pos: Pos;
+} | {
+    kind: 'call';
+    callee: Expr;
+    args: Arg[];
+    pos: Pos;
+} | {
+    kind: 'lambda';
+    params: Param[];
+    body: Expr;
+    pos: Pos;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: Expr;
+    pos: Pos;
+};
+export type ListItem = {
+    kind: 'item';
+    expr: Expr;
+} | {
+    kind: 'each';
+    expr: Expr;
+} | {
+    kind: 'for';
+    assigns: Assign[];
+    body: ListItem;
+} | {
+    kind: 'if';
+    cond: Expr;
+    then: ListItem;
+    else: ListItem | null;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: ListItem;
+};
+export interface Arg {
+    name: string | null;
+    value: Expr;
+}
+export interface Param {
+    name: string;
+    default: Expr | null;
+}
+export interface Assign {
+    name: string;
+    value: Expr;
+    pos: Pos;
+}
+export type Stmt = {
+    kind: 'assign';
+    name: string;
+    value: Expr;
+    span: [number, number];
+    pos: Pos;
+} | {
+    kind: 'module';
+    name: string;
+    params: Param[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'function';
+    name: string;
+    params: Param[];
+    body: Expr;
+    pos: Pos;
+} | {
+    kind: 'call';
+    name: string;
+    args: Arg[];
+    children: Stmt[];
+    modifier: string | null;
+    pos: Pos;
+} | {
+    kind: 'for';
+    assigns: Assign[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'if';
+    cond: Expr;
+    then: Stmt[];
+    else: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'block';
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'use';
+    path: string;
+    include: boolean;
+    pos: Pos;
+};
+export interface Program {
+    body: Stmt[];
+}

package/dist/ast.d.ts

@@ -0,0 +1,160 @@
+import type { Pos } from './lexer.js';
+export type Expr = {
+    kind: 'num';
+    value: number;
+    pos: Pos;
+} | {
+    kind: 'str';
+    value: string;
+    pos: Pos;
+} | {
+    kind: 'bool';
+    value: boolean;
+    pos: Pos;
+} | {
+    kind: 'undef';
+    pos: Pos;
+} | {
+    kind: 'var';
+    name: string;
+    pos: Pos;
+} | {
+    kind: 'list';
+    items: ListItem[];
+    pos: Pos;
+} | {
+    kind: 'range';
+    start: Expr;
+    step: Expr | null;
+    end: Expr;
+    pos: Pos;
+} | {
+    kind: 'unary';
+    op: string;
+    arg: Expr;
+    pos: Pos;
+} | {
+    kind: 'binary';
+    op: string;
+    left: Expr;
+    right: Expr;
+    pos: Pos;
+} | {
+    kind: 'ternary';
+    cond: Expr;
+    then: Expr;
+    else: Expr;
+    pos: Pos;
+} | {
+    kind: 'index';
+    target: Expr;
+    index: Expr;
+    pos: Pos;
+} | {
+    kind: 'member';
+    target: Expr;
+    name: string;
+    pos: Pos;
+} | {
+    kind: 'call';
+    callee: Expr;
+    args: Arg[];
+    pos: Pos;
+} | {
+    kind: 'lambda';
+    params: Param[];
+    body: Expr;
+    pos: Pos;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: Expr;
+    pos: Pos;
+};
+export type ListItem = {
+    kind: 'item';
+    expr: Expr;
+} | {
+    kind: 'each';
+    expr: Expr;
+} | {
+    kind: 'for';
+    assigns: Assign[];
+    body: ListItem;
+} | {
+    kind: 'if';
+    cond: Expr;
+    then: ListItem;
+    else: ListItem | null;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: ListItem;
+};
+export interface Arg {
+    name: string | null;
+    value: Expr;
+}
+export interface Param {
+    name: string;
+    default: Expr | null;
+}
+export interface Assign {
+    name: string;
+    value: Expr;
+    pos: Pos;
+}
+export type Stmt = {
+    kind: 'assign';
+    name: string;
+    value: Expr;
+    span: [number, number];
+    pos: Pos;
+} | {
+    kind: 'module';
+    name: string;
+    params: Param[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'function';
+    name: string;
+    params: Param[];
+    body: Expr;
+    pos: Pos;
+} | {
+    kind: 'call';
+    name: string;
+    args: Arg[];
+    children: Stmt[];
+    modifier: string | null;
+    pos: Pos;
+} | {
+    kind: 'for';
+    assigns: Assign[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'if';
+    cond: Expr;
+    then: Stmt[];
+    else: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'let';
+    assigns: Assign[];
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'block';
+    body: Stmt[];
+    pos: Pos;
+} | {
+    kind: 'use';
+    path: string;
+    include: boolean;
+    pos: Pos;
+};
+export interface Program {
+    body: Stmt[];
+}

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};