@three-flatland/normals 0.1.0-alpha.1

package/dist/resolveNormalMap.js

@@ -0,0 +1,97 @@
+import {
+  DataTexture,
+  RGBAFormat,
+  UnsignedByteType,
+  TextureLoader as ThreeTextureLoader
+} from "three";
+import {
+  bakedSiblingURL,
+  devtimeWarn,
+  hashDescriptor,
+  probeBakedSibling
+} from "@three-flatland/bake";
+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;
+}
+async function loadTextureURL(url) {
+  return new Promise((resolve, reject) => {
+    const loader = new ThreeTextureLoader();
+    loader.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;
+}
+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);
+}
+export {
+  resolveNormalMap
+};
+//# sourceMappingURL=resolveNormalMap.js.map

package/dist/resolveNormalMap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolveNormalMap.ts"],"sourcesContent":["import {\n  DataTexture,\n  RGBAFormat,\n  UnsignedByteType,\n  TextureLoader as ThreeTextureLoader,\n  type Texture,\n} from 'three'\nimport {\n  bakedSiblingURL,\n  devtimeWarn,\n  hashDescriptor,\n  probeBakedSibling,\n} from '@three-flatland/bake'\nimport type { NormalSourceDescriptor } from './descriptor.js'\n\nexport interface ResolveNormalMapOptions {\n  /**\n   * Generate this asset's normal map in the browser on every load\n   * instead of loading a pre-baked `.normal.png` sidecar. Fetches the\n   * source image, decodes its pixels, and runs `bakeNormalMap` in\n   * memory each time — no HEAD probe, no devtime \"no baked sibling\"\n   * warning.\n   *\n   * The returned data is always a valid normal map: this flag chooses\n   * *where* the bake happens (browser vs CI), not whether you get one.\n   *\n   * Use when runtime is the right home for the bake — procedurally\n   * varied content, throwaway prototypes, asset bundles where shipping\n   * the sidecar isn't worth the bytes. Not a dev-iteration knob: the\n   * default path (probe → bake on miss + warn) already handles that.\n   *\n   * Mirrors `SlugFontLoader.forceRuntime` and every other baked-asset\n   * loader in the codebase.\n   */\n  forceRuntime?: boolean\n  /**\n   * Force the returned texture's `flipY` to this value. Pass the\n   * diffuse texture's `flipY` so the normal map samples 1:1 with the\n   * diffuse on the GPU regardless of whether the normal came from the\n   * image-loader path (default true) or the in-memory `DataTexture`\n   * path (default false).\n   */\n  flipY?: boolean\n}\n\n/**\n * Resolve the normal map for an asset URL + descriptor.\n *\n * 1. Hash the descriptor.\n * 2. Probe the baked sibling `<source>.normal.png` (unless\n *    `forceRuntime`). If present and its stamped hash matches, load\n *    and return that texture directly.\n * 3. On miss (or stale hash), fetch the source, decode its pixels,\n *    lazy-import + run `bakeNormalMap` in memory, and wrap the result\n *    in a `DataTexture`. Runtime bake is the always-on fallback when\n *    normals were requested.\n *\n * Browser-only — uses `fetch`, `createImageBitmap`, `OffscreenCanvas`.\n * Safe to call from any Three.js loader runtime.\n */\nexport async function resolveNormalMap(\n  sourceURL: string,\n  descriptor: NormalSourceDescriptor,\n  options: ResolveNormalMapOptions = {}\n): Promise<Texture> {\n  const hash = hashDescriptor(descriptor)\n\n  if (!options.forceRuntime) {\n    const bakedURL = bakedSiblingURL(sourceURL, '.normal.png')\n    const probe = await probeBakedSibling(bakedURL, { expectedHash: hash })\n    if (probe.ok && probe.hashMatches) {\n      const tex = await loadTextureURL(bakedURL)\n      if (options.flipY !== undefined) tex.flipY = options.flipY\n      tex.needsUpdate = true\n      return tex\n    }\n    if (probe.ok && !probe.hashMatches) {\n      devtimeWarn(\n        'normal',\n        sourceURL,\n        `${bakedURL} exists but its descriptor hash is stale — re-baking in memory. ` +\n          `Run \\`npx flatland-bake normal ${sourceURL} --descriptor <descriptor>.json\\` to refresh.`\n      )\n    } else {\n      devtimeWarn(\n        'normal',\n        sourceURL,\n        `No baked sibling at ${bakedURL} — baking in memory. ` +\n          `Run \\`npx flatland-bake normal\\` for production.`\n      )\n    }\n  }\n\n  const tex = await bakeInMemory(sourceURL, descriptor)\n  if (options.flipY !== undefined) tex.flipY = options.flipY\n  tex.needsUpdate = true\n  return tex\n}\n\n// ─── Private ──────────────────────────────────────────────────────────────\n\nasync function loadTextureURL(url: string): Promise<Texture> {\n  return new Promise((resolve, reject) => {\n    const loader = new ThreeTextureLoader()\n    loader.load(\n      url,\n      (tex) => resolve(tex as Texture),\n      undefined,\n      (err) => reject(err as Error)\n    )\n  })\n}\n\nasync function bakeInMemory(\n  sourceURL: string,\n  descriptor: NormalSourceDescriptor\n): Promise<Texture> {\n  const res = await fetch(sourceURL)\n  if (!res.ok) {\n    throw new Error(`resolveNormalMap: failed to fetch ${sourceURL} (${res.status})`)\n  }\n  const blob = await res.blob()\n  const bitmap = await createImageBitmap(blob)\n  const { width, height } = bitmap\n  const pixels = imageBitmapToRGBA(bitmap, width, height)\n  bitmap.close()\n\n  const { bakeNormalMap } = await import('./bake.js')\n  const normalPixels = bakeNormalMap(pixels, width, height, descriptor)\n  const texture = new DataTexture(\n    normalPixels,\n    width,\n    height,\n    RGBAFormat,\n    UnsignedByteType\n  )\n  texture.needsUpdate = true\n  return texture\n}\n\nfunction imageBitmapToRGBA(\n  bitmap: ImageBitmap,\n  width: number,\n  height: number\n): Uint8Array {\n  // OffscreenCanvas where available (workers + modern browsers), fall\n  // back to a regular 2D canvas in environments that don't ship it.\n  if (typeof OffscreenCanvas !== 'undefined') {\n    const canvas = new OffscreenCanvas(width, height)\n    const ctx = canvas.getContext('2d')\n    if (!ctx) throw new Error('resolveNormalMap: OffscreenCanvas 2D context unavailable')\n    ctx.drawImage(bitmap, 0, 0)\n    const data = ctx.getImageData(0, 0, width, height)\n    return new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength)\n  }\n  const canvas = document.createElement('canvas')\n  canvas.width = width\n  canvas.height = height\n  const ctx = canvas.getContext('2d')\n  if (!ctx) throw new Error('resolveNormalMap: Canvas 2D context unavailable')\n  ctx.drawImage(bitmap, 0, 0)\n  const data = ctx.getImageData(0, 0, width, height)\n  return new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength)\n}\n\n"],"mappings":"AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,OAEZ;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAgDP,eAAsB,iBACpB,WACA,YACA,UAAmC,CAAC,GAClB;AAClB,QAAM,OAAO,eAAe,UAAU;AAEtC,MAAI,CAAC,QAAQ,cAAc;AACzB,UAAM,WAAW,gBAAgB,WAAW,aAAa;AACzD,UAAM,QAAQ,MAAM,kBAAkB,UAAU,EAAE,cAAc,KAAK,CAAC;AACtE,QAAI,MAAM,MAAM,MAAM,aAAa;AACjC,YAAMA,OAAM,MAAM,eAAe,QAAQ;AACzC,UAAI,QAAQ,UAAU,OAAW,CAAAA,KAAI,QAAQ,QAAQ;AACrD,MAAAA,KAAI,cAAc;AAClB,aAAOA;AAAA,IACT;AACA,QAAI,MAAM,MAAM,CAAC,MAAM,aAAa;AAClC;AAAA,QACE;AAAA,QACA;AAAA,QACA,GAAG,QAAQ,uGACyB,SAAS;AAAA,MAC/C;AAAA,IACF,OAAO;AACL;AAAA,QACE;AAAA,QACA;AAAA,QACA,uBAAuB,QAAQ;AAAA,MAEjC;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAM,aAAa,WAAW,UAAU;AACpD,MAAI,QAAQ,UAAU,OAAW,KAAI,QAAQ,QAAQ;AACrD,MAAI,cAAc;AAClB,SAAO;AACT;AAIA,eAAe,eAAe,KAA+B;AAC3D,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,SAAS,IAAI,mBAAmB;AACtC,WAAO;AAAA,MACL;AAAA,MACA,CAAC,QAAQ,QAAQ,GAAc;AAAA,MAC/B;AAAA,MACA,CAAC,QAAQ,OAAO,GAAY;AAAA,IAC9B;AAAA,EACF,CAAC;AACH;AAEA,eAAe,aACb,WACA,YACkB;AAClB,QAAM,MAAM,MAAM,MAAM,SAAS;AACjC,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,IAAI,MAAM,qCAAqC,SAAS,KAAK,IAAI,MAAM,GAAG;AAAA,EAClF;AACA,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,QAAM,SAAS,MAAM,kBAAkB,IAAI;AAC3C,QAAM,EAAE,OAAO,OAAO,IAAI;AAC1B,QAAM,SAAS,kBAAkB,QAAQ,OAAO,MAAM;AACtD,SAAO,MAAM;AAEb,QAAM,EAAE,cAAc,IAAI,MAAM,OAAO,WAAW;AAClD,QAAM,eAAe,cAAc,QAAQ,OAAO,QAAQ,UAAU;AACpE,QAAM,UAAU,IAAI;AAAA,IAClB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACA,UAAQ,cAAc;AACtB,SAAO;AACT;AAEA,SAAS,kBACP,QACA,OACA,QACY;AAGZ,MAAI,OAAO,oBAAoB,aAAa;AAC1C,UAAMC,UAAS,IAAI,gBAAgB,OAAO,MAAM;AAChD,UAAMC,OAAMD,QAAO,WAAW,IAAI;AAClC,QAAI,CAACC,KAAK,OAAM,IAAI,MAAM,0DAA0D;AACpF,IAAAA,KAAI,UAAU,QAAQ,GAAG,CAAC;AAC1B,UAAMC,QAAOD,KAAI,aAAa,GAAG,GAAG,OAAO,MAAM;AACjD,WAAO,IAAI,WAAWC,MAAK,KAAK,QAAQA,MAAK,KAAK,YAAYA,MAAK,KAAK,UAAU;AAAA,EACpF;AACA,QAAM,SAAS,SAAS,cAAc,QAAQ;AAC9C,SAAO,QAAQ;AACf,SAAO,SAAS;AAChB,QAAM,MAAM,OAAO,WAAW,IAAI;AAClC,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,iDAAiD;AAC3E,MAAI,UAAU,QAAQ,GAAG,CAAC;AAC1B,QAAM,OAAO,IAAI,aAAa,GAAG,GAAG,OAAO,MAAM;AACjD,SAAO,IAAI,WAAW,KAAK,KAAK,QAAQ,KAAK,KAAK,YAAY,KAAK,KAAK,UAAU;AACpF;","names":["tex","canvas","ctx","data"]}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@three-flatland/normals",
+  "version": "0.1.0-alpha.1",
+  "description": "Offline + runtime normal map generation for sprites and tilesets. Contributes a `normal` subcommand to the flatland-bake CLI.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "types": "./dist/node.d.ts",
+        "import": "./dist/node.js"
+      },
+      "browser": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "./node": {
+      "source": "./src/node.ts",
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./cli": {
+      "source": "./src/cli.ts",
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./bake": {
+      "source": "./src/bake.ts",
+      "types": "./dist/bake.d.ts",
+      "import": "./dist/bake.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "pngjs": "^7.0.0",
+    "@three-flatland/bake": "0.1.0-alpha.1"
+  },
+  "peerDependencies": {
+    "three": ">=0.170.0"
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5",
+    "@types/three": "^0.183.1",
+    "three": "^0.183.1"
+  },
+  "flatland": {
+    "bake": [
+      {
+        "name": "normal",
+        "description": "Bake a tangent-space normal map from a sprite PNG",
+        "entry": "./dist/cli.js"
+      }
+    ]
+  },
+  "keywords": [
+    "three-flatland",
+    "normal-map",
+    "bake"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thejustinwalsh/three-flatland.git",
+    "directory": "packages/normals"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}