@forgeax/engine-pack 0.1.2

package/src/atlas/shelf-pack.ts

@@ -0,0 +1,176 @@
+// Pure-function shelf packer for the `forgeax-engine-remote-asset atlas`
+// subcommand (feat-20260521-sprite-atlas-animation M5' T-31). Maps a list
+// of decoded RGBA sprites to a non-overlapping atlas region map +
+// atlasWidth / atlasHeight envelope.
+//
+// Why pure-fn (plan-strategy section 2 D-4):
+//   - sidecar (`<name>.atlas.meta.json`) addresses regions by source name,
+//     so the on-disk contract is stable under algorithm swaps. Future feats
+//     can replace shelfPack with MaxRects / rectpack2D without breaking
+//     downstream consumers (charter P5 producer/consumer split).
+//   - the caller (runAtlas) owns disk IO + decode; this file owns only the
+//     geometric layout decision so unit tests do not need filesystem state.
+//
+// Algorithm (research F-1 Godot chart_pack shelf precedent, ~80 LOC MVP):
+//   1. Validate: empty input -> 'atlas-empty-input'; any single image
+//      width/height > maxAtlasSize -> 'atlas-size-exceeded' (caller cannot
+//      recover by repacking, so we fail-fast before the inner loop).
+//   2. Sort by height descending (standard shelf optimisation -- tall
+//      sprites on the bottom shelves keep gaps small); break ties by name
+//      so layouts are deterministic across runs (helps reproducible builds
+//      + cross-platform CI parity).
+//   3. Pick a target shelf width by `nextPow2(ceil(sqrt(totalArea)))` so
+//      the first shelf width is roughly square; clamp to maxAtlasSize and
+//      widen if any single image exceeds the initial guess.
+//   4. Walk left-to-right; start a new shelf when the cursor would overflow
+//      the target width. New shelves stack downward; bail out with
+//      'atlas-size-exceeded' if a placement would push past maxAtlasSize.
+//   5. atlasHeight = nextPow2(usedHeight) clamped to maxAtlasSize so the
+//      output dimensions are GPU-friendly (most sprite atlases live happily
+//      inside power-of-two limits even when WebGPU lifts the requirement).
+
+import type { ImageErrorCode } from '@forgeax/engine-types';
+
+/**
+ * Decoded image input for shelfPack. `pixels` length must equal
+ * `width * height * 4` (RGBA8); the field is carried so the caller can
+ * blit into the atlas buffer without re-decoding inside this module.
+ */
+export interface AtlasImageInput {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+  readonly pixels: Uint8Array;
+}
+
+/**
+ * One placed sprite inside the packed atlas. `(x, y)` is the top-left
+ * corner in pixel coordinates; `(w, h)` mirrors the source dimensions.
+ */
+export interface AtlasRegion {
+  readonly name: string;
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+export interface ShelfPackResult {
+  readonly atlasWidth: number;
+  readonly atlasHeight: number;
+  readonly regions: ReadonlyArray<AtlasRegion>;
+}
+
+/**
+ * Detail shape used by both `atlas-empty-input` and `atlas-size-exceeded`
+ * branches. Fields are optional because the two codes carry different
+ * subsets; the caller projects each branch onto the matching
+ * `ImageErrorDetail` variant before emitting the structured error.
+ */
+export interface ShelfPackError {
+  readonly code: Extract<ImageErrorCode, 'atlas-empty-input' | 'atlas-size-exceeded'>;
+  readonly detail: {
+    readonly name?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly maxAtlasSize?: number;
+    readonly receivedCount?: number;
+  };
+}
+
+export type ShelfPackOutcome =
+  | { readonly ok: true; readonly value: ShelfPackResult }
+  | { readonly ok: false; readonly error: ShelfPackError };
+
+function nextPow2(n: number): number {
+  if (n <= 1) return 1;
+  let p = 1;
+  while (p < n) p <<= 1;
+  return p;
+}
+
+export function shelfPack(
+  images: ReadonlyArray<AtlasImageInput>,
+  opts: { readonly maxAtlasSize: number },
+): ShelfPackOutcome {
+  const { maxAtlasSize } = opts;
+
+  if (images.length === 0) {
+    return {
+      ok: false,
+      error: { code: 'atlas-empty-input', detail: { receivedCount: 0 } },
+    };
+  }
+
+  for (const img of images) {
+    if (img.width > maxAtlasSize || img.height > maxAtlasSize) {
+      return {
+        ok: false,
+        error: {
+          code: 'atlas-size-exceeded',
+          detail: {
+            name: img.name,
+            width: img.width,
+            height: img.height,
+            maxAtlasSize,
+          },
+        },
+      };
+    }
+  }
+
+  const sorted = [...images].sort((a, b) => {
+    if (b.height !== a.height) return b.height - a.height;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+
+  let totalArea = 0;
+  let maxImageWidth = 0;
+  for (const img of sorted) {
+    totalArea += img.width * img.height;
+    if (img.width > maxImageWidth) maxImageWidth = img.width;
+  }
+  let targetWidth = nextPow2(Math.ceil(Math.sqrt(totalArea)));
+  if (maxImageWidth > targetWidth) targetWidth = nextPow2(maxImageWidth);
+  if (targetWidth > maxAtlasSize) targetWidth = maxAtlasSize;
+
+  const regions: AtlasRegion[] = [];
+  let cursorX = 0;
+  let cursorY = 0;
+  const firstHeight = sorted[0]?.height ?? 0;
+  let currentShelfHeight = firstHeight;
+  let usedWidth = 0;
+
+  for (const img of sorted) {
+    if (cursorX + img.width > targetWidth && cursorX !== 0) {
+      cursorY += currentShelfHeight;
+      cursorX = 0;
+      currentShelfHeight = img.height;
+    }
+    if (cursorY + img.height > maxAtlasSize) {
+      return {
+        ok: false,
+        error: {
+          code: 'atlas-size-exceeded',
+          detail: {
+            name: img.name,
+            width: img.width,
+            height: img.height,
+            maxAtlasSize,
+          },
+        },
+      };
+    }
+    regions.push({ name: img.name, x: cursorX, y: cursorY, w: img.width, h: img.height });
+    cursorX += img.width;
+    if (cursorX > usedWidth) usedWidth = cursorX;
+  }
+
+  const usedHeight = cursorY + currentShelfHeight;
+  let atlasWidth = nextPow2(usedWidth);
+  if (atlasWidth > maxAtlasSize) atlasWidth = maxAtlasSize;
+  let atlasHeight = nextPow2(usedHeight);
+  if (atlasHeight > maxAtlasSize) atlasHeight = maxAtlasSize;
+
+  return { ok: true, value: { atlasWidth, atlasHeight, regions } };
+}

package/src/atlas/upng-ambient.d.ts

@@ -0,0 +1,13 @@
+// Ambient declaration for `upng-js` (PNG decoder/encoder) used by the
+// `forgeax-engine-remote-asset atlas` subcommand (run-atlas.ts) and by
+// its hermetic CLI integration tests under `__tests__/`. The package
+// ships without bundled `.d.ts`; consumer sites cast through local
+// interfaces to match the subset they use.
+//
+// Mirrors `packages/image/src/image-decoders.d.ts` so the `import('upng-js')`
+// site in run-atlas.ts type-resolves under tsc -b without an `any` escape
+// hatch leak. The pack package keeps a private declaration here rather
+// than reaching into engine-image (`@forgeax/engine-image` would create a
+// circular dep: image already depends on pack via @forgeax/engine-pack).
+
+declare module 'upng-js';

package/src/bridge.ts

@@ -0,0 +1,2 @@
+// bridge.ts — AssetRegistry bridge placeholder (M2)
+export {};

package/src/builtin.ts

@@ -0,0 +1,79 @@
+import type { AssetGuid } from './guid.js';
+import { AssetGuid as AssetGuidNS } from './guid.js';
+
+/**
+ * ForgeaX engine namespace UUID for UUIDv5 derivation.
+ * Value: 9a09805a-7623-482e-b322-9fc3591f2a38
+ * This is a custom namespace; it is intentionally NOT the RFC 4122 X.500 namespace.
+ */
+const _nsResult = AssetGuidNS.parse('9a09805a-7623-482e-b322-9fc3591f2a38');
+if (!_nsResult.ok) throw new Error('builtin: FORGEAX_NAMESPACE is not a valid UUID');
+export const FORGEAX_NAMESPACE: AssetGuid = _nsResult.value;
+
+/**
+ * Derive a stable UUIDv5 AssetGuid from a name within the ForgeaX namespace.
+ * Uses SHA-1 via Node.js `node:crypto` or Web Crypto API (RFC 4122 §4.3).
+ * Deterministic: same name always produces the same bytes.
+ */
+export async function deriveBuiltin(name: string): Promise<AssetGuid> {
+  const nsBytes = FORGEAX_NAMESPACE;
+  const nameBytes = new TextEncoder().encode(name);
+
+  // Concatenate namespace bytes + name bytes for SHA-1 digest
+  const concat = new Uint8Array(16 + nameBytes.length);
+  concat.set(nsBytes, 0);
+  concat.set(nameBytes, 16);
+
+  let hashBytes: Uint8Array;
+
+  if (typeof globalThis !== 'undefined' && globalThis.crypto?.subtle !== undefined) {
+    // Browser / Web Crypto path
+    const buffer = await globalThis.crypto.subtle.digest('SHA-1', concat);
+    hashBytes = new Uint8Array(buffer);
+  } else {
+    // Node.js path
+    const { createHash } = await import('node:crypto');
+    const hash = createHash('sha1');
+    hash.update(concat);
+    hashBytes = hash.digest();
+  }
+
+  // RFC 4122 §4.3: assemble UUIDv5 from first 16 bytes of SHA-1 digest
+  const uuidBytes = new Uint8Array(16);
+  uuidBytes.set(hashBytes.subarray(0, 16));
+
+  // Set version bits: byte 6, high nibble = 0x5 (version 5)
+  // biome-ignore lint/style/noNonNullAssertion: uuidBytes is 16 bytes
+  uuidBytes[6] = (uuidBytes[6]! & 0x0f) | 0x50;
+  // Set variant bits: byte 8, high 2 bits = 0b10
+  // biome-ignore lint/style/noNonNullAssertion: uuidBytes is 16 bytes
+  uuidBytes[8] = (uuidBytes[8]! & 0x3f) | 0x80;
+
+  return uuidBytes as AssetGuid;
+}
+
+function formatSync(bytes: Uint8Array): string {
+  return AssetGuidNS.format(bytes as AssetGuid);
+}
+
+async function deriveSync(name: string): Promise<string> {
+  return formatSync(await deriveBuiltin(name));
+}
+
+/**
+ * Pre-computed compile-time constant for the HANDLE_CUBE builtin GUID.
+ * Derived from: deriveBuiltin('HANDLE_CUBE') under FORGEAX_NAMESPACE.
+ */
+export const BUILTIN_HANDLE_CUBE = await deriveSync('HANDLE_CUBE');
+
+/**
+ * Pre-computed compile-time constant for the HANDLE_TRIANGLE builtin GUID.
+ * Derived from: deriveBuiltin('HANDLE_TRIANGLE') under FORGEAX_NAMESPACE.
+ */
+export const BUILTIN_HANDLE_TRIANGLE = await deriveSync('HANDLE_TRIANGLE');
+
+/**
+ * Pre-computed compile-time constant for the HANDLE_QUAD builtin GUID.
+ * Derived from: deriveBuiltin('HANDLE_QUAD') under FORGEAX_NAMESPACE.
+ */
+export const BUILTIN_HANDLE_QUAD = await deriveSync('HANDLE_QUAD');