@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/createRenderer.ts

@@ -1,61 +1,49 @@
 // 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';
+// frame interpretation live in the render owner assembly.
+import type { RenderError, Renderer, RendererOptions } from '@forgeax/engine-render';
+import type { BundlerOptions } from '@forgeax/engine-render/internal/construct-renderer';
+import { err, ok, type Result } from '@forgeax/engine-types';
 import { EngineEnvironmentError } from './errors/environment';
+import { constructRuntimeRendererHost } from './renderer-host';
 
+/**
+ * Assemble the sole public renderer host.
+ *
+ * Runtime owns backend selection and partial-construction cleanup. Render owns
+ * the scene/frame contract; successful construction returns the host that
+ * exposes attach, draw, inspect, observe, and recover. Expected failures are
+ * structured Result errors at the owning boundary; environment failures retain
+ * EngineEnvironmentError recovery guidance for the caller.
+ */
 export async function createRenderer(
   canvas: HTMLCanvasElement | OffscreenCanvas,
   options?: RendererOptions,
   bundler?: BundlerOptions,
-): Promise<Renderer> {
+): Promise<Result<Renderer, EngineEnvironmentError | RenderError>> {
   if (options !== undefined && 'rhi' in options && options.rhi === undefined) {
-    throw new EngineEnvironmentError('no usable rendering backend');
+    return err(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 }),
+          ...(options.standardProfile === undefined
+            ? {}
+            : { standardProfile: options.standardProfile }),
         };
   try {
-    return await constructRenderer(canvas, rendererOptions, bundler);
+    const constructed = await constructRuntimeRendererHost(canvas, rendererOptions, bundler);
+    if (!constructed.ok) return err(constructed.error);
+    return ok(constructed.value.renderer);
   } catch (cause) {
-    if (isStructuredRenderError(cause)) throw cause;
-    if (cause instanceof EngineEnvironmentError) throw cause;
+    if (cause instanceof EngineEnvironmentError) return err(cause);
     const detail = cause instanceof Error ? cause : new Error(String(cause));
-    throw new EngineEnvironmentError('renderer construction failed', { webgpuError: detail });
+    return err(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/errors/environment.ts

@@ -3,4 +3,4 @@
 export {
   EngineEnvironmentError,
   type EngineEnvironmentErrorDetail,
-} from '@forgeax/engine-render/internal';
+} from '@forgeax/engine-render/internal/construct-renderer';

package/src/index.ts

@@ -1,18 +1,16 @@
 // @forgeax/engine-runtime — public API surface (M3).
 //
 // Surface (K-4):
-//   - createRenderer(canvas, options?) — async factory; uses WebGPU
-//     exclusively; throws EngineEnvironmentError when no adapter is usable.
-//   - Renderer / RendererOptions / RendererBackend / RendererLostInfo /
+//   - createRenderer(canvas, options?) — async Result factory; uses WebGPU
+//     exclusively and returns EngineEnvironmentError or RenderError on failure.
+//   - Renderer / RendererOptions / RendererLostInfo /
 //     RendererLostListener — types for callers.
-//   - EngineEnvironmentError — thrown when no backend is usable.
+//   - EngineEnvironmentError — returned when no backend is usable.
 //
 // What is **NOT** here, by design (acceptance grep checks negative existence):
 //   - any internal backend module — locked by `package.json#exports`
 //     entry `"./internal/*": null`.
 
-import { createRenderer as _createRendererForEngineAlias } from './createRenderer';
-
 /**
  * `acquireCanvasContext` facade re-export (M3 D-P3 / w15).
  *
@@ -27,7 +25,6 @@ import { createRenderer as _createRendererForEngineAlias } from './createRendere
  */
 export { acquireCanvasContext } from '@forgeax/engine-rhi-webgpu';
 export { defaultAssetDecoderContributions } from './asset-contributions';
-export { builtinAssetKind } from './asset-kind';
 export { createRenderer } from './createRenderer';
 
 // feat-20260704-runtime-tier1-decomposition M2 / w10 (D-3 / D-9): the top-level
@@ -38,53 +35,17 @@ export { createRenderer } from './createRenderer';
 // ./errors/<cluster> (NOT the transitional errors.ts barrel, deleted in w15;
 // NOT the @forgeax/engine-types zombie RuntimeErrorCode -- D-9).
 
-// Asset loading contracts live in @forgeax/engine-assets-runtime. This barrel
-// stays focused on renderer assembly and never re-exports asset-core symbols.
+// feat-20260705-runtime-tier2-decomposition M1 / w14: the asset cluster error
+// re-exports (AssetRuntimeError / *Detail types + MaterialResolvedEmptyPasses /
+// SceneCollect* classes) moved to @forgeax/engine-assets-runtime. Consumers
+// import them from that package directly (AC-105: runtime barrel exports zero
+// asset-cluster symbols).
 // -- environment cluster --
 export { EngineEnvironmentError } from './errors/environment';
-export {
-  type SpriteAnimationErrorCode,
-  SpriteAnimationInvalidError,
-} from './errors/sprite-animation';
 // -- recover cluster --
 // -- render cluster --
 // -- skin cluster --
 
-/**
- * `Engine` namespace alias for `createRenderer` (w55 round 2 fix-up F-3
- * closure). Plan-strategy §7.1 / §7.2 / §7.4 + requirements.md §AI User
- * Affordances reference the factory in `Engine.create({ canvas })` form;
- * the concrete code-level entry is `createRenderer(canvas, options?)`. To
- * keep both call sites valid without forcing a doc-wide rewrite (the
- * plan/requirements text is appended-only audit history per architecture
- * principle 7), the namespace alias re-exports `createRenderer` under the
- * `Engine.create` shape — AI users can write either form and TypeScript
- * resolution lands on the same factory.
- *
- * Single SSOT: the runtime behaviour, signatures, and JSDoc all live on
- * `createRenderer`; `Engine.create` is a thin re-export (charter
- * proposition 1 progressive disclosure — both names are grep-able + lead
- * to the same body; proposition 5 consistent abstraction — the alias does
- * not introduce a second factory shape).
- *
- * Usage parity:
- *
- *   import { createRenderer } from '@forgeax/engine-runtime';
- *   const renderer = await createRenderer(canvas, { ... }, bundler?);
- *
- *   // identical:
- *   import { Engine } from '@forgeax/engine-runtime';
- *   const renderer = await Engine.create(canvas, { ... }, bundler?);
- *
- * feat-20260608-create-app-param-surface-trim / M2 / R-8: Engine.create
- * is a thin re-export of createRenderer; the third BundlerOptions arg
- * forwards verbatim through the alias (no separate Engine.create
- * implementation -- `create: createRenderer` shape).
- */
-export const Engine = {
-  create: _createRendererForEngineAlias,
-} as const;
-
 // ─── ECS render bridge (feat-20260509-ecs-render-bridge-mvp) ────────────────
 //
 // Single-import surface for the 5-component schema set + builtin asset handles
@@ -110,20 +71,19 @@ export const Engine = {
  * Read both fields directly through typed property access after the
  * `code === 'limit-exceeded'` discriminant narrows `err.detail`.
  *
- * The `Renderer.onError` channel fans out **both** error families —
- * `RhiError` (RHI layer) and `RuntimeError` (runtime layer, e.g.
- * `'equirect-projection-failed'`) — so the listener parameter is the
- * `RhiError | RuntimeError` union (feat-20260531-skybox-env-background:
- * widened from `RhiError` only, dropping the prior `as any` fan-out cast).
- * The disjoint `RhiErrorCode` / `RuntimeErrorCode` literal sets let
- * `switch (e.code)` narrow each arm to the concrete class without a default.
+ * The `Renderer.subscribe` channel projects renderer-owned failures through
+ * one `RendererEvent` union. The public operation error is always `RenderError`;
+ * lower-layer causes remain structured in its detail instead of creating a
+ * second listener/error authority.
  *
  * @example
  *   import {
  *     RhiError, type RhiErrorCode, type LimitExceededDetail,
  *   } from '@forgeax/engine-runtime';
- *   import { type EquirectProjectionFailedDetail, type RendererError } from '@forgeax/engine-render';
- *   renderer.onError((e: RendererError) => {
+ *   import { type RenderError } from '@forgeax/engine-render';
+ *   renderer.subscribe((event) => {
+ *     if (event.kind !== 'error') return;
+ *     const e: RenderError = event.error;
  *     switch (e.code) {
  *       case 'limit-exceeded': {
  *         const detail = e.detail as LimitExceededDetail;
@@ -148,20 +108,6 @@ export {
   type RhiShaderCompileDetail,
   type RhiWebgpuRuntimeDetail,
 } from '@forgeax/engine-rhi';
-/**
- * feat-20260527-sprite-nineslice M4 / w16 (D-5 + AC-16): per-Renderer
- * EngineMetrics counter. Surfaced through `renderer.metrics`; exported here
- * so AI users can grep `EngineMetrics` and reach the public type for ts
- * generics, and so test utilities can construct a free-standing instance.
- *
- * @example
- *   const renderer = await createRenderer(canvas);
- *   // ...later, after the world has rendered for a few frames...
- *   const counts = renderer.metrics.snapshot();
- *   if (counts['nineslice.scale-too-small'] !== undefined) {
- *     // surface a once-per-session UI hint, run a regression bench, etc.
- *   }
- */
 /**
  * Asset system SSOT re-exports (feat-20260511-asset-system-v1 / w30 / D-P7 +
  * plan-strategy §7.4 discoverability dual-entry).
@@ -170,7 +116,7 @@ export {
  * 4-member union + `AssetError` class + `ASSET_ERROR_HINTS` per-code hint table);
  * this barrel is a thin re-export so AI users can write a single-line import —
  *
- *   import type { Asset } from '@forgeax/engine-types';
+ *   import type { Asset } from '@forgeax/engine-assets-runtime';
  *   import type { Handle } from '@forgeax/engine-types';
  *   import { AssetError } from '@forgeax/engine-runtime';
  *
@@ -191,9 +137,14 @@ export {
   type TextureAsset,
   type VertexAttributeMap,
 } from '@forgeax/engine-types';
-// Asset payload types are imported from @forgeax/engine-types. Primitive mesh
-// payloads are owned by @forgeax/engine-geometry and become ordinary per-World
-// shared references during host assembly.
+// feat-20260705-runtime-tier2-decomposition M1 / w14: Asset / MeshAsset types
+// moved to @forgeax/engine-assets-runtime (AC-105).
+// feat-20260705-runtime-tier2-decomposition M1 / w14: AssetRegistry + the
+// HANDLE_* builtin mesh handles moved to @forgeax/engine-assets-runtime (AC-105).
+// feat-20260705-runtime-tier2-decomposition M1 / w14: the process-static
+// BuiltinAssetRegistry tier (BUILTIN_* payloads) moved to
+// @forgeax/engine-assets-runtime (AC-105). Geometry owns the shared runtime
+// vertex layout.
 // Runtime-specific authoring components remain here. Domain authorities are
 // imported directly from @forgeax/engine-scene, @forgeax/engine-animation,
 // @forgeax/engine-skinning, and @forgeax/engine-render.
@@ -233,9 +184,8 @@ export { createDevImportTransport } from './dev-import-transport';
  * glyphTextLayoutSystem (feat-20260531-world-space-msdf-text-rendering) -- lays
  * out + bakes every `GlyphText` entity, attaching MeshFilter + MeshRenderer on
  * first observation and re-baking in place on a text / size / color change.
- * `renderer.attachWorld(world)` installs this derived-state owner before the
- * first `world.update()`; `renderer.draw()` only reads the published result.
- * `createApp` performs the attachment automatically.
+ * `createApp` attaches the World and owns the returned render lease before
+ * the first frame; `Renderer.draw` consumes only that lease-bound request.
  */
 /**
  * GpuBuffer / GpuTexture runtime wrappers + GpuResource union
@@ -253,12 +203,10 @@ export { createDevImportTransport } from './dev-import-transport';
  * `Result.err({ code: 'destroy-after-destroy' })`.
  */
 /**
- * feat-20260601-gpu-resource-store-extraction M1: the GPU residency store.
- * Reachable as `renderer.store`; exported here so AI users can construct one
- * directly for tests and `grep GpuResourceStore` discovers it.
  */
-// Runtime decoders are installed by Runtime/App assembly through the typed
-// AssetRegistry lease seam; this barrel does not expose a second loader table.
+// feat-20260705-runtime-tier2-decomposition M1 / w14: the loader-injection
+// surface (LoaderRegistry / wireDefaultLoaders / createDefaultLoaderRegistry)
+// moved to @forgeax/engine-assets-runtime (AC-105).
 // feat-20260705-runtime-tier2-decomposition M2 / w25: the picking cluster
 // (pick / pickVertex / pickVertexOnEntity / pickTile + PickHit / VertexHit /
 // PickError / PickErrorCode / PickTileError / PickTileHit) moved to
@@ -278,10 +226,10 @@ export { createDevImportTransport } from './dev-import-transport';
  *     Camera, DirectionalLight, MeshFilter, MeshRenderer,
  *   } from '@forgeax/engine-render';
  *   import { Transform } from '@forgeax/engine-scene';
- *   import { createRenderer } from '@forgeax/engine-runtime';
+ *   import { AssetRegistry, HANDLE_CUBE, HANDLE_TRIANGLE } from '@forgeax/engine-assets-runtime';
  */
-// Shared-reference resolution belongs to ECS; renderer only consumes the
-// owner projection supplied by the current World.
+// feat-20260705-runtime-tier2-decomposition M1 / w14: resolveAssetHandle moved
+// to @forgeax/engine-assets-runtime (AC-105).
 export type { SpriteParamValues } from './sprite-param-values';
 // feat-20260630-viewport-2x2-run-x-display-redesign M2 / w12 / plan-strategy D-2:
 // engine-neutral by-entity-id active camera selection (no editor concept).
@@ -303,7 +251,7 @@ export type { SpriteParamValues } from './sprite-param-values';
  *     TRANSPARENT_SORT_CONFIG_KEY,
  *     TRANSPARENT_SORT_MODE_LAYER_Y,
  *     setTransparentSortConfig,
- *   } from '@forgeax/engine-render/internal';
+ *   } from '@forgeax/engine-render/authoring';
  *   const r = setTransparentSortConfig(world,
  *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });
  */
@@ -337,8 +285,9 @@ export { spriteAnimationTickSystem } from './systems/sprite-animation-tick';
 // / probeVideoHighPerfUpload / VideoCapabilityDevice) moved to
 // @forgeax/engine-graphics-extras (AC-303). Zero shim -- import from that
 // package.
-// Typed asset loading is exposed by @forgeax/engine-assets-runtime. Renderer
-// construction consumes only owner projections and device services.
+// feat-20260705-runtime-tier2-decomposition M1 / w14: createDefaultLoaderRegistry
+// + wireDefaultLoaders moved to @forgeax/engine-assets-runtime. Consumers import
+// them from that package directly (AC-105).
 
 // ─── Math namespace re-export (M2 / w15) ────────────────────────────────
 
@@ -377,16 +326,11 @@ export { quat } from '@forgeax/engine-math';
 // collectSceneAsset removed — replaced by rootsToSceneAsset (forest entry,
 // schema-derived field dispatch, engine-self-contained GUID resolution).
 // serializeSceneAssetToPack now uses schema-derived refs[] index (D-1/D-2).
-export { rootsToSceneAsset, serializeSceneAssetToPack } from './collect-scene-asset';
 export {
-  createSceneAssetPort,
-  type SceneAssetPort,
-  type SceneAssetPortError,
-} from './scene-asset-port';
-export {
-  SceneCollectAssetGuidUnresolvedError,
-  SceneCollectEntityRefOutOfClosureError,
-} from './scene-collect-errors';
+  rootsToSceneAsset,
+  type SceneAssetGuidLookup,
+  serializeSceneAssetToPack,
+} from './collect-scene-asset';
 // feat-20260626 M6 / m6-4: debug-draw auto-attach glue is re-exported from the
 // main barrel (was a separate tsup entry). The separate entry produced a SECOND
 // module copy of the mutable `registeredDebugDraw` registry: createApp set it on
@@ -414,26 +358,20 @@ export {
 // alongside the existing fullscreen post-process register / not-found /
 // reads-not-found codes. AI users `switch (err.code)` over the closed
 // 6-member union without `default`; .detail narrows per-code per charter P3.
-// feat-20260604 M3 / w19: render-graph-primitives — the public AI-user vocabulary
-// for assembling a render pipeline's per-frame graph (addScenePass /
-// addShadowPass / addSkyboxPass / addBloomPasses / addTonemapPass /
-// addFullscreenPass). The urp pipeline (w21) and any custom
-// pipeline use these factories — the dogfood proof of D-5.
+// feat-20260604 M3 / w19: render-graph-primitives — low-level typed record helpers
+// used by the Standard feature graph. Graph topology is declared by RenderFeaturePlan;
+// recordSsao* and encodeFullscreenPass remain the executable RHI-facing leaves.
 // feat-20260601-customizable-render-pipeline-seam-and-dogfood-rend M1.
 /**
- * Render-pipeline surface. `renderer.registerPipeline(id, impl)` registers a
- * `RenderPipeline` logic; `renderer.installPipeline(handle)` installs the pipeline bound
- * by a `RenderPipelineAsset` handle from the renderer-owned projection. The built-in
- * `forgeax::urp` (`urpPipeline`) is the authoritative worked
- * example - it is dogfooded through the same public channel inside `createRenderer`.
+ * Render surface. The renderer host assembles one Standard pipeline and
+ * accepts closed RenderFeature declarations at App construction. Pipelines,
+ * device handles, and asset registries remain owner-internal implementation
+ * details rather than renderer methods.
  *
  * @example
- *   import {
- *     type RenderPipeline,
- *     PipelineError, type PipelineErrorCode,
- *     URP_PIPELINE_ID,
+ *   import type {
+ *     RenderFeaturePlan,
  *   } from '@forgeax/engine-render';
- *   // urpPipeline remains an engine-internal implementation.
  */
 // RenderPipelineContext is barrel-exported for typed pass encode closures.
 // feat-20260701-rootstosceneasset verify minor-edit (F2): collectSubtree is a

package/src/renderer-host.ts

@@ -0,0 +1,33 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { RenderError, RendererOptions, RenderResult } from '@forgeax/engine-render';
+import type {
+  BundlerOptions,
+  RendererHostAssembly,
+} from '@forgeax/engine-render/internal/construct-renderer';
+import { constructRendererHost } from '@forgeax/engine-render/internal/construct-renderer';
+import { loadBackendPack } from './backend-selection';
+
+export type {
+  BundlerOptions,
+  RendererHostAssembly,
+} from '@forgeax/engine-render/internal/construct-renderer';
+
+/** Assemble renderer plus asset services in the Runtime-owned backend host. */
+export async function constructRuntimeRendererHost(
+  canvas: unknown,
+  options?: RendererOptions,
+  bundler?: BundlerOptions,
+): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+  const first = await loadBackendPack(options);
+  if (!first.ok) throw first.error;
+  const constructed = await constructRendererHost(canvas, options, bundler, first.value);
+  if (constructed.ok || options?.rhi !== undefined || typeof globalThis === 'undefined') {
+    return constructed;
+  }
+  const fallback = await loadBackendPack(options, true);
+  if (!fallback.ok) return constructed;
+  return constructRendererHost(canvas, options, bundler, fallback.value);
+}
+
+export { loadRhiPack } from './backend-selection';
+export type { AssetRegistry };

package/src/scene-instances/__tests__/post-spawn-resolve-joints.unit.test.ts

@@ -7,11 +7,11 @@
 //   - missing joint inside subtree: structured error 'skin-joint-path-unresolved'.
 
 import { World } from '@forgeax/engine-ecs';
-import { postSpawnResolveJoints } from '@forgeax/engine-render/internal';
 import { ChildOf, Name } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
 import type { SkinAsset } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
+import { postSpawnResolveJoints } from '../../../../render/src/scene-instances/post-spawn-resolve-joints';
 
 /**
  * Build a 3-joint linear chain `Root -> Spine -> Hip` rooted at a fresh entity,

package/src/scene-instances/index.ts

@@ -0,0 +1,4 @@
+export {
+  postSpawnResolveJoints,
+  type SkinJointResolver,
+} from '../../../render/src/scene-instances/post-spawn-resolve-joints';

package/src/scene-utils/mount-override-fold.ts

@@ -40,6 +40,7 @@
 // member land in the PARENT anchor's state, not the folded child anchor's; the
 // child anchor's own mountTimeOverrides is empty. See the M5 implement report.)
 
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import {
   componentDefinition,
   type Component as EcsComponent,
@@ -55,7 +56,6 @@ import type {
   SceneAsset,
   SceneEntity,
 } from '@forgeax/engine-types';
-import type { SceneAssetPort } from '../scene-asset-port';
 
 /** Minimal structural view of a SceneInstanceState the fold reads (D-4 boundary:
  * `world.getSceneInstanceState(root).value` is structurally assignable). */
@@ -143,12 +143,8 @@ function liveFields(
  * MountOverride[] (child-namespace localIds, live value domain). See file
  * header for the full contract. Returns [] when nothing differs from source.
  */
-export function foldMountOverrides(
-  world: World,
-  assets: SceneAssetPort,
-  state: FoldSceneInstanceState,
-): MountOverride[] {
-  const sourceRes = assets.resolve<SceneAsset>(
+export function foldMountOverrides(world: World, state: FoldSceneInstanceState): MountOverride[] {
+  const sourceRes = resolveAssetHandle<SceneAsset>(
     world,
     state.source as unknown as Handle<string, 'shared'>,
   );

package/src/systems/__tests__/transparent-sort.bench.ts

@@ -55,14 +55,14 @@
 // (5_000_000 ns/op working baseline; R1 F-2 defer note above).
 
 import { World } from '@forgeax/engine-ecs';
+import { bench, describe } from 'vitest';
+import type { TransparentEntry } from '../../../../render/src/systems/transparent-sort-config';
 import {
   setTransparentSortConfig,
   TRANSPARENT_SORT_MODE_LAYER_Y,
   TRANSPARENT_SORT_MODE_LAYER_YZ,
   TRANSPARENT_SORT_MODE_LAYER_Z,
-} from '@forgeax/engine-render/internal';
-import { bench, describe } from 'vitest';
-import type { TransparentEntry } from '../transparent-sort';
+} from '../../../../render/src/systems/transparent-sort-config';
 import { transparentSortEntries } from '../transparent-sort';
 import { createXorshift32 } from './_xorshift';
 

package/src/systems/sprite-animation-tick.ts

@@ -58,13 +58,13 @@
 // charter P3 + P4 + P5 + F1.
 
 import { type EntityHandle, Time, type World } from '@forgeax/engine-ecs';
+import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
 import {
   SpriteAnimation,
   SpriteRegionOverride,
   spritePlaybackModeFromU32,
 } from '@forgeax/engine-render/authoring';
 import { err, ok, type Result } from '@forgeax/engine-types';
-import { SpriteAnimationInvalidError } from '../errors/sprite-animation';
 
 /**
  * Walk every entity carrying `SpriteAnimation`, advance its dt

package/src/systems/transparent-sort.ts

@@ -10,14 +10,15 @@
 // budget):
 //
 //   1. Walk `entries` once and project each into:
-//        - `layers   : Float64Array(n)` — primary sort key (Layer.value).
+//        - `layers   : Int32Array(n)`   — primary sort key (Layer.value).
 //        - `sortVals : Float64Array(n)` — predicted sort value per entry,
 //          derived from `mode` + `yzAlpha` + per-entry inputs OR the
 //          per-entity `sortKey` override.
-//        - `indices  : Int32Array(n)`   — reusable `[0..n)` index buffer.
-//   2. Stable radix passes sort `indices` by material, sort value, then
-//      layer. The least-significant-first order composes the same composite
-//      ordering without a boxed JS comparator or per-call index array.
+//        - `indices  : number[]`        — initially `[0..n)`.
+//   2. `indices.sort((a, b) => ...)` with the composite comparator
+//      `(layers[a] - layers[b]) || (sortVals[a] - sortVals[b])`.
+//      Array.prototype.sort has been stable since ES2019; tie-breakers
+//      fall back to insertion order (charter F1 deterministic output).
 //   3. Return entries reordered by the sorted indices.
 //
 // Why SoA over Object-of-Structs comparator: V8's PSP / TimSort visits
@@ -58,29 +59,14 @@
 // archetypeStorage layout).
 
 import type { World } from '@forgeax/engine-ecs';
-import type { TransparentEntry } from '@forgeax/engine-render/internal';
+import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
 import {
   getTransparentSortConfig,
   TRANSPARENT_SORT_MODE_DISTANCE,
   TRANSPARENT_SORT_MODE_LAYER_Y,
   TRANSPARENT_SORT_MODE_LAYER_YZ,
   TRANSPARENT_SORT_MODE_LAYER_Z,
-} from '@forgeax/engine-render/internal';
-
-export type { TransparentEntry } from '@forgeax/engine-render/internal';
-
-let transparentSortLayers = new Float64Array(0);
-let transparentSortValues = new Float64Array(0);
-let transparentSortMaterials = new Float64Array(0);
-let transparentSortIndices = new Int32Array(0);
-
-function ensureTransparentSortCapacity(n: number): void {
-  if (transparentSortIndices.length >= n) return;
-  transparentSortLayers = new Float64Array(n);
-  transparentSortValues = new Float64Array(n);
-  transparentSortMaterials = new Float64Array(n);
-  transparentSortIndices = new Int32Array(n);
-}
+} from '../../../render/src/systems/transparent-sort-config';
 
 /**
  * Sort the transparent-bucket entries by `(layer ASC, sortValue ASC,
@@ -121,28 +107,42 @@ export function transparentSortEntries(
   const mode = cfg.mode;
   const yzAlpha = cfg.yzAlpha;
 
-  // SoA pre-projection columns. Reuse the columns and the stable radix index
-  // buffer so steady-state sorting does not allocate a boxed index array.
-  ensureTransparentSortCapacity(n);
-  const layers = transparentSortLayers;
-  const sortVals = transparentSortValues;
-  const materials = transparentSortMaterials;
-  const indices = transparentSortIndices.subarray(0, n);
+  // SoA pre-projection columns. Float64Array gives sub-ms / 10k bench
+  // headroom over Object-of-Structs comparator (D-8); Int32Array carries
+  // the signed i32 Layer.value verbatim (negatives preserved).
+  const layers = new Int32Array(n);
+  const sortVals = new Float64Array(n);
   for (let i = 0; i < n; i++) {
     const e = entries[i] as TransparentEntry;
     layers[i] = e.layer;
     sortVals[i] = computeSortValue(e, mode, yzAlpha, cameraPos);
-    materials[i] = e.materialHandle;
-    indices[i] = i;
   }
 
-  // Stable least-significant passes compose the same order as the former
-  // comparator: material is tertiary for modes 0/1/2, sortValue is secondary,
-  // and layer is primary. Distance intentionally omits material, preserving
-  // insertion order for exact distance ties.
-  if (mode !== TRANSPARENT_SORT_MODE_DISTANCE) argsortInPlace(materials, indices);
-  argsortInPlace(sortVals, indices);
-  argsortInPlace(layers, indices);
+  // indices argsort — Array.prototype.sort stability (ES2019+) preserves
+  // insertion order when the comparator returns 0. We avoid TypedArray.sort
+  // because its stability is not specified by the ECMAScript standard.
+  const indices: number[] = new Array(n);
+  for (let i = 0; i < n; i++) indices[i] = i;
+  indices.sort((a, b) => {
+    const la = layers[a] as number;
+    const lb = layers[b] as number;
+    if (la !== lb) return la - lb;
+    const va = sortVals[a] as number;
+    const vb = sortVals[b] as number;
+    if (va !== vb) return va < vb ? -1 : 1;
+    // Tertiary tiebreaker for modes 0/1/2: group same-materialHandle entries
+    // together so consecutive equal-(layer, sortVal, materialHandle) runs can
+    // collapse into fold buckets. Matches sortTransparentDispatch semantics.
+    // Not applied for DISTANCE (mode 3) — ties at exact same camera distance
+    // are undefined in depth order; stable insertion order is preserved there.
+    if (mode !== TRANSPARENT_SORT_MODE_DISTANCE) {
+      return (
+        (entries[a] as TransparentEntry).materialHandle -
+        (entries[b] as TransparentEntry).materialHandle
+      );
+    }
+    return 0;
+  });
 
   const sorted: TransparentEntry[] = new Array(n);
   for (let i = 0; i < n; i++) {

package/src/tilemap-register-validate.ts

@@ -11,13 +11,13 @@
 // state, no further migration to a tilemap feature package).
 
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
-import {
-  TileLayer as runtimeTileLayer,
-  Tilemap as runtimeTilemap,
-} from '@forgeax/engine-render/authoring';
 import { err, ok, type Result } from '@forgeax/engine-rhi';
 import { ChildOf } from '@forgeax/engine-scene';
 import { ASSET_ERROR_HINTS, AssetError } from '@forgeax/engine-types';
+import {
+  TileLayer as runtimeTileLayer,
+  Tilemap as runtimeTilemap,
+} from '../../render/src/components';
 
 function invalidValue(field: string, value: unknown, reason: string): AssetError {
   return new AssetError({

package/dist/__tests__/bind-group-cache-binding.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=bind-group-cache-binding.test.d.ts.map

package/dist/__tests__/bind-group-cache-binding.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bind-group-cache-binding.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bind-group-cache-binding.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/bind-group-cache-frame.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=bind-group-cache-frame.test.d.ts.map