@mylasertools/kerfscript 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,38 @@
-# KerfScript
-
-**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/)
+<p align="center">
+  <a href="https://kerfscript.mylasertools.com"><img src=".github/readme/banner.png" alt="KerfScript, a programming language for laser cutting" width="840"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mylasertools/kerfscript"><img src="https://img.shields.io/npm/v/@mylasertools/kerfscript?color=d8361f&label=npm" alt="npm version"></a>
+  <a href="COMMERCIAL-LICENSE.md"><img src="https://img.shields.io/badge/licence-AGPL--3.0%20or%20free%20commercial-1f1a17" alt="Licence: AGPL-3.0 or free commercial"></a>
+  <a href="LANGUAGE.md"><img src="https://img.shields.io/badge/language-0.1-e3c69a" alt="Language version 0.1"></a>
+  <a href="https://kerfscript.mylasertools.com/playground/"><img src="https://img.shields.io/badge/try%20it-playground-5a3519" alt="Try it in the playground"></a>
+</p>
+
+<p align="center">
+  <a href="https://kerfscript.mylasertools.com">Website</a> ·
+  <a href="https://kerfscript.mylasertools.com/playground/">Playground</a> ·
+  <a href="https://kerfscript.mylasertools.com/models/">Models</a> ·
+  <a href="https://kerfscript.mylasertools.com/docs/">Docs</a> ·
+  <a href="https://www.npmjs.com/package/@mylasertools/kerfscript">npm</a>
+</p>
 
 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.
 
+<p align="center">
+  <a href="https://kerfscript.mylasertools.com/playground/?model=fractal-tree"><img src=".github/readme/playground.gif" alt="Moving a slider in the playground changes the number in the code and redraws the fractal tree" width="840"></a>
+  <br><sub>The <a href="https://kerfscript.mylasertools.com/playground/">playground</a> runs the interpreter in your browser. A comment after a number turns it into a slider.</sub>
+</p>
+
+## Example
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
 ```kerf
 use <kerf/box>
 
@@ -28,6 +49,13 @@ $kerf = 0.15; // [0:0.01:0.5]
 box([width, depth, height], lid = lid);
 ```
 
+</td>
+<td width="50%" valign="top">
+<img src=".github/readme/model-box.png" alt="Six finger-jointed panels of a box, packed on a sheet">
+</td>
+</tr>
+</table>
+
 ```sh
 npx @mylasertools/kerfscript render box.kerf -o box.svg -D width=200
 ```
@@ -37,6 +65,35 @@ 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.
 
+## Made with KerfScript
+
+Every model is a file in [examples/](examples). Open one on the website to
+turn it around in 3D, change its settings and download the SVG or DXF, or copy
+it as the start of your own design.
+
+<table>
+<tr>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/hadal/"><img src="site/public/3d/hadal.webp" alt="Hadal sculpture, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/hadal/">Hadal sculpture</a></b><br><sub>13 slotted parts, ribs computed from lists</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/tilt-maze/"><img src="site/public/3d/tilt-maze.webp" alt="Tilt maze, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/tilt-maze/">Tilt maze</a></b><br><sub>a new maze for every seed, by recursion</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/topo-island/"><img src="site/public/3d/topo-island.webp" alt="Layered island, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/topo-island/">Layered island</a></b><br><sub>contours traced from a height formula</sub></td>
+</tr>
+<tr>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/fractal-tree/"><img src="site/public/3d/fractal-tree.webp" alt="Fractal tree, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/fractal-tree/">Fractal tree</a></b><br><sub>a module that calls itself</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/round-badge/"><img src="site/public/3d/round-badge.webp" alt="Round badge, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/round-badge/">Round badge</a></b><br><sub>text set letter by letter around a circle</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/winterlight/"><img src="site/public/3d/winterlight.webp" alt="Winterlight ornaments, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/winterlight/">Winterlight ornaments</a></b><br><sub>one-piece ornaments with scored detail</sub></td>
+</tr>
+<tr>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/xenospora/"><img src="site/public/3d/xenospora.webp" alt="Xenospora seed pod, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/xenospora/">Xenospora seed pod</a></b><br><sub>16 parts on 3 sheets, one file per sheet</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/solstice/"><img src="site/public/3d/solstice.webp" alt="Solstice lantern, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/solstice/">Solstice lantern</a></b><br><sub>tabs, slots and a fit test piece</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/box/"><img src="site/public/3d/box.webp" alt="Finger-jointed box, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/box/">Finger-jointed box</a></b><br><sub>six panels from one library call</sub></td>
+</tr>
+<tr>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/wave-cathedral/"><img src="site/public/3d/wave-cathedral.webp" alt="Wave Cathedral, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/wave-cathedral/">Wave Cathedral</a></b><br><sub>17 different ribs from one formula</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/gift-tags/"><img src="site/public/3d/gift-tags.webp" alt="Gift tags from a list, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/gift-tags/">Gift tags from a list</a></b><br><sub>one tag per name, each name fitted</sub></td>
+<td width="33%" valign="top"><a href="https://kerfscript.mylasertools.com/models/umbra/"><img src="site/public/3d/umbra.webp" alt="Umbra shadow machine, assembled"></a><br><b><a href="https://kerfscript.mylasertools.com/models/umbra/">Umbra shadow machine</a></b><br><sub>six fins whose shadows make one dragon</sub></td>
+</tr>
+</table>
+
 ## Why a new language
 
 - **Laser concepts are built in.** `engrave()`, `score()` and `cut()` put
