@volter/threejs-runtime 0.5.65

package/src/asset-formats/render-env.ts

@@ -0,0 +1,318 @@
+/**
+ * Render settings — the tone-mapping / post-processing / render-feature scope
+ * the engine's renderer setup reads (`setup/setup-renderer.ts`).
+ *
+ * Exactly THREE scopes, and each is here because `setup-renderer.ts` reads
+ * every one of its fields to build the postprocessing chain. A setting with
+ * no such reader does not belong in this descriptor.
+ */
+import { z } from 'zod';
+import { buildRenderingZod } from '../render/render-features';
+
+export const ToneMappingDescriptorSchema = z
+  .object({
+    mode: z
+      .enum(['none', 'linear', 'reinhard', 'cineon', 'aces', 'agx'])
+      .optional()
+      .describe('Tone mapping operator'),
+    exposure: z.number().optional().describe('Exposure level'),
+  })
+  .describe('Tone mapping configuration');
+
+export type ToneMappingDescriptor = z.infer<typeof ToneMappingDescriptorSchema>;
+
+export const PostProcessingDescriptorSchema = z
+  .object({
+    // ── Bloom & Vignette ──────────────────────────────────────────────────
+    bloom: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable bloom effect'),
+        intensity: z.number().optional().describe('Bloom intensity multiplier'),
+        luminanceThreshold: z.number().optional().describe('Minimum luminance to trigger bloom'),
+        luminanceSmoothing: z
+          .number()
+          .optional()
+          .describe('Smoothing applied to luminance threshold'),
+      })
+      .optional()
+      .describe('Bloom glow effect'),
+    vignette: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable vignette effect'),
+        darkness: z.number().optional().describe('Vignette darkness intensity'),
+        offset: z.number().optional().describe('Vignette offset from center'),
+      })
+      .optional()
+      .describe('Screen-edge darkening effect'),
+
+    // ── Color adjustments ─────────────────────────────────────────────────
+    brightnessContrast: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable brightness/contrast adjustment'),
+        brightness: z.number().optional().describe('Brightness adjustment (-1 to 1)'),
+        contrast: z.number().optional().describe('Contrast adjustment (-1 to 1)'),
+      })
+      .optional()
+      .describe('Brightness and contrast color adjustment'),
+    hueSaturation: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable hue/saturation adjustment'),
+        hue: z.number().optional().describe('Hue rotation in radians'),
+        saturation: z.number().optional().describe('Saturation adjustment (-1 to 1)'),
+      })
+      .optional()
+      .describe('Hue rotation and saturation color adjustment'),
+    sepia: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable sepia tone'),
+        intensity: z.number().optional().describe('Sepia effect intensity (0 to 1)'),
+      })
+      .optional()
+      .describe('Warm sepia tone for vintage photograph look'),
+    colorDepth: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable color depth reduction'),
+        bits: z.number().optional().describe('Number of color bits per channel (1–16)'),
+      })
+      .optional()
+      .describe('Reduce color bit depth for posterized/banded look'),
+
+    // ── Lens effects ──────────────────────────────────────────────────────
+    chromaticAberration: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable chromatic aberration'),
+        offsetX: z.number().optional().describe('Horizontal color fringe offset'),
+        offsetY: z.number().optional().describe('Vertical color fringe offset'),
+        radialModulation: z.boolean().optional().describe('Increase effect toward screen edges'),
+        modulationOffset: z.number().optional().describe('Radial modulation offset from center'),
+      })
+      .optional()
+      .describe('Lens chromatic aberration (color fringing at screen edges)'),
+    lensDistortion: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable lens distortion'),
+        distortionX: z.number().optional().describe('Horizontal barrel/pincushion distortion'),
+        distortionY: z.number().optional().describe('Vertical barrel/pincushion distortion'),
+        focalLengthX: z.number().optional().describe('Horizontal focal length'),
+        focalLengthY: z.number().optional().describe('Vertical focal length'),
+        skew: z.number().optional().describe('Lens skew angle'),
+      })
+      .optional()
+      .describe('Barrel/pincushion lens distortion'),
+    depthOfField: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable depth of field'),
+        worldFocusDistance: z.number().optional().describe('Focus distance in world units'),
+        worldFocusRange: z.number().optional().describe('Focus range in world units'),
+        bokehScale: z.number().optional().describe('Bokeh blur scale'),
+        focalLength: z.number().optional().describe('Camera focal length in mm'),
+      })
+      .optional()
+      .describe('Physically-based depth of field with bokeh blur'),
+    tiltShift: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable tilt-shift effect'),
+        offset: z.number().optional().describe('Focus band offset from center'),
+        rotation: z.number().optional().describe('Focus band rotation in radians'),
+        focusArea: z.number().optional().describe('Focus band width (0–1)'),
+        feather: z.number().optional().describe('Blur falloff smoothness'),
+      })
+      .optional()
+      .describe('Tilt-shift miniature-world blur effect'),
+
+    // ── Film / retro ──────────────────────────────────────────────────────
+    noise: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable film grain noise'),
+        premultiply: z
+          .boolean()
+          .optional()
+          .describe('Multiply noise with input color instead of adding'),
+      })
+      .optional()
+      .describe('Random per-pixel noise overlay (film grain)'),
+    scanline: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable scanline overlay'),
+        density: z.number().optional().describe('Number of scanlines across screen height'),
+      })
+      .optional()
+      .describe('Horizontal scanline overlay (CRT monitor look)'),
+    dotScreen: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable dot screen halftone'),
+        angle: z.number().optional().describe('Pattern angle in radians'),
+        scale: z.number().optional().describe('Pattern dot scale'),
+      })
+      .optional()
+      .describe('Halftone dot pattern (newspaper/comic look)'),
+    grid: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable grid overlay'),
+        scale: z.number().optional().describe('Grid cell scale'),
+        lineWidth: z.number().optional().describe('Grid line width'),
+      })
+      .optional()
+      .describe('Visible grid pattern overlay'),
+    pixelation: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable pixelation'),
+        granularity: z.number().optional().describe('Pixel size (higher = more pixelated)'),
+      })
+      .optional()
+      .describe('Reduce resolution for pixel-art / mosaic effect'),
+    glitch: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable digital glitch effect'),
+        delayX: z.number().optional().describe('Minimum delay between glitches (seconds)'),
+        delayY: z.number().optional().describe('Maximum delay between glitches (seconds)'),
+        durationX: z.number().optional().describe('Minimum glitch duration (seconds)'),
+        durationY: z.number().optional().describe('Maximum glitch duration (seconds)'),
+        strengthX: z.number().optional().describe('Minimum glitch strength'),
+        strengthY: z.number().optional().describe('Maximum glitch strength'),
+        columns: z.number().optional().describe('Number of glitch columns'),
+        ratio: z.number().optional().describe('Glitch ratio (0–1)'),
+      })
+      .optional()
+      .describe('Random digital glitch artifacts (block displacement, color shifting)'),
+
+    // ── Distortion ────────────────────────────────────────────────────────
+    shockWave: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable shock wave distortion'),
+        speed: z.number().optional().describe('Wave propagation speed'),
+        maxRadius: z.number().optional().describe('Maximum wave radius'),
+        waveSize: z.number().optional().describe('Width of the distortion wave'),
+        amplitude: z.number().optional().describe('Distortion strength'),
+        positionX: z.number().optional().describe('Wave origin X in world space'),
+        positionY: z.number().optional().describe('Wave origin Y in world space'),
+        positionZ: z.number().optional().describe('Wave origin Z in world space'),
+      })
+      .optional()
+      .describe('Expanding spherical distortion wave from a point'),
+
+    // ── Anti-aliasing ─────────────────────────────────────────────────────
+    smaa: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable SMAA anti-aliasing'),
+        preset: z
+          .enum(['low', 'medium', 'high', 'ultra'])
+          .optional()
+          .describe('Quality preset (higher = better quality, more cost)'),
+      })
+      .optional()
+      .describe('Subpixel Morphological Anti-Aliasing'),
+
+    // ── Ambient occlusion ─────────────────────────────────────────────────
+    ssao: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable screen-space ambient occlusion'),
+        radius: z.number().optional().describe('Occlusion sampling radius'),
+        intensity: z.number().optional().describe('Occlusion intensity multiplier'),
+        bias: z.number().optional().describe('Depth bias to reduce self-occlusion artifacts'),
+        samples: z.number().optional().describe('Number of occlusion samples per pixel'),
+        rings: z.number().optional().describe('Number of spiral sample rings'),
+        fade: z.number().optional().describe('Distance at which occlusion fades out'),
+        color: z.string().optional().describe('Occlusion tint color as CSS hex'),
+      })
+      .optional()
+      .describe('Screen-space ambient occlusion (darken creases and crevices)'),
+    n8ao: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable N8AO ambient occlusion'),
+        aoSamples: z.number().optional().describe('Number of AO samples (default 16)'),
+        aoRadius: z.number().optional().describe('AO sampling radius in world units'),
+        intensity: z.number().optional().describe('AO intensity multiplier'),
+        denoiseSamples: z.number().optional().describe('Number of denoise samples'),
+        denoiseRadius: z.number().optional().describe('Denoise blur radius'),
+        distanceFalloff: z.number().optional().describe('AO distance falloff'),
+        screenSpaceRadius: z
+          .boolean()
+          .optional()
+          .describe('Use screen-space radius instead of world-space'),
+        color: z.string().optional().describe('AO tint color as CSS hex'),
+        halfRes: z.boolean().optional().describe('Render AO at half resolution for performance'),
+      })
+      .optional()
+      .describe('High-quality ambient occlusion (N8AO — alternative to SSAO)'),
+
+    // ── Entity-referencing effects ────────────────────────────────────────
+    godRays: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable god rays'),
+        sourceEntity: z.string().optional().describe('Entity ID of the light source mesh'),
+        density: z.number().optional().describe('Ray density'),
+        decay: z.number().optional().describe('Ray intensity decay along distance'),
+        weight: z.number().optional().describe('Ray weight / brightness'),
+        exposure: z.number().optional().describe('Overall god ray exposure'),
+        samples: z.number().optional().describe('Number of ray-march samples'),
+      })
+      .optional()
+      .describe('Volumetric light shafts from a light source entity'),
+    outline: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable outline effect'),
+        tags: z.array(z.string()).optional().describe('Entity tags to outline'),
+        edgeStrength: z.number().optional().describe('Outline edge thickness / strength'),
+        pulseSpeed: z.number().optional().describe('Outline pulse animation speed (0 = no pulse)'),
+        visibleEdgeColor: z.string().optional().describe('Color of visible edges as CSS hex'),
+        hiddenEdgeColor: z
+          .string()
+          .optional()
+          .describe('Color of hidden/occluded edges as CSS hex'),
+        xRay: z.boolean().optional().describe('Show outline through occluding objects'),
+      })
+      .optional()
+      .describe('Highlight entities matching tags with colored outlines'),
+
+    // ── Screen-space reflections & GI (realism-effects) ───────────────────
+    ssr: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable screen-space reflections'),
+        intensity: z.number().optional().describe('Reflection intensity'),
+        exponent: z.number().optional().describe('Reflection falloff exponent'),
+        distance: z.number().optional().describe('Maximum reflection ray distance'),
+        thickness: z.number().optional().describe('Depth thickness for hit testing'),
+        maxRoughness: z.number().optional().describe('Maximum roughness for reflections (0–1)'),
+      })
+      .optional()
+      .describe('Screen-space reflections for reflective/glossy surfaces'),
+    ssgi: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable screen-space global illumination'),
+        intensity: z.number().optional().describe('Indirect light intensity'),
+        distance: z.number().optional().describe('Maximum GI ray distance'),
+        thickness: z.number().optional().describe('Depth thickness for hit testing'),
+        maxRoughness: z.number().optional().describe('Maximum roughness for GI (0–1)'),
+      })
+      .optional()
+      .describe('Screen-space global illumination (indirect lighting bounce)'),
+    motionBlur: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable motion blur'),
+        intensity: z.number().optional().describe('Motion blur intensity'),
+        jitter: z.number().optional().describe('Sample jitter amount'),
+        samples: z.number().optional().describe('Number of blur samples'),
+      })
+      .optional()
+      .describe('Per-object motion blur from camera and object movement'),
+  })
+  .describe('Post-processing effects');
+
+export type PostProcessingDescriptor = z.infer<typeof PostProcessingDescriptorSchema>;
+
+export const RenderEnvironmentSchema = z
+  .object({
+    toneMapping: ToneMappingDescriptorSchema.optional().describe('Tone mapping configuration'),
+    postProcessing: PostProcessingDescriptorSchema.optional().describe(
+      'Post-processing effects (bloom, vignette, SSAO, SSR, ...)',
+    ),
+    rendering: buildRenderingZod()
+      .optional()
+      .describe(
+        'Render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry.',
+      ),
+  })
+  .describe('Renderer-level settings read by setup/setup-renderer.ts');
+
+export type RenderEnvironment = z.infer<typeof RenderEnvironmentSchema>;

