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

package/dist/index.d.ts

@@ -1,320 +1,5 @@
-import { Loader, Texture, LoadingManager } from 'three';
-import { BakedAssetLoaderOptions } from '@three-flatland/bake';
-
-/**
- * Normal source descriptor — the shared shape used across three
- * surfaces:
- *
- *   1. Library API   `bakeNormalMap(pixels, w, h, descriptor)`
- *   2. CLI           `flatland-bake normal --descriptor <file>`
- *   3. Loader API    `LDtkLoader.load(url, { normals: descriptor })`
- *
- * The descriptor carries enough information for the baker to emit a
- * 1:1 co-registered normal map: where the regions live, how each
- * region tilts, and what per-texel bump source to use.
- *
- * All types are pure and browser-safe — consumed identically by node
- * bakers and browser runtime loaders.
- */
-/**
- * Screen-relative direction the surface normal's XY component points.
- *
- * Mental model: imagine the baked normal as an arrow. `NormalDirection`
- * is the screen-space direction that arrow tilts toward — equivalently,
- * the direction the tile's visible face is "pointing." For a wall at
- * the top of the map (visible face toward the camera below), that's
- * `'south'` / `'down'`.
- *
- * Cardinal and compass aliases are equivalent; the canonical form in
- * the codebase is NSEW. Numbers are interpreted as radians in standard
- * math convention (0 = +X / right, CCW positive).
- */
-type NormalDirection = 'flat' | 'up' | 'north' | 'down' | 'south' | 'left' | 'west' | 'right' | 'east' | 'up-left' | 'north-west' | 'up-right' | 'north-east' | 'down-left' | 'south-west' | 'down-right' | 'south-east' | number;
-/**
- * Resolve a `NormalDirection` to an angle in radians, or `null` when
- * the direction is `'flat'` (no tilt).
- *
- * Convention: 0 = +X / right, π/2 = +Y / up, π = -X / left,
- * -π/2 = -Y / down. Matches `Math.atan2` output.
- */
-declare function directionToAngle(direction: NormalDirection | undefined): number | null;
-/**
- * Per-texel bump source inside a region. Each non-'none' mode runs a
- * central-difference gradient on the named channel; the result is
- * treated as a height field where high values are raised and low
- * values are sunken. Negative `strength` inverts (dark = raised).
- *
- * - `'alpha'` — gradient on the source alpha channel (default).
- *   Preserves sprite silhouette edges — the classic path for
- *   transparent sprites. Solid opaque regions produce no bump.
- * - `'luminance'` — gradient on Rec. 709 luminance `(0.2126·R +
- *   0.7152·G + 0.0722·B)`. Brick faces read as raised; dark mortar
- *   lines read as sunken grooves. Right mode for solid opaque
- *   tilesets.
- * - `'red'` / `'green'` / `'blue'` — gradient on a single color
- *   channel. Use when your art treats one channel as a height map
- *   (e.g., packing height into the red channel of a data texture).
- * - `'none'` — flat fill at the region's tilt direction. No per-texel
- *   variation; cheapest and useful for uniform surfaces.
- */
-type NormalBump = 'alpha' | 'luminance' | 'red' | 'green' | 'blue' | 'none';
-interface NormalRegion {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    /** Per-texel bump source. Default inherits from descriptor (`'alpha'`). */
-    bump?: NormalBump;
-    /** Base tilt direction. Default inherits from descriptor (`'flat'`). */
-    direction?: NormalDirection;
-    /**
-     * Tilt angle in radians from flat. Ignored when `direction === 'flat'`.
-     * Default inherits from descriptor, which defaults to `Math.PI / 4`.
-     */
-    pitch?: number;
-    /** Gradient strength multiplier for this region. Default 1. */
-    strength?: number;
-    /**
-     * World-space elevation of the region in [0, 1], where 0 = ground
-     * plane (floor) and 1 = top-of-wall (cap). Baked into the normal
-     * atlas's B channel and consumed by the light pass to compute
-     * per-fragment light direction (`L.z = lightHeight − elevation`).
-     *
-     * Default inherits from the descriptor, which defaults to 0. Cap
-     * regions typically set 1; tilted face regions typically set 0.5.
-     */
-    elevation?: number;
-}
-interface NormalSourceDescriptor {
-    /** Reserved for future schema evolution. Currently always `1`. */
-    version?: 1;
-    /** Default bump source for regions that don't specify one. Default `'alpha'`. */
-    bump?: NormalBump;
-    /** Default tilt for regions that don't specify one. Default `'flat'`. */
-    direction?: NormalDirection;
-    /** Default tilt pitch in radians. Default `Math.PI / 4`. */
-    pitch?: number;
-    /** Default gradient strength. Default `1`. */
-    strength?: number;
-    /** Default elevation for regions that don't specify one. Default 0 (ground). */
-    elevation?: number;
-    /**
-     * Regions of the source texture. When omitted, the whole texture is
-     * treated as a single region inheriting all descriptor defaults.
-     */
-    regions?: NormalRegion[];
-}
-declare const DEFAULT_PITCH: number;
-declare const DEFAULT_STRENGTH = 1;
-declare const DEFAULT_BUMP: NormalBump;
-declare const DEFAULT_ELEVATION = 0;
-/**
- * Merge a region against its parent descriptor defaults. Returns a
- * fully-populated region suitable for direct consumption by the baker.
- */
-interface ResolvedNormalRegion {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    bump: NormalBump;
-    /** Tilt angle in radians, or `null` when the region is flat. */
-    angle: number | null;
-    pitch: number;
-    strength: number;
-    /** World-space elevation in [0, 1]. Written to the output B channel. */
-    elevation: number;
-}
-declare function resolveRegion(region: NormalRegion, descriptor?: NormalSourceDescriptor): ResolvedNormalRegion;
-
-/**
- * @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;
-
-/**
- * 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;
-}
-
-interface ResolveNormalMapOptions {
-    /**
-     * Generate this asset's normal map in the browser on every load
-     * instead of loading a pre-baked `.normal.png` sidecar. Fetches the
-     * source image, decodes its pixels, and runs `bakeNormalMap` in
-     * memory each time — no HEAD probe, no devtime "no baked sibling"
-     * warning.
-     *
-     * The returned data is always a valid normal map: this flag chooses
-     * *where* the bake happens (browser vs CI), not whether you get one.
-     *
-     * Use when runtime is the right home for the bake — 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 → bake on miss + warn) already handles that.
-     *
-     * Mirrors `SlugFontLoader.forceRuntime` and every other baked-asset
-     * loader in the codebase.
-     */
-    forceRuntime?: boolean;
-    /**
-     * Force the returned texture's `flipY` to this value. Pass the
-     * diffuse texture's `flipY` so the normal map samples 1:1 with the
-     * diffuse on the GPU regardless of whether the normal came from the
-     * image-loader path (default true) or the in-memory `DataTexture`
-     * path (default false).
-     */
-    flipY?: boolean;
-}
-/**
- * Resolve the normal map for an asset URL + descriptor.
- *
- * 1. Hash the descriptor.
- * 2. Probe the baked sibling `<source>.normal.png` (unless
- *    `forceRuntime`). If present and its stamped hash matches, load
- *    and return that texture directly.
- * 3. On miss (or stale hash), fetch the source, decode its pixels,
- *    lazy-import + run `bakeNormalMap` in memory, and wrap the result
- *    in a `DataTexture`. Runtime bake is the always-on fallback when
- *    normals were requested.
- *
- * Browser-only — uses `fetch`, `createImageBitmap`, `OffscreenCanvas`.
- * Safe to call from any Three.js loader runtime.
- */
-declare function resolveNormalMap(sourceURL: string, descriptor: NormalSourceDescriptor, options?: ResolveNormalMapOptions): Promise<Texture>;
-
-export { type BakeOptions, DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, type NormalBump, type NormalDirection, NormalMapLoader, type NormalMapResult, type NormalRegion, type NormalSourceDescriptor, type ResolveNormalMapOptions, type ResolvedNormalRegion, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion };
+import { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, NormalBump, NormalDirection, NormalRegion, NormalSourceDescriptor, ResolvedNormalRegion, directionToAngle, resolveRegion } from "./descriptor.js";
+import { NormalMapLoader, NormalMapResult } from "./NormalMapLoader.js";
+import { BakeOptions, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL } from "./bake.js";
+import { ResolveNormalMapOptions, resolveNormalMap } from "./resolveNormalMap.js";
+export { type BakeOptions, DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, type NormalBump, type NormalDirection, NormalMapLoader, type NormalMapResult, type NormalRegion, type NormalSourceDescriptor, type ResolveNormalMapOptions, type ResolvedNormalRegion, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion };

