nicevg 0.0.0-stage → 0.15.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# nicevg for TypeScript (Bun and Node)
 
-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.
+nicevg で図を SVG に描く。TypeScript や JavaScript から、Bun では `bun:ffi`、Node では [koffi](https://koffi.dev/) でネイティブライブラリを呼ぶ。図はノードとコネクタの配列（Sketch）のほか、SVG の文字列でも渡せる。処理は Rust のネイティブコードで動くので、CLI と同じ速さで、出力も同じになる。
+
+## インストール
+
+```sh
+npm install nicevg   # または bun add nicevg
+```
+
+パッケージには、次の環境向けにビルド済みのネイティブライブラリが入っているので、インストール時にスクリプトは走らず、Rust も要らない。
+
+| 環境 | 対象 |
+|---|---|
+| Linux | x64、arm64（glibc 2.17 以降） |
+| macOS | arm64、x64 |
+| Windows | x64 |
+
+## 使い方
+
+入口は `render()` 1 つ。図を受け取り、配置の問題を直し、ノードを少し動かして折れ・交差・混雑を減らして、SVG を表す `Svg` を返す。
+
+```ts
+import { render } from "nicevg";
+
+const svg = render({
+  nodes: [
+    { id: "order", x: 20, y: 20, width: 120, height: 56, label: "Order" },
+    { id: "bill", x: 300, y: 160, width: 120, height: 56, label: "Bill" },
+    { id: "user", x: 40, y: 200, width: 80, height: 80, shape: "circle", label: "User" },
+  ],
+  connectors: [
+    { from: "order", to: "bill", label: "invoice" },
+    { from: "user", to: "order" },
+  ],
+});
+
+await svg.write("diagram.svg"); // ファイルに書く
+const text = svg.toString(); // SVG の文字列（`${svg}` でも同じ）
+
+for (const node of svg.report.diagram.nodes) {
+  console.log(node.id, node.bounds); // 動いた後の位置と大きさ
+}
+for (const connector of svg.report.diagram.connectors) {
+  console.log(connector.from, connector.to, connector.points); // 両端のノードと、直交する経路の折れ点
+}
+console.log(svg.report.issues); // 残った問題（なければ空）
+console.log(svg.changes); // 何を直し、何を動かしたか
+```
+
+- `input` は `Sketch`、`{ svg: string }`、または前に返った `Svg`。
+
+### Sketch
+
+| 項目 | 内容 |
+|---|---|
+| `nodes[].id`、`x`、`y`、`width`、`height` | ノードの id と、左上の位置と大きさ |
+| `nodes[].shape` | `"rect"`（既定）か `"circle"`。円は外接する正方形を `x`〜`height` で渡す |
+| `nodes[].label`、`fontSize` | 中に書く文字（`\n` で改行）。子を持つノードでは左上に、それ以外では中央に置く |
+| `nodes[].parent` | このノードを入れる親ノードの id |
+| `nodes[].allowOverlap` | 意図した重なりなら `true` |
+| `connectors[].from`、`to` | 両端のノードの id |
+| `connectors[].points` | 経路の折れ点。省くと、修正と配置調整が両端のノードの辺から辺へ経路を引く |
+| `connectors[].label`、`fontSize` | コネクタの脇に置く文字 |
+
+`Svg` の `report.diagram` は、描いた図を読み直したもので、ノード（`bounds`、ラベルの範囲 `labelBounds`）、コネクタ（`points`）、ラベル（`bounds`、説明するコネクタの id `connector`）を持つ。コネクタは id を持たないので、`from` と `to` で見分ける。文字の幅は、全角を 1 文字あたりフォントサイズ、それ以外を 0.59 倍として見積もる。
+
+形の書き方が違う入力や、存在しないノードを指す `from`・`to`・`parent` は、どこが何を指しているか（`connectors[0].to` など）を書いた `NicevgError` を投げる。
+
+描画は呼んだスレッドで最後まで走る。大きな図の配置調整は 1〜2 秒かかり、その間すべてのコアを使う。
+
+## 開発
+
+Bun と Node（型を取り除いて .ts を動かせる 22.18 以降）、Rust のツールチェーンが要る。
+
+```sh
+bun install
+bun run build       # cargo でネイティブライブラリを作って native/ に置き、tsc で src/ を dist/ に書き出す
+bun run test        # Bun で src/ を、Node でビルドした dist/ をテストする
+bun run typecheck
+```
+
+パッケージは Bun には `src/` の TypeScript を、Node には `dist/` の JavaScript と型定義を渡す（`package.json` の `exports`）。ネイティブライブラリは `NICEVG_LIBRARY` 環境変数、`native/<platform>-<arch>/`（`bun run build` が置く場所で、公開するパッケージでは全環境ぶん）、リポジトリの `target/release/` の順に探す。
+
+`v*` のタグを push すると、`.github/workflows/npm.yml` が各環境のネイティブライブラリを作ってパッケージに入れ、Bun と Node でテストしてから npm に公開する。タグの版と `package.json` の `version` が違えば止まるので、リリースのときは Rust の `Cargo.toml`（ルートと `bindings/js`）と一緒に `package.json` の版も上げる。手で実行すると、公開せずにビルドとパックだけを確かめられる。
+
+公開は npm の Trusted Publishing（GitHub Actions の OIDC）で、npm のトークンを使わず、配布元の証明（provenance）も自動で付く。
+
+Trusted Publisher はすでに npm にあるパッケージにしか登録できないので、最初の 1 回だけは手元から公開する。npm のアカウントで 2FA を有効にしたうえで、次のようにする。
+
+1. Actions の「Publish to npm」を手で実行する（手での実行は公開しない）。全環境のライブラリをそれぞれの環境でテストし、まとめたパッケージが、成果物 `npm-package` に残る。
+2. それを手元に落として公開する（2FA のワンタイムコードを聞かれる）。手元からの公開なので、この版には配布元の証明が付かない。
+   ```sh
+   gh run download <run-id> -n npm-package
+   npm publish ./nicevg-<version>.tgz
+   ```
+3. このリポジトリと `npm.yml` を Trusted Publisher に登録する（npmjs.com のパッケージの設定か、次のコマンド。どちらも 2FA が要る）。
+   ```sh
+   npm trust github nicevg --file npm.yml --repo takagiy/nicevg --allow-publish
+   ```
+
+以後はタグの push だけで公開される。npm のトークンは作らない（2FA を回避するトークンは、npm が段階的に廃止している）。

package/dist/bun-ffi.d.ts

@@ -0,0 +1,2 @@
+import type { Render } from "./native.ts";
+export declare function open(path: string): Render;

package/dist/bun-ffi.js

@@ -0,0 +1,23 @@
+// The native library through Bun's FFI.
+import { createRequire } from "node:module";
+export function open(path) {
+    // Loaded here rather than imported, so that the package loads on Node.
+    const { dlopen, FFIType, toArrayBuffer } = createRequire(import.meta.url)("bun:ffi");
+    // Bun runs on 64-bit platforms only, where a `usize` is a `u64`.
+    const { symbols } = dlopen(path, {
+        nicevg_render: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr], returns: FFIType.ptr },
+        nicevg_free: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void },
+    });
+    return (request) => {
+        const replyLength = new BigUint64Array(1);
+        const reply = symbols.nicevg_render(request, request.length, replyLength);
+        const length = Number(replyLength[0]);
+        try {
+            return new TextDecoder().decode(new Uint8Array(toArrayBuffer(reply, 0, length)));
+        }
+        finally {
+            symbols.nicevg_free(reply, length);
+        }
+    };
+}
+//# sourceMappingURL=bun-ffi.js.map