package/src/asset-formats/tuples.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const Vec3Schema = z
+  .tuple([z.number(), z.number(), z.number()])
+  .describe('3D vector as [x, y, z]');
+export const QuatSchema = z
+  .tuple([z.number(), z.number(), z.number(), z.number()])
+  .describe('Quaternion as [x, y, z, w]');
+
+export type Vec3 = z.infer<typeof Vec3Schema>;
+export type Quat = z.infer<typeof QuatSchema>;
+
+export const TransformSchema = z
+  .object({
+    position: Vec3Schema.optional().describe('World-space position [x, y, z]'),
+    rotation: QuatSchema.optional().describe('Rotation quaternion [x, y, z, w]'),
+    scale: Vec3Schema.optional().describe('Scale factor per axis [x, y, z]. Defaults to [1, 1, 1]'),
+  })
+  .describe('Local transform relative to parent entity');
+
+export type Transform = z.infer<typeof TransformSchema>;

package/src/asset-loaders.ts

@@ -0,0 +1,242 @@
+/**
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/threejs-runtime/src/animation/xstate-animation-binding.ts.)
+ *
+ * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
+ * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
+ * (entity-factory, scene-sync). Previously this logic was duplicated across six
+ * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
+ * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
+ * not propagate. Everything funnels through the shared loaders in `../loader`
+ * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
+ * LoadingManager / asset-prefix rewrite).
+ *
+ * Cache lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
+ * This is deliberate: (1) it makes repeated Play→Stop→Play cheap, and (2) it
+ * underpins the `__sharedGeometry` contract from P0.2 — GLTF clones share the
+ * cached source geometry, so clearing mid-session would orphan live clones. The
+ * caches are keyed by URL, so loading the SAME asset N times is bounded (one
+ * entry per distinct URL, not per load). They are released only on full runtime
+ * teardown via {@link clearAssetCaches}.
+ */
+
+import type { SplatMesh } from '@sparkjsdev/spark';
+import * as THREE from 'three';
+import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+import { AssetParseError } from './asset-parse-error';
+import { setUserData } from './ecs/user-data';
+import { gltfLoader, resolveUrl, textureLoader } from './loader';
+
+const textureCache = new Map<string, THREE.Texture>();
+const gltfCache = new Map<
+  string,
+  Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
+>();
+const splatBytesCache = new Map<string, Promise<Uint8Array>>();
+
+/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
+export function loadTexture(url: string): THREE.Texture {
+  const cached = textureCache.get(url);
+  if (cached) return cached;
+  const tex = textureLoader.load(url);
+  textureCache.set(url, tex);
+  return tex;
+}
+
+/**
+ * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
+ * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
+ *
+ * Clone-safety contract (P0.2 — load-bearing, tested):
+ * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
+ * We give each clone its OWN materials (so scene cleanup can dispose them
+ * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
+ * so cleanup (engine create-runtime fullCleanup + editor scene-sync
+ * disposeObject3D) skips disposing the shared geometry buffers.
+ */
+export function loadGLTF(
+  url: string,
+): Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }> {
+  let cached = gltfCache.get(url);
+  if (!cached) {
+    cached = new Promise((resolve, reject) => {
+      gltfLoader.load(
+        url,
+        (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
+        undefined,
+        (err) => reject(err),
+      );
+    });
+    gltfCache.set(url, cached);
+  }
+  return cached.then((entry) => {
+    const scene = SkeletonUtils.clone(entry.scene) as THREE.Group;
+    scene.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        child.material = Array.isArray(child.material)
+          ? child.material.map((m) => m.clone())
+          : child.material.clone();
+        setUserData(child, '__sharedGeometry', true);
+      }
+    });
+    return { scene, animations: entry.animations };
+  });
+}
+
+/**
+ * Load one native Gaussian-splat asset as Spark's own Object3D.
+ *
+ * The URL cache stores immutable source bytes, not a live SplatMesh: every scene
+ * entity needs its own transformable/disposable Object3D, while repeated uses of
+ * the same SPZ must not download the multi-megabyte source more than once.
+ * Spark stays a lazy chunk so games without splats do not pay its bundle cost.
+ */
+export async function loadSplat(url: string, providedBytes?: Uint8Array): Promise<SplatMesh> {
+  let bytes = splatBytesCache.get(url);
+  if (!bytes && providedBytes) {
+    bytes = Promise.resolve(providedBytes);
+    splatBytesCache.set(url, bytes);
+  }
+  if (!bytes) {
+    bytes = fetch(resolveUrl(url)).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(
+          `Failed to load Gaussian splat: ${url} (${response.status} ${response.statusText})`,
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    });
+    splatBytesCache.set(url, bytes);
+  }
+
+  try {
+    const [{ SplatMesh }, fileBytes] = await Promise.all([import('@sparkjsdev/spark'), bytes]);
+    const mesh = new SplatMesh({ fileBytes, fileName: url, raycastable: true });
+    await mesh.initialized;
+    setUserData(mesh, 'gaussianSplat', { src: url, numSplats: mesh.numSplats });
+    const bounds = mesh.getBoundingBox();
+    if (!bounds.isEmpty()) {
+      // Three's generic Box3.setFromObject only understands geometry-bearing
+      // Object3Ds. Spark intentionally renders without THREE.BufferGeometry,
+      // so give editor/runtime framing a hidden, non-pickable bounds proxy.
+      // It is infrastructure, never authored hierarchy or rendered content.
+      // Include a framing margin. This proxy is consumed by generic editor
+      // focus/selection bounds, while inspectors continue to report Spark's
+      // exact Gaussian bounds directly.
+      const size = bounds.getSize(new THREE.Vector3()).multiplyScalar(1.5);
+      const center = bounds.getCenter(new THREE.Vector3());
+      const proxy = new THREE.Mesh(new THREE.BoxGeometry(size.x, size.y, size.z));
+      proxy.name = '__vgai_splat_bounds';
+      proxy.position.copy(center);
+      proxy.visible = false;
+      proxy.raycast = () => {};
+      setUserData(proxy, 'engineInternal', true);
+      mesh.add(proxy);
+    }
+    return mesh;
+  } catch (error) {
+    // A failed fetch must be retryable after the source is repaired or the
+    // network recovers; successful source bytes remain cached across instances.
+    splatBytesCache.delete(url);
+    throw error;
+  }
+}
+
+/**
+ * Resolve a single named node inside an already-loaded glTF scene graph (F4,
+ * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
+ * callers pass the `scene` they already got from {@link loadGLTF}.
+ *
+ * The returned node is the SAME object (and shares the SAME geometry) as
+ * found in `scene` — nothing is cloned or copied out. `scene` is already a
+ * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
+ * so mutating/detaching the returned node is safe.
+ *
+ * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
+ * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
+ * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
+ * throws a loud `AssetParseError` instead of silently producing broken skinning.
+ */
+export function resolveGltfNode(
+  scene: THREE.Object3D,
+  nodeName: string,
+  src: string,
+): THREE.Object3D {
+  const node = scene.getObjectByName(nodeName);
+  if (!node) {
+    throw new AssetParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message: `glTF "${src}" has no node named "${nodeName}" (getObjectByName found nothing)`,
+        },
+      ],
+      src,
+    );
+  }
+
+  const isSkinned = (o: THREE.Object3D) => (o as THREE.SkinnedMesh).isSkinnedMesh;
+  let containsSkinned = isSkinned(node);
+  if (!containsSkinned) {
+    node.traverse((child) => {
+      if (isSkinned(child)) containsSkinned = true;
+    });
+  }
+  if (containsSkinned) {
+    throw new AssetParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message:
+            `glTF "${src}" node "${nodeName}" is (or contains) a SkinnedMesh — a skinned mesh ` +
+            'cannot be lifted out of its armature (atomic-subtree rule). Reference the whole ' +
+            'file instead of a `node`, or bake/export a non-skinned sub-asset.',
+        },
+      ],
+      src,
+    );
+  }
+
+  return node;
+}
+
+/**
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
+ *
+ * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
+ * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
+ * also clears that env cache.
+ */
+export function clearAssetCaches(): void {
+  textureCache.clear();
+  gltfCache.clear();
+  splatBytesCache.clear();
+}
+
+/**
+ * Drop the cached entry for ONE asset URL after its bytes changed on disk
+ * (editor asset-optimization write-back — W4a). Existing clones keep their
+ * shared geometry alive (the cache entry only owns the lookup, not the
+ * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
+ * rewritten file instead of serving stale bytes.
+ */
+export function invalidateCachedAsset(url: string): void {
+  textureCache.delete(url);
+  gltfCache.delete(url);
+}
+
+/**
+ * Test-only: current sizes of the module-level caches. Used by the P1.8 headless
+ * test to assert caches stay bounded (one entry per distinct asset URL) across
+ * repeated loads of the same scene, rather than growing per load.
+ */
+export function assetCacheSizes(): { textures: number; gltf: number; splat: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size, splat: splatBytesCache.size };
+}