package/dist/index.js

@@ -1,33 +1,5 @@
-import {
-  bakeNormalMap,
-  bakeNormalMapFromPixels,
-  bakedNormalURL
-} from "./bake.js";
-import {
-  NormalMapLoader
-} from "./NormalMapLoader.js";
-import {
-  resolveNormalMap
-} from "./resolveNormalMap.js";
-import {
-  directionToAngle,
-  resolveRegion,
-  DEFAULT_PITCH,
-  DEFAULT_STRENGTH,
-  DEFAULT_BUMP,
-  DEFAULT_ELEVATION
-} from "./descriptor.js";
-export {
-  DEFAULT_BUMP,
-  DEFAULT_ELEVATION,
-  DEFAULT_PITCH,
-  DEFAULT_STRENGTH,
-  NormalMapLoader,
-  bakeNormalMap,
-  bakeNormalMapFromPixels,
-  bakedNormalURL,
-  directionToAngle,
-  resolveNormalMap,
-  resolveRegion
-};
-//# sourceMappingURL=index.js.map
+import { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, directionToAngle, resolveRegion } from "./descriptor.js";
+import { bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL } from "./bake.js";
+import { NormalMapLoader } from "./NormalMapLoader.js";
+import { resolveNormalMap } from "./resolveNormalMap.js";
+export { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, NormalMapLoader, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion };

package/dist/node.d.ts

@@ -1,21 +1,7 @@
-import { NormalSourceDescriptor, BakeOptions } from './index.js';
-export { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, NormalBump, NormalDirection, NormalMapLoader, NormalMapResult, NormalRegion, ResolveNormalMapOptions, ResolvedNormalRegion, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion } from './index.js';
-import 'three';
-import '@three-flatland/bake';
-
-/**
- * Bake a normal map from a PNG file on disk.
- *
- * Node-only wrapper around `bakeNormalMap` — handles file I/O and
- * stamps the output PNG with a `tEXt` chunk containing the descriptor
- * hash, so `probeBakedSibling` can invalidate stale outputs.
- *
- * Second argument accepts either:
- *   - A full `NormalSourceDescriptor` (region-aware).
- *   - A legacy `BakeOptions` (`{ strength }`) — for back-compat with
- *     existing callers; promoted to a zero-region descriptor.
- *   - A path to a descriptor JSON file.
- */
-declare function bakeNormalMapFile(inputPath: string, descriptorOrOptions?: NormalSourceDescriptor | BakeOptions | string, outputPath?: string): string;
-
-export { BakeOptions, NormalSourceDescriptor, bakeNormalMapFile };
+import { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, NormalBump, NormalDirection, NormalRegion, NormalSourceDescriptor, ResolvedNormalRegion, directionToAngle, resolveRegion } from "./descriptor.js";
+import { NormalMapLoader, NormalMapResult } from "./NormalMapLoader.js";
+import { BakeOptions, bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL } from "./bake.js";
+import { bakeNormalMapFile } from "./bake.node.js";
+import { ResolveNormalMapOptions, resolveNormalMap } from "./resolveNormalMap.js";
+import "./index.js";
+export { type BakeOptions, DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, type NormalBump, type NormalDirection, NormalMapLoader, type NormalMapResult, type NormalRegion, type NormalSourceDescriptor, type ResolveNormalMapOptions, type ResolvedNormalRegion, bakeNormalMap, bakeNormalMapFile, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion };

