@kitschpatrol/unplugin-tldraw 1.0.0

package/dist/tldraw-ZdwazU9j.js

@@ -0,0 +1,309 @@
+import { defu } from "defu";
+import { log, setDefaultLogOptions } from "lognow";
+import path from "node:path";
+import { tldrawToImage } from "@kitschpatrol/tldraw-cli";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import pLimit from "p-limit";
+import prettyBytes from "pretty-bytes";
+import prettyMilliseconds from "pretty-ms";
+//#region src/core/options.ts
+const DEFAULT_OPTIONS = {
+	cacheDirectory: "./node_modules/.cache/tldraw",
+	cacheEnabled: true,
+	defaultImageOptions: {
+		dark: false,
+		format: "svg",
+		padding: 32,
+		scale: 1,
+		stripStyle: false,
+		transparent: false
+	},
+	maxConcurrentConversions: 2,
+	pruneCacheOnBuild: false,
+	verbose: false
+};
+/**
+* Resolve and normalize user options.
+*/
+function resolveOptions(options) {
+	const resolved = defu(options, DEFAULT_OPTIONS);
+	resolved.cacheDirectory = path.resolve(resolved.cacheDirectory);
+	return resolved;
+}
+/**
+* Parse query params from an import path into per-import overrides.
+* Converts string values to appropriate types (booleans, numbers).
+*/
+function parseImportOverrides(queryString) {
+	const params = new URLSearchParams(queryString);
+	const overrides = {};
+	for (const [key, value] of params.entries()) {
+		if (key === "tldr" || key === "tldraw") continue;
+		switch (key) {
+			case "dark":
+			case "stripStyle":
+			case "transparent":
+				if (value === "true" || value === "") overrides[key] = true;
+				else if (value === "false") overrides[key] = false;
+				else log.warn(`Ignoring invalid value for "${key}": "${value}". Expected "true" or "false".`);
+				break;
+			case "format":
+				overrides.format = value;
+				break;
+			case "frame":
+			case "page":
+				overrides[key] = value;
+				break;
+			case "padding":
+			case "scale": {
+				const numberValue = Number(value);
+				if (!Number.isNaN(numberValue)) overrides[key] = numberValue;
+				break;
+			}
+			default: break;
+		}
+	}
+	return overrides;
+}
+//#endregion
+//#region src/core/tldraw.ts
+const CACHE_FILE_NAME = ".tldraw-plugin-cache.json";
+const TLDR_EXTENSION_REGEX = /\.tldr(?:\?|$)/;
+const CACHE_HASH_REGEX = /-([a-f\d]{8})\.[^.]+$/;
+var TldrawExport = class {
+	/**
+	* Pattern matching `.tldr` file imports. The `resolveId` hook filters on
+	* this.
+	*/
+	get identifierPattern() {
+		return TLDR_EXTENSION_REGEX;
+	}
+	convertLimit;
+	options;
+	pathsSeen = /* @__PURE__ */ new Set();
+	pendingRequests = /* @__PURE__ */ new Map();
+	persistentCacheDirty = false;
+	resolvedCache = /* @__PURE__ */ new Map();
+	get cacheFilePath() {
+		return path.join(this.options.cacheDirectory, CACHE_FILE_NAME);
+	}
+	constructor(options) {
+		this.options = resolveOptions(options);
+		this.convertLimit = pLimit(this.options.maxConcurrentConversions);
+		setDefaultLogOptions({
+			name: "unplugin-tldraw",
+			verbose: this.options.verbose
+		});
+	}
+	/**
+	* Converts a `.tldr` file to an image and returns the absolute path of the
+	* cached image. Uses caching, request deduplication, and concurrency
+	* limiting.
+	*
+	* @param tldrPath - Absolute or relative path to the `.tldr` file.
+	* @param overrides - Per-import option overrides (from query params).
+	*/
+	async convert(tldrPath, overrides) {
+		const absolutePath = path.resolve(tldrPath);
+		const cacheKey = overrides && Object.keys(overrides).length > 0 ? `${absolutePath}?${stableStringify(overrides)}` : absolutePath;
+		if (this.options.cacheEnabled) {
+			const cached = this.resolvedCache.get(cacheKey);
+			if (cached !== void 0) {
+				if (await this.isFileHashCurrent(absolutePath, cached, overrides)) {
+					log.debug(`Cache hit for "${this.relativePath(absolutePath)}"`);
+					if (this.options.pruneCacheOnBuild) this.pathsSeen.add(cached);
+					return cached;
+				}
+				this.resolvedCache.delete(cacheKey);
+				this.persistentCacheDirty = true;
+			}
+		}
+		const pending = this.pendingRequests.get(cacheKey);
+		if (pending !== void 0) {
+			log.debug(`Waiting for in-flight conversion of "${this.relativePath(absolutePath)}"`);
+			return pending;
+		}
+		const convertPromise = this.convertLimit(async () => this.doConvert(absolutePath, overrides));
+		this.pendingRequests.set(cacheKey, convertPromise);
+		try {
+			const result = await convertPromise;
+			this.resolvedCache.set(cacheKey, result);
+			this.persistentCacheDirty = true;
+			await this.savePersistentCache();
+			return result;
+		} finally {
+			this.pendingRequests.delete(cacheKey);
+		}
+	}
+	/**
+	* Initialize the cache directory and load persistent cache from disk.
+	*/
+	async initialize() {
+		await fs.mkdir(this.options.cacheDirectory, { recursive: true });
+		await this.loadPersistentCache();
+		log.debug(`Initialized with cache at "${this.options.cacheDirectory}"`);
+	}
+	/**
+	* Delete cached files that were not used during this build.
+	*/
+	async pruneCache() {
+		if (!this.options.pruneCacheOnBuild) return;
+		const destinationFiles = await fs.readdir(this.options.cacheDirectory);
+		const fileNamesToKeep = new Set(Array.from(this.pathsSeen, (filePath) => path.basename(filePath)));
+		for (const destinationFile of destinationFiles) {
+			if (destinationFile === CACHE_FILE_NAME) continue;
+			if (!fileNamesToKeep.has(destinationFile)) {
+				log.debug(`Cleaning up unused image: ${destinationFile}`);
+				await fs.rm(path.join(this.options.cacheDirectory, destinationFile));
+			}
+		}
+	}
+	/**
+	* Persist the in-memory cache to disk.
+	*/
+	async savePersistentCache() {
+		if (!this.persistentCacheDirty) return;
+		const cache = {};
+		for (const [identifier, result] of this.resolvedCache.entries()) cache[this.toRelativeCacheKey(identifier)] = { result: toPosixPath(path.relative(this.options.cacheDirectory, result)) };
+		await fs.writeFile(this.cacheFilePath, JSON.stringify(cache, void 0, 2));
+		this.persistentCacheDirty = false;
+		log.debug(`Saved ${this.resolvedCache.size} entries to persistent cache`);
+	}
+	async doConvert(absolutePath, overrides) {
+		const startTime = performance.now();
+		const { frame, page, ...imageOverrides } = overrides ?? {};
+		const mergedImageOptions = defu(imageOverrides, this.options.defaultImageOptions);
+		const { format } = mergedImageOptions;
+		const optionsForHash = { ...mergedImageOptions };
+		if (frame !== void 0) optionsForHash.frame = frame;
+		if (page !== void 0) optionsForHash.page = page;
+		const contentHash = await computeCacheKey(absolutePath, optionsForHash);
+		const slugParts = [path.basename(absolutePath, ".tldr")];
+		if (page !== void 0) slugParts.push(slugify(page));
+		if (frame !== void 0) slugParts.push(slugify(frame));
+		slugParts.push(contentHash);
+		const cachedFileName = `${slugParts.filter(Boolean).join("-")}.${format}`;
+		const cachedFilePath = path.join(this.options.cacheDirectory, cachedFileName);
+		if (this.options.cacheEnabled && await fileExists(cachedFilePath)) {
+			log.debug(`Disk cache hit for "${this.relativePath(absolutePath)}" → "${cachedFileName}"`);
+			if (this.options.pruneCacheOnBuild) this.pathsSeen.add(cachedFilePath);
+			return cachedFilePath;
+		}
+		log.debug(`Converting "${this.relativePath(absolutePath)}"...`);
+		await fs.mkdir(this.options.cacheDirectory, { recursive: true });
+		const tempOutputDirectory = path.join(this.options.cacheDirectory, `.tmp-${crypto.randomUUID()}`);
+		await fs.mkdir(tempOutputDirectory, { recursive: true });
+		const tldrawCliOptions = {
+			dark: mergedImageOptions.dark,
+			format,
+			output: tempOutputDirectory,
+			padding: mergedImageOptions.padding,
+			scale: mergedImageOptions.scale,
+			stripStyle: mergedImageOptions.stripStyle,
+			transparent: mergedImageOptions.transparent
+		};
+		if (frame !== void 0) tldrawCliOptions.frames = [frame];
+		if (page !== void 0) tldrawCliOptions.pages = [page];
+		try {
+			const outputFile = (await tldrawToImage(absolutePath, tldrawCliOptions))[0];
+			if (!outputFile) throw new Error(`tldraw-cli produced no output for "${absolutePath}"`);
+			await fs.rename(outputFile, cachedFilePath);
+		} finally {
+			await fs.rm(tempOutputDirectory, {
+				force: true,
+				recursive: true
+			});
+		}
+		if (this.options.pruneCacheOnBuild) this.pathsSeen.add(cachedFilePath);
+		const elapsed = prettyMilliseconds(performance.now() - startTime);
+		const fileSize = prettyBytes((await fs.stat(cachedFilePath)).size);
+		log.debug(`Converted in ${elapsed} (${fileSize}) → "${cachedFileName}"`);
+		return cachedFilePath;
+	}
+	fromRelativeCacheKey(relativeKey) {
+		const queryIndex = relativeKey.indexOf("?");
+		const relativePath = queryIndex === -1 ? relativeKey : relativeKey.slice(0, queryIndex);
+		const query = queryIndex === -1 ? "" : relativeKey.slice(queryIndex);
+		return path.resolve(this.options.cacheDirectory, relativePath) + query;
+	}
+	/**
+	* Checks if a cached result still matches the source file's content hash.
+	*/
+	async isFileHashCurrent(sourcePath, cachedResultPath, overrides) {
+		if (!await fileExists(cachedResultPath)) return false;
+		const cachedBasename = path.basename(cachedResultPath);
+		const cachedHashMatch = CACHE_HASH_REGEX.exec(cachedBasename);
+		if (!cachedHashMatch?.[1]) return false;
+		const { frame, page, ...imageOverrides } = overrides ?? {};
+		const optionsForHash = { ...defu(imageOverrides, this.options.defaultImageOptions) };
+		if (frame !== void 0) optionsForHash.frame = frame;
+		if (page !== void 0) optionsForHash.page = page;
+		return await computeCacheKey(sourcePath, optionsForHash) === cachedHashMatch[1];
+	}
+	async loadPersistentCache() {
+		try {
+			const cacheContent = await fs.readFile(this.cacheFilePath, "utf8");
+			const cache = JSON.parse(cacheContent);
+			let validEntries = 0;
+			let staleEntries = 0;
+			for (const [relativeIdentifier, entry] of Object.entries(cache)) {
+				const absoluteIdentifier = this.fromRelativeCacheKey(relativeIdentifier);
+				const absoluteResult = path.resolve(this.options.cacheDirectory, entry.result);
+				if (await fileExists(absoluteResult)) {
+					this.resolvedCache.set(absoluteIdentifier, absoluteResult);
+					validEntries++;
+				} else {
+					this.persistentCacheDirty = true;
+					staleEntries++;
+				}
+			}
+			if (staleEntries > 0) log.debug(`Removed ${staleEntries} stale entries from cache (files no longer exist on disk)`);
+			log.debug(`Loaded ${validEntries} entries from persistent cache`);
+		} catch {}
+	}
+	relativePath(absolutePath) {
+		return path.relative(process.cwd(), absolutePath);
+	}
+	toRelativeCacheKey(absoluteKey) {
+		const queryIndex = absoluteKey.indexOf("?");
+		const absolutePath = queryIndex === -1 ? absoluteKey : absoluteKey.slice(0, queryIndex);
+		const query = queryIndex === -1 ? "" : absoluteKey.slice(queryIndex);
+		return toPosixPath(path.relative(this.options.cacheDirectory, absolutePath)) + query;
+	}
+};
+async function computeCacheKey(filePath, options) {
+	const fileBuffer = await fs.readFile(filePath);
+	const hash = crypto.createHash("sha1");
+	hash.update(fileBuffer);
+	hash.update(stableStringify(options));
+	return hash.digest("hex").slice(0, 8);
+}
+function stableStringify(value) {
+	return JSON.stringify(value, Object.keys(value).toSorted());
+}
+/**
+* Convert a native path string to POSIX form. No-op on POSIX. Used when
+* persisting paths to disk so the cache file is portable across OSes.
+*/
+function toPosixPath(p) {
+	return p.split(path.sep).join("/");
+}
+async function fileExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+/**
+* Simple slugify for frame/page names in filenames. Converts to lowercase,
+* replaces non-alphanumeric with hyphens, trims.
+*/
+function slugify(text) {
+	return text.toLowerCase().replaceAll(/[^\da-z]+/g, "-").replaceAll(/^-+|-+$/g, "");
+}
+//#endregion
+export { parseImportOverrides as n, resolveOptions as r, TldrawExport as t };

