@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/src/atlas/shelf-pack.ts

@@ -0,0 +1,172 @@
+// 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 sizeExceeded(
+  image: AtlasImageInput,
+  maxAtlasSize: number,
+): { readonly ok: false; readonly error: ShelfPackError } {
+  return {
+    ok: false,
+    error: {
+      code: 'atlas-size-exceeded',
+      detail: {
+        name: image.name,
+        width: image.width,
+        height: image.height,
+        maxAtlasSize,
+      },
+    },
+  };
+}
+
+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 sizeExceeded(img, 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 sizeExceeded(img, 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/build.ts

@@ -0,0 +1,139 @@
+// @forgeax/engine-pack/build
+// Node-only catalog, source scanning, package finalization, and build evidence.
+
+export type {
+  AnimationClip,
+  AnimationGraph,
+  Asset,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  MaterialAsset,
+  MeshAsset,
+  PackV2,
+  PackV2Error,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+export type { ArtifactPathContext } from './artifact-path.js';
+export { validateArtifactPath } from './artifact-path.js';
+export {
+  buildCatalogProjection,
+  type CatalogAuthority,
+  type CatalogBuildError,
+  type CatalogBuildErrorCode,
+  type CatalogBuildProjectionOptions,
+  type CatalogBuildResult,
+  type CatalogImporterPolicy,
+  type CatalogProducerVisibility,
+  metaPathForGuid,
+} from './catalog-builder.js';
+export { calculateCatalogDelta } from './catalog-delta.js';
+export {
+  type CatalogOutputDeclaration,
+  type CatalogProducerMeta,
+  type CookedPackageProjection,
+  catalogProjectionFor,
+  currentProjectionFor,
+  findReservedAssetKindConflict,
+  type PackageCatalogInput,
+  projectCookedPackageEntry,
+  projectExternalCatalogEntries,
+  projectPackageCatalog,
+  projectRuntimeCatalogRow,
+  type RuntimeCatalogRowInput,
+} from './catalog-projection.js';
+export { type LoadAssetConfigResult, loadAssetConfig } from './config.js';
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  type MaterialCookArtifact,
+  type MaterialCookIdentityExpectation,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  serializeMaterialCookReceipt,
+  validateCookedMaterialRecord,
+  validateMaterialCookReceipt,
+} from './evidence/material-cook.js';
+export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';
+export {
+  decodeMeshBinHeader,
+  MESH_BIN_DIGEST_BYTES,
+  MESH_BIN_HEADER_V4_BYTES,
+  MESH_BIN_PROJECTION_VERSION,
+  MESH_BIN_VERSION,
+  type MeshBinContractError,
+  type MeshBinHeaderResult,
+  type MeshBinHeaderV4,
+  writeMeshBinHeader,
+} from './mesh-bin-contract.js';
+export {
+  type AuthoredPackAssetInput,
+  type AuthoredPackInput,
+  type FinalizedPackageProduct,
+  finalizePackageProduct,
+  finalizePackageTransportSource,
+  type PackageArtifactBody,
+  type PackageFinalizePolicy,
+  type PackageFinalizeResult,
+  type PackageFinalizerError,
+  type PackageProduct,
+  type PackageProductAsset,
+  packageTransportRevision,
+  upgradeLegacyAuthoredPack,
+} from './package-finalizer.js';
+export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
+export { resolveAssetSource } from './resolve-asset-source.js';
+export { parsePackV2, validateMeta, validatePack, validatePackV2 } from './runtime.js';
+export {
+  createRuntimePackPublication,
+  type RuntimePackAssetInput,
+  type RuntimePackEnvelope,
+  type RuntimePackInput,
+  type RuntimePackPublication,
+  type RuntimePackPublicationInput,
+} from './runtime-publication.js';
+export {
+  type InventoryDeclaration,
+  type ScanInventory,
+  type ScanOptions,
+  type ScriptablePackInventoryDeclaration,
+  type ScriptablePackScanOptions,
+  STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS,
+  scanInventory,
+} from './scanner.js';
+export {
+  type AssetReader,
+  isScriptablePackAssetKind,
+  projectScriptablePackMeta,
+  projectScriptablePackSceneComponents,
+  SCRIPTABLE_PACK_ASSET_KINDS,
+  SCRIPTABLE_PACK_CAPABILITY_MANIFEST,
+  type ScriptablePackAssetDeclaration,
+  type ScriptablePackAssetDeclarations,
+  type ScriptablePackAssetFor,
+  type ScriptablePackAssetKind,
+  type ScriptablePackDefinition,
+  type ScriptablePackError,
+  type ScriptablePackExternalAssets,
+  type ScriptablePackMetaJson,
+  type ScriptablePackOutputs,
+  type ScriptablePackPublicationEnvelope,
+  type ScriptablePackReadError,
+  type ScriptablePackSceneComponent,
+  type ScriptablePackSceneComponentInput,
+  type ScriptablePackSourceClosureEntry,
+  validateScriptablePackDefinition,
+} from './scriptable-pack.js';
+export { calculateTopologyDiff, diffTopology } from './topology.js';

package/src/builtin.ts

@@ -0,0 +1,117 @@
+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');
+
+/** Pre-computed UUIDv5 for the Engine-owned sphere mesh descriptor. */
+export const BUILTIN_HANDLE_SPHERE = await deriveSync('HANDLE_SPHERE');
+
+/** Pre-computed UUIDv5 for the Engine-owned nine-slice quad descriptor. */
+export const BUILTIN_HANDLE_NINESLICE_QUAD = await deriveSync('HANDLE_NINESLICE_QUAD');
+
+/** Pre-computed UUIDv5 for the Engine-owned cylinder mesh descriptor. */
+export const BUILTIN_HANDLE_CYLINDER = await deriveSync('HANDLE_CYLINDER');
+
+export type BuiltinMeshGeometry =
+  | 'procedural-cube'
+  | 'procedural-triangle'
+  | 'procedural-quad'
+  | 'procedural-sphere'
+  | 'procedural-nine-slice-quad'
+  | 'procedural-cylinder';
+
+/**
+ * The complete Engine-owned procedural mesh catalog.
+ *
+ * These are Pack descriptors, not runtime payloads: the Geometry decoder
+ * expands each `geometry` token into its validated MeshAsset. DevKit uses this
+ * list to materialize only the descriptors a standalone project does not
+ * already author, keeping the shipped game self-contained without duplicate
+ * GUID declarations.
+ */
+export const BUILTIN_MESH_ASSETS: ReadonlyArray<{
+  readonly guid: string;
+  readonly geometry: BuiltinMeshGeometry;
+}> = Object.freeze([
+  { guid: BUILTIN_HANDLE_CUBE, geometry: 'procedural-cube' },
+  { guid: BUILTIN_HANDLE_TRIANGLE, geometry: 'procedural-triangle' },
+  { guid: BUILTIN_HANDLE_QUAD, geometry: 'procedural-quad' },
+  { guid: BUILTIN_HANDLE_SPHERE, geometry: 'procedural-sphere' },
+  { guid: BUILTIN_HANDLE_NINESLICE_QUAD, geometry: 'procedural-nine-slice-quad' },
+  { guid: BUILTIN_HANDLE_CYLINDER, geometry: 'procedural-cylinder' },
+]);