package/src/asset-parse-error.ts

@@ -0,0 +1,29 @@
+/**
+ * The GENERIC fetched-asset parse error.
+ *
+ * Every authored asset format the engine validates at fetch time throws this
+ * when Zod rejects the payload, naming the offending file (T4.6). It lives
+ * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
+ * every caller (currently the input-map loader in `input/input-manager.ts`)
+ * does not have to reach into an unrelated subsystem for it.
+ *
+ * The name says ASSET, not scene: an `.inputmap.json` failure is not a scene
+ * failure, and the class covers every structured fetched asset.
+ */
+
+import type { ZodIssue } from 'zod';
+
+export class AssetParseError extends Error {
+  readonly issues: ZodIssue[];
+  /** The offending file's path/URL, when the caller knows it (T4.6). */
+  readonly filePath?: string | undefined;
+
+  constructor(issues: ZodIssue[], filePath?: string) {
+    const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+    const header = filePath ? `Asset validation failed (${filePath}):` : 'Asset validation failed:';
+    super(`${header}\n${msg}`);
+    this.name = 'AssetParseError';
+    this.issues = issues;
+    this.filePath = filePath;
+  }
+}

package/src/assets.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
+ *
+ * Inspired by Unity's Resources.Load / Godot's load():
+ *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
+ *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
+ *
+ * GLTF files (.glb/.gltf) resolve to GLTFResult.
+ * JSON files resolve to the parsed object (caller provides type via generic).
+ *
+ * Cache lives for the app lifetime — no dispose needed.
+ */
+
+import type { AssetCache, GLTFResult } from '@volter/editor-project/adapter/asset-cache';
+import { gltfLoader, resolveUrl } from './loader';
+
+export type { AssetCache, GLTFResult } from '@volter/editor-project/adapter/asset-cache';
+
+export function createAssetCache(): AssetCache {
+  const cache = new Map<string, Promise<unknown>>();
+  const resolved = new Map<string, unknown>();
+  // Use the shared, DRACO-wired GLTFLoader (A2 / CB2) — no second loader instance.
+  // This cache keeps the parsed source GLTFResult (load/get semantics for gameplay
+  // code); it does NOT clone. Callers that need disposal-safe clones use
+  // asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
+
+  function load<T = unknown>(url: string): Promise<T> {
+    const existing = cache.get(url);
+    if (existing) return existing as Promise<T>;
+
+    let promise: Promise<unknown>;
+
+    if (url.endsWith('.glb') || url.endsWith('.gltf')) {
+      promise = new Promise<GLTFResult>((resolve, reject) => {
+        gltfLoader.load(
+          url,
+          (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
+          undefined,
+          reject,
+        );
+      });
+    } else if (url.endsWith('.json')) {
+      promise = fetch(resolveUrl(url)).then((r) => {
+        if (!r.ok) throw new Error(`Failed to fetch ${url}: ${r.status}`);
+        return r.json();
+      });
+    } else {
+      throw new Error(`AssetCache: unsupported file type for "${url}"`);
+    }
+
+    const tracked = promise.then((value) => {
+      resolved.set(url, value);
+      return value;
+    });
+
+    cache.set(url, tracked);
+    return tracked as Promise<T>;
+  }
+
+  function get<T = unknown>(url: string): T {
+    if (!resolved.has(url)) {
+      throw new Error(`AssetCache: "${url}" not loaded. Call load() first and await it.`);
+    }
+    return resolved.get(url) as T;
+  }
+
+  return { load, get };
+}