package/dist/vite.d.ts

@@ -0,0 +1,23 @@
+import { n as Options } from "./options-OhkbiFS8.js";
+import * as _$vite from "vite";
+
+//#region src/vite.d.ts
+/**
+ * This entry file is for Vite plugin.
+ *
+ * @module
+ */
+/**
+ * Vite plugin
+ *
+ * @example
+ * 	// vite.config.ts
+ * 	import tldraw from '@kitschpatrol/unplugin-tldraw/vite'
+ *
+ * 	export default defineConfig({
+ * 		plugins: [tldraw()],
+ * 	})
+ */
+declare const _default: (options?: Options | undefined) => _$vite.Plugin<any> | _$vite.Plugin<any>[];
+//#endregion
+export { _default as default };

package/dist/vite.js

@@ -0,0 +1,22 @@
+import { unpluginFactory } from "./index.js";
+import { createVitePlugin } from "unplugin";
+//#region src/vite.ts
+/**
+* This entry file is for Vite plugin.
+*
+* @module
+*/
+/**
+* Vite plugin
+*
+* @example
+* 	// vite.config.ts
+* 	import tldraw from '@kitschpatrol/unplugin-tldraw/vite'
+*
+* 	export default defineConfig({
+* 		plugins: [tldraw()],
+* 	})
+*/
+var vite_default = createVitePlugin(unpluginFactory);
+//#endregion
+export { vite_default as default };

