@aethervtt/shard-texture 0.0.1

package/dist/decode/webp.js

@@ -0,0 +1,39 @@
+import { ShardError } from "@aethervtt/shard-core";
+let ready;
+function decoder() {
+  ready ??= (async () => {
+    const mod = await import("@jsquash/webp/decode");
+    if (typeof process !== "undefined" && process.versions?.node) {
+      const wasmUrl = new URL(
+        "./codec/dec/webp_dec.wasm",
+        import.meta.resolve("@jsquash/webp/decode")
+      );
+      const { readFile } = await import("node:fs/promises");
+      await mod.init(await WebAssembly.compile(await readFile(wasmUrl)));
+    }
+    return mod.default;
+  })();
+  return ready;
+}
+async function decodeWebp(bytes) {
+  try {
+    const decode = await decoder();
+    const copy = bytes.slice();
+    const img = await decode(copy.buffer);
+    return {
+      width: img.width,
+      height: img.height,
+      kind: "u8",
+      data: new Uint8Array(img.data.buffer)
+    };
+  } catch (cause) {
+    throw new ShardError(
+      "texture/decode-failed",
+      `WebP decode failed: ${cause.message}`,
+      { cause }
+    );
+  }
+}
+export {
+  decodeWebp
+};

package/dist/image.d.ts

@@ -0,0 +1,7 @@
+/** A decoded image: RGBA8 (`u8`) or RGBA float (`f32`, linear, for HDR). Top row first. */
+export interface Image {
+    width: number;
+    height: number;
+    kind: 'u8' | 'f32';
+    data: Uint8Array | Float32Array;
+}

package/dist/importer.d.ts

@@ -0,0 +1,34 @@
+import { type JsonValue } from '@aethervtt/shard-core';
+import type { Image } from './image.js';
+import { type TextureUsage } from './mips.js';
+export declare const TextureImportSettings: import("@aethervtt/shard-core").ComponentDef<{
+    readonly usage: import("@aethervtt/shard-core").FieldType<"color" | "data" | "hdr" | "normal", "u8">;
+    readonly mipmaps: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly compression: import("@aethervtt/shard-core").FieldType<"etc1s" | "none" | "uastc", "u8">;
+    readonly maxSize: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly flipY: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly premultiplyAlpha: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly normalMap: import("@aethervtt/shard-core").FieldType<"directx" | "opengl", "u8">;
+}>;
+export interface TextureSettings {
+    usage: TextureUsage;
+    mipmaps: boolean;
+    compression: 'none' | 'etc1s' | 'uastc';
+    maxSize: number;
+    flipY: boolean;
+    premultiplyAlpha: boolean;
+    normalMap?: 'opengl' | 'directx';
+}
+/** Flips a normal map's green channel in place (DirectX → OpenGL, or back). */
+export declare function flipGreen(image: Image): Image;
+/** Usage from the file name, for a new `.meta`. */
+export declare function usageFromName(path: string): TextureUsage;
+/**
+ * Imports image bytes into a KTX2 artifact. Shared by the file importer and by glTF (embedded
+ * images), so the same bytes become the same artifact wherever they come from.
+ */
+export declare function importImageBytes(bytes: Uint8Array, settings: TextureSettings, warn?: (message: string) => void): Promise<{
+    bytes: Uint8Array;
+    info: Record<string, JsonValue>;
+}>;
+export declare const TextureImporter: import("@aethervtt/shard-assets").ImporterDef;

package/dist/importer.js