package/dist/node.js

@@ -1,6 +1,6 @@
-export * from "./index.js";
+import { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, directionToAngle, resolveRegion } from "./descriptor.js";
+import { bakeNormalMap, bakeNormalMapFromPixels, bakedNormalURL } from "./bake.js";
+import { NormalMapLoader } from "./NormalMapLoader.js";
 import { bakeNormalMapFile } from "./bake.node.js";
-export {
-  bakeNormalMapFile
-};
-//# sourceMappingURL=node.js.map
+import { resolveNormalMap } from "./resolveNormalMap.js";
+export { DEFAULT_BUMP, DEFAULT_ELEVATION, DEFAULT_PITCH, DEFAULT_STRENGTH, NormalMapLoader, bakeNormalMap, bakeNormalMapFile, bakeNormalMapFromPixels, bakedNormalURL, directionToAngle, resolveNormalMap, resolveRegion };

package/dist/resolveNormalMap.d.ts

@@ -0,0 +1,51 @@
+import { NormalSourceDescriptor } from "./descriptor.js";
+import { Texture } from "three";
+//#region src/resolveNormalMap.d.ts
+interface ResolveNormalMapOptions {
+  /**
+   * Generate this asset's normal map in the browser on every load
+   * instead of loading a pre-baked `.normal.png` sidecar. Fetches the
+   * source image, decodes its pixels, and runs `bakeNormalMap` in
+   * memory each time — no HEAD probe, no devtime "no baked sibling"
+   * warning.
+   *
+   * The returned data is always a valid normal map: this flag chooses
+   * *where* the bake happens (browser vs CI), not whether you get one.
+   *
+   * Use when runtime is the right home for the bake — 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 → bake on miss + warn) already handles that.
+   *
+   * Mirrors `SlugFontLoader.forceRuntime` and every other baked-asset
+   * loader in the codebase.
+   */
+  forceRuntime?: boolean;
+  /**
+   * Force the returned texture's `flipY` to this value. Pass the
+   * diffuse texture's `flipY` so the normal map samples 1:1 with the
+   * diffuse on the GPU regardless of whether the normal came from the
+   * image-loader path (default true) or the in-memory `DataTexture`
+   * path (default false).
+   */
+  flipY?: boolean;
+}
+/**
+ * Resolve the normal map for an asset URL + descriptor.
+ *
+ * 1. Hash the descriptor.
+ * 2. Probe the baked sibling `<source>.normal.png` (unless
+ *    `forceRuntime`). If present and its stamped hash matches, load
+ *    and return that texture directly.
+ * 3. On miss (or stale hash), fetch the source, decode its pixels,
+ *    lazy-import + run `bakeNormalMap` in memory, and wrap the result
+ *    in a `DataTexture`. Runtime bake is the always-on fallback when
+ *    normals were requested.
+ *
+ * Browser-only — uses `fetch`, `createImageBitmap`, `OffscreenCanvas`.
+ * Safe to call from any Three.js loader runtime.
+ */
+declare function resolveNormalMap(sourceURL: string, descriptor: NormalSourceDescriptor, options?: ResolveNormalMapOptions): Promise<Texture>;
+//#endregion
+export { ResolveNormalMapOptions, resolveNormalMap };
+//# sourceMappingURL=resolveNormalMap.d.ts.map