package/dist/bun-ffi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun-ffi.js","sourceRoot":"","sources":["../src/bun-ffi.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM5C,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAA6B,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC/G,iEAAiE;IACjE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE;QAC/B,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE;QACtF,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;KACzE,CAAC,CAAC;IACH,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,CAAY,CAAC;QACrF,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACnF,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * nicevg for TypeScript on Bun and Node: renders diagrams given as shapes
+ * (or as SVG text) into SVG, repairing their layout and arranging their
+ * nodes, by calling the native library through Bun's FFI or through koffi.
+ *
+ * ```ts
+ * import { render } from "nicevg";
+ *
+ * const svg = render({
+ *   nodes: [
+ *     { id: "order", x: 20, y: 20, width: 120, height: 56, label: "Order" },
+ *     { id: "bill", x: 300, y: 160, width: 120, height: 56, label: "Bill" },
+ *   ],
+ *   connectors: [{ from: "order", to: "bill", label: "invoice" }],
+ * });
+ * await svg.write("diagram.svg");
+ * svg.report.diagram.connectors; // where the routes ended up, in the order given
+ * ```
+ *
+ * Rendering runs on the calling thread and blocks it until done; arranging
+ * a large diagram takes a second or two, using every core.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A box, or a circle whose bounds are the square around it. */
+export interface SketchNode {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    shape?: "rect" | "circle";
+    /** Its text, lines split at `\n`: at the top left of a node with children, centred in any other. */
+    label?: string;
+    fontSize?: number;
+    /** The node this one sits inside. */
+    parent?: string;
+    /** Whether it may overlap other nodes on purpose. */
+    allowOverlap?: boolean;
+}
+/**
+ * A connector from one node to another, along `points` when given. Without
+ * them it runs between the nodes' centres, which rendering reroutes from
+ * side to side. Connectors have no id: in the rendered diagram, tell them
+ * apart by their `from` and `to`.
+ */
+export interface SketchConnector {
+    from: string;
+    to: string;
+    points?: Point[];
+    /** Its text, lines split at `\n`, placed beside it. */
+    label?: string;
+    fontSize?: number;
+}
+/** A diagram as nodes and the connectors between them. */
+export interface Sketch {
+    nodes: SketchNode[];
+    connectors?: SketchConnector[];
+}
+/** A diagram to render: a sketch, SVG text following nicevg's SVG contract, or an Svg rendered before. */
+export type Input = Sketch | {
+    svg: string;
+} | Svg;
+export interface DiagramNode {
+    id: string;
+    shape?: "circle";
+    bounds: Bounds;
+    labelBounds: Bounds[];
+    parentId?: string;
+    allowOverlap?: boolean;
+}
+export interface DiagramConnector {
+    /** Its id in an SVG; a sketch's connectors get one for their labels to refer to. */
+    id: string;
+    from: string;
+    to: string;
+    points: Point[];
+}
+export interface DiagramLabel {
+    id: string;
+    bounds: Bounds;
+    /** The id of the connector it describes. */
+    connector?: string;
+}
+export interface Diagram {
+    nodes: DiagramNode[];
+    connectors: DiagramConnector[];
+    labels: DiagramLabel[];
+    unsupportedElements: {
+        id: string;
+        tagName: string;
+    }[];
+}
+export interface Issue {
+    code: string;
+    message: string;
+    elements: string[];
+    details?: Record<string, unknown>;
+}
+export interface AnalysisReport {
+    valid: boolean;
+    issues: Issue[];
+    drawingBounds: Bounds | null;
+    diagram: Diagram;
+}
+export interface Change {
+    code: string;
+    message: string;
+    elements: string[];
+}
+/** A rendered diagram as SVG, with what rendering changed and the diagram read back from it. */
+export declare class Svg {
+    #private;
+    /** What fixing and arranging changed, in order. */
+    readonly changes: Change[];
+    /** The diagram read back: where its nodes, routes and labels ended up, and any issue left. */
+    readonly report: AnalysisReport;
+    constructor(text: string, 
+    /** What fixing and arranging changed, in order. */
+    changes: Change[], 
+    /** The diagram read back: where its nodes, routes and labels ended up, and any issue left. */
+    report: AnalysisReport);
+    /** The SVG text. */
+    toString(): string;
+    /** Writes the SVG text to a file. */
+    write(path: string | URL): Promise<void>;
+}
+/** An input nicevg cannot read, saying what is wrong and where. */
+export declare class NicevgError extends Error {
+    name: string;
+}
+/**
+ * Renders a diagram into SVG: repairs its layout errors (overlapping nodes,
+ * routes through nodes, stray labels and more), routes the connectors given
+ * no points, and moves nodes a little where that reads better.
+ */
+export declare function render(input: Input): Svg;

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * nicevg for TypeScript on Bun and Node: renders diagrams given as shapes
+ * (or as SVG text) into SVG, repairing their layout and arranging their
+ * nodes, by calling the native library through Bun's FFI or through koffi.
+ *
+ * ```ts
+ * import { render } from "nicevg";
+ *
+ * const svg = render({
+ *   nodes: [
+ *     { id: "order", x: 20, y: 20, width: 120, height: 56, label: "Order" },
+ *     { id: "bill", x: 300, y: 160, width: 120, height: 56, label: "Bill" },
+ *   ],
+ *   connectors: [{ from: "order", to: "bill", label: "invoice" }],
+ * });
+ * await svg.write("diagram.svg");
+ * svg.report.diagram.connectors; // where the routes ended up, in the order given
+ * ```
+ *
+ * Rendering runs on the calling thread and blocks it until done; arranging
+ * a large diagram takes a second or two, using every core.
+ */
+import { writeFile } from "node:fs/promises";
+import { call as native } from "./native.js";
+/** A rendered diagram as SVG, with what rendering changed and the diagram read back from it. */
+export class Svg {
+    changes;
+    report;
+    #text;
+    constructor(text, 
+    /** What fixing and arranging changed, in order. */
+    changes, 
+    /** The diagram read back: where its nodes, routes and labels ended up, and any issue left. */
+    report) {
+        this.changes = changes;
+        this.report = report;
+        this.#text = text;
+    }
+    /** The SVG text. */
+    toString() {
+        return this.#text;
+    }
+    /** Writes the SVG text to a file. */
+    write(path) {
+        return writeFile(path, this.#text);
+    }
+}
+/** An input nicevg cannot read, saying what is wrong and where. */
+export class NicevgError extends Error {
+    name = "NicevgError";
+}
+/**
+ * Renders a diagram into SVG: repairs its layout errors (overlapping nodes,
+ * routes through nodes, stray labels and more), routes the connectors given
+ * no points, and moves nodes a little where that reads better.
+ */
+export function render(input) {
+    const request = new TextEncoder().encode(JSON.stringify(input instanceof Svg ? { svg: input.toString() } : input));
+    const reply = JSON.parse(native(request));
+    if ("error" in reply) {
+        throw new NicevgError(reply.error);
+    }
+    return new Svg(reply.ok.svg, reply.ok.changes, reply.ok.report);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AA0G7C,gGAAgG;AAChG,MAAM,OAAO,GAAG;IAMH;IAEA;IAPF,KAAK,CAAS;IAEvB,YACE,IAAY;IACZ,mDAAmD;IAC1C,OAAiB;IAC1B,8FAA8F;IACrF,MAAsB;QAFtB,YAAO,GAAP,OAAO,CAAU;QAEjB,WAAM,GAAN,MAAM,CAAgB;QAE/B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,oBAAoB;IACpB,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,IAAkB;QACtB,OAAO,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,GAAG,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAY;IACjC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACnH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAEnB,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC"}

package/dist/native.d.ts

@@ -0,0 +1,4 @@
+/** Fixes and arranges the diagram in a JSON request, returning the JSON reply. */
+export type Render = (request: Uint8Array) => string;
+/** Fixes and arranges the diagram in `request`, opening the library on first use. */
+export declare function call(request: Uint8Array): string;

package/dist/native.js

@@ -0,0 +1,34 @@
+// Finding and calling the native library, through Bun's FFI on Bun and
+// through koffi elsewhere.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { open as openOnBun } from "./bun-ffi.js";
+import { open as openOnNode } from "./node-ffi.js";
+const extension = process.platform === "win32" ? "dll" : process.platform === "darwin" ? "dylib" : "so";
+const libraryName = process.platform === "win32" ? `nicevg_ffi.${extension}` : `libnicevg_ffi.${extension}`;
+/** The package's root: this file sits in `src/`, or compiled in `dist/`. */
+const root = fileURLToPath(new URL("..", import.meta.url));
+/**
+ * Where the native library may be: as set, packaged for this platform in
+ * `native/<platform>-<arch>/`, or built in this repository.
+ */
+function libraryPath() {
+    const candidates = [
+        process.env.NICEVG_LIBRARY,
+        join(root, "native", `${process.platform}-${process.arch}`, libraryName),
+        join(root, "..", "..", "target", "release", libraryName),
+    ].filter((candidate) => candidate !== undefined);
+    const found = candidates.find((candidate) => existsSync(candidate));
+    if (!found) {
+        throw new Error(`nicevg: no native library for ${process.platform}-${process.arch}; looked at ${candidates.join(", ")}.`);
+    }
+    return found;
+}
+let render;
+/** Fixes and arranges the diagram in `request`, opening the library on first use. */
+export function call(request) {
+    render ??= (typeof Bun === "undefined" ? openOnNode : openOnBun)(libraryPath());
+    return render(request);
+}
+//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,2BAA2B;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AAKnD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACxG,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,SAAS,EAAE,CAAC,CAAC,CAAC,iBAAiB,SAAS,EAAE,CAAC;AAC5G,4EAA4E;AAC5E,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE3D;;;GAGG;AACH,SAAS,WAAW;IAClB,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,GAAG,CAAC,cAAc;QAC1B,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC;QACxE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC;KACzD,CAAC,MAAM,CAAC,CAAC,SAAS,EAAuB,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,eAAe,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,IAAI,MAA0B,CAAC;AAE/B,qFAAqF;AACrF,MAAM,UAAU,IAAI,CAAC,OAAmB;IACtC,MAAM,KAAK,CAAC,OAAO,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC"}

package/dist/node-ffi.d.ts

@@ -0,0 +1,2 @@
+import type { Render } from "./native.ts";
+export declare function open(path: string): Render;

package/dist/node-ffi.js

@@ -0,0 +1,23 @@
+// The native library through koffi, for Node.
+import { createRequire } from "node:module";
+export function open(path) {
+    // Loaded here rather than imported, so that Bun never loads it.
+    const koffi = createRequire(import.meta.url)("koffi");
+    const library = koffi.load(path);
+    const render = library.func("void *nicevg_render(const uint8_t *request, size_t length, _Out_ size_t *reply_length)");
+    const free = library.func("void nicevg_free(void *reply, size_t length)");
+    return (request) => {
+        const replyLength = [0];
+        const reply = render(request, request.length, replyLength);
+        const length = Number(replyLength[0]);
+        try {
+            // Copied out rather than viewed in place, which Electron forbids.
+            const bytes = koffi.decode(reply, koffi.array("uint8_t", length, "Typed"));
+            return new TextDecoder().decode(bytes);
+        }
+        finally {
+            free(reply, length);
+        }
+    };
+}
+//# sourceMappingURL=node-ffi.js.map

package/dist/node-ffi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-ffi.js","sourceRoot":"","sources":["../src/node-ffi.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,gEAAgE;IAChE,MAAM,KAAK,GAA2B,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CACzB,wFAAwF,CACzF,CAAC;IACF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC1E,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,kEAAkE;YAClE,MAAM,KAAK,GAAe,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YACvF,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "nicevg",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.15.0",
+  "description": "Deterministic checks and repairs for diagrams, given as shapes or SVG, on Bun and Node through native FFI.",
+  "keywords": [
+    "diagram",
+    "svg",
+    "layout",
+    "routing",
+    "ffi"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/takagiy/nicevg#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/takagiy/nicevg.git",
+    "directory": "bindings/js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "native"
+  ],
+  "engines": {
+    "bun": ">=1.1",
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run build:native && bun run build:js",
+    "build:native": "bun run scripts/build-native.ts",
+    "build:js": "tsc -p tsconfig.build.json",
+    "test": "bun run test:bun && bun run test:node",
+    "test:bun": "bun test ./test/bun",
+    "test:node": "node --test \"test/node/**/*.test.*\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "koffi": "3.3.3"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "@types/node": "24.10.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/bun-ffi.ts

@@ -0,0 +1,27 @@
+// The native library through Bun's FFI.
+
+import { createRequire } from "node:module";
+
+import type { Pointer } from "bun:ffi";
+
+import type { Render } from "./native.ts";
+
+export function open(path: string): Render {
+  // Loaded here rather than imported, so that the package loads on Node.
+  const { dlopen, FFIType, toArrayBuffer }: typeof import("bun:ffi") = createRequire(import.meta.url)("bun:ffi");
+  // Bun runs on 64-bit platforms only, where a `usize` is a `u64`.
+  const { symbols } = dlopen(path, {
+    nicevg_render: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr], returns: FFIType.ptr },
+    nicevg_free: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void },
+  });
+  return (request) => {
+    const replyLength = new BigUint64Array(1);
+    const reply = symbols.nicevg_render(request, request.length, replyLength) as Pointer;
+    const length = Number(replyLength[0]);
+    try {
+      return new TextDecoder().decode(new Uint8Array(toArrayBuffer(reply, 0, length)));
+    } finally {
+      symbols.nicevg_free(reply, length);
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+/**
+ * nicevg for TypeScript on Bun and Node: renders diagrams given as shapes
+ * (or as SVG text) into SVG, repairing their layout and arranging their
+ * nodes, by calling the native library through Bun's FFI or through koffi.
+ *
+ * ```ts
+ * import { render } from "nicevg";
+ *
+ * const svg = render({
+ *   nodes: [
+ *     { id: "order", x: 20, y: 20, width: 120, height: 56, label: "Order" },
+ *     { id: "bill", x: 300, y: 160, width: 120, height: 56, label: "Bill" },
+ *   ],
+ *   connectors: [{ from: "order", to: "bill", label: "invoice" }],
+ * });
+ * await svg.write("diagram.svg");
+ * svg.report.diagram.connectors; // where the routes ended up, in the order given
+ * ```
+ *
+ * Rendering runs on the calling thread and blocks it until done; arranging
+ * a large diagram takes a second or two, using every core.
+ */
+
+import { writeFile } from "node:fs/promises";
+
+import { call as native } from "./native.ts";
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** A box, or a circle whose bounds are the square around it. */
+export interface SketchNode {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  shape?: "rect" | "circle";
+  /** Its text, lines split at `\n`: at the top left of a node with children, centred in any other. */
+  label?: string;
+  fontSize?: number;
+  /** The node this one sits inside. */
+  parent?: string;
+  /** Whether it may overlap other nodes on purpose. */
+  allowOverlap?: boolean;
+}
+
+/**
+ * A connector from one node to another, along `points` when given. Without
+ * them it runs between the nodes' centres, which rendering reroutes from
+ * side to side. Connectors have no id: in the rendered diagram, tell them
+ * apart by their `from` and `to`.
+ */
+export interface SketchConnector {
+  from: string;
+  to: string;
+  points?: Point[];
+  /** Its text, lines split at `\n`, placed beside it. */
+  label?: string;
+  fontSize?: number;
+}
+
+/** A diagram as nodes and the connectors between them. */
+export interface Sketch {
+  nodes: SketchNode[];
+  connectors?: SketchConnector[];
+}
+
+/** A diagram to render: a sketch, SVG text following nicevg's SVG contract, or an Svg rendered before. */
+export type Input = Sketch | { svg: string } | Svg;
+
+export interface DiagramNode {
+  id: string;
+  shape?: "circle";
+  bounds: Bounds;
+  labelBounds: Bounds[];
+  parentId?: string;
+  allowOverlap?: boolean;
+}
+
+export interface DiagramConnector {
+  /** Its id in an SVG; a sketch's connectors get one for their labels to refer to. */
+  id: string;
+  from: string;
+  to: string;
+  points: Point[];
+}
+
+export interface DiagramLabel {
+  id: string;
+  bounds: Bounds;
+  /** The id of the connector it describes. */
+  connector?: string;
+}
+
+export interface Diagram {
+  nodes: DiagramNode[];
+  connectors: DiagramConnector[];
+  labels: DiagramLabel[];
+  unsupportedElements: { id: string; tagName: string }[];
+}
+
+export interface Issue {
+  code: string;
+  message: string;
+  elements: string[];
+  details?: Record<string, unknown>;
+}
+
+export interface AnalysisReport {
+  valid: boolean;
+  issues: Issue[];
+  drawingBounds: Bounds | null;
+  diagram: Diagram;
+}
+
+export interface Change {
+  code: string;
+  message: string;
+  elements: string[];
+}
+
+/** A rendered diagram as SVG, with what rendering changed and the diagram read back from it. */
+export class Svg {
+  readonly #text: string;
+
+  constructor(
+    text: string,
+    /** What fixing and arranging changed, in order. */
+    readonly changes: Change[],
+    /** The diagram read back: where its nodes, routes and labels ended up, and any issue left. */
+    readonly report: AnalysisReport,
+  ) {
+    this.#text = text;
+  }
+
+  /** The SVG text. */
+  toString(): string {
+    return this.#text;
+  }
+
+  /** Writes the SVG text to a file. */
+  write(path: string | URL): Promise<void> {
+    return writeFile(path, this.#text);
+  }
+}
+
+/** An input nicevg cannot read, saying what is wrong and where. */
+export class NicevgError extends Error {
+  override name = "NicevgError";
+}
+
+/**
+ * Renders a diagram into SVG: repairs its layout errors (overlapping nodes,
+ * routes through nodes, stray labels and more), routes the connectors given
+ * no points, and moves nodes a little where that reads better.
+ */
+export function render(input: Input): Svg {
+  const request = new TextEncoder().encode(JSON.stringify(input instanceof Svg ? { svg: input.toString() } : input));
+  const reply = JSON.parse(native(request)) as
+    | { ok: { svg: string; changes: Change[]; report: AnalysisReport } }
+    | { error: string };
+  if ("error" in reply) {
+    throw new NicevgError(reply.error);
+  }
+  return new Svg(reply.ok.svg, reply.ok.changes, reply.ok.report);
+}

package/src/lib.rs

@@ -0,0 +1,81 @@
+//! A C interface to nicevg for runtimes that load native libraries, such as
+//! Bun's FFI or koffi on Node: a diagram as JSON in, the fixed and arranged
+//! diagram as JSON out.
+//!
+//! The request is either `{"svg": "..."}` or a sketch (`{"nodes": [...],
+//! "connectors": [...]}`). The reply is `{"ok": ...}`, holding the fix
+//! result, or `{"error": "..."}`.
+
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use serde_json::{Value, json};
+
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
+enum Input {
+    Svg(String),
+    Sketch(nicevg::Sketch),
+}
+
+fn read(request: &[u8]) -> Result<Input, String> {
+    let value: Value = serde_json::from_slice(request).map_err(|error| format!("invalid JSON: {error}"))?;
+    if let Some(svg) = value.get("svg") {
+        return svg
+            .as_str()
+            .map(|svg| Input::Svg(svg.to_owned()))
+            .ok_or_else(|| "svg: expected a string".to_owned());
+    }
+    serde_path_to_error::deserialize(value)
+        .map(Input::Sketch)
+        .map_err(|error| format!("{}: {}", error.path(), error.inner()))
+}
+
+fn render(request: &[u8]) -> Result<Value, String> {
+    let result = match read(request)? {
+        Input::Svg(svg) => nicevg::arrange(&svg).map_err(|error| error.to_string())?,
+        Input::Sketch(sketch) => nicevg::arrange_sketch(&sketch).map_err(|error| error.to_string())?,
+    };
+    Ok(serde_json::to_value(result).expect("serializable result"))
+}
+
+/// Fixes and arranges the diagram in the JSON request of `length` bytes at
+/// `request`, and returns the JSON reply, its length written to
+/// `reply_length`. The caller frees the reply with [`nicevg_free`].
+///
+/// # Safety
+///
+/// `request` points to `length` readable bytes and `reply_length` to a
+/// writable `usize`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn nicevg_render(request: *const u8, length: usize, reply_length: *mut usize) -> *mut u8 {
+    let request = if length == 0 {
+        &[][..]
+    } else {
+        // SAFETY: the caller passes `length` readable bytes.
+        unsafe { std::slice::from_raw_parts(request, length) }
+    };
+    let reply = match catch_unwind(AssertUnwindSafe(|| render(request))) {
+        Ok(Ok(value)) => json!({ "ok": value }),
+        Ok(Err(message)) => json!({ "error": message }),
+        Err(_) => json!({ "error": "nicevg stopped on an internal error" }),
+    };
+    let bytes = serde_json::to_vec(&reply)
+        .expect("serializable reply")
+        .into_boxed_slice();
+    // SAFETY: the caller passes a writable `usize`.
+    unsafe { *reply_length = bytes.len() };
+    Box::into_raw(bytes).cast::<u8>()
+}
+
+/// Frees a reply [`nicevg_render`] returned.
+///
+/// # Safety
+///
+/// `reply` and `length` are a reply and its length from [`nicevg_render`],
+/// freed only once.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn nicevg_free(reply: *mut u8, length: usize) {
+    // SAFETY: the reply was a boxed slice of `length` bytes.
+    drop(unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(reply, length)) });
+}

