@forgeax/engine-runtime 0.1.2

package/src/components/__tests__/tile-layer.unit.test.ts

@@ -0,0 +1,125 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M1 / w5.
+//
+// Production assertion for `TileLayer.sortScope` (round-2; replaces the
+// round-1 forward-looking type-only lock). The upstream `feat-20260622`
+// chunk system has landed in the rebased branch (D-V-3 confirmation in
+// verify-decisions.md: PR #502 merged 2026-06-26T07:24Z) so `TileLayer`
+// is now an importable runtime component and we can assert the real
+// `sortScope: SortScope` field surface instead of a stand-alone type
+// alias.
+//
+// What round-2 changes vs round-1:
+//   - The literal-union type `SortScope` now comes from
+//     `@forgeax/engine-runtime` (re-exported via the components barrel);
+//     the test imports it instead of redeclaring a parallel type alias.
+//   - We spawn an actual TileLayer entity with `sortScope: 'per-cell'`
+//     and read the bridge u8 (`encodeSortScope('per-cell') === 1`) back
+//     from the column. Forward-looking-only `@ts-expect-error`
+//     assignment checks are kept for the AI-user surface (closed union
+//     remains exhaustive at compile time).
+//
+// Anchors: requirements AC-02 (breaking change, TS-error-only migration);
+// plan-strategy R-NEW-2 (sortScope storage decision); verify-decisions
+// D-V-3 (R-NEW-1 fallback graduation: forward-looking -> production
+// because upstream landed during merge resolution). Charter F1 (single-
+// symbol discovery — `SortScope` grep lands here + `tile-layer.ts`),
+// P1 (progressive disclosure — `'layer'` / `'per-cell'` reads directly).
+
+import { World } from '@forgeax/engine-ecs';
+import {
+  decodeSortScope,
+  encodeSortScope,
+  type SortScope,
+  TileLayer,
+} from '@forgeax/engine-render/authoring';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('TileLayer.sortScope union lock (w5, round-2 production)', () => {
+  it("'layer' is assignable to SortScope", () => {
+    const v: SortScope = 'layer';
+    expectTypeOf<typeof v>().toMatchTypeOf<SortScope>();
+  });
+
+  it("'per-cell' is assignable to SortScope", () => {
+    const v: SortScope = 'per-cell';
+    expectTypeOf<typeof v>().toMatchTypeOf<SortScope>();
+  });
+
+  it('exhaustive switch over SortScope narrows both arms (compile-time)', () => {
+    function classify(s: SortScope): 'terrain' | 'object' {
+      switch (s) {
+        case 'layer':
+          return 'terrain';
+        case 'per-cell':
+          return 'object';
+      }
+    }
+    expectTypeOf(classify).parameter(0).toEqualTypeOf<SortScope>();
+  });
+
+  it('union has exactly the 2 literal members (no widening to string)', () => {
+    expectTypeOf<SortScope>().toEqualTypeOf<'layer' | 'per-cell'>();
+  });
+
+  it('@ts-expect-error: arbitrary strings are not assignable to SortScope', () => {
+    // @ts-expect-error 'random' is outside the closed union.
+    const wrong1: SortScope = 'random';
+    void wrong1;
+    // @ts-expect-error legacy 'ySort' u8 literals are not assignable.
+    const wrong2: SortScope = 0;
+    void wrong2;
+    // @ts-expect-error legacy 'ySort' u8 literals are not assignable.
+    const wrong3: SortScope = 1;
+    void wrong3;
+  });
+});
+
+describe('TileLayer.sortScope production bridge (w5, round-2)', () => {
+  it("encodeSortScope('layer') === 0", () => {
+    expect(encodeSortScope('layer')).toBe(0);
+  });
+
+  it("encodeSortScope('per-cell') === 1", () => {
+    expect(encodeSortScope('per-cell')).toBe(1);
+  });
+
+  it("decodeSortScope(0) === 'layer'", () => {
+    expect(decodeSortScope(0)).toBe('layer');
+  });
+
+  it("decodeSortScope(1) === 'per-cell'", () => {
+    expect(decodeSortScope(1)).toBe('per-cell');
+  });
+
+  it("decodeSortScope(undefined | out-of-range) defaults to 'layer'", () => {
+    expect(decodeSortScope(undefined)).toBe('layer');
+    expect(decodeSortScope(2)).toBe('layer');
+    expect(decodeSortScope(255)).toBe('layer');
+  });
+
+  it('spawn TileLayer with sortScope omitted -> stored u8 = 0 (default layer)', () => {
+    const world = new World();
+    const entity = world
+      .spawn({ component: TileLayer, data: { tiles: new Uint32Array(4) } })
+      .unwrap();
+    const row = world.get(entity, TileLayer).unwrap();
+    expect(row.sortScope).toBe(0);
+    expect(decodeSortScope(row.sortScope)).toBe('layer');
+  });
+
+  it("spawn TileLayer with sortScope: 'per-cell' bridges to stored u8 = 1", () => {
+    const world = new World();
+    const entity = world
+      .spawn({
+        component: TileLayer,
+        data: {
+          tiles: new Uint32Array(4),
+          sortScope: encodeSortScope('per-cell'),
+        },
+      })
+      .unwrap();
+    const row = world.get(entity, TileLayer).unwrap();
+    expect(row.sortScope).toBe(1);
+    expect(decodeSortScope(row.sortScope)).toBe('per-cell');
+  });
+});

