@three-flatland/bake 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/index.d.ts

@@ -1,162 +1,6 @@
-/**
- * Contract every baker must satisfy.
- *
- * Bakers are registered by package.json via a `flatland.bake` field:
- *
- * ```json
- * {
- *   "flatland": {
- *     "bake": [
- *       { "name": "font", "description": "Bake SlugFont", "entry": "./dist/cli.js" }
- *     ]
- *   }
- * }
- * ```
- *
- * Entry modules must default-export a `Baker`. The legacy `flatland.bakers`
- * shape is still accepted for one release with a deprecation warning.
- */
-interface Baker {
-    /** Subcommand name used on the CLI: `flatland-bake <name> ...` */
-    name: string;
-    /** One-line description shown by `flatland-bake --list`. */
-    description: string;
-    /**
-     * Run the baker with the CLI args that follow the subcommand.
-     * Resolves to an exit code (0 = success).
-     */
-    run(args: string[]): Promise<number>;
-    /** Optional multiline usage string for `flatland-bake <name> --help`. */
-    usage?(): string;
-}
-interface BakerRegistration {
-    name: string;
-    description: string;
-    entry: string;
-    /** Package that declared the baker — used in diagnostics. */
-    packageName: string;
-    /** Absolute path on disk the `entry` resolves to. */
-    resolvedEntry: string;
-}
-interface FlatlandManifestEntry {
-    name: string;
-    description: string;
-    entry: string;
-}
-interface FlatlandManifest {
-    /** Current registration shape. */
-    bake?: FlatlandManifestEntry[];
-    /** @deprecated Legacy shape; use `bake` instead. Accepted for one release. */
-    bakers?: FlatlandManifestEntry[];
-}
-/**
- * Shared option interface for every loader that speaks the
- * "try baked sibling first → fall back to in-memory generation" pattern.
- *
- * Loaders extend this with their asset-specific options:
- *
- * ```ts
- * interface MyLoaderOptions extends BakedAssetLoaderOptions {
- *   // asset-specific fields
- * }
- * ```
- */
-interface BakedAssetLoaderOptions {
-    /**
-     * Generate this asset's derived data in the browser on every load
-     * instead of loading a pre-baked sidecar. The runtime generator
-     * becomes the canonical source — no sidecar probe, no devtime "no
-     * baked sibling" warning, just a fresh generate on every load.
-     *
-     * If you ask for the data (e.g. `normals: true`), you always get it.
-     * `forceRuntime` chooses *where* the generation happens — browser vs
-     * CI — it does not choose whether you get the data. The default path
-     * still produces the data on every miss; this flag just commits to
-     * "the browser is always where it's produced for this asset."
-     *
-     * Use when runtime really is the right home for the generation:
-     * procedurally varied content, throwaway prototypes, asset bundles
-     * where shipping the sidecar isn't worth the bytes. Not a dev-
-     * iteration knob — the default path (probe → generate on miss + warn
-     * pointing at `flatland-bake`) already handles iteration.
-     *
-     * Default `false`. Mirrors `SlugFontLoader.forceRuntime` — one flag
-     * across every baked-asset loader in the codebase.
-     */
-    forceRuntime?: boolean;
-}
-/**
- * Metadata stamped into a baked PNG's `tEXt` chunk under the key
- * `flatland`. Read back by `probeBakedSibling` to validate the baked
- * file still matches the descriptor a consumer is about to use.
- */
-interface BakedSidecarMetadata {
-    /** Content hash of the descriptor that produced this file. */
-    hash: string;
-    /** Schema version of the metadata format itself. */
-    v: 1;
-}
-
-/**
- * Derive the sibling URL for a baked asset.
- *
- * @example
- *   bakedSiblingURL('/sprites/knight.png', '.normal.png')
- *     // → '/sprites/knight.normal.png'
- *
- * Query strings and fragments are preserved:
- *   bakedSiblingURL('/a.png?v=2', '.normal.png')
- *     // → '/a.normal.png?v=2'
- */
-declare function bakedSiblingURL(sourceURL: string, suffix: string): string;
-/**
- * Stable content hash of any JSON-serializable value. FNV-1a 64-bit over
- * a canonical stringification (sorted keys). Deterministic across
- * browser and node, no deps, sync.
- *
- * Intended for cache invalidation of baked sidecars — not for any
- * cryptographic purpose.
- */
-declare function hashDescriptor(value: unknown): string;
-/**
- * HEAD-probe a baked sibling URL and, when `expectedHash` is provided,
- * range-fetch the PNG header to verify the tEXt stamp matches.
- *
- * Returns `{ ok: false }` when the sibling is missing or unreachable.
- * Returns `{ ok: true, hashMatches }` otherwise; callers decide whether
- * to use the baked file or re-generate in-memory.
- */
-declare function probeBakedSibling(url: string, opts?: {
-    expectedHash?: string;
-}): Promise<{
-    ok: true;
-    hashMatches: boolean;
-    url: string;
-} | {
-    ok: false;
-}>;
-/**
- * Minimal PNG `tEXt` chunk reader. Walks chunks after the 8-byte
- * signature, stopping when it finds one whose keyword matches `key`.
- *
- * Returns the chunk's Latin-1 text value, or `null` when the keyword is
- * absent / the buffer is not a valid PNG.
- */
-declare function readPngTextChunk(buffer: ArrayBuffer, key: string): string | null;
-
-/**
- * Emit a console warning gated on `NODE_ENV !== 'production'`. Deduped
- * per `(category, url)` — the same warning never fires twice.
- *
- * Shared by every sidecar-using loader so warnings surface uniformly
- * across the ecosystem (normals, fonts, atlases, …).
- *
- * @param category short tag identifying what system warned (e.g. 'normal')
- * @param url      absolute URL or path of the asset
- * @param message  the message shown to the user
- */
-declare function devtimeWarn(category: string, url: string, message: string): void;
-/** Clear the devtime-warning dedupe cache. Intended for tests. */
-declare function _resetDevtimeWarnings(): void;
-
-export { type BakedAssetLoaderOptions, type BakedSidecarMetadata, type Baker, type BakerRegistration, type FlatlandManifest, type FlatlandManifestEntry, _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, hashDescriptor, probeBakedSibling, readPngTextChunk };
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { _resetDevtimeWarnings, devtimeWarn } from "./devtimeWarn.js";
+import { BakedAssetLoaderOptions, BakedSidecarMetadata, Baker, BakerRegistration, FlatlandManifest, FlatlandManifestEntry } from "./types.js";
+import { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk } from "./sidecar.js";
+export { type BakedAssetLoaderOptions, type BakedSidecarMetadata, type Baker, type BakerRegistration, type FlatlandManifest, type FlatlandManifestEntry, _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, hashDescriptor, probeBakedSibling, readPngTextChunk };