package/dist/webpack.d.ts

@@ -0,0 +1,23 @@
+import { n as Options } from "./options-OhkbiFS8.js";
+import * as _$webpack from "webpack";
+
+//#region src/webpack.d.ts
+/**
+ * This entry file is for webpack plugin.
+ *
+ * @module
+ */
+/**
+ * Webpack plugin
+ *
+ * @example
+ * 	// webpack.config.js
+ * 	import tldraw from '@kitschpatrol/unplugin-tldraw/webpack'
+ *
+ * 	export default {
+ * 		plugins: [tldraw()],
+ * 	}
+ */
+declare const _default: (options?: Options | undefined) => _$webpack.WebpackPluginInstance;
+//#endregion
+export { _default as default };

package/dist/webpack.js

@@ -0,0 +1,22 @@
+import { unpluginFactory } from "./index.js";
+import { createWebpackPlugin } from "unplugin";
+//#region src/webpack.ts
+/**
+* This entry file is for webpack plugin.
+*
+* @module
+*/
+/**
+* Webpack plugin
+*
+* @example
+* 	// webpack.config.js
+* 	import tldraw from '@kitschpatrol/unplugin-tldraw/webpack'
+*
+* 	export default {
+* 		plugins: [tldraw()],
+* 	}
+*/
+var webpack_default = createWebpackPlugin(unpluginFactory);
+//#endregion
+export { webpack_default as default };

