@three-flatland/normals 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -59,7 +59,7 @@ flatland-bake normal <input.png> --descriptor <input.normal.json>
 | `--strength <n>` | Gradient multiplier before normalization (default `1`) |
 | `--descriptor <path>` | Region-aware descriptor JSON — per-frame / per-tile control for atlases and tilemaps |
 
-See the [three-flatland docs](https://thejustinwalsh.com/three-flatland/) for descriptor examples covering sprite sheets, LDtk tilesets, and directional (3/4-view wall) tiles.
+See the [three-flatland docs](https://tjw.dev/three-flatland/) for descriptor examples covering sprite sheets, LDtk tilesets, and directional (3/4-view wall) tiles.
 
 ### Loader options
 
@@ -212,7 +212,7 @@ This package is renderer-agnostic and works with any Three.js WebGPU project. Ba
 
 ## Documentation
 
-Full docs, interactive examples, and API reference at **[thejustinwalsh.com/three-flatland](https://thejustinwalsh.com/three-flatland/)**
+Full docs, interactive examples, and API reference at **[tjw.dev/three-flatland](https://tjw.dev/three-flatland/)**
 
 ## License
 

package/dist/NormalMapLoader.d.ts

@@ -0,0 +1,99 @@
+import { NormalSourceDescriptor } from "./descriptor.js";
+import { Loader, LoadingManager, Texture } from "three";
+import { BakedAssetLoaderOptions } from "@three-flatland/bake";
+//#region src/NormalMapLoader.d.ts
+/**
+ * Options accepted by `NormalMapLoader.load()`. Inherits `forceRuntime`
+ * from the shared {@link BakedAssetLoaderOptions} so every baked-asset
+ * loader in the codebase advertises the same option shape.
+ */
+interface NormalMapLoaderStaticOptions extends BakedAssetLoaderOptions {
+  /**
+   * When provided, missing sidecars trigger an in-memory bake via
+   * `resolveNormalMap`. Without a descriptor, `NormalMapLoader.load()` can
+   * only probe the baked sibling and returns `null` on miss (legacy
+   * behavior, preserved for backward compat).
+   */
+  descriptor?: NormalSourceDescriptor;
+}
+/**
+ * Result of loading a sprite's normal data.
+ *
+ * Either a baked normal texture (fast path) or `null`, signalling the caller
+ * to use the runtime TSL `normalFromSprite` helper against the sprite's own
+ * alpha channel.
+ */
+type NormalMapResult = Texture | null;
+/**
+ * Loader for per-sprite normal maps following the canonical three-flatland
+ * "try baked → fall back to runtime" pattern documented in
+ * `planning/bake/loader-pattern.md`.
+ *
+ * Given a sprite PNG URL, this loader fetches the sibling `.normal.png` that
+ * `flatland-bake normal` produces. If it is absent, the loader resolves to
+ * `null` so the lit material can switch to its TSL runtime fallback.
+ *
+ * Only the baked path uses the network — the runtime branch is a shader
+ * concern and lives in `@three-flatland/nodes/lighting/normalFromSprite`.
+ *
+ * @example
+ * ```ts
+ * // Vanilla static API
+ * const normalTex = await NormalMapLoader.load('/sprites/knight.png')
+ * if (normalTex) material.normalMap = normalTex
+ * else material.useRuntimeNormals = true
+ *
+ * // Skip the baked probe — go straight to runtime (or null without descriptor)
+ * const tex = await NormalMapLoader.load(url, { forceRuntime: true })
+ *
+ * // R3F useLoader
+ * const tex = useLoader(NormalMapLoader, '/sprites/knight.png')
+ * ```
+ */
+declare class NormalMapLoader extends Loader<NormalMapResult> {
+  /**
+   * Generate this asset's normal map in the browser on every load
+   * instead of loading a pre-baked `.normal.png` sidecar. With a
+   * `descriptor`, the in-memory bake runs on every load. Without a
+   * descriptor, the loader resolves directly to `null` and the caller
+   * uses the TSL runtime fallback. Suppresses the "no baked sibling"
+   * warn either way.
+   *
+   * Use when runtime is the right home for the bake. Not a dev-iteration
+   * knob — the default path (probe → bake on miss + warn) already
+   * handles iteration. See {@link BakedAssetLoaderOptions.forceRuntime}.
+   */
+  forceRuntime: boolean;
+  /**
+   * When set, missing sidecars trigger an in-memory bake via
+   * `resolveNormalMap`. Without a descriptor, the loader can only probe
+   * the baked sibling and returns `null` on miss (legacy behavior).
+   *
+   * Set via the `useLoader` callback:
+   * ```ts
+   * useLoader(NormalMapLoader, url, undefined, (l) => { l.descriptor = desc })
+   * ```
+   */
+  descriptor: NormalSourceDescriptor | undefined;
+  constructor(manager?: LoadingManager);
+  load(url: string, onLoad?: (data: NormalMapResult) => void, onProgress?: (event: ProgressEvent) => void, onError?: (err: unknown) => void): NormalMapResult;
+  loadAsync(url: string): Promise<NormalMapResult>;
+  /**
+   * Vanilla cache: keyed by `(url, forceRuntime, descriptor hash)` so
+   * two callers passing *different* descriptors for the same URL get
+   * distinct results instead of colliding on the first one's bake.
+   *
+   * Instance API (R3F `useLoader`) bypasses this map — R3F has its own
+   * suspense cache and we don't want double-caching to fight the lifecycle.
+   */
+  private static _cache;
+  static load(url: string, options?: NormalMapLoaderStaticOptions): Promise<NormalMapResult>;
+  static clearCache(): void;
+  private static _loadImpl;
+  private static _tryLoadBaked;
+}
+/** Clear the devtime-warning dedupe set. Intended for tests. */
+declare function _resetDevtimeWarnings(): void;
+//#endregion
+export { NormalMapLoader, NormalMapLoaderStaticOptions, NormalMapResult, _resetDevtimeWarnings };
+//# sourceMappingURL=NormalMapLoader.d.ts.map

package/dist/NormalMapLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NormalMapLoader.d.ts","names":[],"sources":["../src/NormalMapLoader.ts"],"mappings":";;;;;;;;;UAeiB,qCAAqC;;;;;;;EAOpD,aAAa;;;;;;;;;KAUH,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BjB,wBAAwB,OAAO;;;;;;;;;;;;;EAa1C;;;;;;;;;;;EAWA,YAAY;EAEA,YAAA,UAAU;EAMtB,KACE,aACA,UAAU,MAAM,0BAChB,cAAc,OAAO,wBACrB,WAAW,wBACV;EAgBH,UAAU,cAAc,QAAQ;;;;;;;;;iBAcjB;SAER,KAAK,aAAa,UAAU,+BAA+B,QAAQ;SAgBnE;iBAMc;iBA4BA;;;iBA6BP"}

package/dist/NormalMapLoader.js

@@ -1,129 +1,132 @@
-import { Loader, TextureLoader } from "three";
-import {
-  devtimeWarn as sharedDevtimeWarn,
-  _resetDevtimeWarnings as sharedResetDevtimeWarnings,
-  hashDescriptor
-} from "@three-flatland/bake";
 import { bakedNormalURL } from "./bake.js";
-class NormalMapLoader extends Loader {
-  /**
-   * Generate this asset's normal map in the browser on every load
-   * instead of loading a pre-baked `.normal.png` sidecar. With a
-   * `descriptor`, the in-memory bake runs on every load. Without a
-   * descriptor, the loader resolves directly to `null` and the caller
-   * uses the TSL runtime fallback. Suppresses the "no baked sibling"
-   * warn either way.
-   *
-   * Use when runtime is the right home for the bake. Not a dev-iteration
-   * knob — the default path (probe → bake on miss + warn) already
-   * handles iteration. See {@link BakedAssetLoaderOptions.forceRuntime}.
-   */
-  forceRuntime = false;
-  /**
-   * When set, missing sidecars trigger an in-memory bake via
-   * `resolveNormalMap`. Without a descriptor, the loader can only probe
-   * the baked sibling and returns `null` on miss (legacy behavior).
-   *
-   * Set via the `useLoader` callback:
-   * ```ts
-   * useLoader(NormalMapLoader, url, undefined, (l) => { l.descriptor = desc })
-   * ```
-   */
-  descriptor = void 0;
-  constructor(manager) {
-    super(manager);
-  }
-  // ─── Instance API (R3F useLoader compatibility) ───
-  load(url, onLoad, onProgress, onError) {
-    const resolved = this.manager.resolveURL(url);
-    NormalMapLoader._loadImpl(resolved, this.forceRuntime, this.descriptor).then((result) => {
-      onLoad?.(result);
-    }).catch((err) => {
-      if (onError) onError(err);
-      else console.error("NormalMapLoader:", err);
-      this.manager.itemError(url);
-    });
-    return null;
-  }
-  loadAsync(url) {
-    return NormalMapLoader._loadImpl(
-      this.manager.resolveURL(url),
-      this.forceRuntime,
-      this.descriptor
-    );
-  }
-  // ─── Static API (vanilla usage) ───
-  /**
-   * Vanilla cache: keyed by `(url, forceRuntime, descriptor hash)` so
-   * two callers passing *different* descriptors for the same URL get
-   * distinct results instead of colliding on the first one's bake.
-   *
-   * Instance API (R3F `useLoader`) bypasses this map — R3F has its own
-   * suspense cache and we don't want double-caching to fight the lifecycle.
-   */
-  static _cache = /* @__PURE__ */ new Map();
-  static load(url, options) {
-    const forceRuntime = options?.forceRuntime ?? false;
-    const descriptor = options?.descriptor;
-    const descriptorKey = descriptor ? hashDescriptor(descriptor) : "nodesc";
-    const cacheKey = `${url}:${forceRuntime ? "runtime" : "probe"}:${descriptorKey}`;
-    const cached = this._cache.get(cacheKey);
-    if (cached) return cached;
-    const promise = this._loadImpl(url, forceRuntime, descriptor);
-    this._cache.set(cacheKey, promise);
-    return promise;
-  }
-  static clearCache() {
-    this._cache.clear();
-  }
-  // ─── Implementation ───
-  static async _loadImpl(url, forceRuntime, descriptor) {
-    if (descriptor) {
-      const { resolveNormalMap } = await import("./resolveNormalMap.js");
-      return resolveNormalMap(url, descriptor, { forceRuntime });
-    }
-    if (!forceRuntime) {
-      const baked = await this._tryLoadBaked(url);
-      if (baked) return baked;
-    }
-    sharedDevtimeWarn(
-      "normal",
-      url,
-      `No baked normal sibling for ${url} and no descriptor passed. Either pre-bake (\`npx flatland-bake normal\`), pass a \`descriptor\` to NormalMapLoader.load() for in-memory bake, or use SpriteSheetLoader/LDtkLoader with \`normals: true\` (which synthesizes a descriptor for you).`
-    );
-    return null;
-  }
-  static async _tryLoadBaked(spriteURL) {
-    const bakedURL = bakedNormalURL(spriteURL);
-    let head;
-    try {
-      head = await fetch(bakedURL, { method: "HEAD" });
-    } catch {
-      return null;
-    }
-    if (!head.ok) return null;
-    return new Promise((resolve, _reject) => {
-      const loader = new TextureLoader();
-      loader.load(
-        bakedURL,
-        (tex) => resolve(tex),
-        void 0,
-        (err) => {
-          console.warn(
-            `[normal] Found ${bakedURL} via HEAD but TextureLoader failed \u2014 falling back to runtime.`,
-            err
-          );
-          resolve(null);
-        }
-      );
-    });
-  }
-}
+import { Loader, TextureLoader } from "three";
+import { _resetDevtimeWarnings as _resetDevtimeWarnings$1, devtimeWarn, hashDescriptor } from "@three-flatland/bake";
+//#region src/NormalMapLoader.ts
+/**
+* Loader for per-sprite normal maps following the canonical three-flatland
+* "try baked → fall back to runtime" pattern documented in
+* `planning/bake/loader-pattern.md`.
+*
+* Given a sprite PNG URL, this loader fetches the sibling `.normal.png` that
+* `flatland-bake normal` produces. If it is absent, the loader resolves to
+* `null` so the lit material can switch to its TSL runtime fallback.
+*
+* Only the baked path uses the network — the runtime branch is a shader
+* concern and lives in `@three-flatland/nodes/lighting/normalFromSprite`.
+*
+* @example
+* ```ts
+* // Vanilla static API
+* const normalTex = await NormalMapLoader.load('/sprites/knight.png')
+* if (normalTex) material.normalMap = normalTex
+* else material.useRuntimeNormals = true
+*
+* // Skip the baked probe — go straight to runtime (or null without descriptor)
+* const tex = await NormalMapLoader.load(url, { forceRuntime: true })
+*
+* // R3F useLoader
+* const tex = useLoader(NormalMapLoader, '/sprites/knight.png')
+* ```
+*/
+var NormalMapLoader = class NormalMapLoader extends Loader {
+	/**
+	* Generate this asset's normal map in the browser on every load
+	* instead of loading a pre-baked `.normal.png` sidecar. With a
+	* `descriptor`, the in-memory bake runs on every load. Without a
+	* descriptor, the loader resolves directly to `null` and the caller
+	* uses the TSL runtime fallback. Suppresses the "no baked sibling"
+	* warn either way.
+	*
+	* Use when runtime is the right home for the bake. Not a dev-iteration
+	* knob — the default path (probe → bake on miss + warn) already
+	* handles iteration. See {@link BakedAssetLoaderOptions.forceRuntime}.
+	*/
+	forceRuntime = false;
+	/**
+	* When set, missing sidecars trigger an in-memory bake via
+	* `resolveNormalMap`. Without a descriptor, the loader can only probe
+	* the baked sibling and returns `null` on miss (legacy behavior).
+	*
+	* Set via the `useLoader` callback:
+	* ```ts
+	* useLoader(NormalMapLoader, url, undefined, (l) => { l.descriptor = desc })
+	* ```
+	*/
+	descriptor = void 0;
+	constructor(manager) {
+		super(manager);
+	}
+	load(url, onLoad, onProgress, onError) {
+		const resolved = this.manager.resolveURL(url);
+		NormalMapLoader._loadImpl(resolved, this.forceRuntime, this.descriptor).then((result) => {
+			onLoad?.(result);
+		}).catch((err) => {
+			if (onError) onError(err);
+			else console.error("NormalMapLoader:", err);
+			this.manager.itemError(url);
+		});
+		return null;
+	}
+	loadAsync(url) {
+		return NormalMapLoader._loadImpl(this.manager.resolveURL(url), this.forceRuntime, this.descriptor);
+	}
+	/**
+	* Vanilla cache: keyed by `(url, forceRuntime, descriptor hash)` so
+	* two callers passing *different* descriptors for the same URL get
+	* distinct results instead of colliding on the first one's bake.
+	*
+	* Instance API (R3F `useLoader`) bypasses this map — R3F has its own
+	* suspense cache and we don't want double-caching to fight the lifecycle.
+	*/
+	static _cache = /* @__PURE__ */ new Map();
+	static load(url, options) {
+		const forceRuntime = options?.forceRuntime ?? false;
+		const descriptor = options?.descriptor;
+		const descriptorKey = descriptor ? hashDescriptor(descriptor) : "nodesc";
+		const cacheKey = `${url}:${forceRuntime ? "runtime" : "probe"}:${descriptorKey}`;
+		const cached = this._cache.get(cacheKey);
+		if (cached) return cached;
+		const promise = this._loadImpl(url, forceRuntime, descriptor);
+		this._cache.set(cacheKey, promise);
+		return promise;
+	}
+	static clearCache() {
+		this._cache.clear();
+	}
+	static async _loadImpl(url, forceRuntime, descriptor) {
+		if (descriptor) {
+			const { resolveNormalMap } = await import("./resolveNormalMap.js");
+			return resolveNormalMap(url, descriptor, { forceRuntime });
+		}
+		if (!forceRuntime) {
+			const baked = await this._tryLoadBaked(url);
+			if (baked) return baked;
+		}
+		devtimeWarn("normal", url, `No baked normal sibling for ${url} and no descriptor passed. Either pre-bake (\`npx flatland-bake normal\`), pass a \`descriptor\` to NormalMapLoader.load() for in-memory bake, or use SpriteSheetLoader/LDtkLoader with \`normals: true\` (which synthesizes a descriptor for you).`);
+		return null;
+	}
+	static async _tryLoadBaked(spriteURL) {
+		const bakedURL = bakedNormalURL(spriteURL);
+		let head;
+		try {
+			head = await fetch(bakedURL, { method: "HEAD" });
+		} catch {
+			return null;
+		}
+		if (!head.ok) return null;
+		return new Promise((resolve, _reject) => {
+			new TextureLoader().load(bakedURL, (tex) => resolve(tex), void 0, (err) => {
+				console.warn(`[normal] Found ${bakedURL} via HEAD but TextureLoader failed — falling back to runtime.`, err);
+				resolve(null);
+			});
+		});
+	}
+};
+/** Clear the devtime-warning dedupe set. Intended for tests. */
 function _resetDevtimeWarnings() {
-  sharedResetDevtimeWarnings();
+	_resetDevtimeWarnings$1();
 }
-export {
-  NormalMapLoader,
-  _resetDevtimeWarnings
-};
+//#endregion
+export { NormalMapLoader, _resetDevtimeWarnings };
+
 //# sourceMappingURL=NormalMapLoader.js.map

package/dist/NormalMapLoader.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/NormalMapLoader.ts"],"sourcesContent":["import { Loader, type LoadingManager, TextureLoader, type Texture } from 'three'\nimport {\n  devtimeWarn as sharedDevtimeWarn,\n  _resetDevtimeWarnings as sharedResetDevtimeWarnings,\n  hashDescriptor,\n  type BakedAssetLoaderOptions,\n} from '@three-flatland/bake'\nimport { bakedNormalURL } from './bake.js'\nimport type { NormalSourceDescriptor } from './descriptor.js'\n\n/**\n * Options accepted by `NormalMapLoader.load()`. Inherits `forceRuntime`\n * from the shared {@link BakedAssetLoaderOptions} so every baked-asset\n * loader in the codebase advertises the same option shape.\n */\nexport interface NormalMapLoaderStaticOptions extends BakedAssetLoaderOptions {\n  /**\n   * When provided, missing sidecars trigger an in-memory bake via\n   * `resolveNormalMap`. Without a descriptor, `NormalMapLoader.load()` can\n   * only probe the baked sibling and returns `null` on miss (legacy\n   * behavior, preserved for backward compat).\n   */\n  descriptor?: NormalSourceDescriptor\n}\n\n/**\n * Result of loading a sprite's normal data.\n *\n * Either a baked normal texture (fast path) or `null`, signalling the caller\n * to use the runtime TSL `normalFromSprite` helper against the sprite's own\n * alpha channel.\n */\nexport type NormalMapResult = Texture | null\n\n/**\n * Loader for per-sprite normal maps following the canonical three-flatland\n * \"try baked → fall back to runtime\" pattern documented in\n * `planning/bake/loader-pattern.md`.\n *\n * Given a sprite PNG URL, this loader fetches the sibling `.normal.png` that\n * `flatland-bake normal` produces. If it is absent, the loader resolves to\n * `null` so the lit material can switch to its TSL runtime fallback.\n *\n * Only the baked path uses the network — the runtime branch is a shader\n * concern and lives in `@three-flatland/nodes/lighting/normalFromSprite`.\n *\n * @example\n * ```ts\n * // Vanilla static API\n * const normalTex = await NormalMapLoader.load('/sprites/knight.png')\n * if (normalTex) material.normalMap = normalTex\n * else material.useRuntimeNormals = true\n *\n * // Skip the baked probe — go straight to runtime (or null without descriptor)\n * const tex = await NormalMapLoader.load(url, { forceRuntime: true })\n *\n * // R3F useLoader\n * const tex = useLoader(NormalMapLoader, '/sprites/knight.png')\n * ```\n */\nexport class NormalMapLoader extends Loader<NormalMapResult> {\n  /**\n   * Generate this asset's normal map in the browser on every load\n   * instead of loading a pre-baked `.normal.png` sidecar. With a\n   * `descriptor`, the in-memory bake runs on every load. Without a\n   * descriptor, the loader resolves directly to `null` and the caller\n   * uses the TSL runtime fallback. Suppresses the \"no baked sibling\"\n   * warn either way.\n   *\n   * Use when runtime is the right home for the bake. Not a dev-iteration\n   * knob — the default path (probe → bake on miss + warn) already\n   * handles iteration. See {@link BakedAssetLoaderOptions.forceRuntime}.\n   */\n  forceRuntime = false\n  /**\n   * When set, missing sidecars trigger an in-memory bake via\n   * `resolveNormalMap`. Without a descriptor, the loader can only probe\n   * the baked sibling and returns `null` on miss (legacy behavior).\n   *\n   * Set via the `useLoader` callback:\n   * ```ts\n   * useLoader(NormalMapLoader, url, undefined, (l) => { l.descriptor = desc })\n   * ```\n   */\n  descriptor: NormalSourceDescriptor | undefined = undefined\n\n  constructor(manager?: LoadingManager) {\n    super(manager)\n  }\n\n  // ─── Instance API (R3F useLoader compatibility) ───\n\n  load(\n    url: string,\n    onLoad?: (data: NormalMapResult) => void,\n    onProgress?: (event: ProgressEvent) => void,\n    onError?: (err: unknown) => void\n  ): NormalMapResult {\n    const resolved = this.manager.resolveURL(url)\n\n    NormalMapLoader._loadImpl(resolved, this.forceRuntime, this.descriptor)\n      .then((result) => {\n        onLoad?.(result)\n      })\n      .catch((err) => {\n        if (onError) onError(err)\n        else console.error('NormalMapLoader:', err)\n        this.manager.itemError(url)\n      })\n\n    return null\n  }\n\n  loadAsync(url: string): Promise<NormalMapResult> {\n    return NormalMapLoader._loadImpl(\n      this.manager.resolveURL(url),\n      this.forceRuntime,\n      this.descriptor\n    )\n  }\n\n  // ─── Static API (vanilla usage) ───\n\n  /**\n   * Vanilla cache: keyed by `(url, forceRuntime, descriptor hash)` so\n   * two callers passing *different* descriptors for the same URL get\n   * distinct results instead of colliding on the first one's bake.\n   *\n   * Instance API (R3F `useLoader`) bypasses this map — R3F has its own\n   * suspense cache and we don't want double-caching to fight the lifecycle.\n   */\n  private static _cache = new Map<string, Promise<NormalMapResult>>()\n\n  static load(\n    url: string,\n    options?: NormalMapLoaderStaticOptions\n  ): Promise<NormalMapResult> {\n    const forceRuntime = options?.forceRuntime ?? false\n    const descriptor = options?.descriptor\n    // Hash the descriptor so distinct descriptors for the same URL get\n    // distinct cache entries. `descriptor ? 'desc' : 'nodesc'` would have\n    // collapsed every (URL, *) pair into one slot — first-bake-wins.\n    const descriptorKey = descriptor ? hashDescriptor(descriptor) : 'nodesc'\n    const cacheKey = `${url}:${forceRuntime ? 'runtime' : 'probe'}:${descriptorKey}`\n    const cached = this._cache.get(cacheKey)\n    if (cached) return cached\n\n    const promise = this._loadImpl(url, forceRuntime, descriptor)\n    this._cache.set(cacheKey, promise)\n    return promise\n  }\n\n  static clearCache(): void {\n    this._cache.clear()\n  }\n\n  // ─── Implementation ───\n\n  private static async _loadImpl(\n    url: string,\n    forceRuntime: boolean,\n    descriptor: NormalSourceDescriptor | undefined\n  ): Promise<NormalMapResult> {\n    // With a descriptor we can do the full resolve: try baked → in-memory bake.\n    if (descriptor) {\n      const { resolveNormalMap } = await import('./resolveNormalMap.js')\n      return resolveNormalMap(url, descriptor, { forceRuntime })\n    }\n\n    // No descriptor → legacy URL-only behavior: probe sidecar, return null on miss.\n    if (!forceRuntime) {\n      const baked = await this._tryLoadBaked(url)\n      if (baked) return baked\n    }\n\n    sharedDevtimeWarn(\n      'normal',\n      url,\n      `No baked normal sibling for ${url} and no descriptor passed. ` +\n        `Either pre-bake (\\`npx flatland-bake normal\\`), pass a \\`descriptor\\` to ` +\n        `NormalMapLoader.load() for in-memory bake, or use SpriteSheetLoader/LDtkLoader ` +\n        `with \\`normals: true\\` (which synthesizes a descriptor for you).`\n    )\n    return null\n  }\n\n  private static async _tryLoadBaked(spriteURL: string): Promise<Texture | null> {\n    const bakedURL = bakedNormalURL(spriteURL)\n\n    // Probe with HEAD first so a 404 stays silent. TextureLoader swallows\n    // network errors into a generic event, which is not what we want.\n    let head: Response\n    try {\n      head = await fetch(bakedURL, { method: 'HEAD' })\n    } catch {\n      return null\n    }\n    if (!head.ok) return null\n\n    return new Promise((resolve, _reject) => {\n      const loader = new TextureLoader()\n      loader.load(\n        bakedURL,\n        (tex) => resolve(tex as unknown as Texture),\n        undefined,\n        (err) => {\n          console.warn(\n            `[normal] Found ${bakedURL} via HEAD but TextureLoader failed — falling back to runtime.`,\n            err\n          )\n          resolve(null)\n        }\n      )\n    })\n  }\n}\n\n/** Clear the devtime-warning dedupe set. Intended for tests. */\nexport function _resetDevtimeWarnings(): void {\n  sharedResetDevtimeWarnings()\n}\n"],"mappings":"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","names":[]}
+{"version":3,"file":"NormalMapLoader.js","names":[],"sources":["../src/NormalMapLoader.ts"],"sourcesContent":["import { Loader, type LoadingManager, TextureLoader, type Texture } from 'three'\nimport {\n  devtimeWarn as sharedDevtimeWarn,\n  _resetDevtimeWarnings as sharedResetDevtimeWarnings,\n  hashDescriptor,\n  type BakedAssetLoaderOptions,\n} from '@three-flatland/bake'\nimport { bakedNormalURL } from './bake.js'\nimport type { NormalSourceDescriptor } from './descriptor.js'\n\n/**\n * Options accepted by `NormalMapLoader.load()`. Inherits `forceRuntime`\n * from the shared {@link BakedAssetLoaderOptions} so every baked-asset\n * loader in the codebase advertises the same option shape.\n */\nexport interface NormalMapLoaderStaticOptions extends BakedAssetLoaderOptions {\n  /**\n   * When provided, missing sidecars trigger an in-memory bake via\n   * `resolveNormalMap`. Without a descriptor, `NormalMapLoader.load()` can\n   * only probe the baked sibling and returns `null` on miss (legacy\n   * behavior, preserved for backward compat).\n   */\n  descriptor?: NormalSourceDescriptor\n}\n\n/**\n * Result of loading a sprite's normal data.\n *\n * Either a baked normal texture (fast path) or `null`, signalling the caller\n * to use the runtime TSL `normalFromSprite` helper against the sprite's own\n * alpha channel.\n */\nexport type NormalMapResult = Texture | null\n\n/**\n * Loader for per-sprite normal maps following the canonical three-flatland\n * \"try baked → fall back to runtime\" pattern documented in\n * `planning/bake/loader-pattern.md`.\n *\n * Given a sprite PNG URL, this loader fetches the sibling `.normal.png` that\n * `flatland-bake normal` produces. If it is absent, the loader resolves to\n * `null` so the lit material can switch to its TSL runtime fallback.\n *\n * Only the baked path uses the network — the runtime branch is a shader\n * concern and lives in `@three-flatland/nodes/lighting/normalFromSprite`.\n *\n * @example\n * ```ts\n * // Vanilla static API\n * const normalTex = await NormalMapLoader.load('/sprites/knight.png')\n * if (normalTex) material.normalMap = normalTex\n * else material.useRuntimeNormals = true\n *\n * // Skip the baked probe — go straight to runtime (or null without descriptor)\n * const tex = await NormalMapLoader.load(url, { forceRuntime: true })\n *\n * // R3F useLoader\n * const tex = useLoader(NormalMapLoader, '/sprites/knight.png')\n * ```\n */\nexport class NormalMapLoader extends Loader<NormalMapResult> {\n  /**\n   * Generate this asset's normal map in the browser on every load\n   * instead of loading a pre-baked `.normal.png` sidecar. With a\n   * `descriptor`, the in-memory bake runs on every load. Without a\n   * descriptor, the loader resolves directly to `null` and the caller\n   * uses the TSL runtime fallback. Suppresses the \"no baked sibling\"\n   * warn either way.\n   *\n   * Use when runtime is the right home for the bake. Not a dev-iteration\n   * knob — the default path (probe → bake on miss + warn) already\n   * handles iteration. See {@link BakedAssetLoaderOptions.forceRuntime}.\n   */\n  forceRuntime = false\n  /**\n   * When set, missing sidecars trigger an in-memory bake via\n   * `resolveNormalMap`. Without a descriptor, the loader can only probe\n   * the baked sibling and returns `null` on miss (legacy behavior).\n   *\n   * Set via the `useLoader` callback:\n   * ```ts\n   * useLoader(NormalMapLoader, url, undefined, (l) => { l.descriptor = desc })\n   * ```\n   */\n  descriptor: NormalSourceDescriptor | undefined = undefined\n\n  constructor(manager?: LoadingManager) {\n    super(manager)\n  }\n\n  // ─── Instance API (R3F useLoader compatibility) ───\n\n  load(\n    url: string,\n    onLoad?: (data: NormalMapResult) => void,\n    onProgress?: (event: ProgressEvent) => void,\n    onError?: (err: unknown) => void\n  ): NormalMapResult {\n    const resolved = this.manager.resolveURL(url)\n\n    NormalMapLoader._loadImpl(resolved, this.forceRuntime, this.descriptor)\n      .then((result) => {\n        onLoad?.(result)\n      })\n      .catch((err) => {\n        if (onError) onError(err)\n        else console.error('NormalMapLoader:', err)\n        this.manager.itemError(url)\n      })\n\n    return null\n  }\n\n  loadAsync(url: string): Promise<NormalMapResult> {\n    return NormalMapLoader._loadImpl(this.manager.resolveURL(url), this.forceRuntime, this.descriptor)\n  }\n\n  // ─── Static API (vanilla usage) ───\n\n  /**\n   * Vanilla cache: keyed by `(url, forceRuntime, descriptor hash)` so\n   * two callers passing *different* descriptors for the same URL get\n   * distinct results instead of colliding on the first one's bake.\n   *\n   * Instance API (R3F `useLoader`) bypasses this map — R3F has its own\n   * suspense cache and we don't want double-caching to fight the lifecycle.\n   */\n  private static _cache = new Map<string, Promise<NormalMapResult>>()\n\n  static load(url: string, options?: NormalMapLoaderStaticOptions): Promise<NormalMapResult> {\n    const forceRuntime = options?.forceRuntime ?? false\n    const descriptor = options?.descriptor\n    // Hash the descriptor so distinct descriptors for the same URL get\n    // distinct cache entries. `descriptor ? 'desc' : 'nodesc'` would have\n    // collapsed every (URL, *) pair into one slot — first-bake-wins.\n    const descriptorKey = descriptor ? hashDescriptor(descriptor) : 'nodesc'\n    const cacheKey = `${url}:${forceRuntime ? 'runtime' : 'probe'}:${descriptorKey}`\n    const cached = this._cache.get(cacheKey)\n    if (cached) return cached\n\n    const promise = this._loadImpl(url, forceRuntime, descriptor)\n    this._cache.set(cacheKey, promise)\n    return promise\n  }\n\n  static clearCache(): void {\n    this._cache.clear()\n  }\n\n  // ─── Implementation ───\n\n  private static async _loadImpl(\n    url: string,\n    forceRuntime: boolean,\n    descriptor: NormalSourceDescriptor | undefined\n  ): Promise<NormalMapResult> {\n    // With a descriptor we can do the full resolve: try baked → in-memory bake.\n    if (descriptor) {\n      const { resolveNormalMap } = await import('./resolveNormalMap.js')\n      return resolveNormalMap(url, descriptor, { forceRuntime })\n    }\n\n    // No descriptor → legacy URL-only behavior: probe sidecar, return null on miss.\n    if (!forceRuntime) {\n      const baked = await this._tryLoadBaked(url)\n      if (baked) return baked\n    }\n\n    sharedDevtimeWarn(\n      'normal',\n      url,\n      `No baked normal sibling for ${url} and no descriptor passed. ` +\n        `Either pre-bake (\\`npx flatland-bake normal\\`), pass a \\`descriptor\\` to ` +\n        `NormalMapLoader.load() for in-memory bake, or use SpriteSheetLoader/LDtkLoader ` +\n        `with \\`normals: true\\` (which synthesizes a descriptor for you).`\n    )\n    return null\n  }\n\n  private static async _tryLoadBaked(spriteURL: string): Promise<Texture | null> {\n    const bakedURL = bakedNormalURL(spriteURL)\n\n    // Probe with HEAD first so a 404 stays silent. TextureLoader swallows\n    // network errors into a generic event, which is not what we want.\n    let head: Response\n    try {\n      head = await fetch(bakedURL, { method: 'HEAD' })\n    } catch {\n      return null\n    }\n    if (!head.ok) return null\n\n    return new Promise((resolve, _reject) => {\n      const loader = new TextureLoader()\n      loader.load(\n        bakedURL,\n        (tex) => resolve(tex as unknown as Texture),\n        undefined,\n        (err) => {\n          console.warn(`[normal] Found ${bakedURL} via HEAD but TextureLoader failed — falling back to runtime.`, err)\n          resolve(null)\n        }\n      )\n    })\n  }\n}\n\n/** Clear the devtime-warning dedupe set. Intended for tests. */\nexport function _resetDevtimeWarnings(): void {\n  sharedResetDevtimeWarnings()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,IAAa,kBAAb,MAAa,wBAAwB,OAAwB;;;;;;;;;;;;;CAa3D,eAAe;;;;;;;;;;;CAWf,aAAiD,KAAA;CAEjD,YAAY,SAA0B;EACpC,MAAM,OAAO;CACf;CAIA,KACE,KACA,QACA,YACA,SACiB;EACjB,MAAM,WAAW,KAAK,QAAQ,WAAW,GAAG;EAE5C,gBAAgB,UAAU,UAAU,KAAK,cAAc,KAAK,UAAU,CAAC,CACpE,MAAM,WAAW;GAChB,SAAS,MAAM;EACjB,CAAC,CAAC,CACD,OAAO,QAAQ;GACd,IAAI,SAAS,QAAQ,GAAG;QACnB,QAAQ,MAAM,oBAAoB,GAAG;GAC1C,KAAK,QAAQ,UAAU,GAAG;EAC5B,CAAC;EAEH,OAAO;CACT;CAEA,UAAU,KAAuC;EAC/C,OAAO,gBAAgB,UAAU,KAAK,QAAQ,WAAW,GAAG,GAAG,KAAK,cAAc,KAAK,UAAU;CACnG;;;;;;;;;CAYA,OAAe,yBAAS,IAAI,IAAsC;CAElE,OAAO,KAAK,KAAa,SAAkE;EACzF,MAAM,eAAe,SAAS,gBAAgB;EAC9C,MAAM,aAAa,SAAS;EAI5B,MAAM,gBAAgB,aAAa,eAAe,UAAU,IAAI;EAChE,MAAM,WAAW,GAAG,IAAI,GAAG,eAAe,YAAY,QAAQ,GAAG;EACjE,MAAM,SAAS,KAAK,OAAO,IAAI,QAAQ;EACvC,IAAI,QAAQ,OAAO;EAEnB,MAAM,UAAU,KAAK,UAAU,KAAK,cAAc,UAAU;EAC5D,KAAK,OAAO,IAAI,UAAU,OAAO;EACjC,OAAO;CACT;CAEA,OAAO,aAAmB;EACxB,KAAK,OAAO,MAAM;CACpB;CAIA,aAAqB,UACnB,KACA,cACA,YAC0B;EAE1B,IAAI,YAAY;GACd,MAAM,EAAE,qBAAqB,MAAM,OAAO;GAC1C,OAAO,iBAAiB,KAAK,YAAY,EAAE,aAAa,CAAC;EAC3D;EAGA,IAAI,CAAC,cAAc;GACjB,MAAM,QAAQ,MAAM,KAAK,cAAc,GAAG;GAC1C,IAAI,OAAO,OAAO;EACpB;EAEA,YACE,UACA,KACA,+BAA+B,IAAI,oPAIrC;EACA,OAAO;CACT;CAEA,aAAqB,cAAc,WAA4C;EAC7E,MAAM,WAAW,eAAe,SAAS;EAIzC,IAAI;EACJ,IAAI;GACF,OAAO,MAAM,MAAM,UAAU,EAAE,QAAQ,OAAO,CAAC;EACjD,QAAQ;GACN,OAAO;EACT;EACA,IAAI,CAAC,KAAK,IAAI,OAAO;EAErB,OAAO,IAAI,SAAS,SAAS,YAAY;GAEvC,IADmB,cACd,CAAC,CAAC,KACL,WACC,QAAQ,QAAQ,GAAyB,GAC1C,KAAA,IACC,QAAQ;IACP,QAAQ,KAAK,kBAAkB,SAAS,gEAAgE,GAAG;IAC3G,QAAQ,IAAI;GACd,CACF;EACF,CAAC;CACH;AACF;;AAGA,SAAgB,wBAA8B;CAC5C,wBAA2B;AAC7B"}

package/dist/bake.d.ts

@@ -0,0 +1,57 @@
+import { NormalSourceDescriptor } from "./descriptor.js";
+//#region src/bake.d.ts
+/**
+ * @deprecated — legacy flat-texture bake options. Use
+ * `bakeNormalMap(pixels, w, h, descriptor)` for region-aware control.
+ */
+interface BakeOptions {
+  /** Scales the alpha gradient before normalization. Default 1. */
+  strength?: number;
+}
+/**
+ * Produce a tangent-space normal map from source pixels + a descriptor.
+ *
+ * Cross-platform: browser + node. No filesystem, no pngjs. Used by
+ * the CLI baker (wrapped with file I/O) and the runtime loader
+ * (called directly on decoded image pixels).
+ *
+ * Per texel in each region:
+ *   1. `bump: 'alpha'` — central-difference gradient on the source
+ *      alpha channel, clamped to the region bounds so adjacent regions
+ *      (e.g. atlas cells) can't bleed into each other.
+ *   2. Compose with a tilt rotation that takes `+Z` to the region's
+ *      `direction` at `pitch` radians.
+ *   3. Normalize and encode to `rgb = normal * 0.5 + 0.5`. Alpha is
+ *      copied from the source so the baked map carries its own
+ *      silhouette.
+ *
+ * Texels outside every region receive the flat normal `(0, 0, 1)`
+ * with the source's alpha — safe default for sparse descriptors.
+ *
+ * @param pixels    RGBA pixel buffer, row-major, 4 bytes per pixel.
+ * @param width     Pixel width.
+ * @param height    Pixel height.
+ * @param descriptor Region / tilt / bump control. Defaults to a single
+ *                   whole-texture flat region with alpha-derived bump.
+ * @returns RGBA pixel buffer containing the encoded normal map.
+ */
+declare function bakeNormalMap(pixels: Uint8Array, width: number, height: number, descriptor?: NormalSourceDescriptor): Uint8Array;
+/**
+ * Legacy back-compat wrapper. Use `bakeNormalMap(pixels, w, h, {
+ * strength })` for equivalent behavior in new code.
+ *
+ * @deprecated
+ */
+declare function bakeNormalMapFromPixels(pixels: Uint8Array, width: number, height: number, options?: BakeOptions): Uint8Array;
+/**
+ * Derive the conventional `.normal.png` sibling URL for a sprite PNG.
+ *
+ * Runtime loaders call this to try the baked output before falling
+ * back to the runtime TSL path.
+ *
+ * Pure string rewrite — browser-safe, no filesystem.
+ */
+declare function bakedNormalURL(spriteURL: string): string;
+//#endregion
+export { BakeOptions, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL };
+//# sourceMappingURL=bake.d.ts.map

package/dist/bake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake.d.ts","names":[],"sources":["../src/bake.ts"],"mappings":";;;;;;UAaiB;;EAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Bc,cACd,QAAQ,YACR,eACA,gBACA,aAAY,yBACX;;;;;;;iBAmKa,wBACd,QAAQ,YACR,eACA,gBACA,UAAS,cACR;;;;;;;;;iBAiBa,eAAe"}