package/dist/index.js

@@ -1,16 +1,6 @@
-import {
-  bakedSiblingURL,
-  probeBakedSibling,
-  readPngTextChunk,
-  hashDescriptor
-} from "./sidecar.js";
-import { devtimeWarn, _resetDevtimeWarnings } from "./devtimeWarn.js";
-export {
-  _resetDevtimeWarnings,
-  bakedSiblingURL,
-  devtimeWarn,
-  hashDescriptor,
-  probeBakedSibling,
-  readPngTextChunk
-};
-//# sourceMappingURL=index.js.map
+import "node:path";
+import "node:url";
+import.meta.url;
+import { _resetDevtimeWarnings, devtimeWarn } from "./devtimeWarn.js";
+import { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk } from "./sidecar.js";
+export { _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, hashDescriptor, probeBakedSibling, readPngTextChunk };

package/dist/node.d.ts

@@ -1,35 +1,8 @@
-import { BakerRegistration, BakedSidecarMetadata } from './index.js';
-export { BakedAssetLoaderOptions, Baker, FlatlandManifest, FlatlandManifestEntry, _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, hashDescriptor, probeBakedSibling, readPngTextChunk } from './index.js';
-
-/**
- * Discover registered bakers by walking `node_modules` near the current
- * working directory. Supports both flat and pnpm-symlinked layouts: every
- * `package.json` that declares a `flatland.bake` (or legacy
- * `flatland.bakers`) field is picked up.
- *
- * Conflicts (multiple packages registering the same baker name) are reported;
- * the first match wins and the rest are returned as warnings so the caller
- * can decide whether to fail or log.
- */
-declare function discoverBakers(cwd?: string): {
-    bakers: BakerRegistration[];
-    conflicts: string[];
-};
-
-/**
- * Write a PNG with a flatland metadata `tEXt` chunk stamped in.
- *
- * The stamp lives under keyword `flatland` and carries the descriptor
- * hash so downstream `probeBakedSibling` calls can invalidate the
- * baked file when the descriptor changes.
- */
-declare function writeSidecarPng(outputPath: string, pixels: Uint8Array, width: number, height: number, metadata: BakedSidecarMetadata): void;
-/**
- * Write a sidecar descriptor JSON file adjacent to the source asset.
- *
- * Same file format `flatland-bake <subcommand> --descriptor` consumes,
- * so the runtime and CLI agree on one shape.
- */
-declare function writeSidecarJson(outputPath: string, descriptor: unknown): void;
-
-export { BakedSidecarMetadata, BakerRegistration, discoverBakers, writeSidecarJson, writeSidecarPng };
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { _resetDevtimeWarnings, devtimeWarn } from "./devtimeWarn.js";
+import { BakedAssetLoaderOptions, BakedSidecarMetadata, Baker, BakerRegistration, FlatlandManifest, FlatlandManifestEntry } from "./types.js";
+import { discoverBakers } from "./discovery.js";
+import { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk } from "./sidecar.js";
+import { writeSidecarJson, writeSidecarPng } from "./writeSidecar.js";
+export { type BakedAssetLoaderOptions, type BakedSidecarMetadata, type Baker, type BakerRegistration, type FlatlandManifest, type FlatlandManifestEntry, _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, discoverBakers, hashDescriptor, probeBakedSibling, readPngTextChunk, writeSidecarJson, writeSidecarPng };

