typescript-sprite-pack-wiring

Answer

Four coordinated changes. Canonical rule: routing is path-based — spriteSheetPath on the config entry is the source of truth; the inventory (SPRITE-INVENTORY.md) maps path → metadata. No registry, no procedural fallback.

1. Schemas: stop rejecting spriteSheetPath

The strict schemas used additionalProperties: false but never declared the field, so valid configs were rejected and entries shipped without it.

// src/config/schemas.ts
export const ENEMY_SCHEMA = {
  type: "object",
  properties: {
    id: { type: "string" },
    name: { type: "string" },
    hp: { type: "integer" },
    spriteSheetPath: { type: "string", minLength: 1 }, // was: absent -> rejected
  },
  required: ["id", "name", "hp", "spriteSheetPath"], // required: no silent procedural art
  additionalProperties: false,
} as const;

export const BOSS_SCHEMA = { /* same shape, plus phases, spriteSheetPath required */ } as const;

2. Routing: path-based resolver replaces the registry

Delete sheetIdForEntity(entityId) / subjectForSheetId(sheetId) and their hand-maintained registry. The resolver reads the config path and looks metadata up by path:

// src/sprites/routing.ts
export function resolveSheetForEntity(entry: EntityConfig): ResolvedSheet {
  const path = entry.spriteSheetPath;
  if (!path) {
    throw new RoutingError(
      `cannot resolve sprite for "${entry.id}": spriteSheetPath not set (procedural art disabled)`,
    );
  }
  const meta = assertRegistered(path); // throws on orphan pack
  return { entityId: entry.id, path, sheetId: meta.sheetId, subject: meta.subject, metadata: meta };
}

Call sites that did sheetIdForEntity(e.id) → subjectForSheetId(...) now call resolveSheetForEntity(e) and render from resolved.path/resolved.metadata.

3. Metadata: register the dash-2.png orphan

sprites/dash/dash-2.png existed on disk but had no inventory entry, so path routing could never resolve it. Register it (canonical source: SPRITE-INVENTORY.md):

// src/sprites/manifest.ts  (mirrors SPRITE-INVENTORY.md)
{
  sheetId: "dash-2",
  subject: "dash",
  pack: "dash",
  path: "sprites/dash/dash-2.png",
  frameWidth: 48,
  frameHeight: 48,
  frameCount: 2,
  anchorX: 0.5,
  anchorY: 0.9,
},

export function assertRegistered(path: string): SheetMetadata {
  const meta = byPath.get(path);
  if (!meta) throw new Error(`sprite pack "${path}" is not registered in SPRITE_INVENTORY`);
  return meta;
}

4. Boot: malformed pack aborts boot — no procedural fallback

Remove the catch { renderProcedural(...) } around pack loading. Validation (registered, on-disk, header format, frame geometry, frame count) throws; boot propagates and aborts:

// src/sprites/packs.ts
export function loadPack(path: string): LoadedPack {
  assertRegistered(path);                       // orphan -> error
  const header = readPackHeader(path);          // missing -> PackError
  if (header.format !== "png-v1") throw new PackError(...);
  const meta = assertRegistered(path);
  const frames = (header.width / meta.frameWidth) * (header.height / meta.frameHeight);
  if (!Number.isInteger(frames) || frames !== header.frameCount || frames !== meta.frameCount) {
    throw new PackError(`"${path}" frame geometry/count mismatch ...`);
  }
  return { ...header, validated: true };
}

// src/boot.ts
export function bootGame(entries: readonly EntityConfig[]): Map<string, RenderDescriptor> {
  const renderers = new Map<string, RenderDescriptor>();
  for (const entry of entries) {
    const resolved = resolveSheetForEntity(entry);   // throws -> boot aborts
    const pack = loadPack(resolved.path);            // throws -> boot aborts
    renderers.set(entry.id, renderEntity(entry, resolved, pack));
  }
  return renderers; // never partial: any failure throws
}