@archipen/render 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archipen contributors
+
+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.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @archipen/render
 
-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.
+Render [Archipen](https://archipen.dev/) diagrams (`.archipen.json`) to SVG, PNG and PDF without a browser. You can
+use it from the command line, from Node, or as an HTTP server.
+
+```sh
+npx @archipen/render export diagram.archipen.json -o diagram.png   # or: npm install -g @archipen/render
+```
+
+```js
+import { renderPng } from '@archipen/render'
+const png = await renderPng(readFileSync('diagram.archipen.json', 'utf8'), { theme: 'dark', scale: 2 })
+```
+
+```sh
+archipen serve --port 8080 --base-path /tools/archipen-api
+curl -X POST --data-binary @diagram.archipen.json 'localhost:8080/tools/archipen-api/export?format=pdf' -o diagram.pdf
+```
+
+Node.js 22 or newer. Run `archipen --help` for all options. Full guide: <https://archipen.dev/export>.
+
+Fonts: Instrument Sans, SIL Open Font License (`fonts/OFL.txt`). Vendor logos: Simple Icons, credited in
+`vendor-icon-credits.txt`; the logos are trademarks of their owners. Bundled third-party code: `dist/THIRD-PARTY-NOTICES.txt`.

package/dist/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,81 @@
+@archipen/render: third-party notices
+=====================================
+
+This build contains code from the following packages. Their licences are reproduced below.
+
+
+------------------------------------------------------------------------------
+
+lucide 1.66.0 (ISC)
+https://github.com/lucide-icons/lucide.git
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+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.
+
+------------------------------------------------------------------------------
+
+zod 4.6.7 (MIT)
+git+https://github.com/colinhacks/zod.git
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+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.

package/dist/chunks/env-D14HK4d7.mjs

@@ -0,0 +1,3 @@
+// src/env.ts
+process.env.NODE_ENV ??= "production";
+export {};

package/dist/chunks/server-BOCCbETh.mjs

@@ -0,0 +1,354 @@
+import { o as fileBaseName, r as FORMATS, t as CONTENT_TYPES } from "./src-79SWTPGl.mjs";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { createServer } from "node:http";
+import { availableParallelism } from "node:os";
+import { Worker } from "node:worker_threads";
+// src/pool.ts
+/** Why a render did not produce a file. */
+var RenderFailure = class extends Error {
+	kind;
+	issues;
+	constructor(kind, message, issues = []) {
+		super(message);
+		this.kind = kind;
+		this.issues = issues;
+	}
+};
+/**
+* worker.mjs sits in dist/. This module is in dist/ or dist/chunks/ once built,
+* and in src/ when the tests run it (they build first).
+*/
+function defaultWorkerUrl() {
+	const url = [
+		"./worker.mjs",
+		"../worker.mjs",
+		"../dist/worker.mjs"
+	].map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
+	if (!url) throw new Error("@archipen/render: dist/worker.mjs not found (run \"npm run build\" in render/)");
+	return url;
+}
+var RenderPool = class {
+	opts;
+	slots = [];
+	queue = [];
+	nextId = 1;
+	closed = false;
+	url;
+	constructor(opts) {
+		this.opts = opts;
+		this.url = opts.workerUrl ?? defaultWorkerUrl();
+		for (let i = 0; i < Math.max(1, opts.workers); i++) this.slots.push(this.spawn());
+	}
+	render(raw, format, opts) {
+		if (this.closed) return Promise.reject(new RenderFailure("busy", "The server is shutting down"));
+		if (this.queue.length >= this.opts.maxQueue) return Promise.reject(new RenderFailure("busy", "The server is busy, try again shortly"));
+		return new Promise((resolve, reject) => {
+			this.queue.push({
+				msg: {
+					id: this.nextId++,
+					raw,
+					format,
+					opts
+				},
+				resolve,
+				reject
+			});
+			this.dispatch();
+		});
+	}
+	async close() {
+		this.closed = true;
+		for (const job of this.queue.splice(0)) job.reject(new RenderFailure("busy", "The server is shutting down"));
+		await Promise.all(this.slots.map((s) => this.finish(s, new RenderFailure("busy", "The server is shutting down"))));
+	}
+	spawn() {
+		const worker = new Worker(this.url, {
+			execArgv: [],
+			resourceLimits: { maxOldGenerationSizeMb: 512 }
+		});
+		worker.unref();
+		const slot = { worker };
+		worker.on("message", (reply) => {
+			const job = slot.job;
+			if (!job || job.msg.id !== reply.id) return;
+			this.done(slot);
+			if (reply.ok) job.resolve(Buffer.from(reply.bytes.buffer, reply.bytes.byteOffset, reply.bytes.byteLength));
+			else if (reply.kind === "diagram") job.reject(new RenderFailure("diagram", "Not a valid Archipen file", reply.issues));
+			else job.reject(new RenderFailure(reply.kind, reply.message));
+			this.dispatch();
+		});
+		worker.on("error", (e) => this.replace(slot, new RenderFailure("error", `Rendering failed: ${e.message}`)));
+		worker.on("exit", () => this.replace(slot, new RenderFailure("error", "Rendering failed")));
+		return slot;
+	}
+	dispatch() {
+		for (const slot of this.slots) {
+			if (slot.job || !this.queue.length) continue;
+			const job = this.queue.shift();
+			slot.job = job;
+			slot.timer = setTimeout(() => {
+				const s = Math.round(this.opts.timeoutMs / 1e3);
+				this.replace(slot, new RenderFailure("timeout", `Rendering took longer than ${s} s; the diagram is too complex`));
+			}, this.opts.timeoutMs);
+			slot.worker.postMessage(job.msg);
+		}
+	}
+	done(slot) {
+		clearTimeout(slot.timer);
+		slot.job = slot.timer = void 0;
+	}
+	/** Reject the slot's running job, if any, and stop its worker. */
+	finish(slot, err) {
+		const job = slot.job;
+		this.done(slot);
+		job?.reject(err);
+		slot.worker.removeAllListeners();
+		slot.worker.on("error", () => {});
+		return slot.worker.terminate();
+	}
+	replace(slot, err) {
+		const i = this.slots.indexOf(slot);
+		if (i < 0) return;
+		this.finish(slot, err);
+		if (this.closed) return;
+		this.slots[i] = this.spawn();
+		this.dispatch();
+	}
+};
+// src/server.ts
+/** Server settings from the environment, as documented in docs/hosting.md. Unset ones keep their defaults. */
+function envOptions(env = process.env) {
+	const int = (name, min) => {
+		const v = env[name];
+		if (v === void 0 || v === "") return void 0;
+		const n = Number(v);
+		if (!Number.isInteger(n) || n < min) throw new Error(`${name} must be a whole number of at least ${min} (got "${v}")`);
+		return n;
+	};
+	return {
+		corsOrigin: env.CORS_ORIGIN || void 0,
+		workers: int("RENDER_WORKERS", 1),
+		maxQueue: int("RENDER_QUEUE", 0),
+		renderTimeoutMs: int("RENDER_TIMEOUT_MS", 100),
+		maxItems: int("MAX_ITEMS", 1)
+	};
+}
+var MB = 1048576;
+var HttpError = class extends Error {
+	status;
+	extra;
+	constructor(status, message, extra = {}) {
+		super(message);
+		this.status = status;
+		this.extra = extra;
+	}
+};
+/** "/tools/api/" → "/tools/api", "" or "/" → "". Throws on a path without a leading slash. */
+function normalizeBasePath(p) {
+	const s = (p ?? "").trim().replace(/\/+$/, "");
+	if (s && !s.startsWith("/")) throw new Error(`BASE_PATH must start with "/" (got "${p}")`);
+	return s;
+}
+function usage(base) {
+	return `Archipen export server
+
+POST ${base}/export?format=svg|png|pdf   body: diagram JSON (.archipen.json)
+  theme=light|dark  projection=iso|2d  page=<id> (default: all pages; PNG: the first)  scale=2 (PNG, max 8)  padding=32
+  transparent=1  animate=1 (SVG)  font=0 (SVG without embedded font)
+GET  ${base}/healthz
+
+Example:
+  curl -X POST --data-binary @diagram.archipen.json '<host>${base}/export?format=png' -o diagram.png
+`;
+}
+var flag = (v) => v !== null && v !== "0" && v !== "false" && v !== "no";
+function numberParam(q, name, min, max) {
+	const v = q.get(name);
+	if (v === null || v === "") return void 0;
+	const n = Number(v);
+	if (!Number.isFinite(n) || n < min || n > max) throw new HttpError(400, `${name} must be a number from ${min} to ${max}`);
+	return n;
+}
+function parseQuery(q) {
+	const format = (q.get("format") ?? "svg").toLowerCase();
+	if (!FORMATS.includes(format)) throw new HttpError(400, "format must be svg, png or pdf");
+	const theme = q.get("theme") ?? void 0;
+	if (theme && theme !== "light" && theme !== "dark") throw new HttpError(400, "theme must be light or dark");
+	const projection = q.get("projection") ?? void 0;
+	if (projection && projection !== "iso" && projection !== "2d") throw new HttpError(400, "projection must be iso or 2d");
+	return {
+		format,
+		opts: {
+			theme,
+			projection,
+			page: q.get("page") || void 0,
+			scale: numberParam(q, "scale", .1, 8),
+			padding: numberParam(q, "padding", 0, 1e3),
+			background: !flag(q.get("transparent")),
+			animate: flag(q.get("animate")),
+			embedFont: q.get("font") === null || flag(q.get("font"))
+		}
+	};
+}
+async function readBody(req, limit) {
+	if (Number(req.headers["content-length"]) > limit) throw new HttpError(413, `Request body is larger than ${Math.round(limit / MB)} MB`);
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		size += chunk.length;
+		if (size > limit) throw new HttpError(413, `Request body is larger than ${Math.round(limit / MB)} MB`);
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
+}
+/** "Web shop" → `inline; filename="Web shop.png"; filename*=UTF-8''Web%20shop.png` (ASCII fallback for old clients). */
+function disposition(name) {
+	return `inline; filename="${name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_")}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+/** Nodes, zones, edges and texts on all pages of a parsed (not yet validated) diagram. */
+function itemCount(raw) {
+	const pages = raw && typeof raw === "object" ? raw.pages : void 0;
+	if (!Array.isArray(pages)) return 0;
+	const count = (p) => p && typeof p === "object" ? [
+		"nodes",
+		"zones",
+		"edges",
+		"texts"
+	].reduce((n, k) => n + (Array.isArray(p[k]) ? p[k].length : 0), 0) : 0;
+	return pages.reduce((n, p) => n + count(p), 0);
+}
+/** The request handler on its own, e.g. to mount it in an existing server. Call `close()` when done. */
+function createHandler(options = {}) {
+	const base = normalizeBasePath(options.basePath);
+	const limit = options.maxBodyBytes ?? 5 * MB;
+	const cors = options.corsOrigin;
+	const maxItems = options.maxItems ?? 1e3;
+	const workers = options.workers ?? availableParallelism();
+	const pool = new RenderPool({
+		workers,
+		maxQueue: options.maxQueue ?? workers * 8,
+		timeoutMs: options.renderTimeoutMs ?? 2e4,
+		workerUrl: options.workerUrl
+	});
+	const send = (res, status, body, type, headers = {}) => {
+		res.writeHead(status, {
+			"Content-Type": type,
+			"Content-Length": Buffer.byteLength(body),
+			...headers
+		});
+		res.end(body);
+	};
+	const sendJson = (res, status, data, headers = {}) => send(res, status, JSON.stringify(data), "application/json; charset=utf-8", headers);
+	const handler = async (req, res) => {
+		res.setHeader("X-Content-Type-Options", "nosniff");
+		res.setHeader("Referrer-Policy", "no-referrer");
+		if (cors) {
+			res.setHeader("Access-Control-Allow-Origin", cors);
+			res.setHeader("Vary", "Origin");
+		}
+		const url = new URL(req.url ?? "/", "http://localhost");
+		const path = url.pathname;
+		const method = req.method ?? "GET";
+		try {
+			if (base && path === base) {
+				res.writeHead(308, { Location: `${base}/${url.search}` });
+				return res.end();
+			}
+			if (path === `${base}/` && (method === "GET" || method === "HEAD")) return send(res, 200, usage(base), "text/plain; charset=utf-8");
+			if (path === `${base}/healthz` && (method === "GET" || method === "HEAD")) return send(res, 200, "ok\n", "text/plain; charset=utf-8", { "Cache-Control": "no-store" });
+			if (path === `${base}/export`) {
+				if (method === "OPTIONS" && cors) {
+					res.writeHead(204, {
+						"Access-Control-Allow-Methods": "POST, OPTIONS",
+						"Access-Control-Allow-Headers": "Content-Type",
+						"Access-Control-Max-Age": "86400"
+					});
+					return res.end();
+				}
+				if (method !== "POST") throw new HttpError(405, "Use POST with the diagram JSON as the body", { allow: "POST" });
+				const { format, opts } = parseQuery(url.searchParams);
+				const body = await readBody(req, limit);
+				let raw;
+				try {
+					raw = JSON.parse(body.toString("utf8"));
+				} catch (e) {
+					throw new HttpError(400, `Body is not valid JSON: ${e.message}`);
+				}
+				const items = itemCount(raw);
+				if (items > maxItems) throw new HttpError(422, `The diagram has ${items} items; this server renders at most ${maxItems}`);
+				const bytes = await pool.render(raw, format, opts);
+				const title = typeof raw.name === "string" ? raw.name : "";
+				const headers = {
+					"Content-Disposition": disposition(`${fileBaseName(title)}.${format}`),
+					"Cache-Control": "no-store"
+				};
+				if (format === "svg") headers["Content-Security-Policy"] = "default-src 'none'; style-src 'unsafe-inline'; font-src data:; img-src data:; sandbox";
+				return send(res, 200, bytes, CONTENT_TYPES[format], headers);
+			}
+			throw new HttpError(404, "Not found");
+		} catch (e) {
+			if (e instanceof HttpError) {
+				const headers = e.status === 405 ? { Allow: String(e.extra.allow) } : {};
+				if (e.status === 413) headers.Connection = "close";
+				return sendJson(res, e.status, { error: e.message }, headers);
+			}
+			if (e instanceof RenderFailure) {
+				if (e.kind === "diagram") return sendJson(res, 400, {
+					error: e.message,
+					issues: e.issues
+				});
+				if (e.kind === "limit" || e.kind === "timeout") return sendJson(res, 422, { error: e.message });
+				if (e.kind === "busy") return sendJson(res, 503, { error: e.message }, { "Retry-After": "5" });
+			}
+			console.error(e);
+			return sendJson(res, 500, { error: "Rendering failed" });
+		}
+	};
+	return Object.assign(handler, { close: () => pool.close() });
+}
+/** Start the export server. Resolves once it is listening. */
+async function startServer(options = {}) {
+	const base = normalizeBasePath(options.basePath);
+	const handler = createHandler({
+		...envOptions(),
+		...withoutUndefined(options),
+		basePath: base
+	});
+	const server = createServer((req, res) => void handler(req, res));
+	server.requestTimeout = 3e4;
+	server.headersTimeout = 1e4;
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port ?? 8080, options.host, resolve);
+	});
+	const { port } = server.address();
+	return {
+		server,
+		url: `http://localhost:${port}${base}/`,
+		close: async () => {
+			await new Promise((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+			await handler.close();
+		}
+	};
+}
+var withoutUndefined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+/** Start the server and stop it cleanly on SIGTERM/SIGINT (needed as PID 1 in a container). Logs where it listens. */
+async function serve(options) {
+	const { url, close } = await startServer(options);
+	console.error(`Archipen export server listening on ${url}`);
+	const stop = () => {
+		close().finally(() => process.exit(0));
+		setTimeout(() => process.exit(0), 5e3).unref();
+	};
+	process.once("SIGTERM", stop);
+	process.once("SIGINT", stop);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) serve({
+	port: Number(process.env.PORT || 8080),
+	basePath: process.env.BASE_PATH
+}).catch((e) => {
+	console.error(`archipen: ${e.message}`);
+	process.exit(1);
+});
+export { startServer as a, serve as i, envOptions as n, normalizeBasePath as r, createHandler as t };