@stdout-design/cli 0.1.0

package/dist/dist-Dm76-R-V.mjs

@@ -0,0 +1,1187 @@
+import { n as isZodObject } from "./validation-CMTs74Vm-C3_d2dBv.mjs";
+import { z } from "zod";
+import path from "node:path";
+import { fromJsx } from "takumi-js/helpers/jsx";
+import { existsSync, unlinkSync } from "node:fs";
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import pLimit from "p-limit";
+import lockfile from "proper-lockfile";
+import realWriteFileAtomic from "write-file-atomic";
+import { Database } from "bun:sqlite";
+import { Kysely, sql } from "kysely";
+import { BunSqliteDialect } from "kysely-bun-sqlite";
+import { Renderer } from "takumi-js/node";
+import { createElement } from "react";
+import { googleFonts } from "@takumi-rs/helpers";
+import { pathToFileURL } from "node:url";
+//#region ../core/dist/index.mjs
+const templateEntrySchema = z.object({
+	componentPath: z.string().min(1, "componentPath is required"),
+	description: z.string().optional()
+});
+const presetSchema = z.object({
+	height: z.number().int().positive(),
+	id: z.string().min(1),
+	platform: z.string().min(1),
+	width: z.number().int().positive()
+});
+const studioConfigSchema = z.object({
+	defaultPreset: z.string().optional(),
+	locales: z.array(z.string()).optional(),
+	outDir: z.string().optional(),
+	presets: z.array(presetSchema),
+	templates: z.record(z.string(), templateEntrySchema)
+});
+const compileTemplate = async (element, options) => {
+	const result = await fromJsx(element, options);
+	return {
+		node: result.node,
+		stylesheets: result.stylesheets
+	};
+};
+const ErrorCode = {
+	API_ERROR: "API_ERROR",
+	CACHE_CLEANUP_FAILED: "CACHE_CLEANUP_FAILED",
+	CACHE_CORRUPT_ENTRY: "CACHE_CORRUPT_ENTRY",
+	CACHE_INIT_FAILED: "CACHE_INIT_FAILED",
+	CACHE_WRITE_FAILED: "CACHE_WRITE_FAILED",
+	CONFIG_INVALID: "CONFIG_INVALID",
+	CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+	FONT_REGISTRATION_FAILED: "FONT_REGISTRATION_FAILED",
+	INTERNAL_ERROR: "INTERNAL_ERROR",
+	LOCALE_LOAD_FAILED: "LOCALE_LOAD_FAILED",
+	PROP_VALIDATION_FAILED: "PROP_VALIDATION_FAILED",
+	RENDERER_NOT_INITIALIZED: "RENDERER_NOT_INITIALIZED",
+	RENDER_FAILED: "RENDER_FAILED",
+	SSE_ERROR: "SSE_ERROR",
+	TEMPLATE_INVALID_EXPORT: "TEMPLATE_INVALID_EXPORT",
+	TEMPLATE_LOAD_FAILED: "TEMPLATE_LOAD_FAILED",
+	TEMPLATE_NOT_FOUND: "TEMPLATE_NOT_FOUND",
+	UI_RENDER_ERROR: "UI_RENDER_ERROR"
+};
+var AppError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "AppError";
+		this.code = code;
+		this.context = context ?? {};
+	}
+};
+const timestamp = () => (/* @__PURE__ */ new Date()).toISOString();
+const stringifyContext = (context) => {
+	if (!context || Object.keys(context).length === 0) return "";
+	return ` ${JSON.stringify(context)}`;
+};
+const logDebug = (message, context) => {
+	console.log(`[${timestamp()}] DEBUG ${message}${stringifyContext(context)}`);
+};
+const logWarn = (message, context) => {
+	console.warn(`[${timestamp()}] WARN ${message}${stringifyContext(context)}`);
+};
+const logError = (code, message, context) => {
+	console.error(`[${timestamp()}] ERROR [${code}] ${message}${stringifyContext(context)}`);
+};
+const createCompileCacheKey = (input) => createHash("sha256").update(`${input.templateId}\u0000${input.templateContentHash}\u0000${input.propsJSON}`).digest("hex").slice(0, 16);
+const createPixelCacheKey = (input) => createHash("sha256").update(`${input.templateContentHash}\u0000${input.propsJSON}\u0000${input.width}x${input.height}\u0000${input.format ?? "png"}`).digest("hex").slice(0, 32);
+/**
+* CompileCache: in-memory compile-result cache.
+*
+* Process-local only, never persisted, never shared across processes.
+* Cheap to recompute, so this uses a simple LRU eviction policy: the
+* `get()` method promotes a hit to most-recently-used position before
+* returning, and eviction removes the least-recently-used entry when
+* capacity is exceeded.
+*/
+const DEFAULT_COMPILED_MAX = 100;
+var CompileCache = class {
+	maxEntries;
+	cache = /* @__PURE__ */ new Map();
+	order = [];
+	contentHashIndex = /* @__PURE__ */ new Map();
+	constructor(maxEntries = DEFAULT_COMPILED_MAX) {
+		this.maxEntries = maxEntries;
+	}
+	get size() {
+		return this.cache.size;
+	}
+	get(key) {
+		if (this.cache.has(key)) {
+			const idx = this.order.indexOf(key);
+			if (idx !== -1) {
+				this.order.splice(idx, 1);
+				this.order.push(key);
+			}
+			return this.cache.get(key);
+		}
+		return null;
+	}
+	set(key, value) {
+		if (!this.cache.has(key)) this.order.push(key);
+		this.cache.set(key, value);
+		while (this.order.length > this.maxEntries) {
+			const oldest = this.order.shift();
+			if (oldest !== void 0) this.cache.delete(oldest);
+		}
+	}
+	/**
+	* Use this instead of `set` when the entry should be invalidatable by
+	* template content hash later (the normal case for template compile
+	* results).
+	*/
+	setWithContentHash(key, contentHash, value) {
+		this.set(key, value);
+		let set = this.contentHashIndex.get(contentHash);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.contentHashIndex.set(contentHash, set);
+		}
+		set.add(key);
+	}
+	/**
+	* Invalidate entries previously written via `setWithContentHash` for a
+	* given content hash. Uses the explicit index built at write time, not
+	* a hash-prefix guess against the cache key itself (the key is a
+	* one-way hash, it cannot be pattern-matched against its own input).
+	*/
+	invalidateByContentHash(contentHash) {
+		const keys = this.contentHashIndex.get(contentHash);
+		if (!keys) return;
+		for (const key of keys) {
+			this.cache.delete(key);
+			const idx = this.order.indexOf(key);
+			if (idx !== -1) this.order.splice(idx, 1);
+		}
+		this.contentHashIndex.delete(contentHash);
+	}
+	clear() {
+		this.cache.clear();
+		this.order.length = 0;
+		this.contentHashIndex.clear();
+	}
+};
+/**
+* Bounds how many concurrent operations (writes/reads through FsStore)
+* run at once. Exists to cap the "N concurrent large-buffer renders spike
+* RSS" risk at the layer that actually does the I/O, rather than trusting
+* every future caller (CLI batch executor, dev-server, MCP) to remember
+* to throttle itself.
+*
+* Deliberately a thin wrapper, not a reimplementation -- p-limit is the
+* de facto standard promise concurrency limiter in the Node/Bun
+* ecosystem, small and heavily exercised. No maxConcurrent (or a
+* non-positive value) means unbounded, matching the cache's behavior
+* before this existed.
+*/
+var ConcurrencyLimiter = class {
+	limit;
+	constructor(maxConcurrent) {
+		this.limit = maxConcurrent && maxConcurrent > 0 ? pLimit(maxConcurrent) : null;
+	}
+	run(fn) {
+		if (!this.limit) return fn();
+		return this.limit(fn);
+	}
+	get activeCount() {
+		return this.limit?.activeCount ?? 0;
+	}
+	get pendingCount() {
+		return this.limit?.pendingCount ?? 0;
+	}
+	get isBounded() {
+		return this.limit !== null;
+	}
+};
+const DEFAULT_DEBOUNCE_MS = 250;
+/**
+* Coordinates eviction across both time (debouncing) and processes
+* (advisory locking), replacing two things from the old monolithic
+* RenderCache:
+*
+* 1. Eviction ran synchronously inside every `setPixels` call, doing a
+*    full-table SUM and (once over budget) a full-table ORDER BY on
+*    every single write. Here, a write just calls `requestEviction()`,
+*    which schedules a debounced check -- the expensive scan runs at
+*    most once per debounce window, not once per write.
+*
+* 2. Multi-process safety was implicit ("WAL mode makes concurrent DB
+*    access safe"), which said nothing about the filesystem-level TOCTOU
+*    race in delete. `proper-lockfile` wraps the actual sweep in an
+*    advisory lock so only one process ever runs a sweep at a time --
+*    the delete race is eliminated by construction (only one actor ever
+*    deletes at once) rather than caught after the fact.
+*/
+var EvictionCoordinator = class {
+	lockTargetPath;
+	maxSizeBytes;
+	debounceMs;
+	getCurrentTotalBytes;
+	sweepFn;
+	debounceTimer = null;
+	constructor(options) {
+		this.lockTargetPath = options.lockTargetPath;
+		this.maxSizeBytes = options.maxSizeBytes;
+		this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+		this.getCurrentTotalBytes = options.getCurrentTotalBytes;
+		this.sweepFn = options.sweep;
+	}
+	/**
+	* Call after every write. Schedules (or no-ops if one is already
+	* scheduled) a debounced budget check -- callers never pay the full
+	* scan cost inline.
+	*/
+	requestEviction() {
+		if (this.debounceTimer) return;
+		this.debounceTimer = setTimeout(async () => {
+			this.debounceTimer = null;
+			try {
+				await this.runIfOverBudget();
+			} catch (error) {
+				logWarn("EvictionCoordinator: debounced sweep failed", { error: String(error) });
+			}
+		}, this.debounceMs);
+		this.debounceTimer.unref?.();
+	}
+	/** Checks the current total against budget and runs a partial sweep only if over. */
+	async runIfOverBudget() {
+		if (await this.getCurrentTotalBytes() <= this.maxSizeBytes) return { freedBytes: 0 };
+		return this.runSweep({ full: false });
+	}
+	/** Forces a full wipe (backs the public `clean()` API), still funneled through the same lock so it can't race another process's sweep. */
+	runFullSweep() {
+		return this.runSweep({ full: true });
+	}
+	async runSweep(options) {
+		let release = null;
+		try {
+			release = await lockfile.lock(this.lockTargetPath, {
+				retries: 0,
+				stale: 1e4
+			});
+		} catch (error) {
+			logDebug("EvictionCoordinator: lock held elsewhere, skipping this pass", { error: String(error) });
+			return { freedBytes: 0 };
+		}
+		try {
+			return await this.sweepFn(options);
+		} finally {
+			await release();
+		}
+	}
+	/** Cancels any pending debounced sweep. Call on shutdown so a timer doesn't fire after the owning cache has closed. */
+	cancelPending() {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+	}
+};
+const defaultFsPrimitives = {
+	existsSync,
+	readFile,
+	stat: (filePath) => stat(filePath),
+	unlink,
+	writeFileAtomic: (filePath, data) => realWriteFileAtomic(filePath, data)
+};
+/**
+* Filesystem I/O for pixel cache entries.
+*
+* Replaces two things from the old monolithic RenderCache:
+*
+* 1. The hand-rolled tmp-file-then-rename with a copy+unlink fallback on
+*    cross-device rename (EXDEV). That fallback was NOT atomic -- a
+*    concurrent reader could observe a partially-copied file at the final
+*    path. `write-file-atomic` (maintained by the npm CLI team, who hit
+*    this exact problem with npm's own package cache) handles the
+*    cross-device case correctly.
+*
+* 2. The size-only integrity check on read (comparing `stat().size`
+*    against a DB column). A same-size bit-flip was silently served as
+*    valid. `Bun.hash()` gives us a cheap digest to verify content, not
+*    just length, on every read.
+*
+* This class knows nothing about SQLite or eviction policy -- it only
+* knows how to put bytes on disk safely and get verified bytes back.
+*/
+var FsStore = class {
+	limiter;
+	fs;
+	constructor(limiter, fs = defaultFsPrimitives) {
+		this.limiter = limiter;
+		this.fs = fs;
+	}
+	/**
+	* Non-cryptographic content hash, used purely for corruption detection
+	* within a cache whose entries are always regenerable -- not for
+	* anything requiring cross-version stability or resistance to
+	* intentional tampering. Bun.hash()'s algorithm is not a documented,
+	* version-stable guarantee; if a future Bun upgrade changes it, the
+	* worst case is a one-time false "corrupted" verdict that costs a
+	* re-render, not data loss.
+	*/
+	computeHash(bytes) {
+		return Bun.hash(bytes).toString(16);
+	}
+	/**
+	* Writes `bytes` to `filePath` atomically: either the write is fully
+	* visible at `filePath` or `filePath` doesn't change at all. No caller
+	* ever observes a partial file at the final path, including across a
+	* cross-device fallback.
+	*/
+	async writeAtomic(filePath, bytes) {
+		const doWrite = () => this.fs.writeFileAtomic(filePath, bytes);
+		await (this.limiter ? this.limiter.run(doWrite) : doWrite());
+	}
+	/**
+	* Reads `filePath` and verifies both size and content hash against the
+	* expected values before returning it. Returns `null` (and does NOT
+	* throw) on any mismatch or read failure -- callers are expected to
+	* treat `null` as "entry is gone/invalid, self-heal by forgetting it,"
+	* matching the old cache's missing-file behavior, now extended to
+	* cover content corruption too instead of only missing/truncated files.
+	*/
+	readVerified(filePath, expectedSizeBytes, expectedContentHash) {
+		const doRead = () => this.readVerifiedUnbounded(filePath, expectedSizeBytes, expectedContentHash);
+		return this.limiter ? this.limiter.run(doRead) : doRead();
+	}
+	async readVerifiedUnbounded(filePath, expectedSizeBytes, expectedContentHash) {
+		if (!this.fs.existsSync(filePath)) {
+			logDebug("FsStore: cached file missing on read", { filePath });
+			return null;
+		}
+		const fileStat = await this.fs.stat(filePath);
+		if (fileStat.size !== expectedSizeBytes) {
+			logWarn("FsStore: size mismatch on read, treating as corrupt", {
+				expected: expectedSizeBytes,
+				filePath,
+				onDisk: fileStat.size
+			});
+			return null;
+		}
+		const bytes = await this.fs.readFile(filePath);
+		if (this.computeHash(bytes) !== expectedContentHash) {
+			logWarn("FsStore: content-hash mismatch on read, treating as corrupt", {
+				expected: expectedContentHash,
+				filePath
+			});
+			return null;
+		}
+		return bytes;
+	}
+	/**
+	* Removes a cache entry's file, if present. Returns the number of
+	* bytes actually freed. Tolerant of the file already being gone (a
+	* concurrent process may have removed it first) -- this is the TOCTOU
+	* gap from the old implementation, still possible here since checking
+	* existence and then deleting is inherently two steps, but now
+	* contained to one small, well-tested method instead of being
+	* duplicated across the eviction and clean code paths.
+	*/
+	async delete(filePath, knownSizeBytes) {
+		if (!this.fs.existsSync(filePath)) return 0;
+		let freed = knownSizeBytes ?? 0;
+		try {
+			if (knownSizeBytes === void 0) freed = (await this.fs.stat(filePath)).size;
+			await this.fs.unlink(filePath);
+		} catch (error) {
+			logWarn("FsStore: failed to delete cache entry file", {
+				error: String(error),
+				filePath
+			});
+			return freed;
+		}
+		return freed;
+	}
+};
+const BUSY_TIMEOUT_MS = 5e3;
+const toRow = (r) => ({
+	contentHash: r.content_hash,
+	createdAt: r.created_at,
+	fileName: r.file_name,
+	hash: r.hash,
+	height: r.height,
+	lastAccessedAt: r.last_accessed_at,
+	sizeBytes: r.size_bytes,
+	width: r.width
+});
+/**
+* SQLite-backed metadata store for pixel cache entries.
+*
+* Two things changed from the pre-split RenderCache:
+*
+* 1. Queries go through Kysely instead of hand-written SQL strings with
+*    positional parameter arrays (`db.run("...", [key, fileName, ...])`)
+*    -- a schema change that adds a column no longer risks a call site's
+*    array silently drifting out of sync; it's a compile error instead.
+*
+* 2. Total size/entry count are maintained by SQLite triggers into a
+*    single-row `cache_totals` table, updated in the same transaction as
+*    every insert/update/delete. Reading the current totals is an O(1)
+*    primary-key lookup instead of `SELECT SUM(size_bytes)` /
+*    `SELECT COUNT(*)` scanning the whole table on every write.
+*/
+var MetadataStore = class {
+	cacheDir;
+	dbPath;
+	rawDb;
+	db;
+	initialized = false;
+	constructor(cacheDir) {
+		this.cacheDir = cacheDir;
+		this.dbPath = cacheDir === ":memory:" ? ":memory:" : path.join(cacheDir, "cache.sqlite");
+	}
+	async init() {
+		if (this.initialized) return;
+		if (this.cacheDir !== ":memory:" && !existsSync(this.cacheDir)) await mkdir(this.cacheDir, { recursive: true });
+		const rawDb = new Database(this.dbPath, {
+			create: true,
+			readwrite: true
+		});
+		rawDb.run("PRAGMA journal_mode = WAL");
+		rawDb.run("PRAGMA synchronous = NORMAL");
+		rawDb.run(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+		rawDb.run("PRAGMA wal_checkpoint(TRUNCATE)");
+		let dbHealthy = true;
+		try {
+			const result = rawDb.query("PRAGMA integrity_check").get();
+			if (result?.integrity_check !== "ok") {
+				dbHealthy = false;
+				logWarn("SQLite integrity check failed, recreating cache database", { result: result?.integrity_check ?? "null" });
+			}
+		} catch {
+			dbHealthy = false;
+			logWarn("SQLite integrity check threw, recreating cache database");
+		}
+		if (dbHealthy) this.rawDb = rawDb;
+		else {
+			rawDb.close();
+			this.deleteDatabaseFiles();
+			const freshDb = new Database(this.dbPath, {
+				create: true,
+				readwrite: true
+			});
+			freshDb.run("PRAGMA journal_mode = WAL");
+			freshDb.run("PRAGMA synchronous = NORMAL");
+			freshDb.run(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+			this.rawDb = freshDb;
+		}
+		this.db = new Kysely({ dialect: new BunSqliteDialect({ database: this.rawDb }) });
+		await this.createSchema();
+		this.initialized = true;
+	}
+	async createSchema() {
+		const db = this.requireDb();
+		await db.schema.createTable("pixel_cache_entries").ifNotExists().addColumn("hash", "text", (c) => c.primaryKey()).addColumn("file_name", "text", (c) => c.notNull()).addColumn("created_at", "integer", (c) => c.notNull()).addColumn("last_accessed_at", "integer", (c) => c.notNull()).addColumn("size_bytes", "integer", (c) => c.notNull()).addColumn("width", "integer", (c) => c.notNull()).addColumn("height", "integer", (c) => c.notNull()).addColumn("content_hash", "text", (c) => c.notNull()).execute();
+		await db.schema.createIndex("idx_last_accessed").ifNotExists().on("pixel_cache_entries").column("last_accessed_at").execute();
+		await db.schema.createTable("cache_totals").ifNotExists().addColumn("id", "integer", (c) => c.primaryKey()).addColumn("total_size_bytes", "integer", (c) => c.notNull().defaultTo(0)).addColumn("entry_count", "integer", (c) => c.notNull().defaultTo(0)).execute();
+		await sql`INSERT OR IGNORE INTO cache_totals (id, total_size_bytes, entry_count) VALUES (1, 0, 0)`.execute(db);
+		await sql`
+      CREATE TRIGGER IF NOT EXISTS trg_pixel_cache_insert
+      AFTER INSERT ON pixel_cache_entries
+      BEGIN
+        UPDATE cache_totals
+        SET total_size_bytes = total_size_bytes + NEW.size_bytes,
+            entry_count = entry_count + 1
+        WHERE id = 1;
+      END;
+    `.execute(db);
+		await sql`
+      CREATE TRIGGER IF NOT EXISTS trg_pixel_cache_delete
+      AFTER DELETE ON pixel_cache_entries
+      BEGIN
+        UPDATE cache_totals
+        SET total_size_bytes = total_size_bytes - OLD.size_bytes,
+            entry_count = entry_count - 1
+        WHERE id = 1;
+      END;
+    `.execute(db);
+		await sql`
+      CREATE TRIGGER IF NOT EXISTS trg_pixel_cache_update_size
+      AFTER UPDATE OF size_bytes ON pixel_cache_entries
+      WHEN OLD.size_bytes != NEW.size_bytes
+      BEGIN
+        UPDATE cache_totals
+        SET total_size_bytes = total_size_bytes - OLD.size_bytes + NEW.size_bytes
+        WHERE id = 1;
+      END;
+    `.execute(db);
+	}
+	close() {
+		if (this.rawDb) {
+			this.rawDb.run("PRAGMA wal_checkpoint(TRUNCATE)");
+			this.rawDb.close();
+		}
+		this.initialized = false;
+	}
+	deleteDatabaseFiles() {
+		if (this.dbPath === ":memory:") return;
+		for (const suffix of [
+			"",
+			"-wal",
+			"-shm"
+		]) try {
+			unlinkSync(`${this.dbPath}${suffix}`);
+		} catch {}
+	}
+	/** Insert a new entry, or update it in place (same behavior as the old ON CONFLICT DO UPDATE) if the hash already exists -- e.g. a re-render at a different size for the same key. */
+	async upsertEntry(input) {
+		const db = this.requireDb();
+		const now = Date.now();
+		await db.insertInto("pixel_cache_entries").values({
+			content_hash: input.contentHash,
+			created_at: now,
+			file_name: input.fileName,
+			hash: input.hash,
+			height: input.height,
+			last_accessed_at: now,
+			size_bytes: input.sizeBytes,
+			width: input.width
+		}).onConflict((oc) => oc.column("hash").doUpdateSet({
+			content_hash: input.contentHash,
+			file_name: input.fileName,
+			height: input.height,
+			last_accessed_at: now,
+			size_bytes: input.sizeBytes,
+			width: input.width
+		})).execute();
+	}
+	async getEntry(hash) {
+		const row = await this.requireDb().selectFrom("pixel_cache_entries").selectAll().where("hash", "=", hash).executeTakeFirst();
+		return row ? toRow(row) : null;
+	}
+	async touchAccess(hash, timestamp = Date.now()) {
+		await this.requireDb().updateTable("pixel_cache_entries").set({ last_accessed_at: timestamp }).where("hash", "=", hash).execute();
+	}
+	async deleteEntry(hash) {
+		await this.requireDb().deleteFrom("pixel_cache_entries").where("hash", "=", hash).execute();
+	}
+	async deleteAll() {
+		await this.requireDb().deleteFrom("pixel_cache_entries").execute();
+	}
+	async listAllOrderedByLastAccessed() {
+		return (await this.requireDb().selectFrom("pixel_cache_entries").selectAll().orderBy("last_accessed_at", "asc").execute()).map(toRow);
+	}
+	/** O(1): reads the trigger-maintained single-row counter instead of scanning the table. */
+	async getTotals() {
+		const row = await this.requireDb().selectFrom("cache_totals").select(["total_size_bytes", "entry_count"]).where("id", "=", 1).executeTakeFirstOrThrow();
+		return {
+			entryCount: row.entry_count,
+			totalSizeBytes: row.total_size_bytes
+		};
+	}
+	requireDb() {
+		if (!this.db) throw new Error("MetadataStore.init() must be called before use.");
+		return this.db;
+	}
+};
+const DEFAULT_MAX_SIZE_MB = 500;
+/**
+* Content-addressed two-stage render cache -- coordinator.
+*
+* This class used to own SQLite calls, filesystem calls, atomicity
+* handling, and eviction policy directly (~400 lines, five
+* responsibilities). It now owns none of that: it constructs and wires
+* together CompileCache, MetadataStore, FsStore, and EvictionCoordinator,
+* and exposes the exact same public method signatures CLI, MCP, and
+* dev-server already depend on. No downstream consumer needs to change
+* anything as a result of this refactor.
+*/
+var RenderCache = class {
+	cacheDir;
+	maxSizeBytes;
+	compiled;
+	maxConcurrentWrites;
+	evictionDebounceMs;
+	metadata;
+	fsStore;
+	eviction;
+	initialized = false;
+	static createCompileCacheKey = createCompileCacheKey;
+	static createPixelCacheKey = createPixelCacheKey;
+	constructor(options) {
+		this.cacheDir = options?.cacheDir ?? ".studio-cache";
+		this.maxSizeBytes = (options?.maxSizeMB ?? DEFAULT_MAX_SIZE_MB) * 1024 * 1024;
+		this.compiled = new CompileCache(options?.compiledMaxEntries);
+		this.maxConcurrentWrites = options?.maxConcurrentWrites;
+		this.evictionDebounceMs = options?.evictionDebounceMs;
+	}
+	async init() {
+		if (this.initialized) return;
+		if (!existsSync(this.cacheDir)) await mkdir(this.cacheDir, { recursive: true });
+		this.metadata = new MetadataStore(this.cacheDir);
+		await this.metadata.init();
+		const limiter = new ConcurrencyLimiter(this.maxConcurrentWrites);
+		this.fsStore = new FsStore(limiter);
+		this.eviction = new EvictionCoordinator({
+			debounceMs: this.evictionDebounceMs,
+			getCurrentTotalBytes: async () => {
+				return (await this.requireMetadata().getTotals()).totalSizeBytes;
+			},
+			lockTargetPath: this.cacheDir,
+			maxSizeBytes: this.maxSizeBytes,
+			sweep: (options) => this.performSweep(options)
+		});
+		this.initialized = true;
+	}
+	close() {
+		this.eviction?.cancelPending();
+		this.metadata?.close();
+		this.initialized = false;
+	}
+	getCompiled(key) {
+		return this.compiled.get(key);
+	}
+	setCompiled(key, value) {
+		this.compiled.set(key, value);
+	}
+	setCompiledWithContentHash(key, contentHash, value) {
+		this.compiled.setWithContentHash(key, contentHash, value);
+	}
+	invalidateCompiledByContentHash(contentHash) {
+		this.compiled.invalidateByContentHash(contentHash);
+	}
+	clearCompiled() {
+		this.compiled.clear();
+	}
+	async getPixels(key) {
+		const metadata = this.requireMetadata();
+		const fsStore = this.requireFsStore();
+		let row;
+		try {
+			row = await metadata.getEntry(key);
+		} catch (error) {
+			logWarn("Pixel metadata read failed, attempting recovery", {
+				error: error instanceof Error ? error.message : String(error),
+				key
+			});
+			await this.recoverMetadata();
+			return null;
+		}
+		if (!row) return null;
+		const filePath = path.join(this.cacheDir, row.fileName);
+		const bytes = await fsStore.readVerified(filePath, row.sizeBytes, row.contentHash);
+		if (bytes === null) {
+			try {
+				await metadata.deleteEntry(key);
+			} catch {}
+			return null;
+		}
+		try {
+			await metadata.touchAccess(key);
+		} catch (error) {
+			logWarn("Pixel touchAccess failed, attempting recovery", {
+				error: error instanceof Error ? error.message : String(error),
+				key
+			});
+			await this.recoverMetadata();
+		}
+		return bytes;
+	}
+	async setPixels(key, bytes, width, height, format = "png") {
+		const metadata = this.requireMetadata();
+		const fsStore = this.requireFsStore();
+		const fileName = `${key}.${format}`;
+		const filePath = path.join(this.cacheDir, fileName);
+		const contentHash = fsStore.computeHash(bytes);
+		await fsStore.writeAtomic(filePath, bytes);
+		await metadata.upsertEntry({
+			contentHash,
+			fileName,
+			hash: key,
+			height,
+			sizeBytes: bytes.length,
+			width
+		});
+		this.requireEviction().requestEviction();
+		return filePath;
+	}
+	async stats() {
+		const totals = await this.requireMetadata().getTotals();
+		return {
+			cacheDir: this.cacheDir,
+			compiled: { entries: this.compiled.size },
+			pixels: {
+				entries: totals.entryCount,
+				maxSizeBytes: this.maxSizeBytes,
+				sizeBytes: totals.totalSizeBytes
+			}
+		};
+	}
+	/** Full wipe -- unlike a budget-triggered sweep, always removes everything, still lock-coordinated. */
+	clean() {
+		this.compiled.clear();
+		return this.requireEviction().runFullSweep();
+	}
+	async performSweep(options) {
+		const metadata = this.requireMetadata();
+		const fsStore = this.requireFsStore();
+		if (options.full) {
+			const rows = await metadata.listAllOrderedByLastAccessed();
+			const freedAmounts = await Promise.all(rows.map((row) => fsStore.delete(path.join(this.cacheDir, row.fileName), row.sizeBytes)));
+			await metadata.deleteAll();
+			return { freedBytes: freedAmounts.reduce((sum, n) => sum + n, 0) };
+		}
+		const totals = await metadata.getTotals();
+		if (totals.totalSizeBytes <= this.maxSizeBytes) return { freedBytes: 0 };
+		const rows = await metadata.listAllOrderedByLastAccessed();
+		let remaining = totals.totalSizeBytes;
+		const rowsToEvict = [];
+		for (const row of rows) {
+			if (remaining <= this.maxSizeBytes) break;
+			rowsToEvict.push(row);
+			remaining -= row.sizeBytes;
+		}
+		return { freedBytes: (await Promise.all(rowsToEvict.map(async (row) => {
+			const freedForRow = await fsStore.delete(path.join(this.cacheDir, row.fileName), row.sizeBytes);
+			await metadata.deleteEntry(row.hash);
+			return freedForRow;
+		}))).reduce((sum, n) => sum + n, 0) };
+	}
+	requireMetadata() {
+		if (!this.metadata) throw new Error("RenderCache.init() must be called before use.");
+		return this.metadata;
+	}
+	async recoverMetadata() {
+		this.metadata?.close();
+		this.metadata = new MetadataStore(this.cacheDir);
+		await this.metadata.init();
+	}
+	requireFsStore() {
+		if (!this.fsStore) throw new Error("RenderCache.init() must be called before use.");
+		return this.fsStore;
+	}
+	requireEviction() {
+		if (!this.eviction) throw new Error("RenderCache.init() must be called before use.");
+		return this.eviction;
+	}
+};
+/**
+* Type-only shim for `@takumi-rs/core` (as re-exported by `takumi-js/node`).
+*
+* Migrated for Takumi v2. The v1 shim existed to work around a broken
+* `export.d.ts` re-export chain in @takumi-rs/core@1.8.6 that hid
+* `render`/`measure` and several option types from consumers on
+* `moduleResolution: "nodenext"`. This file re-declares the v2 surface we
+* actually use, backed by the real runtime export.
+*
+* TODO(verify-on-upgrade): the v1 packaging bug this shim worked around
+* has not been independently re-verified against the v2 release actually
+* installed. Once upgraded, run the same isolated-probe check described
+* in the v1 version of this file (import the types directly from
+* "takumi-js/node" in a throwaway file and see if `render`/`measure`/
+* `registerFont` resolve). If they do, delete this file and switch all
+* importers back to `takumi-js/node` directly. Tracked against the
+* upstream repo: https://github.com/kane50613/takumi
+*
+* v2 breaking changes reflected below (see /docs/upgrade/v2):
+* - `new Renderer(options)` -> `new Renderer()`. The constructor takes no
+*   arguments; fonts and images are now per-render options instead of
+*   construction-time state.
+* - `loadFont` / `loadFonts` / `loadFontSync` -> `registerFont`. Use this
+*   only to preload a font once and reuse it across many renders; most
+*   callers should just pass `fonts` on the render/measure call instead.
+* - The persistent image store and `GlobalContext` are gone.
+*   `putPersistentImage` / `clearImageStore` no longer exist. Every image
+*   a render needs must be passed through `images`, keyed by `src`.
+* - `fetchedResources` -> `images`. `images` also accepts a group form
+*   (`{ sources, fetch, fetchCache }`) that combines pre-fetched entries,
+*   a custom fetch implementation, and a shared byte cache.
+* - `format` stays a string, but `quality` (jpeg / lossy webp) and
+*   `lossless` (webp) are now separate optional fields instead of one
+*   combined quality argument.
+* - `fonts` entries may be bare URL strings, fetched and cached on demand,
+*   in addition to loaded font descriptors / raw bytes.
+*/
+const Renderer$1 = Renderer;
+/**
+* Renderer lifecycle -- v2.
+*
+* v1 kept a single Renderer instance and rebuilt it whenever
+* font/persistent-image config changed, because fonts and images were
+* construction-time state (`new Renderer({ fonts, persistentImages })`).
+* That reconfigure-on-drift mechanism required every caller to pass the
+* current config on every call so drift could be detected -- and in the
+* shipped v1 code, `renderToPixels`/`measureTemplate` never actually did
+* that (both called `getRenderer()` with no arguments), so config changes
+* silently never took effect.
+*
+* v2 removes the problem at the source: `new Renderer()` takes no
+* arguments at all. Fonts are now a per-render option
+* (`render(node, { fonts })`), so there is nothing renderer-construction-
+* time to drift out of sync with `studio.config.ts` in the first place.
+* The singleton below exists purely to reuse the renderer's internal font
+* cache/thread pool across calls, per Takumi's own performance guidance --
+* it carries no configuration state to go stale.
+*/
+let activeRenderer = null;
+const __getRendererForTesting = () => {
+	if (!activeRenderer) activeRenderer = new Renderer$1();
+	return activeRenderer;
+};
+/**
+* Renders a compiled template to pixels.
+*
+* `width`/`height` are REQUIRED here, not optional pass-through fields.
+* Takumi's `render()` returns only a Buffer -- it does not report back the
+* dimensions it used, so auto-sized output isn't supported by this
+* wrapper. Callers that need auto-sizing must call `measureTemplate` first
+* and pass the resulting width/height through explicitly (see
+* `renderAutoSized` below).
+*
+* Any `fonts`/`fontFamilies`/`images` the template needs must be supplied
+* via `options` -- there is no construction-time renderer config to fall
+* back on in v2.
+*/
+const renderToPixels = async (template, dimensions, options, signal) => {
+	const renderer = __getRendererForTesting();
+	logDebug("renderer.render start", {
+		fontFamilies: options?.fontFamilies,
+		fonts: options?.fonts?.filter((f) => typeof f === "object" && "name" in f).map((f) => ({
+			dataType: typeof f.data,
+			name: f.name
+		})),
+		fontsCount: options?.fonts?.length ?? 0,
+		lang: options?.lang
+	});
+	return {
+		bytes: await renderer.render(template.node, {
+			...options,
+			height: dimensions.height,
+			stylesheets: [...options?.stylesheets ?? [], ...template.stylesheets],
+			width: dimensions.width
+		}, signal),
+		format: options?.format ?? "png",
+		height: dimensions.height,
+		width: dimensions.width
+	};
+};
+const measureTemplate = (template, options, signal) => {
+	return __getRendererForTesting().measure(template.node, {
+		...options,
+		stylesheets: [...options?.stylesheets ?? [], ...template.stylesheets]
+	}, signal);
+};
+const mergeLocale = (props, localeData) => {
+	if (!localeData) return props;
+	const merged = { ...props };
+	for (const [key, value] of Object.entries(localeData)) if (Array.isArray(value) && Array.isArray(merged[key])) merged[key] = value;
+	else if (typeof value === "string" && typeof merged[key] === "string") merged[key] = value;
+	return merged;
+};
+/**
+* Expands rows × locales × presets into a flat array of matrix cells.
+* Locale data is merged into props during expansion so each cell carries
+* fully resolved props.
+*/
+const expandMatrix = (input) => {
+	const { rows, locales, presets, baseProps = {} } = input;
+	if (rows.length === 0) return [];
+	const cells = [];
+	for (const [rowIndex, row] of rows.entries()) {
+		const rowKey = String(row.key ?? row.id ?? row.slug ?? String(rowIndex));
+		const rowProps = {
+			...baseProps,
+			...row
+		};
+		delete rowProps.key;
+		delete rowProps.id;
+		delete rowProps.slug;
+		for (const locale of locales) {
+			const localeProps = mergeLocale(rowProps, locale.data);
+			for (const preset of presets) cells.push({
+				locale: locale.id,
+				preset: {
+					height: preset.height,
+					id: preset.id,
+					width: preset.width
+				},
+				props: {
+					...localeProps,
+					locale: locale.id
+				},
+				rowIndex,
+				rowKey
+			});
+		}
+	}
+	return cells;
+};
+const ensureDir = async (dir) => {
+	if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+};
+const tryWriteFile = async (filePath, data) => {
+	try {
+		await writeFile(filePath, data);
+	} catch (error) {
+		logWarn("Failed to write output file", {
+			error: String(error),
+			filePath
+		});
+	}
+};
+const renderOne = async (input) => {
+	const start = performance.now();
+	const { compiledTemplate, contentHash, props, width, height, format = "png", locale, cache, outDir, filename, signal, renderOptions } = input;
+	const propsJSON = JSON.stringify(props);
+	const pixelKey = RenderCache.createPixelCacheKey({
+		format,
+		height,
+		propsJSON,
+		templateContentHash: contentHash,
+		width
+	});
+	const cached = await cache.getPixels(pixelKey);
+	if (cached) {
+		const outputPath = `${outDir}/${filename}`;
+		await ensureDir(outDir);
+		await tryWriteFile(outputPath, cached);
+		return {
+			cacheHit: true,
+			durationMs: performance.now() - start,
+			outputPath
+		};
+	}
+	const lang = locale?.startsWith("ar") ? "ar" : void 0;
+	logDebug("renderOne -> renderToPixels", {
+		fontFamilies: renderOptions?.fontFamilies,
+		fontNames: renderOptions?.fonts?.map((f) => typeof f === "object" && "name" in f ? f.name : "raw"),
+		fontsCount: renderOptions?.fonts?.length ?? 0,
+		lang,
+		locale
+	});
+	const output = await renderToPixels(compiledTemplate, {
+		height,
+		width
+	}, {
+		fontFamilies: renderOptions?.fontFamilies,
+		fonts: renderOptions?.fonts,
+		format,
+		lang
+	}, signal);
+	await cache.setPixels(pixelKey, output.bytes, width, height, format);
+	const outputPath = `${outDir}/${filename}`;
+	await ensureDir(outDir);
+	await tryWriteFile(outputPath, output.bytes);
+	return {
+		cacheHit: false,
+		durationMs: performance.now() - start,
+		outputPath
+	};
+};
+const generateOutputFilename = (options) => {
+	const { templateId, locale, presetId, rowKey, format = "png" } = options;
+	return `${templateId}.${locale}.${presetId}.${rowKey}.${format}`;
+};
+const writeManifest = async (filePath, manifest) => {
+	await mkdir(path.dirname(filePath), { recursive: true });
+	await writeFile(filePath, JSON.stringify(manifest, null, 2));
+};
+const loadConfig = async (rootDir) => {
+	const configPath = path.resolve(rootDir, "studio.config.ts");
+	try {
+		await readFile(configPath, "utf-8");
+	} catch {
+		throw new AppError(ErrorCode.CONFIG_NOT_FOUND, `No studio.config.ts found in ${rootDir}.`);
+	}
+	logDebug("Loading studio.config.ts", { path: configPath });
+	const mod = await import(pathToFileURL(configPath).href);
+	const raw = mod.default ?? mod;
+	const parsed = studioConfigSchema.safeParse(raw);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+		throw new AppError(ErrorCode.CONFIG_INVALID, `studio.config.ts is invalid: ${issues}`);
+	}
+	return parsed.data;
+};
+const importTemplateForBatch = async (rootDir, componentPath, templateId) => {
+	const fullPath = path.resolve(rootDir, `${componentPath}.tsx`);
+	let content;
+	try {
+		content = await readFile(fullPath, "utf-8");
+	} catch {
+		throw new AppError(ErrorCode.TEMPLATE_LOAD_FAILED, `Template file not found: ${fullPath}`, {
+			componentPath,
+			templateId
+		});
+	}
+	const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+	logDebug("Loading template", {
+		path: fullPath,
+		templateId
+	});
+	const mod = await import(pathToFileURL(fullPath).href);
+	if (typeof mod.default !== "function") throw new AppError(ErrorCode.TEMPLATE_INVALID_EXPORT, `Template "${templateId}" must have a default export that is a component function.`, { templateId });
+	const { propsSchema } = mod;
+	if (!isZodObject(propsSchema)) throw new AppError(ErrorCode.TEMPLATE_INVALID_EXPORT, `Template "${templateId}" must export a "propsSchema" that is a z.object({...}).`, { templateId });
+	return {
+		contentHash,
+		module: mod
+	};
+};
+const parseDataFile = async (filePath) => {
+	const content = await readFile(filePath, "utf-8");
+	if (filePath.endsWith(".json")) {
+		const data = JSON.parse(content);
+		if (Array.isArray(data)) return data;
+		throw new AppError(ErrorCode.API_ERROR, "JSON data file must contain an array of objects.");
+	}
+	if (filePath.endsWith(".csv")) {
+		const { parse } = await import("csv-parse/sync");
+		return parse(content, {
+			columns: true,
+			skip_empty_lines: true,
+			trim: true
+		});
+	}
+	throw new AppError(ErrorCode.API_ERROR, "Data file must be .csv or .json.");
+};
+const resolveLocales = async (rootDir, localeCodes, templateId) => {
+	if (localeCodes.length === 0) return [{ id: "default" }];
+	return await Promise.all(localeCodes.map(async (code) => {
+		const localePath = path.resolve(rootDir, `locales/${code}.json`);
+		try {
+			const content = await readFile(localePath, "utf-8");
+			return {
+				data: JSON.parse(content)[templateId],
+				id: code
+			};
+		} catch {
+			return { id: code };
+		}
+	}));
+};
+const isFontDescriptor = (f) => typeof f === "object" && !(f instanceof Uint8Array);
+const resolveArabicFonts = async (_locales) => {
+	let fonts = [];
+	let fontFamilies = [];
+	try {
+		fonts = await googleFonts([{
+			name: "Noto Sans Arabic",
+			weight: [400, 700]
+		}]);
+		fontFamilies = fonts.filter(isFontDescriptor).map((f) => String(f.name ?? "")).filter(Boolean);
+		logDebug("googleFonts resolved", {
+			count: fonts.length,
+			hasData: fonts.filter(isFontDescriptor).map((f) => typeof f.data),
+			names: fonts.filter(isFontDescriptor).map((f) => f.name)
+		});
+	} catch (error) {
+		logDebug("googleFonts failed, using direct URL fallback", { error: String(error) });
+		fonts = [{
+			data: /* @__PURE__ */ new Uint8Array(0),
+			name: "Noto Sans Arabic",
+			weight: 400
+		}];
+		fontFamilies = ["Noto Sans Arabic"];
+	}
+	return {
+		fontFamilies,
+		fonts
+	};
+};
+const runBatch = async (input) => {
+	const start = performance.now();
+	const { baseProps = {}, dataFile, failFast = false, cacheDir: cacheDirOverride, locales: filterLocales, outDir: outDirOverride, presets: filterPresets, rootDir, rows: inlineRows, templateId } = input;
+	const config = await loadConfig(rootDir);
+	const entry = config.templates[templateId];
+	if (!entry) throw new Error(`Template not found: ${templateId}`);
+	const { contentHash, module } = await importTemplateForBatch(rootDir, entry.componentPath, templateId);
+	const Component = module.default;
+	const presets = (filterPresets ?? config.presets.map((p) => p.id)).map((id) => {
+		const p = config.presets.find((preset) => preset.id === id);
+		if (!p) throw new Error(`Preset not found: ${id}`);
+		return {
+			height: p.height,
+			id: p.id,
+			width: p.width
+		};
+	});
+	const locales = await resolveLocales(rootDir, filterLocales ?? config.locales ?? [], templateId);
+	const cells = expandMatrix({
+		baseProps,
+		locales,
+		presets,
+		rows: dataFile ? await parseDataFile(path.resolve(rootDir, dataFile)) : inlineRows ?? []
+	});
+	const outDir = path.resolve(rootDir, outDirOverride ?? config.outDir ?? "./out");
+	const cache = new RenderCache({ cacheDir: cacheDirOverride ?? path.resolve(rootDir, ".studio-cache") });
+	await cache.init();
+	const arabicLocales = locales.filter((l) => l.id.startsWith("ar"));
+	logDebug("Arabic locale detection", {
+		arabicCount: arabicLocales.length,
+		localeIds: locales.map((l) => l.id)
+	});
+	let fonts = [];
+	let fontFamilies;
+	if (arabicLocales.length > 0) {
+		const { fonts: resolvedFonts, fontFamilies: resolvedFamilies } = await resolveArabicFonts(locales);
+		fonts = resolvedFonts;
+		fontFamilies = resolvedFamilies;
+	}
+	const succeeded = [];
+	const failed = [];
+	const renderOptions = fonts.length > 0 ? {
+		fontFamilies,
+		fonts
+	} : void 0;
+	logDebug("renderOptions before loop", {
+		fontFamilies,
+		fontsCount: fonts.length,
+		hasOptions: renderOptions !== void 0
+	});
+	try {
+		for (const cell of cells) try {
+			const result = await renderOne({
+				cache,
+				compiledTemplate: await compileTemplate(createElement(Component, cell.props)),
+				contentHash,
+				filename: generateOutputFilename({
+					locale: cell.locale,
+					presetId: cell.preset.id,
+					rowKey: cell.rowKey,
+					templateId
+				}),
+				height: cell.preset.height,
+				locale: cell.locale,
+				outDir,
+				props: cell.props,
+				renderOptions,
+				templateId,
+				width: cell.preset.width
+			});
+			succeeded.push({
+				cacheHit: result.cacheHit,
+				locale: cell.locale,
+				outputPath: result.outputPath,
+				preset: cell.preset.id,
+				rowIndex: cell.rowIndex
+			});
+		} catch (error) {
+			failed.push({
+				error: error instanceof Error ? error.message : String(error),
+				locale: cell.locale,
+				preset: cell.preset.id,
+				rowIndex: cell.rowIndex
+			});
+			if (failFast) throw error;
+		}
+	} finally {
+		cache.close();
+	}
+	const manifest = {
+		completedCount: cells.length,
+		failed,
+		status: failFast && failed.length > 0 ? "aborted" : "completed",
+		succeeded,
+		totalCount: cells.length
+	};
+	await writeManifest(`${outDir}/manifest.json`, manifest);
+	return {
+		elapsedMs: performance.now() - start,
+		manifest
+	};
+};
+//#endregion
+export { importTemplateForBatch as a, logWarn as c, runBatch as d, studioConfigSchema as f, compileTemplate as i, measureTemplate as l, ErrorCode as n, loadConfig as o, RenderCache as r, logError as s, AppError as t, renderToPixels as u };