package/src/native.ts

@@ -0,0 +1,44 @@
+// Finding and calling the native library, through Bun's FFI on Bun and
+// through koffi elsewhere.
+
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+import { open as openOnBun } from "./bun-ffi.ts";
+import { open as openOnNode } from "./node-ffi.ts";
+
+/** Fixes and arranges the diagram in a JSON request, returning the JSON reply. */
+export type Render = (request: Uint8Array) => string;
+
+const extension = process.platform === "win32" ? "dll" : process.platform === "darwin" ? "dylib" : "so";
+const libraryName = process.platform === "win32" ? `nicevg_ffi.${extension}` : `libnicevg_ffi.${extension}`;
+/** The package's root: this file sits in `src/`, or compiled in `dist/`. */
+const root = fileURLToPath(new URL("..", import.meta.url));
+
+/**
+ * Where the native library may be: as set, packaged for this platform in
+ * `native/<platform>-<arch>/`, or built in this repository.
+ */
+function libraryPath(): string {
+  const candidates = [
+    process.env.NICEVG_LIBRARY,
+    join(root, "native", `${process.platform}-${process.arch}`, libraryName),
+    join(root, "..", "..", "target", "release", libraryName),
+  ].filter((candidate): candidate is string => candidate !== undefined);
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) {
+    throw new Error(
+      `nicevg: no native library for ${process.platform}-${process.arch}; looked at ${candidates.join(", ")}.`,
+    );
+  }
+  return found;
+}
+
+let render: Render | undefined;
+
+/** Fixes and arranges the diagram in `request`, opening the library on first use. */
+export function call(request: Uint8Array): string {
+  render ??= (typeof Bun === "undefined" ? openOnNode : openOnBun)(libraryPath());
+  return render(request);
+}

package/src/node-ffi.ts

@@ -0,0 +1,27 @@
+// The native library through koffi, for Node.
+
+import { createRequire } from "node:module";
+
+import type { Render } from "./native.ts";
+
+export function open(path: string): Render {
+  // Loaded here rather than imported, so that Bun never loads it.
+  const koffi: typeof import("koffi") = createRequire(import.meta.url)("koffi");
+  const library = koffi.load(path);
+  const render = library.func(
+    "void *nicevg_render(const uint8_t *request, size_t length, _Out_ size_t *reply_length)",
+  );
+  const free = library.func("void nicevg_free(void *reply, size_t length)");
+  return (request) => {
+    const replyLength = [0];
+    const reply = render(request, request.length, replyLength);
+    const length = Number(replyLength[0]);
+    try {
+      // Copied out rather than viewed in place, which Electron forbids.
+      const bytes: Uint8Array = koffi.decode(reply, koffi.array("uint8_t", length, "Typed"));
+      return new TextDecoder().decode(bytes);
+    } finally {
+      free(reply, length);
+    }
+  };
+}