package/dist/resolveNormalMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNormalMap.d.ts","names":[],"sources":["../src/resolveNormalMap.ts"],"mappings":";;;UAIiB;;;;;;;;;;;;;;;;;;;EAmBf;;;;;;;;EAQA;;;;;;;;;;;;;;;;;iBAkBoB,iBACpB,mBACA,YAAY,wBACZ,UAAS,0BACR,QAAQ"}

package/dist/resolveNormalMap.js

@@ -1,97 +1,76 @@
-import {
-  DataTexture,
-  RGBAFormat,
-  UnsignedByteType,
-  TextureLoader as ThreeTextureLoader
-} from "three";
-import {
-  bakedSiblingURL,
-  devtimeWarn,
-  hashDescriptor,
-  probeBakedSibling
-} from "@three-flatland/bake";
+import { DataTexture, RGBAFormat, TextureLoader, UnsignedByteType } from "three";
+import { bakedSiblingURL, devtimeWarn, hashDescriptor, probeBakedSibling } from "@three-flatland/bake";
+//#region src/resolveNormalMap.ts
+/**
+* Resolve the normal map for an asset URL + descriptor.
+*
+* 1. Hash the descriptor.
+* 2. Probe the baked sibling `<source>.normal.png` (unless
+*    `forceRuntime`). If present and its stamped hash matches, load
+*    and return that texture directly.
+* 3. On miss (or stale hash), fetch the source, decode its pixels,
+*    lazy-import + run `bakeNormalMap` in memory, and wrap the result
+*    in a `DataTexture`. Runtime bake is the always-on fallback when
+*    normals were requested.
+*
+* Browser-only — uses `fetch`, `createImageBitmap`, `OffscreenCanvas`.
+* Safe to call from any Three.js loader runtime.
+*/
 async function resolveNormalMap(sourceURL, descriptor, options = {}) {
-  const hash = hashDescriptor(descriptor);
-  if (!options.forceRuntime) {
-    const bakedURL = bakedSiblingURL(sourceURL, ".normal.png");
-    const probe = await probeBakedSibling(bakedURL, { expectedHash: hash });
-    if (probe.ok && probe.hashMatches) {
-      const tex2 = await loadTextureURL(bakedURL);
-      if (options.flipY !== void 0) tex2.flipY = options.flipY;
-      tex2.needsUpdate = true;
-      return tex2;
-    }
-    if (probe.ok && !probe.hashMatches) {
-      devtimeWarn(
-        "normal",
-        sourceURL,
-        `${bakedURL} exists but its descriptor hash is stale \u2014 re-baking in memory. Run \`npx flatland-bake normal ${sourceURL} --descriptor <descriptor>.json\` to refresh.`
-      );
-    } else {
-      devtimeWarn(
-        "normal",
-        sourceURL,
-        `No baked sibling at ${bakedURL} \u2014 baking in memory. Run \`npx flatland-bake normal\` for production.`
-      );
-    }
-  }
-  const tex = await bakeInMemory(sourceURL, descriptor);
-  if (options.flipY !== void 0) tex.flipY = options.flipY;
-  tex.needsUpdate = true;
-  return tex;
+	const hash = hashDescriptor(descriptor);
+	if (!options.forceRuntime) {
+		const bakedURL = bakedSiblingURL(sourceURL, ".normal.png");
+		const probe = await probeBakedSibling(bakedURL, { expectedHash: hash });
+		if (probe.ok && probe.hashMatches) {
+			const tex = await loadTextureURL(bakedURL);
+			if (options.flipY !== void 0) tex.flipY = options.flipY;
+			tex.needsUpdate = true;
+			return tex;
+		}
+		if (probe.ok && !probe.hashMatches) devtimeWarn("normal", sourceURL, `${bakedURL} exists but its descriptor hash is stale — re-baking in memory. Run \`npx flatland-bake normal ${sourceURL} --descriptor <descriptor>.json\` to refresh.`);
+		else devtimeWarn("normal", sourceURL, `No baked sibling at ${bakedURL} — baking in memory. Run \`npx flatland-bake normal\` for production.`);
+	}
+	const tex = await bakeInMemory(sourceURL, descriptor);
+	if (options.flipY !== void 0) tex.flipY = options.flipY;
+	tex.needsUpdate = true;
+	return tex;
 }
 async function loadTextureURL(url) {
-  return new Promise((resolve, reject) => {
-    const loader = new ThreeTextureLoader();
-    loader.load(
-      url,
-      (tex) => resolve(tex),
-      void 0,
-      (err) => reject(err)
-    );
-  });
+	return new Promise((resolve, reject) => {
+		new TextureLoader().load(url, (tex) => resolve(tex), void 0, (err) => reject(err));
+	});
 }
 async function bakeInMemory(sourceURL, descriptor) {
-  const res = await fetch(sourceURL);
-  if (!res.ok) {
-    throw new Error(`resolveNormalMap: failed to fetch ${sourceURL} (${res.status})`);
-  }
-  const blob = await res.blob();
-  const bitmap = await createImageBitmap(blob);
-  const { width, height } = bitmap;
-  const pixels = imageBitmapToRGBA(bitmap, width, height);
-  bitmap.close();
-  const { bakeNormalMap } = await import("./bake.js");
-  const normalPixels = bakeNormalMap(pixels, width, height, descriptor);
-  const texture = new DataTexture(
-    normalPixels,
-    width,
-    height,
-    RGBAFormat,
-    UnsignedByteType
-  );
-  texture.needsUpdate = true;
-  return texture;
+	const res = await fetch(sourceURL);
+	if (!res.ok) throw new Error(`resolveNormalMap: failed to fetch ${sourceURL} (${res.status})`);
+	const blob = await res.blob();
+	const bitmap = await createImageBitmap(blob);
+	const { width, height } = bitmap;
+	const pixels = imageBitmapToRGBA(bitmap, width, height);
+	bitmap.close();
+	const { bakeNormalMap } = await import("./bake.js");
+	const texture = new DataTexture(bakeNormalMap(pixels, width, height, descriptor), width, height, RGBAFormat, UnsignedByteType);
+	texture.needsUpdate = true;
+	return texture;
 }
 function imageBitmapToRGBA(bitmap, width, height) {
-  if (typeof OffscreenCanvas !== "undefined") {
-    const canvas2 = new OffscreenCanvas(width, height);
-    const ctx2 = canvas2.getContext("2d");
-    if (!ctx2) throw new Error("resolveNormalMap: OffscreenCanvas 2D context unavailable");
-    ctx2.drawImage(bitmap, 0, 0);
-    const data2 = ctx2.getImageData(0, 0, width, height);
-    return new Uint8Array(data2.data.buffer, data2.data.byteOffset, data2.data.byteLength);
-  }
-  const canvas = document.createElement("canvas");
-  canvas.width = width;
-  canvas.height = height;
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("resolveNormalMap: Canvas 2D context unavailable");
-  ctx.drawImage(bitmap, 0, 0);
-  const data = ctx.getImageData(0, 0, width, height);
-  return new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength);
+	if (typeof OffscreenCanvas !== "undefined") {
+		const ctx = new OffscreenCanvas(width, height).getContext("2d");
+		if (!ctx) throw new Error("resolveNormalMap: OffscreenCanvas 2D context unavailable");
+		ctx.drawImage(bitmap, 0, 0);
+		const data = ctx.getImageData(0, 0, width, height);
+		return new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength);
+	}
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error("resolveNormalMap: Canvas 2D context unavailable");
+	ctx.drawImage(bitmap, 0, 0);
+	const data = ctx.getImageData(0, 0, width, height);
+	return new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength);
 }
-export {
-  resolveNormalMap
-};
+//#endregion
+export { resolveNormalMap };
+
 //# sourceMappingURL=resolveNormalMap.js.map