etassia 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,15 +1,95 @@
1
- # etassia-ts
1
+ # etassia
2
2
 
3
- TypeScript binding for the Etassia Rust runtime: `crates/etassia-wasm` (etassia-core on
4
- `wasm32-unknown-unknown`, no wasm-bindgen glue) plus a thin loader. All rendering,
5
- including number formatting, happens in Rust; JS only moves bytes.
3
+ The npm package `etassia` is the TypeScript binding for the Etassia diagram
4
+ engine: a Mermaid-syntax diagram source is rendered to SVG by the Rust runtime
5
+ (`crates/etassia-wasm` on the `wasm32-unknown-unknown` target), which ships
6
+ inside the package as WebAssembly. All rendering, including number formatting,
7
+ happens in Rust; JavaScript only moves bytes. The package is a single
8
+ platform-independent artifact, because the same `.wasm` binary serves every
9
+ operating system and processor architecture that Node.js 20 or newer supports.
10
+
11
+ ## Install
12
+
13
+ ```sh
14
+ npm install etassia
15
+ ```
16
+
17
+ ## Usage
6
18
 
7
19
  ```ts
8
- import { render, detect, UnportedError, EtassiaError } from "etassia-ts";
9
- try { const svg = render("pie\n \"a\": 1\n"); }
10
- catch (e) { if (e instanceof UnportedError) { /* use the Ruby fallback */ } }
20
+ import { render, detect, UnportedError, EtassiaError } from "etassia";
21
+
22
+ try {
23
+ const svg = render("pie\n \"a\": 1\n"); // SVG bytes, produced entirely by the Rust runtime
24
+ } catch (e) {
25
+ if (e instanceof UnportedError) {
26
+ // The runtime has no renderer for this diagram type; use the Ruby fallback.
27
+ } else if (e instanceof EtassiaError) {
28
+ // The source is invalid: errorClass, line and col describe the failure.
29
+ }
30
+ }
11
31
  ```
12
32
 
13
- `npm test` builds the wasm (needs the `wasm32-unknown-unknown` rust target), then
14
- renders every `golden/` case (or `ETASSIA_GOLDEN_DIR`) and byte-compares it with Ruby's SVG.
15
- Not published; version unchanged.
33
+ `detect(source)` returns the diagram type name and throws `EtassiaError` when
34
+ the type is undetectable.
35
+
36
+ ## Engine pinning and releases
37
+
38
+ Every release of this package vendors the engine built from one exact
39
+ etassia-rs commit. The commit is recorded in `etassia-rs-version.txt` at the
40
+ repository root, and the `etassia-rs` git submodule is pinned to the same
41
+ commit. The ride ritual is that the package version and the pin move together
42
+ in one commit: an engine update is a version bump plus the new pin, and no
43
+ release ships a wasm binary whose provenance is not the recorded commit. At
44
+ build time, `scripts/build-wasm.mjs` reads the pin and fetches the engine
45
+ source for that commit from codeload.github.com into `tmp/engine`; a local
46
+ etassia-rs checkout is used instead when the `ETASSIA_ENGINE_DIR` environment
47
+ variable names it. The golden corpus that the tests and the smoke check render
48
+ against comes from the same submodule, so the corpus and the engine are pinned
49
+ together.
50
+
51
+ Releases are cut by pushing a tag of the form `etassia-ts-v<version>`, where
52
+ the version equals the `version` field of `package.json`, and the release
53
+ workflow fails when the two differ. Publication to npm uses Trusted Publishing
54
+ (OIDC), which signs the published tarball with provenance that npm verifies
55
+ against this repository and this workflow file.
56
+
57
+ ## Development
58
+
59
+ ```sh
60
+ npm ci
61
+ npm run build # fetches the pinned engine, builds crates/etassia-wasm, compiles src/ to dist/
62
+ npm test # renders the whole golden corpus through the wasm build and byte-compares it with Ruby
63
+ ```
64
+
65
+ `npm test` requires the `wasm32-unknown-unknown` Rust target; the build script
66
+ installs it through rustup when rustup is available. When `ETASSIA_ENGINE_DIR`
67
+ points at a local etassia-rs checkout, the build compiles that checkout instead
68
+ of the pin, which is the workflow for engine development.
69
+
70
+ The installed tarball is smoked separately from the build: `npm pack` produces
71
+ the tarball, the tarball is installed into a clean project, and
72
+ `scripts/smoke_installed_npm.mjs` renders one golden case and compares the
73
+ result byte for byte with the Ruby-rendered reference.
74
+
75
+ ```sh
76
+ mkdir -p pkg && npm pack --pack-destination pkg
77
+ # in a clean project, with the tarball and the two golden files copied in:
78
+ npm install --no-audit --no-fund ./etassia-*.tgz
79
+ node scripts/smoke_installed_npm.mjs \
80
+ etassia-rs/golden/pie/pie_spec-0b1f3197.mmd \
81
+ etassia-rs/golden/pie/pie_spec-0b1f3197.svg
82
+ ```
83
+
84
+ ## WebAssembly notes
85
+
86
+ The shipped `dist/etassia.wasm` is the raw cdylib output of
87
+ `crates/etassia-wasm`; the package does not run the wasm-bindgen command-line
88
+ tool and does not generate glue code. `src/index.ts` instantiates the module
89
+ directly and supplies the one import that the binary declares on the render
90
+ path, the `__wbg_getRandomValues_*` stub that fills the entropy request of the
91
+ getrandom dependency, which seeds hash generators; every other stub throws when
92
+ called, which keeps an unexpected import visible instead of silent. Rendering
93
+ allocates the source in linear memory, calls `etassia_render` or
94
+ `etassia_detect`, and reads the result back through the result pointer; the
95
+ source allocation is released even when the call fails.
package/dist/etassia.wasm CHANGED
Binary file
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "etassia",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "TypeScript binding for the Etassia Rust runtime (etassia-core compiled to WebAssembly)",
5
5
  "license": "BSD-2-Clause",
6
- "repository": { "type": "git", "url": "git+https://github.com/etassia/etassia-rs.git", "directory": "bindings/ts" },
6
+ "repository": { "type": "git", "url": "git+https://github.com/etassia/etassia-ts.git" },
7
7
  "type": "module",
8
8
  "main": "dist/index.js",
9
9
  "types": "dist/index.d.ts",
@@ -13,7 +13,8 @@
13
13
  "scripts": {
14
14
  "build:wasm": "node scripts/build-wasm.mjs",
15
15
  "build": "npm run build:wasm && tsc -p tsconfig.json",
16
- "test": "npm run build && node --test test/golden.test.mjs"
16
+ "test": "npm run build && node --test test/golden.test.mjs",
17
+ "prepublishOnly": "npm run build"
17
18
  },
18
19
  "devDependencies": {
19
20
  "@types/node": "^22.0.0",