package/dist/node.js

@@ -1,9 +1,8 @@
-export * from "./index.js";
+import "node:path";
+import "node:url";
+import.meta.url;
 import { discoverBakers } from "./discovery.js";
-import { writeSidecarPng, writeSidecarJson } from "./writeSidecar.js";
-export {
-  discoverBakers,
-  writeSidecarJson,
-  writeSidecarPng
-};
-//# sourceMappingURL=node.js.map
+import { _resetDevtimeWarnings, devtimeWarn } from "./devtimeWarn.js";
+import { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk } from "./sidecar.js";
+import { writeSidecarJson, writeSidecarPng } from "./writeSidecar.js";
+export { _resetDevtimeWarnings, bakedSiblingURL, devtimeWarn, discoverBakers, hashDescriptor, probeBakedSibling, readPngTextChunk, writeSidecarJson, writeSidecarPng };

package/dist/sidecar.d.ts

@@ -0,0 +1,52 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/sidecar.d.ts
+/**
+ * Derive the sibling URL for a baked asset.
+ *
+ * @example
+ *   bakedSiblingURL('/sprites/knight.png', '.normal.png')
+ *     // → '/sprites/knight.normal.png'
+ *
+ * Query strings and fragments are preserved:
+ *   bakedSiblingURL('/a.png?v=2', '.normal.png')
+ *     // → '/a.normal.png?v=2'
+ */
+declare function bakedSiblingURL(sourceURL: string, suffix: string): string;
+/**
+ * Stable content hash of any JSON-serializable value. FNV-1a 64-bit over
+ * a canonical stringification (sorted keys). Deterministic across
+ * browser and node, no deps, sync.
+ *
+ * Intended for cache invalidation of baked sidecars — not for any
+ * cryptographic purpose.
+ */
+declare function hashDescriptor(value: unknown): string;
+/**
+ * HEAD-probe a baked sibling URL and, when `expectedHash` is provided,
+ * range-fetch the PNG header to verify the tEXt stamp matches.
+ *
+ * Returns `{ ok: false }` when the sibling is missing or unreachable.
+ * Returns `{ ok: true, hashMatches }` otherwise; callers decide whether
+ * to use the baked file or re-generate in-memory.
+ */
+declare function probeBakedSibling(url: string, opts?: {
+  expectedHash?: string;
+}): Promise<{
+  ok: true;
+  hashMatches: boolean;
+  url: string;
+} | {
+  ok: false;
+}>;
+/**
+ * Minimal PNG `tEXt` chunk reader. Walks chunks after the 8-byte
+ * signature, stopping when it finds one whose keyword matches `key`.
+ *
+ * Returns the chunk's Latin-1 text value, or `null` when the keyword is
+ * absent / the buffer is not a valid PNG.
+ */
+declare function readPngTextChunk(buffer: ArrayBuffer, key: string): string | null;
+//#endregion
+export { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk };
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","names":[],"sources":["../src/sidecar.ts"],"mappings":";;;;;;;;;;;;;;iBAagB,gBAAgB,mBAAmB;;;;;;;;;iBAYnC,eAAe;;;;;;;;;iBAkCT,kBACpB,aACA;EAAS;IACR;EAAU;EAAU;EAAsB;;EAAkB;;;;;;;;;iBA2C/C,iBAAiB,QAAQ,aAAa"}

