@glissade/cli 0.11.0 → 0.12.0-pre.0

package/dist/frameCache.js

@@ -0,0 +1,299 @@
+import { t as __exportAll } from "./rolldown-runtime.js";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { serializeDisplayList } from "@glissade/scene";
+import { createHash } from "node:crypto";
+import { deflateSync, inflateSync } from "node:zlib";
+//#region src/frameCache.ts
+/**
+* gs render persistent raster cache — the on-disk `.gscache` (DESIGN.md §3.5,
+* 0.12). A content-addressed disk cache so a one-line edit doesn't re-rasterize
+* every blur-heavy frame across runs/shards. This LAYERS ON the in-memory §3.5
+* group-bitmap LRU (`scene/src/raster2d.ts`) — it does NOT replace it: the
+* in-memory cache spans groups WITHIN one process; this spans WHOLE FRAMES across
+* processes/runs.
+*
+* LOCKED scope (per the 0.12 card): WHOLE-FRAME granularity only — the key is over
+* the ENTIRE frame's DisplayList, not per-group (per-group tiling is DEFERRED to
+* 0.13). A hit is the "this frame's content is byte-identical to a prior render"
+* case, so byte-safety is by construction.
+*
+* THE failure mode is SILENT corruption: a stale tile served from an INCOMPLETE
+* key. So the key MUST fold EVERY byte-affecting input (§ key completeness):
+*   1. the frame's DisplayList-snapshot bytes (`serializeDisplayList` — the shipped
+*      byte-preserving collapse serializer; resources already inlined to content,
+*      and the post-evaluate DisplayList already encodes resolved device
+*      transforms, so this captures geometry/paint/transform for a whole frame),
+*   2. the glissade VERSION (any Raster2D-composite / Skia-toolchain change
+*      invalidates every frame — bump-on-version is the cheapest correct
+*      invalidation; text/font tiles are thereby scoped to the pinned toolchain),
+*   3. the BackendCaps id (filters / shaders / maxTextureSize).
+* `version` and `capsId` have no source inside `scene`, so they are INJECTED via a
+* `CacheKeyContext` from the CLI — NEVER read from disk.
+*
+* HIT == MISS: the HIT path reuses the SAME composite/encode routine as a MISS.
+* The miss path renders, reads raw RGBA, stores it; the hit path loads the stored
+* RGBA back into the backend (`putPixels`) and hands it to the IDENTICAL downstream
+* (`encodePng()` / the ffmpeg pipe), so a hit is byte-identical to a cold render.
+* `mode:'off'` skips the cache entirely → the EXACT current equality baseline.
+*
+* Storage: raw-RGBA + zlib (Node `zlib`), one file per frame keyed by the hash. NO
+* ffmpeg / FFV1. Whole-frame RGBA is ~MBs/frame, so a size-capped LRU ships from
+* day one (access-time ordered, default 2 GB) — an uncapped `.gscache` would eat a
+* dev disk on the first full episode.
+*
+* Concurrency: shards SHARE one `.gscache` dir. The cache is content-addressed
+* (filename IS the key), writes are atomic (temp-file + rename), and LRU is derived
+* from filesystem mtime (touched on read). A delete/regenerate race between shards
+* is benign — a missing entry just re-renders.
+*/
+var frameCache_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_CACHE_MAX_SIZE: () => DEFAULT_CACHE_MAX_SIZE,
+	FrameCache: () => FrameCache,
+	FrameCacheError: () => FrameCacheError,
+	capsId: () => capsId,
+	clearFrameCache: () => clearFrameCache,
+	frameCacheKey: () => frameCacheKey,
+	parseCacheMaxSize: () => parseCacheMaxSize,
+	probeEntryHeader: () => probeEntryHeader
+});
+/** Default LRU cap: 2 GB of compressed entries (the card's default). */
+const DEFAULT_CACHE_MAX_SIZE = 2 * 1024 * 1024 * 1024;
+/** The on-disk file magic + format version — a format change must invalidate every entry. */
+const MAGIC = 1196639025;
+const HEADER_BYTES = 16;
+var FrameCacheError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FrameCacheError";
+	}
+};
+/**
+* Stable, content-addressed key for ONE whole frame. Folds EVERY byte-affecting
+* input: the DisplayList-snapshot bytes (geometry/paint/transform, resources
+* inlined to content), the glissade version, and the backend caps id. An
+* incomplete key here IS the only failure mode (a stale frame served for changed
+* content), so the NEGATIVE gate test asserts that dropping any component makes
+* `gs cache verify` fail.
+*/
+function frameCacheKey(dl, ctx) {
+	return createHash("sha256").update(serializeDisplayList(dl)).update("\0").update(ctx.version).update("\0").update(ctx.capsId).digest("hex");
+}
+/** A canonical BackendCaps id (filters sorted, shaders, maxTextureSize) — the §3 caps fold. */
+function capsId(caps) {
+	return `caps:f=${[...caps.filters].sort().join(",")};s=${caps.shaders ? 1 : 0};tex=${caps.maxTextureSize}`;
+}
+/**
+* One frame entry on disk: a 16-byte header (magic, format version, width,
+* height) followed by zlib-deflated straight RGBA. Width/height let the loader
+* sanity-check the buffer against the live canvas size before blitting (a
+* defensive guard — a mismatched size would otherwise corrupt the frame).
+*/
+function encodeEntry(width, height, rgba) {
+	const header = Buffer.alloc(HEADER_BYTES);
+	header.writeUInt32BE(MAGIC, 0);
+	header.writeUInt32BE(1, 4);
+	header.writeUInt32BE(width, 8);
+	header.writeUInt32BE(height, 12);
+	const body = deflateSync(Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength));
+	return Buffer.concat([header, body]);
+}
+function decodeEntry(buf) {
+	if (buf.length < HEADER_BYTES || buf.readUInt32BE(0) !== MAGIC) throw new FrameCacheError("corrupt .gscache entry (bad magic)");
+	const width = buf.readUInt32BE(8);
+	const height = buf.readUInt32BE(12);
+	const raw = inflateSync(buf.subarray(HEADER_BYTES));
+	return {
+		width,
+		height,
+		rgba: new Uint8ClampedArray(raw.buffer, raw.byteOffset, raw.byteLength)
+	};
+}
+/**
+* The persistent whole-frame raster cache. One instance per render process; shards
+* each open their own over the SAME dir (content-addressed + atomic writes make
+* that safe). A `mode:'off'` instance is inert — `get` always misses and `put` is a
+* no-op — so the cache-off path is the exact current baseline.
+*/
+var FrameCache = class {
+	dir;
+	mode;
+	maxSize;
+	stats = {
+		hits: 0,
+		misses: 0,
+		stored: 0,
+		evicted: 0
+	};
+	constructor(opts) {
+		this.dir = opts.dir;
+		this.mode = opts.mode;
+		this.maxSize = opts.maxSize ?? 2147483648;
+		if (this.mode !== "off") mkdirSync(this.dir, { recursive: true });
+	}
+	pathFor(key) {
+		return join(this.dir, `${key}.gscf`);
+	}
+	/**
+	* Look up a whole-frame RGBA by key. On a hit, the file's mtime is touched
+	* (access-time bump for the LRU) and the decoded RGBA returned; the caller blits
+	* it via `backend.putPixels` and runs the IDENTICAL encode. Returns undefined on
+	* a miss or in `mode:'off'`. A corrupt/truncated entry is treated as a miss (it
+	* is deleted so it re-renders) rather than a hard error — the cache is advisory.
+	*/
+	get(key) {
+		if (this.mode === "off") return void 0;
+		const file = this.pathFor(key);
+		if (!existsSync(file)) {
+			this.stats.misses++;
+			return;
+		}
+		try {
+			const { rgba } = decodeEntry(readFileSync(file));
+			const now = /* @__PURE__ */ new Date();
+			try {
+				utimesSync(file, now, now);
+			} catch {}
+			this.stats.hits++;
+			return rgba;
+		} catch {
+			try {
+				unlinkSync(file);
+			} catch {}
+			this.stats.misses++;
+			return;
+		}
+	}
+	/**
+	* Store a whole-frame RGBA under its key. No-op in `read-only`/`off`. The write
+	* is atomic (temp file + rename) so a crash/interrupt never leaves a torn entry
+	* a later run could half-read (the single failure mode). After a store the LRU
+	* size cap is enforced.
+	*/
+	put(key, width, height, rgba) {
+		if (this.mode !== "read-write") return;
+		const file = this.pathFor(key);
+		if (existsSync(file)) {
+			const now = /* @__PURE__ */ new Date();
+			try {
+				utimesSync(file, now, now);
+			} catch {}
+			return;
+		}
+		const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+		writeFileSync(tmp, encodeEntry(width, height, rgba));
+		try {
+			renameSync(tmp, file);
+		} catch {
+			try {
+				unlinkSync(tmp);
+			} catch {}
+			return;
+		}
+		this.stats.stored++;
+		this.enforceSizeCap();
+	}
+	/**
+	* Evict oldest (by mtime) entries until the total compressed size is within
+	* `maxSize`. Content-addressed + idempotent, so a delete racing a peer's
+	* regeneration is benign. Runs after each store; cheap relative to a frame
+	* rasterize.
+	*/
+	enforceSizeCap() {
+		let entries;
+		try {
+			entries = readdirSync(this.dir).filter((f) => f.endsWith(".gscf")).map((f) => {
+				const p = join(this.dir, f);
+				const st = statSync(p);
+				return {
+					file: p,
+					size: st.size,
+					mtime: st.mtimeMs
+				};
+			});
+		} catch {
+			return;
+		}
+		let total = entries.reduce((s, e) => s + e.size, 0);
+		if (total <= this.maxSize) return;
+		entries.sort((a, b) => a.mtime - b.mtime);
+		for (const e of entries) {
+			if (total <= this.maxSize) break;
+			try {
+				unlinkSync(e.file);
+				total -= e.size;
+				this.stats.evicted++;
+			} catch {
+				total -= e.size;
+			}
+		}
+	}
+	/** Snapshot of hit/miss/store/evict counters (for the render summary + tests). */
+	getStats() {
+		return { ...this.stats };
+	}
+	/** Total compressed bytes currently on disk (for tests / a `--cache` summary). */
+	diskSize() {
+		if (this.mode === "off" || !existsSync(this.dir)) return 0;
+		let total = 0;
+		for (const f of readdirSync(this.dir)) {
+			if (!f.endsWith(".gscf")) continue;
+			try {
+				total += statSync(join(this.dir, f)).size;
+			} catch {}
+		}
+		return total;
+	}
+	/** Number of entries currently on disk (tests). */
+	entryCount() {
+		if (this.mode === "off" || !existsSync(this.dir)) return 0;
+		return readdirSync(this.dir).filter((f) => f.endsWith(".gscf")).length;
+	}
+};
+/**
+* Parse a `--cache-max-size` flag: a raw byte count or a human size (`2GB`,
+* `512MB`, `1.5g`). Rejects garbage so a typo doesn't silently default. Case- and
+* suffix-insensitive (b/k/m/g, optionally with a trailing `b`).
+*/
+function parseCacheMaxSize(flag) {
+	const m = /^(\d+(?:\.\d+)?)\s*([kmgt]?)b?$/i.exec(flag.trim());
+	if (!m) throw new FrameCacheError(`--cache-max-size must be a byte count or size like '2GB'/'512MB', got '${flag}'`);
+	const n = Number(m[1]);
+	const unit = (m[2] ?? "").toLowerCase();
+	return Math.floor(n * ({
+		"": 1,
+		k: 1024,
+		m: 1024 ** 2,
+		g: 1024 ** 3,
+		t: 1024 ** 4
+	}[unit] ?? 1));
+}
+/**
+* Read the magic-validated header of an entry WITHOUT inflating its body — a cheap
+* existence + size probe used by `gs cache verify` to report what it sampled.
+*/
+function probeEntryHeader(file) {
+	let fd;
+	try {
+		fd = openSync(file, "r");
+		const header = Buffer.alloc(HEADER_BYTES);
+		if (readSync(fd, header, 0, HEADER_BYTES, 0) < HEADER_BYTES || header.readUInt32BE(0) !== MAGIC) return void 0;
+		return {
+			width: header.readUInt32BE(8),
+			height: header.readUInt32BE(12)
+		};
+	} catch {
+		return;
+	} finally {
+		if (fd !== void 0) closeSync(fd);
+	}
+}
+/** Remove the whole `.gscache` dir (a `gs cache clear` convenience / test cleanup). */
+function clearFrameCache(dir) {
+	rmSync(dir, {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+export { clearFrameCache as a, parseCacheMaxSize as c, capsId as i, probeEntryHeader as l, FrameCache as n, frameCacheKey as o, FrameCacheError as r, frameCache_exports as s, DEFAULT_CACHE_MAX_SIZE as t };