package/src/components/__tests__/tilemap.test-d.ts

@@ -0,0 +1,35 @@
+// tilemap.test-d - type-level shape assertions for the Tilemap component schema
+// (feat-20260608 M0 baseline rebuild).
+//
+// Anchors: plan-tasks m0-t3; plan-strategy §M0 targetFiles (tilemap.ts);
+// AGENTS.md §Component naming (single-semantic component drops Component suffix).
+
+import { type SchemaOf, World } from '@forgeax/engine-ecs';
+import { Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf } from '@forgeax/engine-scene';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('Tilemap component schema (M0 baseline)', () => {
+  it('type-level: 5 schema fields (cols / rows / tileSize / tileset / chunkSize)', () => {
+    type Schema = SchemaOf<typeof Tilemap>;
+    const schema: Schema = {
+      cols: 'u32',
+      rows: 'u32',
+      tileSize: 'array<f32, 2>',
+      chunkSize: 'u32',
+      tileset: 'string',
+    };
+    expectTypeOf(schema.cols).toEqualTypeOf<'u32'>();
+    expectTypeOf(schema.rows).toEqualTypeOf<'u32'>();
+    // feat-20260709 M3: tileSizeX/tileSizeY collapsed into one inline
+    // array<f32,2> column (tileSize).
+    expectTypeOf(schema.tileSize).toEqualTypeOf<'array<f32, 2>'>();
+    expectTypeOf(schema.chunkSize).toEqualTypeOf<'u32'>();
+    expectTypeOf(schema.tileset).toEqualTypeOf<'string'>();
+  });
+
+  it('type-level: Tilemap is consumable by world.query({ read: [...] })', () => {
+    const query = new World().query({ read: [Tilemap, ChildOf] });
+    expectTypeOf(query).not.toBeNever();
+  });
+});

package/src/components/__tests__/transform-vec-schema.test.ts