package/dist/sidecar.js

@@ -1,109 +1,154 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/sidecar.ts
+/**
+* Derive the sibling URL for a baked asset.
+*
+* @example
+*   bakedSiblingURL('/sprites/knight.png', '.normal.png')
+*     // → '/sprites/knight.normal.png'
+*
+* Query strings and fragments are preserved:
+*   bakedSiblingURL('/a.png?v=2', '.normal.png')
+*     // → '/a.normal.png?v=2'
+*/
 function bakedSiblingURL(sourceURL, suffix) {
-  return sourceURL.replace(/\.(\w+)($|[?#])/i, `${suffix}$2`);
+	return sourceURL.replace(/\.(\w+)($|[?#])/i, `${suffix}$2`);
 }
+/**
+* Stable content hash of any JSON-serializable value. FNV-1a 64-bit over
+* a canonical stringification (sorted keys). Deterministic across
+* browser and node, no deps, sync.
+*
+* Intended for cache invalidation of baked sidecars — not for any
+* cryptographic purpose.
+*/
 function hashDescriptor(value) {
-  const canonical = stableStringify(value);
-  return fnv1a64(canonical);
+	return fnv1a64(stableStringify(value));
 }
 function stableStringify(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-  if (Array.isArray(value)) {
-    return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
-  }
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+	const obj = value;
+	return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
 }
 function fnv1a64(str) {
-  let hash = 0xcbf29ce484222325n;
-  const prime = 0x100000001b3n;
-  const mask = 0xffffffffffffffffn;
-  for (let i = 0; i < str.length; i++) {
-    hash = hash ^ BigInt(str.charCodeAt(i));
-    hash = hash * prime & mask;
-  }
-  return hash.toString(16).padStart(16, "0");
+	let hash = 14695981039346656037n;
+	const prime = 1099511628211n;
+	const mask = 18446744073709551615n;
+	for (let i = 0; i < str.length; i++) {
+		hash = hash ^ BigInt(str.charCodeAt(i));
+		hash = hash * prime & mask;
+	}
+	return hash.toString(16).padStart(16, "0");
 }
+/**
+* HEAD-probe a baked sibling URL and, when `expectedHash` is provided,
+* range-fetch the PNG header to verify the tEXt stamp matches.
+*
+* Returns `{ ok: false }` when the sibling is missing or unreachable.
+* Returns `{ ok: true, hashMatches }` otherwise; callers decide whether
+* to use the baked file or re-generate in-memory.
+*/
 async function probeBakedSibling(url, opts) {
-  let head;
-  try {
-    head = await fetch(url, { method: "HEAD" });
-  } catch {
-    return { ok: false };
-  }
-  if (!head.ok) return { ok: false };
-  if (opts?.expectedHash === void 0) {
-    return { ok: true, hashMatches: true, url };
-  }
-  let header;
-  try {
-    header = await fetch(url, { headers: { Range: "bytes=0-4095" } });
-  } catch {
-    return { ok: true, hashMatches: false, url };
-  }
-  if (!header.ok) {
-    return { ok: true, hashMatches: false, url };
-  }
-  const buf = await header.arrayBuffer();
-  const metaJSON = readPngTextChunk(buf, "flatland");
-  if (!metaJSON) return { ok: true, hashMatches: false, url };
-  try {
-    const meta = JSON.parse(metaJSON);
-    return { ok: true, hashMatches: meta.hash === opts.expectedHash, url };
-  } catch {
-    return { ok: true, hashMatches: false, url };
-  }
+	let head;
+	try {
+		head = await fetch(url, { method: "HEAD" });
+	} catch {
+		return { ok: false };
+	}
+	if (!head.ok) return { ok: false };
+	if (opts?.expectedHash === void 0) return {
+		ok: true,
+		hashMatches: true,
+		url
+	};
+	let header;
+	try {
+		header = await fetch(url, { headers: { Range: "bytes=0-4095" } });
+	} catch {
+		return {
+			ok: true,
+			hashMatches: false,
+			url
+		};
+	}
+	if (!header.ok) return {
+		ok: true,
+		hashMatches: false,
+		url
+	};
+	const metaJSON = readPngTextChunk(await header.arrayBuffer(), "flatland");
+	if (!metaJSON) return {
+		ok: true,
+		hashMatches: false,
+		url
+	};
+	try {
+		return {
+			ok: true,
+			hashMatches: JSON.parse(metaJSON).hash === opts.expectedHash,
+			url
+		};
+	} catch {
+		return {
+			ok: true,
+			hashMatches: false,
+			url
+		};
+	}
 }
+/**
+* Minimal PNG `tEXt` chunk reader. Walks chunks after the 8-byte
+* signature, stopping when it finds one whose keyword matches `key`.
+*
+* Returns the chunk's Latin-1 text value, or `null` when the keyword is
+* absent / the buffer is not a valid PNG.
+*/
 function readPngTextChunk(buffer, key) {
-  if (buffer.byteLength < 8) return null;
-  const view = new DataView(buffer);
-  const expectedSig = [137, 80, 78, 71, 13, 10, 26, 10];
-  for (let i = 0; i < 8; i++) {
-    if (view.getUint8(i) !== expectedSig[i]) return null;
-  }
-  let offset = 8;
-  while (offset + 8 <= buffer.byteLength) {
-    const length = view.getUint32(offset);
-    const type = String.fromCharCode(
-      view.getUint8(offset + 4),
-      view.getUint8(offset + 5),
-      view.getUint8(offset + 6),
-      view.getUint8(offset + 7)
-    );
-    const dataStart = offset + 8;
-    const dataEnd = dataStart + length;
-    if (dataEnd + 4 > buffer.byteLength) return null;
-    if (type === "tEXt") {
-      let sepIdx = -1;
-      for (let i = dataStart; i < dataEnd; i++) {
-        if (view.getUint8(i) === 0) {
-          sepIdx = i;
-          break;
-        }
-      }
-      if (sepIdx > dataStart) {
-        let keyword = "";
-        for (let i = dataStart; i < sepIdx; i++) {
-          keyword += String.fromCharCode(view.getUint8(i));
-        }
-        if (keyword === key) {
-          let value = "";
-          for (let i = sepIdx + 1; i < dataEnd; i++) {
-            value += String.fromCharCode(view.getUint8(i));
-          }
-          return value;
-        }
-      }
-    }
-    if (type === "IEND") return null;
-    offset = dataEnd + 4;
-  }
-  return null;
+	if (buffer.byteLength < 8) return null;
+	const view = new DataView(buffer);
+	const expectedSig = [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	];
+	for (let i = 0; i < 8; i++) if (view.getUint8(i) !== expectedSig[i]) return null;
+	let offset = 8;
+	while (offset + 8 <= buffer.byteLength) {
+		const length = view.getUint32(offset);
+		const type = String.fromCharCode(view.getUint8(offset + 4), view.getUint8(offset + 5), view.getUint8(offset + 6), view.getUint8(offset + 7));
+		const dataStart = offset + 8;
+		const dataEnd = dataStart + length;
+		if (dataEnd + 4 > buffer.byteLength) return null;
+		if (type === "tEXt") {
+			let sepIdx = -1;
+			for (let i = dataStart; i < dataEnd; i++) if (view.getUint8(i) === 0) {
+				sepIdx = i;
+				break;
+			}
+			if (sepIdx > dataStart) {
+				let keyword = "";
+				for (let i = dataStart; i < sepIdx; i++) keyword += String.fromCharCode(view.getUint8(i));
+				if (keyword === key) {
+					let value = "";
+					for (let i = sepIdx + 1; i < dataEnd; i++) value += String.fromCharCode(view.getUint8(i));
+					return value;
+				}
+			}
+		}
+		if (type === "IEND") return null;
+		offset = dataEnd + 4;
+	}
+	return null;
 }
-export {
-  bakedSiblingURL,
-  hashDescriptor,
-  probeBakedSibling,
-  readPngTextChunk
-};
+//#endregion
+export { bakedSiblingURL, hashDescriptor, probeBakedSibling, readPngTextChunk };
+
 //# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sidecar.ts"],"sourcesContent":["import type { BakedSidecarMetadata } from './types.js'\n\n/**\n * Derive the sibling URL for a baked asset.\n *\n * @example\n *   bakedSiblingURL('/sprites/knight.png', '.normal.png')\n *     // → '/sprites/knight.normal.png'\n *\n * Query strings and fragments are preserved:\n *   bakedSiblingURL('/a.png?v=2', '.normal.png')\n *     // → '/a.normal.png?v=2'\n */\nexport function bakedSiblingURL(sourceURL: string, suffix: string): string {\n  return sourceURL.replace(/\\.(\\w+)($|[?#])/i, `${suffix}$2`)\n}\n\n/**\n * Stable content hash of any JSON-serializable value. FNV-1a 64-bit over\n * a canonical stringification (sorted keys). Deterministic across\n * browser and node, no deps, sync.\n *\n * Intended for cache invalidation of baked sidecars — not for any\n * cryptographic purpose.\n */\nexport function hashDescriptor(value: unknown): string {\n  const canonical = stableStringify(value)\n  return fnv1a64(canonical)\n}\n\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'\n  if (Array.isArray(value)) {\n    return '[' + value.map((v) => stableStringify(v)).join(',') + ']'\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj).sort()\n  return (\n    '{' +\n    keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') +\n    '}'\n  )\n}\n\nfunction fnv1a64(str: string): string {\n  let hash = 0xcbf29ce484222325n\n  const prime = 0x100000001b3n\n  const mask = 0xffffffffffffffffn\n  for (let i = 0; i < str.length; i++) {\n    hash = hash ^ BigInt(str.charCodeAt(i))\n    hash = (hash * prime) & mask\n  }\n  return hash.toString(16).padStart(16, '0')\n}\n\n/**\n * HEAD-probe a baked sibling URL and, when `expectedHash` is provided,\n * range-fetch the PNG header to verify the tEXt stamp matches.\n *\n * Returns `{ ok: false }` when the sibling is missing or unreachable.\n * Returns `{ ok: true, hashMatches }` otherwise; callers decide whether\n * to use the baked file or re-generate in-memory.\n */\nexport async function probeBakedSibling(\n  url: string,\n  opts?: { expectedHash?: string }\n): Promise<{ ok: true; hashMatches: boolean; url: string } | { ok: false }> {\n  let head: Response\n  try {\n    head = await fetch(url, { method: 'HEAD' })\n  } catch {\n    return { ok: false }\n  }\n  if (!head.ok) return { ok: false }\n\n  if (opts?.expectedHash === undefined) {\n    return { ok: true, hashMatches: true, url }\n  }\n\n  // Range-fetch the PNG header to read the tEXt stamp. We don't need the\n  // full image; the first ~4 KB comfortably covers signature + IHDR +\n  // metadata chunks for every baker we emit.\n  let header: Response\n  try {\n    header = await fetch(url, { headers: { Range: 'bytes=0-4095' } })\n  } catch {\n    return { ok: true, hashMatches: false, url }\n  }\n  if (!header.ok) {\n    return { ok: true, hashMatches: false, url }\n  }\n  const buf = await header.arrayBuffer()\n  const metaJSON = readPngTextChunk(buf, 'flatland')\n  if (!metaJSON) return { ok: true, hashMatches: false, url }\n  try {\n    const meta = JSON.parse(metaJSON) as BakedSidecarMetadata\n    return { ok: true, hashMatches: meta.hash === opts.expectedHash, url }\n  } catch {\n    return { ok: true, hashMatches: false, url }\n  }\n}\n\n/**\n * Minimal PNG `tEXt` chunk reader. Walks chunks after the 8-byte\n * signature, stopping when it finds one whose keyword matches `key`.\n *\n * Returns the chunk's Latin-1 text value, or `null` when the keyword is\n * absent / the buffer is not a valid PNG.\n */\nexport function readPngTextChunk(buffer: ArrayBuffer, key: string): string | null {\n  if (buffer.byteLength < 8) return null\n  const view = new DataView(buffer)\n  const expectedSig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]\n  for (let i = 0; i < 8; i++) {\n    if (view.getUint8(i) !== expectedSig[i]) return null\n  }\n\n  let offset = 8\n  while (offset + 8 <= buffer.byteLength) {\n    const length = view.getUint32(offset)\n    const type = String.fromCharCode(\n      view.getUint8(offset + 4),\n      view.getUint8(offset + 5),\n      view.getUint8(offset + 6),\n      view.getUint8(offset + 7)\n    )\n    const dataStart = offset + 8\n    const dataEnd = dataStart + length\n    if (dataEnd + 4 > buffer.byteLength) return null\n\n    if (type === 'tEXt') {\n      let sepIdx = -1\n      for (let i = dataStart; i < dataEnd; i++) {\n        if (view.getUint8(i) === 0) {\n          sepIdx = i\n          break\n        }\n      }\n      if (sepIdx > dataStart) {\n        let keyword = ''\n        for (let i = dataStart; i < sepIdx; i++) {\n          keyword += String.fromCharCode(view.getUint8(i))\n        }\n        if (keyword === key) {\n          let value = ''\n          for (let i = sepIdx + 1; i < dataEnd; i++) {\n            value += String.fromCharCode(view.getUint8(i))\n          }\n          return value\n        }\n      }\n    }\n\n    if (type === 'IEND') return null\n    offset = dataEnd + 4\n  }\n  return null\n}\n"],"mappings":"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","names":[]}
+{"version":3,"file":"sidecar.js","names":[],"sources":["../src/sidecar.ts"],"sourcesContent":["import type { BakedSidecarMetadata } from './types.js'\n\n/**\n * Derive the sibling URL for a baked asset.\n *\n * @example\n *   bakedSiblingURL('/sprites/knight.png', '.normal.png')\n *     // → '/sprites/knight.normal.png'\n *\n * Query strings and fragments are preserved:\n *   bakedSiblingURL('/a.png?v=2', '.normal.png')\n *     // → '/a.normal.png?v=2'\n */\nexport function bakedSiblingURL(sourceURL: string, suffix: string): string {\n  return sourceURL.replace(/\\.(\\w+)($|[?#])/i, `${suffix}$2`)\n}\n\n/**\n * Stable content hash of any JSON-serializable value. FNV-1a 64-bit over\n * a canonical stringification (sorted keys). Deterministic across\n * browser and node, no deps, sync.\n *\n * Intended for cache invalidation of baked sidecars — not for any\n * cryptographic purpose.\n */\nexport function hashDescriptor(value: unknown): string {\n  const canonical = stableStringify(value)\n  return fnv1a64(canonical)\n}\n\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'\n  if (Array.isArray(value)) {\n    return '[' + value.map((v) => stableStringify(v)).join(',') + ']'\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj).sort()\n  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') + '}'\n}\n\nfunction fnv1a64(str: string): string {\n  let hash = 0xcbf29ce484222325n\n  const prime = 0x100000001b3n\n  const mask = 0xffffffffffffffffn\n  for (let i = 0; i < str.length; i++) {\n    hash = hash ^ BigInt(str.charCodeAt(i))\n    hash = (hash * prime) & mask\n  }\n  return hash.toString(16).padStart(16, '0')\n}\n\n/**\n * HEAD-probe a baked sibling URL and, when `expectedHash` is provided,\n * range-fetch the PNG header to verify the tEXt stamp matches.\n *\n * Returns `{ ok: false }` when the sibling is missing or unreachable.\n * Returns `{ ok: true, hashMatches }` otherwise; callers decide whether\n * to use the baked file or re-generate in-memory.\n */\nexport async function probeBakedSibling(\n  url: string,\n  opts?: { expectedHash?: string }\n): Promise<{ ok: true; hashMatches: boolean; url: string } | { ok: false }> {\n  let head: Response\n  try {\n    head = await fetch(url, { method: 'HEAD' })\n  } catch {\n    return { ok: false }\n  }\n  if (!head.ok) return { ok: false }\n\n  if (opts?.expectedHash === undefined) {\n    return { ok: true, hashMatches: true, url }\n  }\n\n  // Range-fetch the PNG header to read the tEXt stamp. We don't need the\n  // full image; the first ~4 KB comfortably covers signature + IHDR +\n  // metadata chunks for every baker we emit.\n  let header: Response\n  try {\n    header = await fetch(url, { headers: { Range: 'bytes=0-4095' } })\n  } catch {\n    return { ok: true, hashMatches: false, url }\n  }\n  if (!header.ok) {\n    return { ok: true, hashMatches: false, url }\n  }\n  const buf = await header.arrayBuffer()\n  const metaJSON = readPngTextChunk(buf, 'flatland')\n  if (!metaJSON) return { ok: true, hashMatches: false, url }\n  try {\n    const meta = JSON.parse(metaJSON) as BakedSidecarMetadata\n    return { ok: true, hashMatches: meta.hash === opts.expectedHash, url }\n  } catch {\n    return { ok: true, hashMatches: false, url }\n  }\n}\n\n/**\n * Minimal PNG `tEXt` chunk reader. Walks chunks after the 8-byte\n * signature, stopping when it finds one whose keyword matches `key`.\n *\n * Returns the chunk's Latin-1 text value, or `null` when the keyword is\n * absent / the buffer is not a valid PNG.\n */\nexport function readPngTextChunk(buffer: ArrayBuffer, key: string): string | null {\n  if (buffer.byteLength < 8) return null\n  const view = new DataView(buffer)\n  const expectedSig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]\n  for (let i = 0; i < 8; i++) {\n    if (view.getUint8(i) !== expectedSig[i]) return null\n  }\n\n  let offset = 8\n  while (offset + 8 <= buffer.byteLength) {\n    const length = view.getUint32(offset)\n    const type = String.fromCharCode(\n      view.getUint8(offset + 4),\n      view.getUint8(offset + 5),\n      view.getUint8(offset + 6),\n      view.getUint8(offset + 7)\n    )\n    const dataStart = offset + 8\n    const dataEnd = dataStart + length\n    if (dataEnd + 4 > buffer.byteLength) return null\n\n    if (type === 'tEXt') {\n      let sepIdx = -1\n      for (let i = dataStart; i < dataEnd; i++) {\n        if (view.getUint8(i) === 0) {\n          sepIdx = i\n          break\n        }\n      }\n      if (sepIdx > dataStart) {\n        let keyword = ''\n        for (let i = dataStart; i < sepIdx; i++) {\n          keyword += String.fromCharCode(view.getUint8(i))\n        }\n        if (keyword === key) {\n          let value = ''\n          for (let i = sepIdx + 1; i < dataEnd; i++) {\n            value += String.fromCharCode(view.getUint8(i))\n          }\n          return value\n        }\n      }\n    }\n\n    if (type === 'IEND') return null\n    offset = dataEnd + 4\n  }\n  return null\n}\n"],"mappings":"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"}