@forgeax/engine-assets-runtime 0.1.3 → 0.1.6

package/src/builtin-asset-registry.ts

@@ -0,0 +1,164 @@
+// ─── BuiltinAssetRegistry (D-15 process-static tier) ────────────────────────
+//
+// D-15 two-tier asset resolution. Builtin payloads (the 5 procedural meshes
+// the engine ships with) are PROCESS-STATIC: a frozen const keyed by a fixed
+// slot u32 in [1, BUILTIN_BASE). They never enter a World's SharedRefStore,
+// never participate in reference counting, and resolve without any World
+// reference — so a builtin handle (HANDLE_CUBE etc.) is transparent across
+// every World and every renderer.
+//
+// R-13 (module init-order): all five payload consts are constructed
+// synchronously at module load, are module-level, and have no side effect.
+// Importing this module then calling resolve() observes fully-constructed
+// frozen payloads — there is no lazy getter and no circular-dependency
+// init hazard.
+//
+// The companion AssetRegistry (asset-registry.ts) retreats to a thin
+// guid<->handle index; user-tier payloads live in World.sharedRefs at
+// slots >= BUILTIN_BASE. AssetRegistry.get(handle) dispatches by slot range:
+// slot < BUILTIN_BASE -> BuiltinAssetRegistry.resolve, else world.sharedRefs.
+
+import {
+  createBoxGeometry,
+  createCylinderGeometry,
+  createPlaneGeometry,
+  createSphereGeometry,
+  meshFromInterleaved,
+} from '@forgeax/engine-geometry';
+import type { Handle, MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE, handleSlot } from '@forgeax/engine-types';
+
+// D-16: BUILTIN_BASE is the slot boundary [1, BUILTIN_BASE) builtin /
+// [BUILTIN_BASE, +inf) user-tier. It lives in @forgeax/engine-types (the
+// single shared dependency of ecs + runtime) to avoid a cross-package cycle;
+// re-exported from the runtime barrel here for AI-user discoverability.
+export { BUILTIN_BASE };
+
+// ─── Builtin geometry data (12F: position + normal + uv + tangent) ──────────
+// bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu: every
+// builtin geometry payload keeps the local-space AABB produced by its geometry
+// factory. Builtins are ordinary MeshAssets at the render boundary, so removing
+// their bounds silently turns them into always-visible renderables and defeats
+// the same frustum-culling path used by imported meshes.
+
+// BUILTIN_CUBE is synthesized from `createBoxGeometry(1, 1, 1)` so the cube
+// inherits Three.js-aligned per-face UV unwrap and per-vertex tangent vec4.
+// The procedural factory always returns Result.ok for valid (>0) extents,
+// hence the unwrap-with-throw is safe at module init.
+const builtinCubeRes = createBoxGeometry(1, 1, 1);
+if (!builtinCubeRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] createBoxGeometry(1,1,1) failed: ${builtinCubeRes.error.code}`,
+  );
+}
+export const BUILTIN_CUBE: TypesMeshAsset = Object.freeze(builtinCubeRes.value);
+
+// BUILTIN_TRIANGLE: 3 vertices in the XY plane facing +Z, with a [0..1]² UV
+// triangle so a textured triangle samples the texture (apex = top-centre,
+// base = bottom-left / bottom-right). meshFromInterleaved expands the
+// 8-floats interleaved input (pos + normal + uv) to the runtime 12-floats
+// stride (adds tangent vec4 per `geometry/tangent.ts` path A).
+const builtinTriangleRes = meshFromInterleaved(
+  new Float32Array([
+    // pos.xyz                normal.xyz       uv.xy
+    0, 0.7, 0, 0, 0, 1, 0.5, 1, -0.7, -0.6, 0, 0, 0, 1, 0, 0, 0.7, -0.6, 0, 0, 0, 1, 1, 0,
+  ]),
+  new Uint16Array([0, 1, 2]),
+);
+if (!builtinTriangleRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] builtin triangle geometry failed: ${builtinTriangleRes.error.code}`,
+  );
+}
+export const BUILTIN_TRIANGLE: TypesMeshAsset = Object.freeze(builtinTriangleRes.value);
+
+// BUILTIN_QUAD: unit-size plane on XY facing +Z (4 vertices, 2 triangles,
+// 6 indices). Synthesised from `createPlaneGeometry(1, 1)` (which itself
+// chains through `meshFromInterleaved`) so the resulting MeshAsset is
+// byte-identical to procedural plane output — zero new layout
+// discriminator, AI users reason about UV / pivot semantics by reading
+// `packages/runtime/src/geometry/plane.ts` (charter P4 consistent
+// abstraction; feat-20260520 M-1 / w06).
+// bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu: this
+// payload follows the same local-AABB contract as every other builtin.
+const builtinQuadRes = createPlaneGeometry(1, 1);
+if (!builtinQuadRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] createPlaneGeometry(1,1) failed: ${builtinQuadRes.error.code}`,
+  );
+}
+export const BUILTIN_QUAD: TypesMeshAsset = Object.freeze(builtinQuadRes.value);
+
+// BUILTIN_SPHERE: UV-sphere synthesised from createSphereGeometry(1, 16, 12).
+// Vertices are at exact radius-1 positions (sphere.ts:40-45) so the
+// |hypot(pos)-1| < 1e-6 radius invariant holds by construction. Index
+// buffer is Uint32Array — downstream consumers (step-3 upload loop,
+// createRenderer.ts) auto-select 'uint32' indexFormat via
+// `instanceof Uint32Array`.
+const builtinSphereRes = createSphereGeometry(1, 16, 12);
+if (!builtinSphereRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] createSphereGeometry(1,16,12) failed: ${builtinSphereRes.error.code}`,
+  );
+}
+export const BUILTIN_SPHERE: TypesMeshAsset = Object.freeze(builtinSphereRes.value);
+
+// BUILTIN_CYLINDER: procedural cylinder synthesised from createCylinderGeometry(0.5, 0.5, 1, 16, 1).
+// Radius-top=radius-bottom=0.5, height=1, 16 radial segments, 1 height segment — a
+// unit-height open cylinder (no caps). meshFromInterleaved expands the 8-floats
+// interleaved input (pos + normal + uv) to the runtime 12-floats stride (adds
+// tangent vec4 per geometry/tangent.ts path A).
+// feat-20260701-editor-world-container-doc-ecs-collapse M0 / AC-16:
+// handle=6, GUID = deriveBuiltin('HANDLE_CYLINDER') UUIDv5
+// (plan-strategy §2 D-6 + §5.6 builtin-guid-ssot gate)
+const builtinCylinderRes = createCylinderGeometry(0.5, 0.5, 1, 16, 1);
+if (!builtinCylinderRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] createCylinderGeometry(0.5,0.5,1,16,1) failed: ${builtinCylinderRes.error.code}`,
+  );
+}
+export const BUILTIN_CYLINDER: TypesMeshAsset = Object.freeze(builtinCylinderRes.value);
+
+// BUILTIN_NINESLICE_QUAD: 4×4 grid plane synthesised from
+// createPlaneGeometry(1, 1, 3, 3) — 16 vertices, 9 sub-quads × 6 indices = 54.
+// Reuses the unit-quad vertex layout (12F: pos + normal + uv + tangent) so
+// HANDLE_NINESLICE_QUAD funnels through the same sprite-pipeline binding
+// table as HANDLE_QUAD; only the vertex_index → (i, j) decomposition in
+// sprite.wgsl branches on slices presence (feat-20260527-sprite-nineslice
+// M3, plan-strategy §D-2 + §D-4).
+const builtinNineSliceQuadRes = createPlaneGeometry(1, 1, 3, 3);
+if (!builtinNineSliceQuadRes.ok) {
+  throw new Error(
+    `[builtin-asset-registry] createPlaneGeometry(1,1,3,3) failed: ${builtinNineSliceQuadRes.error.code}`,
+  );
+}
+export const BUILTIN_NINESLICE_QUAD: TypesMeshAsset = Object.freeze(builtinNineSliceQuadRes.value);
+
+// Slot u32 -> frozen payload. Slot ids 1..5 are the fixed builtin handle
+// values (HANDLE_CUBE=1 .. HANDLE_NINESLICE_QUAD=5) defined in asset-registry.
+const BUILTIN_BY_SLOT: ReadonlyMap<number, TypesMeshAsset> = new Map([
+  [1, BUILTIN_CUBE],
+  [2, BUILTIN_TRIANGLE],
+  [3, BUILTIN_QUAD],
+  [4, BUILTIN_SPHERE],
+  [5, BUILTIN_NINESLICE_QUAD],
+  [6, BUILTIN_CYLINDER],
+]);
+
+/**
+ * Process-static builtin asset resolver (D-15). `resolve(handle)` returns the
+ * frozen builtin payload when `slot < BUILTIN_BASE`, else `null` (the slot
+ * belongs to the user tier — resolve it through `world.sharedRefs.resolve`).
+ *
+ * Read-only: there is no register / mint surface. The five builtin payloads
+ * are fixed at module load. AI users `import { BuiltinAssetRegistry } from
+ * '@forgeax/engine-runtime'` and resolve a builtin handle without a World.
+ */
+export const BuiltinAssetRegistry = Object.freeze({
+  resolve<T extends TypesMeshAsset>(handle: Handle<string, 'shared'>): T | null {
+    const slot = handleSlot(handle);
+    if (slot >= BUILTIN_BASE) return null;
+    const payload = BUILTIN_BY_SLOT.get(slot);
+    return payload === undefined ? null : (payload as T);
+  },
+});

package/src/catalog-source.ts

@@ -1,14 +1,14 @@
+import { err, ok, type Result } from '@forgeax/engine-rhi';
 import {
   ASSET_ERROR_HINTS,
   AssetError,
   type CatalogDelta,
   type CatalogEntry,
-  err,
-  ok,
   type ResourceRevision,
-  type Result,
   type RuntimeAssetBinding,
 } from '@forgeax/engine-types';
+import { fetchCatalog } from './registry/catalog';
+
 export type CatalogListener = (delta: CatalogDelta) => void;
 
 /** Read-only catalog source backed by static entries or a canonical URL. */
@@ -69,33 +69,17 @@ export function createCatalogSource(options: {
           }),
         );
       }
-      const response = await (options.fetch ?? globalThis.fetch)(options.url);
-      if (!response.ok) {
-        return err(
-          new AssetError({
-            code: 'asset-fetch-failed',
-            expected: 'the configured Catalog URL to return HTTP 200',
-            hint: 'verify the producer Catalog URL and republish the current snapshot',
-            detail: { sourcePath: options.url },
-          }),
-        );
-      }
-      let raw: unknown;
-      try {
-        raw = await response.json();
-      } catch {
-        return err(
-          new AssetError({
-            code: 'asset-parse-failed',
-            expected: 'the configured Catalog URL to return JSON',
-            hint: 'repair the producer Catalog before loading the current publication',
-          }),
-        );
-      }
-      const rows = scopedRows(raw, options.expectedScope);
-      if (!rows.ok) return rows;
-      const result = rows.value.map((row) => ({ ...row }));
-      return ok(result);
+      const result = await fetchCatalog(
+        options.url,
+        options.fetch ?? globalThis.fetch,
+        undefined,
+        options.expectedRevision,
+        options.expectedScope,
+      );
+      if (!result.ok) return result;
+      return ok(
+        [...result.value].map(([guid, entry]) => ({ guid, ...entry })) as readonly CatalogEntry[],
+      );
     },
     subscribe(listener) {
       return options.subscribe?.(listener) ?? (() => {});
@@ -103,43 +87,3 @@ export function createCatalogSource(options: {
     ...(options.expectedScope === undefined ? {} : { expectedScope: options.expectedScope }),
   };
 }
-
-function scopedRows(
-  raw: unknown,
-  expectedScope: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'> | undefined,
-): Result<readonly CatalogEntry[], AssetError> {
-  if (Array.isArray(raw)) return ok(raw as readonly CatalogEntry[]);
-  if (raw === null || typeof raw !== 'object') return parseRowsError('Catalog JSON rows');
-  const snapshot = raw as Record<string, unknown>;
-  if (!Array.isArray(snapshot.entries)) return parseRowsError('Catalog JSON entries');
-  if (expectedScope !== undefined) {
-    if (
-      snapshot.scopeId !== expectedScope.scopeId ||
-      snapshot.generation !== expectedScope.generation ||
-      snapshot.authority !== 'authoritative'
-    ) {
-      return err(
-        new AssetError({
-          code: 'asset-parse-failed',
-          expected: 'the Catalog snapshot to match the active scope and generation',
-          hint: 'restore the authoritative producer Catalog for the active runtime scope',
-          detail: {
-            expectedScope,
-            actualScope: { scopeId: snapshot.scopeId, generation: snapshot.generation },
-          } as never,
-        }),
-      );
-    }
-  }
-  return ok(snapshot.entries as readonly CatalogEntry[]);
-}
-
-function parseRowsError(expected: string): Result<never, AssetError> {
-  return err(
-    new AssetError({
-      code: 'asset-parse-failed',
-      expected,
-      hint: 'repair the producer Catalog before loading the current publication',
-    }),
-  );
-}

package/src/decode-image-bytes.ts

@@ -0,0 +1,126 @@
+// @forgeax/engine-assets-runtime -- runtime image byte decoder
+// (tweak-20260714-runtime-image-bytes-decoder-add-decodeimagebytes M2 / m2-1).
+//
+// M1 established the signature + TSDoc contract + red test skeleton. M2
+// fills the body:
+//   1. mime whitelist pre-check (PNG / JPEG); non-match -> structured
+//      `image-format-unsupported` err (charter P3 explicit failure).
+//   2. Delegate to `@forgeax/engine-image::decodeImageInBrowser` (SSOT
+//      browser-safe decoder; charter architecture principle 1 SSOT).
+//   3. Map `DecodedImage` -> `TextureAsset` POD; `format` derives from
+//      `opts.colorSpace` (srgb -> 'rgba8unorm-srgb' / linear ->
+//      'rgba8unorm', mirrors `image-importer.ts` colorSpaceToFormat); when
+//      `opts.mipmap !== false`, `mipLevelCount` derives from
+//      `numMipLevels({width,height})` (charter Derive-Don't-Duplicate).
+//
+// decode-image-bytes.ts is the SINGLE assets-runtime file allowed to
+// statically import @forgeax/engine-image (charter D-2; the
+// scripts/check-image-pipeline-isolation.mjs Path (a.2-anti) whitelist
+// row anchors this exact path). The gate's (a.1) forbidden-symbol regex
+// `\basync\s+function\s+decodeImage\b` does NOT match `decodeImageBytes`
+// because `\b` between `e` and `B` fails (both are word chars) --
+// verified at M2 by running the gate locally.
+import { decodeImageInBrowser } from '@forgeax/engine-image';
+import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { makeImageError } from './image-error';
+import { numMipLevels } from './mipmap-generator';
+
+/** v1 mime whitelist -- PNG / JPEG only (charter P1 progressive disclosure). */
+const SUPPORTED_MIMES = ['image/png', 'image/jpeg'] as const;
+type SupportedMime = (typeof SUPPORTED_MIMES)[number];
+
+function isSupportedMime(mime: string): mime is SupportedMime {
+  return SUPPORTED_MIMES.some((supportedMime) => supportedMime === mime);
+}
+
+/**
+ * Decode a PNG / JPEG byte stream into a `TextureAsset` POD.
+ *
+ * Runtime SDK entry for AI users who hold image bytes (fetched over the
+ * network, embedded as base64, produced by an out-of-tree decoder, etc.) and
+ * want to feed them into `world.allocSharedRef('TextureAsset', pod)` +
+ * `GpuResourceStore.ensureResident` without the disk-side importer / build
+ * pipeline in the loop (charter P1 progressive disclosure: one-step "bytes
+ * in, POD out").
+ *
+ * v1 supports the two universally-decodable mime types: `image/png` and
+ * `image/jpeg`. Failure surfaces are all structured via the closed
+ * `ImageError` union (`.code` / `.expected` / `.hint` / `.detail`); the
+ * function never throws for expected failures (AGENTS.md Error model +
+ * charter P3 explicit failure).
+ *
+ * Error codes possible (subset of the closed `ImageErrorCode` union):
+ * - `image-format-unsupported` -- mime not in the v1 whitelist (`detail.actualMime`)
+ * - `image-decode-failed` -- decoder rejected the bytes, or the environment
+ *   lacks `createImageBitmap` (`detail.reason`)
+ *
+ * @param bytes - Encoded image byte stream (`Uint8Array` or `ArrayBuffer`).
+ * @param mime - Byte-stream mime type. v1 whitelist: `'image/png' | 'image/jpeg'`.
+ * @param opts - Optional decode overrides:
+ *   - `colorSpace`: `'srgb'` (default) or `'linear'`. Derives POD `format`:
+ *     `srgb -> 'rgba8unorm-srgb'`, `linear -> 'rgba8unorm'`.
+ *   - `mipmap`: `true` (default) or `false`. When true, `mipLevelCount` is
+ *     computed via `numMipLevels({ width, height })`; when false, forced 1.
+ * @returns `ok(TextureAsset)` on success; `err(ImageError)` on failure.
+ *
+ * @example
+ * ```ts
+ * import { decodeImageBytes } from '@forgeax/engine-assets-runtime';
+ *
+ * const bytes = new Uint8Array(await (await fetch(url)).arrayBuffer());
+ * const result = await decodeImageBytes(bytes, 'image/png');
+ * if (!result.ok) {
+ *   // The ImageError code and detail are one correlated discriminated union.
+ *   switch (result.error.code) {
+ *     case 'image-format-unsupported':
+ *       console.error('bad mime:', result.error.detail.actualMime);
+ *       break;
+ *     case 'image-decode-failed':
+ *       console.error('decode reason:', result.error.detail.reason);
+ *       break;
+ *   }
+ *   return;
+ * }
+ * const handle = world.allocSharedRef('TextureAsset', result.value);
+ * ```
+ */
+export async function decodeImageBytes(
+  bytes: Uint8Array | ArrayBuffer,
+  mime: string,
+  opts: { colorSpace?: 'srgb' | 'linear'; mipmap?: boolean } = {},
+): Promise<Result<TextureAsset, ImageError>> {
+  if (!isSupportedMime(mime)) {
+    return err(
+      makeImageError({
+        code: 'image-format-unsupported',
+        actualMime: mime,
+      }),
+    );
+  }
+
+  const colorSpace = opts.colorSpace ?? 'srgb';
+  const mipmap = opts.mipmap ?? true;
+
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const decoded = await decodeImageInBrowser(u8, mime, { colorSpace, mipmap });
+  if (!decoded.ok) {
+    return err(decoded.error);
+  }
+
+  const dec = decoded.value;
+  const format: GPUTextureFormat = colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
+  const mipLevelCount = mipmap ? numMipLevels({ width: dec.width, height: dec.height }) : 1;
+
+  const pod: TextureAsset = {
+    kind: 'texture',
+    width: dec.width,
+    height: dec.height,
+    format,
+    data: dec.bytes,
+    colorSpace,
+    mipmap,
+    mipLevelCount,
+  };
+  return ok(pod);
+}

package/src/dynamic-texture-store.ts

@@ -0,0 +1,234 @@
+// @forgeax/engine-assets-runtime — DynamicTextureStore: transient per-frame GPU
+// textures for video sources (feat-20260623-world-space-video-asset M4 / w15).
+//
+// D-3: video frames are re-uploaded every frame — the opposite of the static
+// "upload once / cache forever" semantics GpuResourceStore.ensureResident
+// implements. Routing video through ensureResident would either poison its
+// permanent cache (AC-08) or crash it (its `switch (pod.kind)` has no `video`
+// arm). So video gets its OWN store with a transient lifecycle, exactly the way
+// cube-texture upload is an eager independent path that never enters the
+// ensureResident switch (research Finding 7 precedent).
+//
+// This store does NOT import GpuResourceStore and accepts NO static texture
+// handle — it is keyed solely by the VideoAsset clip handle. Each key owns a
+// single GPUTexture sized to the source video; the texture is recreated only
+// when the source dimensions change (a steady-size clip allocates once and is
+// re-written in place every frame via copyExternalImageToTexture). The view is
+// re-fetched after each upload so the bind group always samples the latest
+// frame.
+//
+// Charter P3: every failure returns a structured Result (never throws for an
+// expected GPU failure); the per-frame caller (record stage videoTextureView)
+// fires the RhiError on the engine error channel and falls back to the default
+// view for that frame.
+
+import type { Result, RhiDevice, RhiError, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { handleSlot } from '@forgeax/engine-types';
+
+/**
+ * The host-owned external image the engine copies a video frame from
+ * (HTMLVideoElement / VideoFrame / ImageBitmap / canvas). Mirrors the `source`
+ * member of the WebGPU `GPUCopyExternalImageSourceInfo` the RHI
+ * `copyExternalImageToTexture` consumes; aliased here so the store does not pull
+ * the whole webgpu descriptor type into its surface.
+ */
+export type CopyExternalImageSource = GPUCopyExternalImageSourceInfo['source'];
+
+/**
+ * GPUTextureUsage bits a video destination texture needs: COPY_DST (the
+ * copyExternalImageToTexture write target), TEXTURE_BINDING (sampled in the
+ * material bind group), and RENDER_ATTACHMENT (required by the WebGPU spec for
+ * a copyExternalImageToTexture destination). Mirrors the literals
+ * gpu-resource-store.ts uses for its upload textures (no shared const exists to
+ * import without coupling the two stores — D-3 keeps them independent).
+ */
+const VIDEO_TEXTURE_USAGE = 0x2 | 0x4 | 0x10;
+
+/** rgba8unorm-srgb: a video frame decodes to sRGB; sampling returns linear. */
+const VIDEO_TEXTURE_FORMAT = 'rgba8unorm-srgb' as const;
+
+/**
+ * The minimal RHI device surface DynamicTextureStore needs. Declared structurally
+ * (not the full RhiDevice) so unit tests drive it with a small mock and the store
+ * stays decoupled from the rest of the device surface (Pipeline Isolation).
+ */
+export interface DynamicTextureDevice {
+  createTexture(desc: {
+    readonly size: {
+      readonly width: number;
+      readonly height: number;
+      readonly depthOrArrayLayers: number;
+    };
+    readonly format: typeof VIDEO_TEXTURE_FORMAT;
+    readonly usage: number;
+    readonly label?: string;
+  }): Result<Texture, RhiError>;
+  createTextureView(texture: Texture, desc: Record<string, never>): Result<TextureView, RhiError>;
+  destroyTexture(texture: Texture): Result<void, RhiError>;
+  readonly queue: {
+    copyExternalImageToTexture(
+      source: { readonly source: CopyExternalImageSource; readonly flipY?: boolean },
+      destination: { readonly texture: Texture },
+      copySize: {
+        readonly width: number;
+        readonly height: number;
+        readonly depthOrArrayLayers: number;
+      },
+    ): Result<void, RhiError>;
+  };
+}
+
+/** Adapt the opaque RHI device to the store's intentionally small upload seam. */
+export function adaptDynamicTextureDevice(device: RhiDevice): DynamicTextureDevice {
+  return {
+    createTexture: (descriptor) =>
+      device.createTexture({
+        ...descriptor,
+        mipLevelCount: undefined,
+        sampleCount: undefined,
+        dimension: undefined,
+        viewFormats: undefined,
+        textureBindingViewDimension: undefined,
+      }),
+    createTextureView: (texture) =>
+      device.createTextureView(texture, {
+        label: undefined,
+        format: undefined,
+        dimension: undefined,
+        usage: undefined,
+        aspect: undefined,
+        baseMipLevel: undefined,
+        mipLevelCount: undefined,
+        baseArrayLayer: undefined,
+        arrayLayerCount: undefined,
+      }),
+    destroyTexture: (texture) => device.destroyTexture(texture),
+    queue: {
+      copyExternalImageToTexture: (source, destination, copySize) =>
+        device.queue.copyExternalImageToTexture(
+          { source: source.source, origin: [0, 0], flipY: source.flipY ?? false },
+          { texture: destination.texture, origin: [0, 0, 0] },
+          copySize,
+        ),
+    },
+  };
+}
+
+interface TransientEntry {
+  texture: Texture;
+  view: TextureView;
+  width: number;
+  height: number;
+}
+
+/**
+ * Transient per-frame texture store for video sources. Independent of
+ * GpuResourceStore: it neither imports nor reaches into the static residency
+ * cache (AC-08 / D-3).
+ */
+export class DynamicTextureStore {
+  private device: DynamicTextureDevice | undefined = undefined;
+  private readonly entries = new Map<number, TransientEntry>();
+
+  /**
+   * Wire the GPU device the store uploads through. Called once after the
+   * renderer captures its device (mirrors GpuResourceStore.configureGpuDevice).
+   * A replacement device invalidates every cached texture: the handles in the
+   * map belong to the old device and cannot be reused after renderer recovery.
+   */
+  configureGpuDevice(device: DynamicTextureDevice): void {
+    if (this.device !== undefined && this.device !== device) {
+      this.destroyAll();
+    }
+    this.device = device;
+  }
+
+  /**
+   * Upload one video frame for `clip` from the host-owned source image
+   * (HTMLVideoElement / VideoFrame / ImageBitmap), (re)allocating the transient
+   * texture when its size changes, and return the current-frame view to bind.
+   *
+   * Returns `undefined` (not an error) when the device is not yet wired or the
+   * source has no decodable dimensions yet (metadata pending) — the caller binds
+   * the default view that frame. A structured RhiError surfaces only when a wired
+   * device rejects the allocation or the copy (charter P3).
+   */
+  uploadFrame(
+    clip: Handle<'VideoAsset', 'shared'>,
+    source: CopyExternalImageSource,
+    width: number,
+    height: number,
+  ): Result<TextureView, RhiError> | undefined {
+    const device = this.device;
+    if (device === undefined) return undefined;
+    if (width <= 0 || height <= 0) return undefined;
+
+    const id = handleSlot(clip);
+    const ensured = this.ensureEntry(device, id, width, height);
+    if (!ensured.ok) return ensured;
+    const entry = ensured.value;
+
+    const copyRes = device.queue.copyExternalImageToTexture(
+      { source, flipY: true },
+      { texture: entry.texture },
+      { width, height, depthOrArrayLayers: 1 },
+    );
+    if (!copyRes.ok) return copyRes;
+    return ok(entry.view);
+  }
+
+  /**
+   * The current-frame view for a clip, if one has been uploaded this session,
+   * else undefined. The record stage reads this when assembling the bind group
+   * (a frame that has not uploaded yet falls back to the default view).
+   */
+  getView(clip: Handle<'VideoAsset', 'shared'>): TextureView | undefined {
+    return this.entries.get(handleSlot(clip))?.view;
+  }
+
+  /** Destroy every transient texture + drop the map (renderer teardown). */
+  destroyAll(): void {
+    const device = this.device;
+    for (const entry of this.entries.values()) {
+      device?.destroyTexture(entry.texture);
+    }
+    this.entries.clear();
+  }
+
+  /**
+   * Get the entry for `id`, (re)allocating its texture + view when absent or
+   * when the source dimensions changed. A same-size re-upload reuses the
+   * existing texture (allocate-once for a steady clip; the per-frame cost is the
+   * copyExternalImageToTexture write, not a texture create).
+   */
+  private ensureEntry(
+    device: DynamicTextureDevice,
+    id: number,
+    width: number,
+    height: number,
+  ): Result<TransientEntry, RhiError> {
+    const existing = this.entries.get(id);
+    if (existing !== undefined && existing.width === width && existing.height === height) {
+      return ok(existing);
+    }
+    if (existing !== undefined) device.destroyTexture(existing.texture);
+
+    const texRes = device.createTexture({
+      size: { width, height, depthOrArrayLayers: 1 },
+      format: VIDEO_TEXTURE_FORMAT,
+      usage: VIDEO_TEXTURE_USAGE,
+      label: `video-transient-${id}`,
+    });
+    if (!texRes.ok) return texRes;
+    const viewRes = device.createTextureView(texRes.value, {});
+    if (!viewRes.ok) {
+      device.destroyTexture(texRes.value);
+      return viewRes;
+    }
+    const entry: TransientEntry = { texture: texRes.value, view: viewRes.value, width, height };
+    this.entries.set(id, entry);
+    return ok(entry);
+  }
+}