@@ -0,0 +1,121 @@
+// feat-20260709 M2 / w4: Transform TRS scalar->array vec schema (TDD red-first).
+//
+// AC-05 (schema shape): Transform declares pos: array<f32, 3> / quat:
+// array<f32, 4> (order [x,y,z,w]) / scale: array<f32, 3>; the legacy 10
+// per-axis f32 scalar columns (posX..scaleZ) are gone -- one cut, no dual
+// path (Change stance: Optimal > compatible).
+//
+// AC-06 (spawn typing, application-point discipline): a real world.spawn
+// call-site with the array data shape typechecks green; the legacy 10-scalar
+// data shape is locked compile-red via @ts-expect-error (InputShapeOf
+// narrowing + excess property check). No standalone *.test-d.ts -- the
+// assertions live on real spawn call-sites in this runtime test file.
+//
+// E1 / D-6 (default equivalence): spawn with data: {} lands the identity
+// transform -- pos [0,0,0] / quat [0,0,0,1] / scale [1,1,1]. quat and scale
+// carry explicit layer-2 defaults (research Finding 4: the layer-3 fallback
+// for array<f32,N> is all-zero, which would produce an invalid zero
+// quaternion / zero scale).
+
+import { World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+describe('w4 -- Transform vec schema (AC-05)', () => {
+  it('(a) schema declares pos/quat/scale array columns, no per-axis scalars', () => {
+    const schema = componentSchema(Transform) as Record<string, string>;
+    expect(schema.pos).toBe('array<f32, 3>');
+    expect(schema.quat).toBe('array<f32, 4>');
+    expect(schema.scale).toBe('array<f32, 3>');
+
+    for (const legacy of [
+      'posX',
+      'posY',
+      'posZ',
+      'quatX',
+      'quatY',
+      'quatZ',
+      'quatW',
+      'scaleX',
+      'scaleY',
+      'scaleZ',
+    ]) {
+      expect(schema[legacy]).toBeUndefined();
+    }
+  });
+
+  it('(b) world column keeps array<f32, 16> (outside the M2 migration surface)', () => {
+    const schema = componentSchema(Transform) as Record<string, string>;
+    expect(schema.world).toBe('array<f32, 16>');
+  });
+});
+
+describe('w4 -- Transform spawn typing (AC-06, real call-sites)', () => {
+  it('array data shape typechecks green and spawns ok', () => {
+    const world = new World();
+    const r = world.spawn({
+      component: Transform,
+      data: { pos: [0, 6, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    const v = world.get(r.value, Transform);
+    expect(v.ok).toBe(true);
+    if (!v.ok) return;
+    expect(Array.from(v.value.pos)).toEqual([0, 6, 0]);
+    expect(Array.from(v.value.quat)).toEqual([0, 0, 0, 1]);
+    expect(Array.from(v.value.scale)).toEqual([1, 1, 1]);
+  });
+
+  it('legacy 10-scalar data shape is compile-red (InputShapeOf narrowing)', () => {
+    const world = new World();
+    const r = world.spawn({
+      component: Transform,
+      data: {
+        // @ts-expect-error legacy per-axis scalar keys were removed in M2; the
+        // narrowed InputShapeOf rejects them at the spawn call-site (AC-06).
+        posX: 1,
+        posY: 2,
+        posZ: 3,
+        quatX: 0,
+        quatY: 0,
+        quatZ: 0,
+        quatW: 1,
+        scaleX: 1,
+        scaleY: 1,
+        scaleZ: 1,
+      },
+    });
+    // Runtime backstop: the same shape fail-fasts through the structured
+    // spawn error path (SpawnDataUnknownFieldError), not a silent write.
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('w4 -- Transform defaults (E1 / D-6)', () => {
+  it('spawn with data: {} lands the identity transform', () => {
+    const world = new World();
+    const e = world.spawn({ component: Transform, data: {} }).unwrap();
+
+    const r = world.get(e, Transform);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(Array.from(r.value.pos)).toEqual([0, 0, 0]);
+    expect(Array.from(r.value.quat)).toEqual([0, 0, 0, 1]);
+    expect(Array.from(r.value.scale)).toEqual([1, 1, 1]);
+  });
+
+  it('partial spawn keeps omitted columns at their defaults', () => {
+    const world = new World();
+    const e = world.spawn({ component: Transform, data: { pos: [4, 5, 6] } }).unwrap();
+
+    const r = world.get(e, Transform);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(Array.from(r.value.pos)).toEqual([4, 5, 6]);
+    expect(Array.from(r.value.quat)).toEqual([0, 0, 0, 1]);
+    expect(Array.from(r.value.scale)).toEqual([1, 1, 1]);
+  });
+});

package/src/create-renderer-env-classify.ts

@@ -0,0 +1,110 @@
+// Outer-message classifier for `EngineEnvironmentError`. Split out of
+// createRenderer.ts so it can be unit-tested without booting the renderer.
+//
+// Why: `createRenderer` wraps Channel 2 / Channel 3 backend failures in a
+// single `EngineEnvironmentError("no usable rendering backend", { ... })`.
+// When the inner failure is genuinely GPU-class (`adapter-unavailable`,
+// `feature-not-enabled`, ...) that wording is correct. When the inner
+// failure is `ShaderError(manifest-malformed)` / `PackError` / `AssetError`
+// the same wording sends downstream investigation chasing GPU adapter caps
+// for hours -- exactly what happened in the 2026-06-09 Studio diagnosis
+// (see `docs/feedbacks/2026-06-09-webkit-hdr-pipeline-runs-on-safari-26-release.md`).
+//
+// The classifier preserves the GPU wording for genuine adapter / device /
+// feature / limit / OOM / device-lost failures and switches to
+// `engine init failed (<Name>: <code>)` for everything else, so an AI user
+// reading either `error.message` (text) or the structured `.detail` lands
+// on the right hypothesis at first glance.
+
+const ENV_GPU_CLASS_RHI_CODES: ReadonlySet<string> = new Set([
+  'adapter-unavailable',
+  'feature-not-enabled',
+  'limit-exceeded',
+  'rhi-not-available',
+  'device-lost',
+  'oom',
+]);
+
+/**
+ * Pick an outer EngineEnvironmentError message based on the inner failure shape.
+ *
+ * @param baseGpuMessage  The historical GPU-class wording, e.g.
+ *                        `'no usable rendering backend'` or
+ *                        `'no usable rendering backend (Channel 3 fallback failed)'`.
+ *                        Returned verbatim for GPU-class inner errors.
+ * @param primary         The inner error (RhiError / ShaderError / PackError /
+ *                        AssetError / raw Error / undefined). Inspected
+ *                        structurally; never narrowed to a class.
+ * @returns               The chosen outer message string.
+ */
+export function classifyEnvErrorReason(
+  baseGpuMessage: string,
+  primary: { code?: unknown; name?: unknown } | undefined,
+): string {
+  if (!primary || typeof primary !== 'object') return baseGpuMessage;
+  const code = (primary as { code?: unknown }).code;
+  if (typeof code === 'string' && ENV_GPU_CLASS_RHI_CODES.has(code)) {
+    return baseGpuMessage;
+  }
+  const name =
+    typeof (primary as { name?: unknown }).name === 'string'
+      ? (primary as { name: string }).name
+      : 'inner';
+  if (typeof code === 'string' && code.length > 0) {
+    return `engine init failed (${name}: ${code})`;
+  }
+  return `engine init failed (${name})`;
+}
+
+/**
+ * bug-20260610-edge-webgpu-disabled-fallback: detect the
+ * "browser is configured to disable hardware GPU acceleration" pattern.
+ *
+ * Symptom (observed on Edge 149 with `edge://flags/#enable-unsafe-webgpu = Disabled`):
+ *   - `navigator.gpu` is truthy (Edge keeps the property for compat sniffing)
+ *   - `canvas.getContext('webgpu')` returns a non-null context (also sniffing-compat)
+ *   - `navigator.gpu.requestAdapter()` returns `null` (the real "off" signal)
+ *   - All WebGL contexts (`webgl`, `webgl2`, `experimental-webgl`) return `null`
+ *     globally — Edge ties the WebGPU flag to the entire hardware GL stack.
+ *   - Only Canvas2D survives.
+ *
+ * Engine result: Channel 2 (rhi-webgpu) fails with `adapter-unavailable`; Channel 3
+ * (rhi-wgpu wasm GL backend) fails with `adapter-unavailable` because the wasm
+ * backend cannot create a WebGL2 context. Both inner errors are GPU-class so
+ * `classifyEnvErrorReason` (correctly) keeps the GPU wording on the outer
+ * message — but a downstream AI user needs to know **this is a browser-config
+ * issue, not a real GPU absence**.
+ *
+ * The pattern is Channel-2-error.code='adapter-unavailable' AND Channel-3-error
+ * also surfaces `adapter-unavailable` / `rhi-not-available` (i.e. *both*
+ * channels report environmental failure rather than asset / shader / pipeline
+ * errors). When matched, append browser-config guidance to the outer message
+ * so it lands in `error.message` and the bootstrap report.
+ *
+ * Returns `undefined` when the pattern does not match — the caller composes
+ * the existing `(reason)` message verbatim (zero-regression for every
+ * non-Edge-flag-disabled scenario).
+ */
+const ENV_DUAL_CHANNEL_ENV_FAIL_CODES: ReadonlySet<string> = new Set([
+  'adapter-unavailable',
+  'rhi-not-available',
+]);
+
+export function composeEnvErrorHint(webgpuError: unknown, wgpuError: unknown): string | undefined {
+  const c1 = (webgpuError as { code?: unknown } | undefined)?.code;
+  const c2 = (wgpuError as { code?: unknown } | undefined)?.code;
+  const w1 = typeof c1 === 'string' ? c1 : undefined;
+  const w2 = typeof c2 === 'string' ? c2 : undefined;
+  if (w1 === undefined || w2 === undefined) return undefined;
+  if (!ENV_DUAL_CHANNEL_ENV_FAIL_CODES.has(w1)) return undefined;
+  if (!ENV_DUAL_CHANNEL_ENV_FAIL_CODES.has(w2)) return undefined;
+  return [
+    'both channels report environmental failure',
+    'on Edge: check edge://flags/#enable-unsafe-webgpu is Enabled (Disabled also blocks WebGL2 in 149+)',
+    'on Chrome/Firefox: re-enable hardware acceleration in browser settings',
+  ].join('; ');
+}
+
+/** Test-only export — keeps the public API surface limited to the named functions above. */
+export const __classifyEnvErrorReasonForTest = classifyEnvErrorReason;
+export const __composeEnvErrorHintForTest = composeEnvErrorHint;

package/src/createRenderer.ts

@@ -0,0 +1,61 @@
+// Runtime is the host assembly facade. Concrete Renderer construction and
+// frame interpretation live in @forgeax/engine-render/internal.
+import type { BundlerOptions, Renderer, RendererOptions } from '@forgeax/engine-render/internal';
+import { constructRenderer } from '@forgeax/engine-render/internal/construct-renderer';
+import { EngineEnvironmentError } from './errors/environment';
+
+export async function createRenderer(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+  options?: RendererOptions,
+  bundler?: BundlerOptions,
+): Promise<Renderer> {
+  if (options !== undefined && 'rhi' in options && options.rhi === undefined) {
+    throw new EngineEnvironmentError('no usable rendering backend');
+  }
+  const rendererOptions: RendererOptions | undefined =
+    options === undefined
+      ? undefined
+      : {
+          ...(options.rhi === undefined ? {} : { rhi: options.rhi }),
+          ...(options.rawDeviceForContextConfigure === undefined
+            ? {}
+            : { rawDeviceForContextConfigure: options.rawDeviceForContextConfigure }),
+          ...(options.features === undefined ? {} : { features: options.features }),
+          ...(options.profiler === undefined ? {} : { profiler: options.profiler }),
+          ...(options.membershipTiming === undefined
+            ? {}
+            : { membershipTiming: options.membershipTiming }),
+          ...(options.rhiInstrumentation === undefined
+            ? {}
+            : { rhiInstrumentation: options.rhiInstrumentation }),
+        };
+  try {
+    return await constructRenderer(canvas, rendererOptions, bundler);
+  } catch (cause) {
+    if (isStructuredRenderError(cause)) throw cause;
+    if (cause instanceof EngineEnvironmentError) throw cause;
+    const detail = cause instanceof Error ? cause : new Error(String(cause));
+    throw new EngineEnvironmentError('renderer construction failed', { webgpuError: detail });
+  }
+}
+
+function isStructuredRenderError(value: unknown): value is Error & {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: unknown;
+} {
+  if (!(value instanceof Error)) return false;
+  const candidate = value as Partial<{
+    code: unknown;
+    expected: unknown;
+    hint: unknown;
+    detail: unknown;
+  }>;
+  return (
+    typeof candidate.code === 'string' &&
+    typeof candidate.expected === 'string' &&
+    typeof candidate.hint === 'string' &&
+    candidate.detail !== undefined
+  );
+}

package/src/dev-import-transport.ts

@@ -0,0 +1,97 @@
+// dev-import-transport.ts -- the dev-only ImportTransport adapter (M4 / w15,
+// AC-04). A host explicitly wires this into createRenderer / createApp so a
+// DDC miss at runtime triggers an on-demand import against the vite-plugin-pack
+// dev server (POST to the binding's scoped import endpoint). The shipped form
+// unwired so a miss fails fast with `asset-not-imported` (AC-08).
+//
+// Pure browser fetch -- no Node-only dependency (AC-04), no import.meta.env /
+// import.meta.hot / NODE_ENV probe (AC-05 / OOS-1: host-explicit assembly is
+// the only path, the library never auto-detects dev vs prod). The module also
+// never imports @forgeax/engine-image (image-pipeline-isolation: runtime/src
+// must not statically depend on the image package).
+
+import type { ImportTransport, PackIndexEntry, RuntimeAssetBinding } from '@forgeax/engine-types';
+
+export type DevImportTransportBinding = Pick<
+  RuntimeAssetBinding,
+  'scopeId' | 'generation' | 'status' | 'importUrlBase'
+>;
+
+/**
+ * Build the dev-only {@link ImportTransport}. A caller must provide the
+ * current runtime binding; `fetchPack(guid)` then issues a scoped POST against
+ * the vite-plugin-pack dev server, which imports
+ * exactly that GUID's `.bin` and returns the single imported catalog row (+ any
+ * sub-asset siblings). The caller patches those rows into its catalog cache
+ * incrementally -- per-asset, never a whole-catalog re-fetch (the four-verb
+ * redesign, 2026-06-06). On a non-2xx / network failure it reports
+ * `{ ok: false }`.
+ *
+ * Aligns with the `wireDefaultLoaders` `create*` / `wire*` factory family so
+ * IDE autocomplete on `@forgeax/engine-runtime` surfaces it.
+ *
+ * @example
+ *   import { createApp } from '@forgeax/engine-app';
+ *   import { createDevImportTransport } from '@forgeax/engine-runtime';
+ *   const app = await createApp(canvas, opts, {
+ *     importTransport: createDevImportTransport(runtimeBinding),
+ *   });
+ */
+export function createDevImportTransport(binding?: DevImportTransportBinding): ImportTransport {
+  return {
+    async fetchPack(
+      guid: string,
+      scope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation' | 'status'>,
+    ): Promise<
+      { readonly ok: true; readonly entries?: readonly PackIndexEntry[] } | { readonly ok: false }
+    > {
+      const active = binding;
+      if (
+        active === undefined ||
+        active.status !== 'ready' ||
+        scope === undefined ||
+        scope.status !== 'ready' ||
+        scope.scopeId !== active.scopeId ||
+        scope.generation !== active.generation
+      ) {
+        return { ok: false };
+      }
+      try {
+        const base = active.importUrlBase.replace(/\/+$/, '');
+        const response = await fetch(`${base}/${encodeURIComponent(guid)}`, { method: 'POST' });
+        if (!response.ok) {
+          // The ImportTransport contract has no error channel (returns only
+          // ok:false), so the runtime would otherwise report a generic
+          // `asset-not-imported`. Surface the dev server's structured failure
+          // body (e.g. `code: fbx-mesh-type-unsupported`, reason, hint) to the
+          // console so the actual cause is visible to AI/human users.
+          try {
+            const fail = (await response.json()) as {
+              code?: string;
+              reason?: string;
+              hint?: string;
+            };
+            console.warn(
+              `[forgeax] import failed for ${guid} (HTTP ${response.status}): ` +
+                `${fail.code ?? 'import-failed'} - ${fail.reason ?? ''}` +
+                (fail.hint ? ` | hint: ${fail.hint}` : ''),
+            );
+          } catch {
+            // Non-JSON error body; nothing extra to surface.
+          }
+          return { ok: false };
+        }
+        try {
+          const body = (await response.json()) as unknown;
+          if (Array.isArray(body)) return { ok: true, entries: body as readonly PackIndexEntry[] };
+        } catch {
+          // Body was not JSON (or empty) -- success without inline rows; the
+          // caller re-resolves the GUID from its cache.
+        }
+        return { ok: true };
+      } catch {
+        return { ok: false };
+      }
+    },
+  };
+}

package/src/errors/environment.ts

@@ -0,0 +1,6 @@
+// Runtime keeps this import path for its public assembly error contract, while
+// render owns the canonical construction error and its structured details.
+export {
+  EngineEnvironmentError,
+  type EngineEnvironmentErrorDetail,
+} from '@forgeax/engine-render/internal';

package/src/errors/sprite-animation.ts

@@ -0,0 +1,5 @@
+// Runtime-owned animation tick failures.
+
+export type SpriteAnimationErrorCode = 'sprite-animation-invalid';
+
+export { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';