@@ -44,17 +101,20 @@ and has not been tested in other laser software.
   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.
+- **Joinery that follows the material.** `finger_rect`, `finger_holes`,
+  `tslot` and `living_hinge` use `$thickness`, so the joints resize when the
+  material changes. Measure your kerf and cut a test piece for a snug fit.
+- **Readable code.** Variables, modules, functions, loops and transforms like
+  `translate()` and `rotate()`. Settings come from comments such as
+  `// [10:1:100]`, which the playground turns into sliders. If you have used
+  OpenSCAD, [Coming from OpenSCAD](docs/openscad.md) lists what differs.
 - **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.
+- **Contained.** Programs read libraries only through the resolver you
+  provide and have no other access to files or the network. Step, recursion
+  and size limits stop runaway programs, and errors name the line. Run
+  programs you did not write in a worker or process you can stop; see
+  [Running untrusted code](docs/javascript.md#running-untrusted-code).
 
 ## Install
 
@@ -62,6 +122,12 @@ and has not been tested in other laser software.
 npm install @mylasertools/kerfscript
 ```
 
+The `kerf` command line also comes as a standalone binary that needs no
+Node.js, and through Homebrew, winget, Chocolatey, Scoop, Snap, the AUR,
+MacPorts and Docker: see [Command line](docs/cli.md#without-nodejs). The
+desktop app is in [Desktop app](docs/desktop.md), and the WebAssembly module
+in [WebAssembly](docs/webassembly.md).
+
 ## Command line
 
 ```sh
@@ -99,7 +165,9 @@ Errors are thrown as `KerfError` with `line` and `col`.
 - [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)
+  the [desktop app](docs/desktop.md), the [command line](docs/cli.md), the
+  [JavaScript API](docs/javascript.md)
+  and [WebAssembly](docs/webassembly.md) for other languages
 - [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
@@ -107,25 +175,6 @@ Errors are thrown as `KerfError` with `line` and `col`.
 - [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
@@ -141,8 +190,9 @@ KerfScript is free software under the
 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).
+Building KerfScript into a closed-source app, machine or service? The
+[commercial licence](COMMERCIAL-LICENSE.md#free-commercial-licence) is free:
+just email hi@mylasertools.com.
 
 "KerfScript" is a trademark of MyLaserTools; see [TRADEMARKS.md](TRADEMARKS.md).
 Contributions need the [CLA](CLA.md); see [CONTRIBUTING.md](CONTRIBUTING.md).

package/THIRD-PARTY-NOTICES.md

@@ -62,8 +62,72 @@ 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)
+## tiny-inflate 1.0.3 (bundled, part of opentype.js)
 
-`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`.
+Source: https://github.com/foliojs/tiny-inflate
+
+```text
+MIT License
+
+Copyright (c) 2015-present Devon Govett
+
+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.
+```
+
+## string.prototype.codepointat 0.2.1 (bundled, part of opentype.js)
+
+Source: https://github.com/mathiasbynens/String.prototype.codePointAt
+
+```text
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+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.
+```
+
+## Desktop app
+
+The desktop app is also built from Rust crates (Tauri and its dependencies)
+under MIT, Apache-2.0, MPL-2.0, BSD, ISC, Zlib, Unicode and similar licences.
+`desktop/THIRD-PARTY-LICENSES.md` lists each one with its licence text, and
+the installers place it next to the app.
+
+## Atkinson Hyperlegible (built into the command line and kerfscript.wasm)
+
+`fonts/AtkinsonHyperlegible-Regular.ttf`, Copyright 2020 Braille Institute
+of America, Inc., licensed under the SIL Open Font License 1.1. See
+`fonts/OFL.txt`. It is embedded unmodified in `dist/cli.js` and
+`kerfscript.wasm`, and the playground serves it; `dist/index.js` does not
+include it.

package/TRADEMARKS.md

@@ -2,16 +2,22 @@
 
 "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
+(AGPL-3.0-only and the free commercial licence) 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.
+This policy identifies the official KerfScript project while allowing others
+to describe tools that work with the language. MyLaserTools controls the
+official language versions and releases.
 
 ## You may, without asking
 
 - say your design, tutorial, course, video or library is written **in**
   KerfScript or works **with** KerfScript
+- describe an independent editor, implementation or service as compatible
+  with a specific KerfScript language version when the claim is accurate,
+  its limitations are clear and you do not imply MyLaserTools endorsement
+- use KerfScript in a descriptive phrase such as "an editor for KerfScript"
+  alongside your own distinct product name
 - 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
@@ -21,19 +27,19 @@ file written for one KerfScript tool works in every tool that uses the name.
 
 - 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
+- call your own implementation, editor or service "official" or imply
+  that MyLaserTools endorses it
 - 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.
+Creative Commons Attribution 4.0 (CC BY 4.0). You may copy, translate and
+adapt it with attribution and a note describing your changes. Adapted
+references are not official KerfScript language versions. MyLaserTools
+publishes the official reference and decides which language changes it adopts.
 
 ## Contact
 
-julia@mylasertools.com
+hi@mylasertools.com