@mylasertools/kerfscript 0.2.1 → 0.4.0

package/docs/webassembly.md

@@ -0,0 +1,133 @@
+# WebAssembly
+
+`kerfscript.wasm` runs KerfScript from any language that can host a
+WebAssembly module: Python, Rust, Go, C#, Java, Ruby and others. It is a
+WASI (preview 1) module built from the same source as the JavaScript package,
+so it makes the same SVG and DXF files, byte for byte.
+
+For JavaScript applications, use the [JavaScript API](javascript.md)
+instead: it is smaller and faster.
+
+## Getting the module
+
+Download `kerfscript-<version>.wasm` from the
+[releases](https://github.com/mylasertools/kerfscript/releases) page and save
+it as `kerfscript.wasm`, or get `kerfscript-wasm-<version>.zip`, which has the
+module with this guide and its licences. You can also build it from the
+repository with [Javy](https://github.com/bytecodealliance/javy):
+
+```sh
+npm run build
+npm run wasm        # writes dist/kerfscript.wasm
+```
+
+Set `JAVY` to the javy binary if it is not on the `PATH`.
+
+## How it works
+
+The module reads one JSON request from standard input, writes one JSON
+response to standard output and exits. Start a fresh instance for each
+request. From a shell, with [Wasmtime](https://wasmtime.dev):
+
+```sh
+echo '{"source": "rect([80, 50]);"}' | wasmtime run kerfscript.wasm
+```
+
+### Request
+
+| Field         | Value                                                                       |
+| ------------- | --------------------------------------------------------------------------- |
+| `command`     | `"render"` (default), `"params"`, `"version"` or `"licenses"`               |
+| `source`      | The program, as a string                                                    |
+| `params`      | Parameter values keyed by name                                              |
+| `files`       | Libraries for `include` and `use`, keyed by path: `{"lib/tab.kerf": "..."}` |
+| `fonts`       | Font files keyed by name, base64 encoded. `Atkinson` is built in            |
+| `defaultFont` | Name to use when `text()` does not specify a font                           |
+| `kerf`        | Kerf override for every part, in millimetres                                |
+| `layout`      | `"pack"` (default) or `"none"`                                              |
+| `sheet`       | Sheet size `[width, height]` in millimetres                                 |
+| `gap`         | Space between packed parts                                                  |
+| `margin`      | Space between the parts and the sheet edge                                  |
+| `guides`      | `true` to include guide layer geometry                                      |
+
+These match the [render() options](javascript.md#options). A path in `files`
+can leave out `.kerf`, as in the program.
+
+### Response
+
+Every response has `ok`. When it is `false`, `error` holds the message and
+`echoes` holds what the program echoed before it stopped. The module never
+exits with an error code for a bad program.
+
+- `render`: `svg` (all sheets, for preview), `width`, `height`, `parts`,
+  `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`.
+- `licenses`: `files`, the licence texts of the module and of everything
+  built into it, keyed by file name: `LICENSE`, `COMMERCIAL-LICENSE.md`,
+  `THIRD-PARTY-NOTICES.md`, `THIRD-PARTY-LICENSES.md` (the JavaScript engine
+  and its Rust crates) and `OFL.txt`. The release ZIP has the same files.
+
+## Python
+
+With the [`wasmtime`](https://pypi.org/project/wasmtime/) package:
+
+```python
+import json, os, tempfile
+from wasmtime import Engine, Linker, Module, Store, WasiConfig
+
+engine = Engine()
+module = Module.from_file(engine, "kerfscript.wasm")
+linker = Linker(engine)
+linker.define_wasi()
+
+def kerf(request):
+    with tempfile.TemporaryDirectory() as d:
+        inp, out = os.path.join(d, "in.json"), os.path.join(d, "out.json")
+        with open(inp, "w", encoding="utf-8") as f:
+            json.dump(request, f)
+        wasi = WasiConfig()
+        wasi.stdin_file = inp
+        wasi.stdout_file = out
+        store = Store(engine)
+        store.set_wasi(wasi)
+        linker.instantiate(store, module).exports(store)["_start"](store)
+        with open(out, encoding="utf-8") as f:
+            return json.load(f)
+
+result = kerf({"source": "w = 80; rect([w, 50]);", "params": {"w": 120}})
+for i, sheet in enumerate(result["sheets"]):
+    with open(f"sheet-{i + 1}.svg", "w", encoding="utf-8", newline="") as f:
+        f.write(sheet["svg"])
+```
+
+Compile the module once and reuse it; each request only needs a new `Store`.
+
+## Node.js
+
+The JavaScript package is the better fit in Node.js, but the module also runs
+under `node:wasi`, which is how the test suite checks it:
+
+```js
+import { closeSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { WASI } from 'node:wasi';
+
+const module = await WebAssembly.compile(readFileSync('kerfscript.wasm'));
+writeFileSync('in.json', JSON.stringify({ source: 'rect([80, 50]);' }));
+const stdin = openSync('in.json', 'r');
+const stdout = openSync('out.json', 'w');
+const wasi = new WASI({ version: 'preview1', stdin, stdout, returnOnExit: true });
+wasi.start(await WebAssembly.instantiate(module, wasi.getImportObject()));
+closeSync(stdin);
+closeSync(stdout);
+console.log(JSON.parse(readFileSync('out.json', 'utf8')).svg);
+```
+
+## Performance
+
+The module carries its own JavaScript engine (QuickJS), so it is about 2 MB
+and renders roughly three to five times slower than Node.js. The example
+designs take well under a second.

package/fonts/OFL.txt

@@ -0,0 +1,92 @@
+Copyright 2020 Braille Institute of America, Inc.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mylasertools/kerfscript",
-  "version": "0.2.1",
+  "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",
@@ -45,12 +45,14 @@
   },
   "files": [
     "dist",
+    "!dist/kerfscript.wasm",
     "README.md",
     "docs",
     "LANGUAGE.md",
     "LICENSE",
     "COMMERCIAL-LICENSE.md",
     "THIRD-PARTY-NOTICES.md",
+    "fonts/OFL.txt",
     "CHANGELOG.md",
     "TRADEMARKS.md",
     "CLA.md"
@@ -70,9 +72,10 @@
     "site": "npm run build && npm --prefix site run build",
     "site:serve": "npm --prefix site run preview",
     "prepack": "npm run check",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
+    "format": "prettier --write . --ignore-path .gitignore --ignore-path .prettierignore --ignore-path .git/info/exclude",
+    "format:check": "prettier --check . --ignore-path .gitignore --ignore-path .prettierignore --ignore-path .git/info/exclude",
     "compat": "node scripts/compat.mjs",
+    "wasm": "node scripts/wasm.mjs",
     "readme-images": "npm run build && cd site && node ../scripts/readme-images.mjs"
   },
   "devDependencies": {