@@ -0,0 +1,168 @@
+import { defineImporter } from "@aethervtt/shard-assets";
+import { defineSchema, ShardError, t } from "@aethervtt/shard-core";
+import { encodeBasis } from "./basis.js";
+import { decodeImage, sniffImage } from "./decode/index.js";
+import { readKtx2, tagKtx2, writeKtx2 } from "./ktx2.js";
+import { buildMips } from "./mips.js";
+const TextureImportSettings = defineSchema(
+  "texture/ImportSettings",
+  {
+    usage: t.enum(["color", "data", "normal", "hdr"], {
+      description: "color: sRGB albedo/emissive. data: linear masks (roughness, metallic, AO). normal: tangent-space normal map. hdr: linear float (environment maps)."
+    }),
+    mipmaps: t.bool({ default: true, description: "Generate a full mip chain." }),
+    compression: t.enum(["none", "etc1s", "uastc"], {
+      description: "Basis Universal. uastc: high quality, larger. etc1s: small, lossy. Encoding takes seconds per texture on first import; the cache keeps the result."
+    }),
+    maxSize: t.u32({ default: 4096, min: 1, max: 16384, description: "Downscale larger images." }),
+    flipY: t.bool({ description: "Flip vertically on import." }),
+    premultiplyAlpha: t.bool({ description: "Multiply color by alpha on import." }),
+    normalMap: t.enum(["opengl", "directx"], {
+      description: "Normal maps: opengl (+Y up, the engine convention) or directx (+Y down: green is flipped on import)."
+    })
+  },
+  { description: "Import settings for images (PNG, JPEG, WebP, .hdr, KTX2)." }
+);
+function flipGreen(image) {
+  const d = image.data;
+  if (image.kind === "u8") for (let i = 1; i < d.length; i += 4) d[i] = 255 - d[i];
+  else for (let i = 1; i < d.length; i += 4) d[i] = 1 - d[i];
+  return image;
+}
+function usageFromName(path) {
+  const name = path.toLowerCase().split("/").pop();
+  if (name.endsWith(".hdr")) return "hdr";
+  if (/normal|_n\.|_nrm/.test(name)) return "normal";
+  if (/rough|metal|_orm|occlusion|_ao[._]|_arm|mask/.test(name)) return "data";
+  return "color";
+}
+function padTo4(rgba, w, h) {
+  const pw = Math.ceil(w / 4) * 4;
+  const ph = Math.ceil(h / 4) * 4;
+  if (pw === w && ph === h) return { data: rgba, width: w, height: h };
+  const out = new Uint8Array(pw * ph * 4);
+  for (let y = 0; y < ph; y++) {
+    const sy = Math.min(h - 1, y);
+    for (let x = 0; x < pw; x++) {
+      const sx = Math.min(w - 1, x);
+      out.set(rgba.subarray((sy * w + sx) * 4, (sy * w + sx) * 4 + 4), (y * pw + x) * 4);
+    }
+  }
+  return { data: out, width: pw, height: ph };
+}
+function toLinearFloat(image) {
+  if (image.kind === "f32") return image;
+  const src = image.data;
+  const out = new Float32Array(src.length);
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i] / 255;
+    out[i] = i % 4 === 3 ? c : c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  }
+  return { width: image.width, height: image.height, kind: "f32", data: out };
+}
+async function importImageBytes(bytes, settings, warn = () => {
+}) {
+  const format = sniffImage(bytes);
+  if (format === "ktx2") {
+    const ktx = readKtx2(bytes);
+    const tagged = tagKtx2(bytes, settings.usage);
+    return {
+      bytes: tagged,
+      info: {
+        width: ktx.width,
+        height: ktx.height,
+        source: "ktx2",
+        compression: ktx.basis ?? "none",
+        mips: ktx.levels.length,
+        usage: settings.usage
+      }
+    };
+  }
+  let image = await decodeImage(bytes);
+  const usage = settings.usage;
+  if (usage === "normal" && settings.normalMap === "directx") image = flipGreen(image);
+  if (usage === "hdr") image = toLinearFloat(image);
+  else if (image.kind === "f32") {
+    warn(
+      'A float image imported as LDR is clamped to [0, 1]; set usage to "hdr" to keep its range.'
+    );
+  }
+  const info = { source: format ?? "unknown", usage };
+  if (settings.compression !== "none" && usage !== "hdr") {
+    const base = buildMips(image, { ...settings, mipmaps: false });
+    const padded = padTo4(base.levels[0], base.width, base.height);
+    if (padded.width !== base.width || padded.height !== base.height) {
+      warn(
+        `Padded ${base.width}x${base.height} to ${padded.width}x${padded.height}: Basis needs multiples of 4.`
+      );
+    }
+    const encoded = await encodeBasis(
+      padded.data,
+      padded.width,
+      padded.height,
+      usage,
+      settings.compression,
+      settings.mipmaps
+    );
+    const out2 = tagKtx2(encoded, usage, settings.premultiplyAlpha);
+    const ktx = readKtx2(out2);
+    return {
+      bytes: out2,
+      info: {
+        ...info,
+        width: ktx.width,
+        height: ktx.height,
+        mips: ktx.levels.length,
+        compression: settings.compression,
+        bytes: out2.byteLength
+      }
+    };
+  }
+  if (settings.compression !== "none") warn("HDR textures are stored uncompressed (rgba16float).");
+  const chain = buildMips(image, settings);
+  const out = writeKtx2(chain, usage, 1, settings.premultiplyAlpha);
+  return {
+    bytes: out,
+    info: {
+      ...info,
+      width: chain.width,
+      height: chain.height,
+      mips: chain.levels.length,
+      compression: "none",
+      bytes: out.byteLength
+    }
+  };
+}
+const TextureImporter = defineImporter({
+  name: "texture",
+  version: 1,
+  extensions: [".png", ".jpg", ".jpeg", ".webp", ".hdr", ".ktx2"],
+  settings: TextureImportSettings,
+  defaults: (path) => ({ usage: usageFromName(path) }),
+  async import(source, ctx) {
+    const settings = ctx.settings;
+    let result;
+    try {
+      result = await importImageBytes(source.bytes, settings, (m) => ctx.warn(m));
+    } catch (err) {
+      if (err instanceof ShardError) throw err;
+      throw new ShardError("texture/decode-failed", `${source.path}: ${err.message}`, {
+        cause: err
+      });
+    }
+    const asset = {
+      label: "",
+      type: "Texture",
+      bytes: result.bytes,
+      info: result.info
+    };
+    return { assets: [asset] };
+  }
+});
+export {
+  TextureImportSettings,
+  TextureImporter,
+  flipGreen,
+  importImageBytes,
+  usageFromName
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { resizeImage, type TextureArrayFile, TextureArrayImporter } from './array.js';
+export { encodeBasis, type TranscodedTexture, type TranscodeTarget, transcodeBasis } from './basis.js';
+export { decodeHdr, decodeImage, decodeJpeg, decodePngImage, decodeWebp, type ImageFormat, sniffImage, } from './decode/index.js';
+export type { Image } from './image.js';
+export { flipGreen, importImageBytes, TextureImporter, TextureImportSettings, type TextureSettings, usageFromName, } from './importer.js';
+export { type Ktx2Data, readKtx2, tagKtx2, writeKtx2 } from './ktx2.js';
+export { buildMips, type MipChain, type MipOptions, type TextureUsage, toHalf } from './mips.js';
+export { type PackItem, type PackResult, packRects, SkylinePacker } from './pack.js';
+export { FORMAT_INFO, setTextureCapabilities, Texture, TextureAssetType, type TextureCapabilities, type TextureFormat, type TextureInit, Textures, textureCapabilities, textureFromKtx2, transcodeTarget, } from './texture.js';

package/dist/index.js

@@ -0,0 +1,62 @@
+import { resizeImage, TextureArrayImporter } from "./array.js";
+import { encodeBasis, transcodeBasis } from "./basis.js";
+import {
+  decodeHdr,
+  decodeImage,
+  decodeJpeg,
+  decodePngImage,
+  decodeWebp,
+  sniffImage
+} from "./decode/index.js";
+import {
+  flipGreen,
+  importImageBytes,
+  TextureImporter,
+  TextureImportSettings,
+  usageFromName
+} from "./importer.js";
+import { readKtx2, tagKtx2, writeKtx2 } from "./ktx2.js";
+import { buildMips, toHalf } from "./mips.js";
+import { packRects, SkylinePacker } from "./pack.js";
+import {
+  FORMAT_INFO,
+  setTextureCapabilities,
+  Texture,
+  TextureAssetType,
+  Textures,
+  textureCapabilities,
+  textureFromKtx2,
+  transcodeTarget
+} from "./texture.js";
+export {
+  FORMAT_INFO,
+  SkylinePacker,
+  Texture,
+  TextureArrayImporter,
+  TextureAssetType,
+  TextureImportSettings,
+  TextureImporter,
+  Textures,
+  buildMips,
+  decodeHdr,
+  decodeImage,
+  decodeJpeg,
+  decodePngImage,
+  decodeWebp,
+  encodeBasis,
+  flipGreen,
+  importImageBytes,
+  packRects,
+  readKtx2,
+  resizeImage,
+  setTextureCapabilities,
+  sniffImage,
+  tagKtx2,
+  textureCapabilities,
+  textureFromKtx2,
+  toHalf,
+  transcodeBasis,
+  transcodeTarget,
+  usageFromName,
+  writeKtx2
+};

package/dist/ktx2.d.ts

@@ -0,0 +1,32 @@
+import { type MipChain, type TextureUsage } from './mips.js';
+/**
+ * Writes an uncompressed KTX2: RGBA8 (sRGB-tagged for color) or RGBA16F for hdr, every level. With
+ * `faces: 6` it's a cube map, and each level holds the six faces one after another.
+ */
+/**
+ * A mip chain as KTX2. `premultiplied` marks color already multiplied by alpha (the DFD flag,
+ * plus a key the engine reads back).
+ */
+export declare function writeKtx2(chain: MipChain, usage: TextureUsage, faces?: number, premultiplied?: boolean, layers?: number): Uint8Array;
+export interface Ktx2Data {
+    width: number;
+    height: number;
+    vkFormat: number;
+    /** Level data, uncompressed (Zstandard supercompression is undone here). Basis data stays encoded. */
+    levels: Uint8Array[];
+    /** Basis Universal payloads need transcoding before upload. */
+    basis: 'etc1s' | 'uastc' | undefined;
+    usage: TextureUsage;
+    srgb: boolean;
+    /** The original file, for the Basis transcoder. */
+    bytes: Uint8Array;
+    /** 1, or 6 for a cube map (each level holds the faces in order +X, -X, +Y, -Y, +Z, -Z). */
+    faces: number;
+    /** Array layers (1 for a plain texture); each level holds them one after another. */
+    layers: number;
+    /** Color is already multiplied by alpha. */
+    premultiplied: boolean;
+}
+export declare function readKtx2(bytes: Uint8Array): Ktx2Data;
+/** Re-tags a KTX2 (e.g. one the Basis encoder wrote) with the engine's usage key. */
+export declare function tagKtx2(bytes: Uint8Array, usage: TextureUsage, premultiplied?: boolean): Uint8Array;

package/dist/ktx2.js

@@ -0,0 +1,124 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { decompress } from "fzstd";
+import {
+  createDefaultContainer,
+  KHR_DF_MODEL_UASTC,
+  KHR_SUPERCOMPRESSION_BASISLZ,
+  KHR_SUPERCOMPRESSION_NONE,
+  KHR_SUPERCOMPRESSION_ZSTD,
+  read,
+  VK_FORMAT_R8G8B8A8_SRGB,
+  VK_FORMAT_R8G8B8A8_UNORM,
+  VK_FORMAT_R16G16B16A16_SFLOAT,
+  write
+} from "ktx-parse";
+import { toHalf } from "./mips.js";
+const USAGE_KEY = "shard.usage";
+const PREMULTIPLIED_KEY = "shard.premultiplied";
+const KHR_DF_FLAG_ALPHA_PREMULTIPLIED = 1;
+function writeKtx2(chain, usage, faces = 1, premultiplied = false, layers = 1) {
+  const hdr = usage === "hdr";
+  const c = createDefaultContainer();
+  c.vkFormat = hdr ? VK_FORMAT_R16G16B16A16_SFLOAT : usage === "color" ? VK_FORMAT_R8G8B8A8_SRGB : VK_FORMAT_R8G8B8A8_UNORM;
+  c.typeSize = hdr ? 2 : 1;
+  c.pixelWidth = chain.width;
+  c.pixelHeight = chain.height;
+  c.levelCount = chain.levels.length;
+  c.faceCount = faces;
+  c.layerCount = layers > 1 ? layers : 0;
+  c.supercompressionScheme = KHR_SUPERCOMPRESSION_NONE;
+  c.levels = chain.levels.map((level) => {
+    const bytes = hdr ? new Uint8Array(toHalf(level).buffer) : new Uint8Array(level.slice().buffer);
+    return { levelData: bytes, uncompressedByteLength: bytes.byteLength };
+  });
+  const dfd = c.dataFormatDescriptor[0];
+  dfd.colorModel = 1;
+  dfd.colorPrimaries = 1;
+  dfd.transferFunction = usage === "color" ? 2 : 1;
+  dfd.bytesPlane = [hdr ? 8 : 4, 0, 0, 0, 0, 0, 0, 0];
+  const bits = hdr ? 16 : 8;
+  dfd.samples = [0, 1, 2, 15].map((channel, i) => ({
+    bitOffset: i * bits,
+    bitLength: bits - 1,
+    // Float channels are signed floats; sRGB textures keep alpha linear.
+    channelType: channel | (hdr ? 192 : 0) | (usage === "color" && channel === 15 ? 16 : 0),
+    samplePosition: [0, 0, 0, 0],
+    sampleLower: hdr ? 3212836864 : 0,
+    sampleUpper: hdr ? 1065353216 : 255
+  }));
+  if (premultiplied) {
+    dfd.flags = KHR_DF_FLAG_ALPHA_PREMULTIPLIED;
+    c.keyValue[PREMULTIPLIED_KEY] = "true";
+  }
+  c.keyValue[USAGE_KEY] = usage;
+  return write(c);
+}
+function readKtx2(bytes) {
+  let c;
+  try {
+    c = read(bytes);
+  } catch (cause) {
+    throw new ShardError(
+      "texture/decode-failed",
+      `Invalid KTX2 file: ${cause.message}`,
+      { cause }
+    );
+  }
+  if (c.faceCount !== 1 && c.faceCount !== 6 || c.pixelDepth > 1 || c.layerCount > 1 && c.faceCount !== 1) {
+    throw new ShardError(
+      "texture/unsupported-format",
+      "3D and cube-array KTX2 textures come later",
+      {
+        hint: "Use a 2D image, a 2D array (*.texarray.json), or a cube map (6 faces)."
+      }
+    );
+  }
+  const dfd = c.dataFormatDescriptor[0];
+  const basis = c.vkFormat === 0 ? c.supercompressionScheme === KHR_SUPERCOMPRESSION_BASISLZ ? "etc1s" : dfd?.colorModel === KHR_DF_MODEL_UASTC ? "uastc" : void 0 : void 0;
+  if ((c.faceCount === 6 || c.layerCount > 1) && basis) {
+    throw new ShardError(
+      "texture/unsupported-format",
+      "Basis-compressed cube maps and arrays come later",
+      {
+        hint: "Store cube maps and texture arrays uncompressed."
+      }
+    );
+  }
+  if (c.vkFormat === 0 && !basis) {
+    throw new ShardError(
+      "texture/unsupported-format",
+      "KTX2 file has an undefined format and no Basis payload"
+    );
+  }
+  const levels = c.levels.map(
+    (l) => !basis && c.supercompressionScheme === KHR_SUPERCOMPRESSION_ZSTD ? decompress(l.levelData) : l.levelData
+  );
+  const srgb = dfd?.transferFunction === 2;
+  const raw = c.keyValue[USAGE_KEY];
+  const tagged = typeof raw === "string" ? raw : raw instanceof Uint8Array ? new TextDecoder().decode(raw) : void 0;
+  const usage = c.vkFormat === VK_FORMAT_R16G16B16A16_SFLOAT ? "hdr" : tagged ? tagged.replace(/\0+$/, "") : srgb ? "color" : "data";
+  return {
+    width: c.pixelWidth,
+    height: Math.max(1, c.pixelHeight),
+    vkFormat: c.vkFormat,
+    levels,
+    basis,
+    usage,
+    srgb,
+    bytes,
+    faces: c.faceCount,
+    layers: Math.max(1, c.layerCount),
+    premultiplied: c.keyValue[PREMULTIPLIED_KEY] !== void 0 || ((dfd?.flags ?? 0) & KHR_DF_FLAG_ALPHA_PREMULTIPLIED) !== 0
+  };
+}
+function tagKtx2(bytes, usage, premultiplied = false) {
+  const c = read(bytes);
+  c.keyValue[USAGE_KEY] = usage;
+  if (premultiplied) c.keyValue[PREMULTIPLIED_KEY] = "true";
+  return write(c);
+}
+export {
+  readKtx2,
+  tagKtx2,
+  writeKtx2
+};

package/dist/mips.d.ts

@@ -0,0 +1,22 @@
+import type { Image } from './image.js';
+export type TextureUsage = 'color' | 'data' | 'normal' | 'hdr';
+export interface MipChain {
+    width: number;
+    height: number;
+    /** Level 0 first; RGBA8 (sRGB-encoded for color) or RGBA float for hdr. */
+    levels: (Uint8Array | Float32Array)[];
+}
+export interface MipOptions {
+    usage: TextureUsage;
+    mipmaps: boolean;
+    maxSize: number;
+    flipY: boolean;
+    premultiplyAlpha: boolean;
+}
+/**
+ * Prepares an image for upload: flip, premultiply, then a full mip chain filtered in linear light
+ * (normal maps renormalized per level). Levels larger than `maxSize` are dropped.
+ */
+export declare function buildMips(image: Image, options: MipOptions): MipChain;
+/** Float32 → IEEE half floats (for rgba16float). */
+export declare function toHalf(data: Float32Array): Uint16Array;

package/dist/mips.js

@@ -0,0 +1,125 @@
+const SRGB_TO_LINEAR = new Float32Array(256);
+for (let i = 0; i < 256; i++) {
+  const c = i / 255;
+  SRGB_TO_LINEAR[i] = c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+const LUT_SIZE = 16384;
+const LINEAR_TO_SRGB = new Uint8Array(LUT_SIZE + 1);
+for (let i = 0; i <= LUT_SIZE; i++) {
+  const v = i / LUT_SIZE;
+  const c = v <= 31308e-7 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
+  LINEAR_TO_SRGB[i] = Math.round(c * 255);
+}
+function linearToSrgb8(v) {
+  return LINEAR_TO_SRGB[v <= 0 ? 0 : v >= 1 ? LUT_SIZE : Math.round(v * LUT_SIZE)];
+}
+function toFloats(image, usage) {
+  if (image.kind === "f32") return Float32Array.from(image.data);
+  const src = image.data;
+  const out = new Float32Array(src.length);
+  for (let i = 0; i < src.length; i += 4) {
+    for (let c = 0; c < 3; c++) {
+      const v = src[i + c];
+      out[i + c] = usage === "color" ? SRGB_TO_LINEAR[v] : usage === "normal" ? v / 255 * 2 - 1 : v / 255;
+    }
+    out[i + 3] = src[i + 3] / 255;
+  }
+  return out;
+}
+function fromFloats(data, usage) {
+  if (usage === "hdr") return data;
+  const out = new Uint8Array(data.length);
+  for (let i = 0; i < data.length; i += 4) {
+    for (let c = 0; c < 3; c++) {
+      const v = data[i + c];
+      out[i + c] = usage === "color" ? linearToSrgb8(v) : usage === "normal" ? Math.round(Math.min(1, Math.max(0, v * 0.5 + 0.5)) * 255) : Math.round(Math.min(1, Math.max(0, v)) * 255);
+    }
+    out[i + 3] = Math.round(Math.min(1, Math.max(0, data[i + 3])) * 255);
+  }
+  return out;
+}
+function downsample(src, w, h, usage) {
+  const nw = Math.max(1, w >> 1);
+  const nh = Math.max(1, h >> 1);
+  const out = new Float32Array(nw * nh * 4);
+  for (let y = 0; y < nh; y++) {
+    const y0 = Math.min(h - 1, y * 2);
+    const y1 = Math.min(h - 1, y * 2 + 1);
+    for (let x = 0; x < nw; x++) {
+      const x0 = Math.min(w - 1, x * 2);
+      const x1 = Math.min(w - 1, x * 2 + 1);
+      const a = (y0 * w + x0) * 4;
+      const b = (y0 * w + x1) * 4;
+      const c = (y1 * w + x0) * 4;
+      const d = (y1 * w + x1) * 4;
+      const o = (y * nw + x) * 4;
+      for (let k = 0; k < 4; k++)
+        out[o + k] = (src[a + k] + src[b + k] + src[c + k] + src[d + k]) * 0.25;
+      if (usage === "normal") {
+        const len = Math.sqrt(out[o] ** 2 + out[o + 1] ** 2 + out[o + 2] ** 2) || 1;
+        out[o] = out[o] / len;
+        out[o + 1] = out[o + 1] / len;
+        out[o + 2] = out[o + 2] / len;
+      }
+    }
+  }
+  return { data: out, width: nw, height: nh };
+}
+function buildMips(image, options) {
+  const { usage } = options;
+  let data = toFloats(image, usage);
+  let w = image.width;
+  let h = image.height;
+  if (options.flipY) {
+    const flipped = new Float32Array(data.length);
+    for (let y = 0; y < h; y++)
+      flipped.set(data.subarray(y * w * 4, (y + 1) * w * 4), (h - 1 - y) * w * 4);
+    data = flipped;
+  }
+  if (options.premultiplyAlpha) {
+    for (let i = 0; i < data.length; i += 4) {
+      data[i] = data[i] * data[i + 3];
+      data[i + 1] = data[i + 1] * data[i + 3];
+      data[i + 2] = data[i + 2] * data[i + 3];
+    }
+  }
+  const chain = [
+    { data, width: w, height: h }
+  ];
+  while ((options.mipmaps || w > options.maxSize || h > options.maxSize) && (w > 1 || h > 1)) {
+    const next = downsample(data, w, h, usage);
+    chain.push(next);
+    data = next.data;
+    w = next.width;
+    h = next.height;
+    if (!options.mipmaps && w <= options.maxSize && h <= options.maxSize) break;
+  }
+  let first = chain.findIndex((l) => l.width <= options.maxSize && l.height <= options.maxSize);
+  if (first === -1) first = chain.length - 1;
+  const kept = options.mipmaps ? chain.slice(first) : [chain[first]];
+  return {
+    width: kept[0].width,
+    height: kept[0].height,
+    levels: kept.map((l) => fromFloats(l.data, usage))
+  };
+}
+function toHalf(data) {
+  const out = new Uint16Array(data.length);
+  const f = new Float32Array(1);
+  const u = new Uint32Array(f.buffer);
+  for (let i = 0; i < data.length; i++) {
+    f[0] = data[i];
+    const x = u[0];
+    const sign = x >>> 16 & 32768;
+    const exp = (x >>> 23 & 255) - 127 + 15;
+    const mant = x & 8388607;
+    if (exp <= 0) out[i] = sign;
+    else if (exp >= 31) out[i] = sign | 31744;
+    else out[i] = sign | exp << 10 | mant >>> 13;
+  }
+  return out;
+}
+export {
+  buildMips,
+  toHalf
+};

package/dist/pack.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Skyline bottom-left rectangle packing (y down: "bottom" is the lowest top edge). Each rectangle
+ * is placed where its top edge sits highest, ties going left.
+ */
+export declare class SkylinePacker {
+    readonly width: number;
+    readonly height: number;
+    /** Skyline segments: x, y (top of the free space), width. */
+    private xs;
+    private ys;
+    private ws;
+    constructor(width: number, height: number);
+    /** Places a w×h rectangle; returns its top-left, or undefined when it doesn't fit. */
+    insert(w: number, h: number): {
+        x: number;
+        y: number;
+    } | undefined;
+    private place;
+}
+export interface PackItem {
+    width: number;
+    height: number;
+}
+export interface PackResult {
+    pages: {
+        width: number;
+        height: number;
+    }[];
+    /** Per item: page, x, y (top-left, in pixels, padding already applied). */
+    placements: {
+        page: number;
+        x: number;
+        y: number;
+    }[];
+}
+/**
+ * Packs items onto the fewest power-of-two pages no larger than `maxSize`: the smallest page that
+ * fits everything left, else a full `maxSize` page and repeat. Padding surrounds every item.
+ */
+export declare function packRects(items: readonly PackItem[], maxSize?: number, padding?: number): PackResult;