package/license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Mika
+
+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/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@kitschpatrol/unplugin-tldraw",
+  "version": "1.0.0",
+  "description": "Unplugin for module-style import of local tldraw .tldr files with automatic conversion to SVG or PNG.",
+  "keywords": [
+    "tldraw",
+    "tldr",
+    "unplugin",
+    "vite",
+    "webpack",
+    "rspack",
+    "rollup",
+    "rolldown",
+    "esbuild",
+    "farm",
+    "bun",
+    "nuxt",
+    "diagram",
+    "drawing",
+    "whiteboard",
+    "sketch",
+    "import",
+    "npm-package"
+  ],
+  "homepage": "https://github.com/kitschpatrol/unplugin-tldraw",
+  "bugs": "https://github.com/kitschpatrol/unplugin-tldraw/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitschpatrol/unplugin-tldraw.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Eric Mika",
+    "email": "eric@ericmika.com",
+    "url": "https://ericmika.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*",
+    "./api": "./dist/api.js",
+    "./bun": "./dist/bun.js",
+    "./client": {
+      "types": "./dist/client.d.ts"
+    },
+    "./esbuild": "./dist/esbuild.js",
+    "./farm": "./dist/farm.js",
+    "./nuxt": "./dist/nuxt.js",
+    "./rolldown": "./dist/rolldown.js",
+    "./rollup": "./dist/rollup.js",
+    "./rspack": "./dist/rspack.js",
+    "./vite": "./dist/vite.js",
+    "./webpack": "./dist/webpack.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./*"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@kitschpatrol/tldraw-cli": "^5.0.16",
+    "@types/node": "~22.18.13",
+    "defu": "^6.1.7",
+    "lognow": "^0.6.1",
+    "p-limit": "^7.3.0",
+    "pretty-bytes": "^7.1.0",
+    "pretty-ms": "^9.3.0",
+    "unplugin": "^3.0.0"
+  },
+  "devDependencies": {
+    "@farmfe/core": ">=1.7.11",
+    "@kitschpatrol/shared-config": "^7.5.1",
+    "@nuxt/kit": "^3.21.2",
+    "@nuxt/schema": "^3.21.2",
+    "@sxzz/test-utils": "^0.5.18",
+    "@vitest/browser-playwright": "^4.1.5",
+    "bumpp": "^11.0.1",
+    "esbuild": "*",
+    "playwright": "^1.59.1",
+    "poptab": "^1.1.0",
+    "rollup": "^4.60.2",
+    "shx": "^0.4.0",
+    "tsdown": "^0.21.10",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.2",
+    "vitest": "^4.1.5",
+    "webpack": "^5.106.2"
+  },
+  "peerDependencies": {
+    "@farmfe/core": ">=1",
+    "@nuxt/kit": "^3",
+    "@nuxt/schema": "^3",
+    "esbuild": "*",
+    "rollup": "^3",
+    "vite": ">=3",
+    "webpack": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "@farmfe/core": {
+      "optional": true
+    },
+    "@nuxt/kit": {
+      "optional": true
+    },
+    "@nuxt/schema": {
+      "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    },
+    "rollup": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "shx rm -f pnpm-lock.yaml && git clean -fdX -e !.claude/",
+    "dev": "tsdown --watch",
+    "fix": "ksc fix",
+    "lint": "ksc lint",
+    "play": "poptab && pnpm -C playground run dev",
+    "release": "bumpp --commit 'Release: %s' && pnpm build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
+    "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts"
+  }
+}