@forgeax/engine-render 0.1.2

package/src/extract/index.ts

@@ -0,0 +1,10 @@
+export type { ExtractedFrame, PreparedExtractContext } from '../render-system-extract';
+export { extractFrame, prepareExtractContext } from '../render-system-extract';
+export {
+  createMaterialInterfaceOwner,
+  type DerivedMaterialCoordinateProjection,
+  type DerivedMaterialSlotProjection,
+  type DerivedMaterialSlotProjectionInput,
+  deriveMaterialSlotProjection,
+} from './material-interface';
+export * from './visibility';

package/src/extract/material-interface.ts

@@ -0,0 +1,604 @@
+import type { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
+import { type CookedMaterialRecord, validateCookedMaterialRecord } from '@forgeax/engine-pack';
+import type {
+  DerivedMaterialInterface,
+  Handle,
+  MaterialAsset,
+  MaterialColorParameterSchema,
+  MaterialParameter,
+  MaterialPass,
+  MaterialPassList,
+  MaterialRenderState,
+  MaterialTextureCoordinates,
+  ParamSchemaEntry,
+  TextureAsset,
+} from '@forgeax/engine-types';
+import {
+  createMaterialError,
+  derive,
+  err,
+  type MaterialError,
+  materialGuidText,
+  materialValuesToLinearRuntime,
+  ok,
+  type Result,
+  resolveMaterialAsset,
+  resolveMaterialTextureCoordinates,
+  toShared,
+} from '@forgeax/engine-types';
+import type { RenderAssetPort } from '../assets/render-asset-port';
+import { resolveRenderAsset } from '../assets/resolve-render-asset';
+import type { GpuResourceStore } from '../gpu-resource-store';
+import {
+  deriveParamSchemaForCensus,
+  type ParamSchemaProjectionCensus,
+} from '../param-schema-projection-census';
+import { deriveTextureExtent } from '../render-data';
+import type {
+  MaterialSnapshot,
+  MaterialSnapshotCache,
+  MaterialSnapshotCacheEntry,
+} from '../render-system-extract';
+
+export interface DerivedMaterialCoordinateProjection extends MaterialTextureCoordinates {
+  readonly physicalUvScale: readonly [number, number];
+}
+
+export interface DerivedMaterialSlotProjection {
+  readonly material: string;
+  readonly derivedInterface: DerivedMaterialInterface;
+  readonly layoutIdentity: string;
+  readonly numericValues: Readonly<Record<string, number | readonly number[]>>;
+  readonly coordinates: ReadonlyMap<string, DerivedMaterialCoordinateProjection>;
+}
+
+export interface DerivedMaterialSlotProjectionInput {
+  readonly material: string;
+  readonly schema: readonly ParamSchemaEntry[];
+  readonly derivedInterface?: DerivedMaterialInterface;
+  readonly values: Readonly<Record<string, unknown>>;
+  readonly coordinates: ReadonlyMap<string, MaterialTextureCoordinates>;
+  readonly textures?: ReadonlyMap<
+    string,
+    { readonly format: GPUTextureFormat; readonly width: number; readonly height: number }
+  >;
+}
+
+/** The material pass list is the single source of truth for caster eligibility. */
+export function hasShadowCasterPass(passes: readonly MaterialPass[]): boolean {
+  return passes.some(
+    (pass) =>
+      (pass.renderState as { readonly tags?: Readonly<Record<string, string>> } | undefined)?.tags
+        ?.LightMode === 'ShadowCaster',
+  );
+}
+
+export function defaultMaterialTextureCoordinates(
+  schemaOrProjection: readonly ParamSchemaEntry[] | DerivedMaterialInterface,
+): Map<string, MaterialTextureCoordinates> {
+  const derivedInterface = Array.isArray(schemaOrProjection)
+    ? derive(schemaOrProjection as readonly ParamSchemaEntry[])
+    : (schemaOrProjection as DerivedMaterialInterface);
+  return new Map(derivedInterface.coordinateRecords.map((record) => [record.parameter, {}]));
+}
+
+export function deriveMaterialSlotProjection(
+  input: DerivedMaterialSlotProjectionInput,
+): Result<DerivedMaterialSlotProjection, MaterialError> {
+  let derived: DerivedMaterialInterface;
+  try {
+    derived = input.derivedInterface ?? derive(input.schema);
+  } catch (error) {
+    return err(
+      createMaterialInterfaceError(
+        input.material,
+        error instanceof Error ? error.message : 'invalid schema',
+      ),
+    );
+  }
+  const numericValues: Record<string, number | readonly number[]> = {};
+  for (const member of derived.numericMembers) {
+    const value = input.values[member.name];
+    if (
+      typeof value === 'number' ||
+      (Array.isArray(value) && value.every((item) => typeof item === 'number'))
+    ) {
+      numericValues[member.name] = value as number | readonly number[];
+    }
+  }
+  const coordinates = new Map<string, DerivedMaterialCoordinateProjection>();
+  for (const record of derived.coordinateRecords) {
+    const authored = input.coordinates.get(record.parameter);
+    const resolved = resolveMaterialTextureCoordinates(authored);
+    const texture = input.textures?.get(record.parameter);
+    const physicalUvScale =
+      texture === undefined
+        ? ([1, 1] as const)
+        : deriveTextureExtent(texture.format, texture.width, texture.height).uvScale;
+    coordinates.set(record.parameter, { ...resolved, physicalUvScale });
+  }
+  return ok({
+    material: input.material,
+    derivedInterface: derived,
+    layoutIdentity: derived.layoutIdentity,
+    numericValues,
+    coordinates,
+  });
+}
+
+function createMaterialInterfaceError(material: string, reason: string) {
+  return {
+    code: 'material-derived-interface-mismatch' as const,
+    expected: 'the material slot projection matches its derived schema interface',
+    hint: 'repair the material schema or coordinates and recook the material',
+    detail: {
+      code: 'material-derived-interface-mismatch' as const,
+      stage: 'extract' as const,
+      material,
+      layoutIdentity: 'unknown',
+      action: 'recook' as const,
+      parameter: reason,
+    },
+    message: `material-derived-interface-mismatch: ${reason}`,
+  };
+}
+
+export interface MaterialInterfaceDependencies {
+  readonly defaultMaterialSnapshot: (materialHandle?: number) => MaterialSnapshot;
+  readonly readStablePersistentMaterialSnapshot: (
+    cache: MaterialSnapshotCache | undefined,
+    handleRaw: number,
+    assets: RenderAssetPort,
+  ) => MaterialSnapshotCacheEntry | undefined;
+  readonly readPersistentMaterialSnapshot: (
+    cache: MaterialSnapshotCache | undefined,
+    handleRaw: number,
+    assets: RenderAssetPort,
+  ) => MaterialSnapshotCacheEntry | undefined;
+  readonly storeMaterialSnapshot: (
+    cache: MaterialSnapshotCache,
+    handleRaw: number,
+    snapshot: MaterialSnapshot,
+    passes: readonly MaterialPass[],
+    root: MaterialAsset,
+    assets: RenderAssetPort,
+  ) => MaterialSnapshotCacheEntry;
+  readonly runtimeMaterialShaderId: (
+    module: string | undefined,
+    passName?: string,
+  ) => string | undefined;
+  readonly pipelineRenderState: (
+    renderState: MaterialRenderState | undefined,
+  ) => MaterialRenderState | undefined;
+  readonly materialColorParameterSchema: (
+    parameters: readonly MaterialParameter[],
+    shaderId: string | undefined,
+    assets: RenderAssetPort,
+  ) => readonly MaterialColorParameterSchema[];
+  readonly materialNormalScale: (values: Readonly<Record<string, unknown>>) => number;
+  readonly materialParametersToParamSchema: (
+    parameters: readonly MaterialParameter[],
+    shaderId: string | undefined,
+    assets: RenderAssetPort,
+  ) => readonly ParamSchemaEntry[];
+  readonly collectUserRegionTextureHandles: (
+    values: Readonly<Record<string, unknown>>,
+    shaderId: string | undefined,
+    paramSchema: readonly ParamSchemaEntry[] | undefined,
+    derivedInterface: DerivedMaterialInterface | undefined,
+    assets: RenderAssetPort,
+    world: World,
+    resolveTexture: (
+      value: unknown,
+      brand: 'TextureAsset',
+    ) => Handle<'TextureAsset', 'shared'> | undefined,
+    videoOut: Map<string, Handle<'VideoAsset', 'shared'>>,
+    paramSchemaProjectionCensus?: ParamSchemaProjectionCensus,
+  ) => Map<string, Handle<'TextureAsset', 'shared'>>;
+  readonly collectMaterialTextureSamplers: (
+    values: Readonly<Record<string, unknown>>,
+    resolveSampler: (value: unknown) => Handle<'SamplerAsset', 'shared'> | undefined,
+  ) => Map<string, Handle<'SamplerAsset', 'shared'>>;
+  readonly materialTextureRef: (value: unknown) => unknown;
+  readonly collectMaterialTextureCoordinates: (
+    values: Readonly<Record<string, unknown>>,
+    schema: readonly ParamSchemaEntry[],
+    derivedInterface?: DerivedMaterialInterface,
+    paramSchemaProjectionCensus?: ParamSchemaProjectionCensus,
+  ) => Map<string, import('@forgeax/engine-types').MaterialTextureCoordinates>;
+  readonly internSharedRefFromGuid: <B extends string>(
+    world: World,
+    assets: RenderAssetPort,
+    guid: string,
+    brand: B,
+  ) => Handle<B, 'shared'> | undefined;
+}
+
+export interface MaterialInterfaceOwner {
+  readonly resolveMaterialSnapshot: (
+    handleRaw: number,
+    world: World,
+    assets: RenderAssetPort,
+    gpuStore?: GpuResourceStore,
+    materialSnapshotCache?: MaterialSnapshotCache,
+    persistentMaterialSnapshotCache?: MaterialSnapshotCache,
+    paramSchemaProjectionCensus?: ParamSchemaProjectionCensus,
+  ) => MaterialSnapshot;
+}
+
+export function resolveMaterialFromPort(
+  root: MaterialAsset,
+  assets: RenderAssetPort,
+  runtimeShaderId: (module: string | undefined, passName?: string) => string | undefined = (
+    module,
+  ) => module,
+): Result<MaterialAsset, MaterialError> {
+  const cooked = cookedMaterialRecord(root, assets);
+  if (!cooked.ok) return cooked;
+  if (cooked.value !== undefined) {
+    const registered = registerCookedMaterialShaders(
+      cooked.value,
+      assets,
+      runtimeShaderId,
+      assets.guidOf(root) ?? '__render_material_root__',
+    );
+    if (!registered.ok) return registered;
+    return ok({
+      ...root,
+      ...(root.passes === undefined
+        ? { passes: cooked.value.resolved.passes as MaterialPassList }
+        : {}),
+      ...(root.parameters === undefined ? { parameters: cooked.value.resolved.parameters } : {}),
+      values: {
+        ...cooked.value.resolved.values,
+        ...(root.values ?? {}),
+      },
+    });
+  }
+
+  const rootKey = assets.guidOf(root) ?? '__render_material_root__';
+  const table: Record<string, MaterialAsset> = { [rootKey]: root };
+  const visited = new Set<string>([rootKey]);
+  let current = root;
+  while (current.parent !== undefined) {
+    const parentKey = materialGuidText(current.parent);
+    if (visited.has(parentKey)) break;
+    visited.add(parentKey);
+    const parent = assets.lookup<MaterialAsset>(parentKey);
+    if (parent === undefined || parent.kind !== 'material') break;
+    table[parentKey] = parent;
+    current = parent;
+  }
+  const resolved = resolveMaterialAsset(rootKey, table);
+  return resolved.ok ? ok(resolved.value.asset) : resolved;
+}
+
+type MaterialAssetWithCooked = MaterialAsset & { readonly cooked?: unknown };
+
+function cookedMaterialRecord(
+  root: MaterialAsset,
+  assets: RenderAssetPort,
+): Result<CookedMaterialRecord | undefined, MaterialError> {
+  const candidate = (root as MaterialAssetWithCooked).cooked;
+  if (candidate === undefined) return ok(undefined);
+  const validated = validateCookedMaterialRecord(candidate);
+  if (validated.ok) return validated;
+  return err(
+    createMaterialError('material-specialization-not-cooked', {
+      code: 'material-specialization-not-cooked',
+      material: assets.guidOf(root) ?? '__render_material_root__',
+      staticSelection: [],
+    }),
+  );
+}
+
+export function materialParametersToParamSchema(
+  parameters: readonly MaterialParameter[],
+): readonly ParamSchemaEntry[] {
+  return parameters.flatMap((parameter): ParamSchemaEntry[] => {
+    if (parameter.static || parameter.type === 'bool') return [];
+    if (parameter.type === 'texture') return [{ name: parameter.name, type: 'texture2d' }];
+    const defaultValue = parameter.default;
+    const numericDefault =
+      typeof defaultValue === 'number' ||
+      (Array.isArray(defaultValue) && defaultValue.every((item) => typeof item === 'number'))
+        ? { default: defaultValue }
+        : {};
+    return [
+      {
+        name: parameter.name,
+        type: parameter.type,
+        ...(parameter.colorSpace === undefined ? {} : { colorSpace: parameter.colorSpace }),
+        ...numericDefault,
+      },
+    ];
+  });
+}
+
+function registerCookedMaterialShaders(
+  record: CookedMaterialRecord,
+  assets: RenderAssetPort,
+  runtimeShaderId: (module: string | undefined, passName?: string) => string | undefined,
+  material: string,
+): Result<void, MaterialError> {
+  const source = new TextDecoder().decode(record.artifact.bytes);
+  const staticSelection = record.resolved.parameters
+    .filter((parameter) => parameter.static)
+    .map((parameter) => parameter.name);
+  if (source.length === 0) {
+    return err(
+      createMaterialError('material-specialization-not-cooked', {
+        code: 'material-specialization-not-cooked',
+        material,
+        staticSelection,
+      }),
+    );
+  }
+  const paramSchema = materialParametersToParamSchema(record.resolved.parameters);
+  for (const pass of record.resolved.passes) {
+    const identifier = runtimeShaderId(pass.program.module, pass.name);
+    if (identifier === undefined || identifier.length === 0) {
+      return err(
+        createMaterialError('material-specialization-not-cooked', {
+          code: 'material-specialization-not-cooked',
+          material,
+          staticSelection,
+        }),
+      );
+    }
+    if (assets.shaderRegistry.findMaterialArtifact(identifier).ok) continue;
+    try {
+      assets.shaderRegistry.installMaterialArtifact(identifier, { source, paramSchema });
+    } catch {
+      return err(
+        createMaterialError('material-specialization-not-cooked', {
+          code: 'material-specialization-not-cooked',
+          material,
+          staticSelection,
+        }),
+      );
+    }
+  }
+  return ok(undefined);
+}
+
+export function createMaterialInterfaceOwner(
+  deps: MaterialInterfaceDependencies,
+): MaterialInterfaceOwner {
+  function resolveMaterialSnapshot(
+    handleRaw: number,
+    world: World,
+    assetsRef: RenderAssetPort,
+    gpuStore?: GpuResourceStore,
+    materialSnapshotCache?: MaterialSnapshotCache,
+    persistentMaterialSnapshotCache?: MaterialSnapshotCache,
+    paramSchemaProjectionCensus?: ParamSchemaProjectionCensus,
+  ): MaterialSnapshot {
+    void gpuStore;
+    if (handleRaw === 0) return deps.defaultMaterialSnapshot(handleRaw);
+    const cached = materialSnapshotCache?.get(handleRaw);
+    if (cached !== undefined) return cached.snapshot;
+    const stablePersistentCached = deps.readStablePersistentMaterialSnapshot(
+      persistentMaterialSnapshotCache,
+      handleRaw,
+      assetsRef,
+    );
+    if (stablePersistentCached !== undefined) {
+      materialSnapshotCache?.set(handleRaw, stablePersistentCached);
+      return stablePersistentCached.snapshot;
+    }
+    const tagged = toShared<'MaterialAsset'>(handleRaw);
+    const resolvedAsset = resolveRenderAsset(world, tagged);
+    if (!resolvedAsset.ok) return deps.defaultMaterialSnapshot(handleRaw);
+    const asset = resolvedAsset.value;
+    if (asset.kind !== 'material') return deps.defaultMaterialSnapshot(handleRaw);
+    const materialGuid = assetsRef.guidOf(asset);
+    const persistentCached = deps.readPersistentMaterialSnapshot(
+      persistentMaterialSnapshotCache,
+      handleRaw,
+      assetsRef,
+    );
+    if (persistentCached !== undefined) {
+      materialSnapshotCache?.set(handleRaw, persistentCached);
+      return persistentCached.snapshot;
+    }
+    const resolvedResult = resolveMaterialFromPort(asset, assetsRef, deps.runtimeMaterialShaderId);
+    if (!resolvedResult.ok) return deps.defaultMaterialSnapshot(handleRaw);
+    const resolved = resolvedResult.value;
+    const allPasses = resolved.passes ?? [];
+    const firstPassShader =
+      allPasses.length > 0
+        ? deps.runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
+        : undefined;
+    const values = materialValuesToLinearRuntime(
+      resolved.values,
+      deps.materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assetsRef),
+      resolved.colorSpace,
+    ) as Readonly<Record<string, unknown>>;
+    const baseColorValue = values.baseColor as readonly number[] | undefined;
+    const baseColor = vec3.create(
+      baseColorValue?.[0] ?? 1,
+      baseColorValue?.[1] ?? 1,
+      baseColorValue?.[2] ?? 1,
+    );
+    const paramSnapshot: Record<string, number | number[] | string> = {};
+    for (const [name, value] of Object.entries(values)) {
+      if (typeof value === 'number' || typeof value === 'string') paramSnapshot[name] = value;
+      else if (Array.isArray(value) && value.every((item) => typeof item === 'number')) {
+        paramSnapshot[name] = value as number[];
+      }
+    }
+    const registeredShader =
+      firstPassShader === undefined
+        ? undefined
+        : assetsRef.shaderRegistry.findMaterialArtifact(firstPassShader);
+    const registeredProjection =
+      registeredShader?.ok === true ? registeredShader.value.paramSchemaProjection : undefined;
+    const materialParamSchema =
+      registeredProjection?.schema ??
+      deps.materialParametersToParamSchema(resolved.parameters ?? [], firstPassShader, assetsRef);
+    const derivedInterface =
+      registeredProjection?.derivedInterface ??
+      (materialParamSchema.length > 0
+        ? deriveParamSchemaForCensus(materialParamSchema, paramSchemaProjectionCensus, 'submesh')
+        : undefined);
+    if (paramSchemaProjectionCensus !== undefined && registeredProjection !== undefined) {
+      paramSchemaProjectionCensus.record('registered-projection-read', 'submesh');
+      if (
+        registeredProjection.schema.length === 0 &&
+        Object.keys(resolved.values ?? {}).some((name) => name.endsWith('Texture'))
+      ) {
+        paramSchemaProjectionCensus.record('empty-schema-legacy-inference', 'submesh');
+      }
+    }
+    const resolveTextureLike = <B extends string>(
+      value: unknown,
+      brand: B,
+    ): Handle<B, 'shared'> | undefined => {
+      if (typeof value === 'number') return value as unknown as Handle<B, 'shared'>;
+      if (typeof value !== 'string') return undefined;
+      return deps.internSharedRefFromGuid(world, assetsRef, value, brand);
+    };
+    const videoTextureFields = new Map<string, Handle<'VideoAsset', 'shared'>>();
+    const textureHandles = deps.collectUserRegionTextureHandles(
+      values,
+      firstPassShader,
+      registeredProjection === undefined ? materialParamSchema : undefined,
+      derivedInterface,
+      assetsRef,
+      world,
+      resolveTextureLike,
+      videoTextureFields,
+      paramSchemaProjectionCensus,
+    );
+    const samplerHandles = deps.collectMaterialTextureSamplers(values, (value) =>
+      resolveTextureLike(deps.materialTextureRef(value), 'SamplerAsset'),
+    );
+    const emissiveTextureHandle = resolveTextureLike(
+      deps.materialTextureRef(values.emissiveTexture),
+      'TextureAsset',
+    );
+    const occlusionTextureHandle = resolveTextureLike(
+      deps.materialTextureRef(values.occlusionTexture),
+      'TextureAsset',
+    );
+    const textureCoordinates = deps.collectMaterialTextureCoordinates(
+      values,
+      materialParamSchema,
+      derivedInterface,
+      paramSchemaProjectionCensus,
+    );
+    const baseColorTextureHandle = textureHandles.get('baseColorTexture');
+    const metallicRoughnessTextureHandle = textureHandles.get('metallicRoughnessTexture');
+    const normalTextureHandle = textureHandles.get('normalTexture');
+    const textureFacts = new Map<string, TextureAsset>();
+    for (const [name, handle] of textureHandles) {
+      const resolvedTexture = resolveRenderAsset(world, handle);
+      if (resolvedTexture.ok && resolvedTexture.value.kind === 'texture') {
+        textureFacts.set(name, resolvedTexture.value);
+      }
+    }
+    for (const [name, handle] of [
+      ['emissiveTexture', emissiveTextureHandle],
+      ['occlusionTexture', occlusionTextureHandle],
+    ] as const) {
+      if (handle === undefined) continue;
+      const resolvedTexture = resolveRenderAsset(world, handle);
+      if (resolvedTexture.ok && resolvedTexture.value.kind === 'texture') {
+        textureFacts.set(name, resolvedTexture.value);
+      }
+    }
+    const derivedMaterialSlot =
+      registeredProjection !== undefined && materialParamSchema.length > 0
+        ? deriveMaterialSlotProjection({
+            material: String(handleRaw),
+            schema: materialParamSchema,
+            derivedInterface: registeredProjection.derivedInterface,
+            values,
+            coordinates: textureCoordinates,
+            textures: textureFacts,
+          })
+        : undefined;
+    const emissiveValue = values.emissive as readonly number[] | undefined;
+    const snapshot: MaterialSnapshot = {
+      baseColor,
+      metallic: typeof values.metallic === 'number' ? values.metallic : 0,
+      roughness: typeof values.roughness === 'number' ? values.roughness : 0.5,
+      clearcoat: typeof values.clearcoat === 'number' ? values.clearcoat : 0,
+      clearcoatRoughness:
+        typeof values.clearcoatRoughness === 'number' ? values.clearcoatRoughness : 0.5,
+      ...(Array.isArray(values.specularTint) && {
+        specularTint: [
+          values.specularTint[0] ?? 1,
+          values.specularTint[1] ?? 1,
+          values.specularTint[2] ?? 1,
+        ] as readonly [number, number, number],
+      }),
+      normalScale: deps.materialNormalScale(values),
+      materialShaderId: firstPassShader,
+      ...(materialGuid === undefined ? {} : { materialGuid }),
+      materialHandle: handleRaw,
+      shadowCaster: hasShadowCasterPass(allPasses),
+      renderState: deps.pipelineRenderState(allPasses[0]?.renderState),
+      paramSnapshot,
+      ...(materialParamSchema.length > 0 && { materialParamSchema }),
+      ...(derivedMaterialSlot?.ok === true && { derivedMaterialSlot: derivedMaterialSlot.value }),
+      ...(derivedMaterialSlot?.ok === false && { derivedMaterialError: derivedMaterialSlot.error }),
+      ...(textureCoordinates.size > 0 && { textureCoordinates }),
+      ...(textureHandles.size > 0 && { textureHandles }),
+      ...(videoTextureFields.size > 0 && { videoTextureFields }),
+      ...(samplerHandles.size > 0 && { samplerHandles }),
+      ...(baseColorTextureHandle !== undefined && { baseColorTexture: baseColorTextureHandle }),
+      ...(metallicRoughnessTextureHandle !== undefined && {
+        metallicRoughnessTexture: metallicRoughnessTextureHandle,
+      }),
+      ...(normalTextureHandle !== undefined && { normalTexture: normalTextureHandle }),
+      ...(emissiveValue !== undefined && {
+        emissive: [
+          emissiveValue[0] ?? 0,
+          emissiveValue[1] ?? 0,
+          emissiveValue[2] ?? 0,
+        ] as readonly [number, number, number],
+      }),
+      ...(typeof values.emissiveIntensity === 'number' && {
+        emissiveIntensity: values.emissiveIntensity,
+      }),
+      ...(emissiveTextureHandle !== undefined && { emissiveTexture: emissiveTextureHandle }),
+      ...(occlusionTextureHandle !== undefined && { occlusionTexture: occlusionTextureHandle }),
+      ...(typeof values.occlusionStrength === 'number' && {
+        occlusionStrength: values.occlusionStrength,
+      }),
+      transparent: allPasses[0]?.renderState?.blend !== undefined,
+    };
+    const stored =
+      materialSnapshotCache !== undefined
+        ? deps.storeMaterialSnapshot(
+            materialSnapshotCache,
+            handleRaw,
+            snapshot,
+            allPasses,
+            asset,
+            assetsRef,
+          )
+        : undefined;
+    const cacheEntry =
+      stored ??
+      (persistentMaterialSnapshotCache !== undefined
+        ? deps.storeMaterialSnapshot(
+            persistentMaterialSnapshotCache,
+            handleRaw,
+            snapshot,
+            allPasses,
+            asset,
+            assetsRef,
+          )
+        : undefined);
+    if (cacheEntry?.crossFrameSafe === true) {
+      persistentMaterialSnapshotCache?.set(handleRaw, cacheEntry);
+    }
+    return snapshot;
+  }
+
+  return { resolveMaterialSnapshot };
+}

package/src/extract/schema-readers.ts

@@ -0,0 +1,27 @@
+import type { Camera, DirectionalLight } from '../components';
+
+export interface RenderExtract {
+  readonly mesh: { readonly assetHandle: unknown };
+  readonly light: { readonly direction: unknown; readonly intensity: number };
+  readonly camera: { readonly projection: number; readonly near: number; readonly far: number };
+}
+
+/** Project the canonical render component rows without copying or adapting their shape. */
+export function readRenderSchemas(
+  mesh: Record<string, unknown>,
+  light: Record<string, unknown>,
+  camera: Record<string, unknown>,
+): RenderExtract {
+  return {
+    mesh: { assetHandle: mesh.assetHandle },
+    light: { direction: light.direction, intensity: Number(light.intensity ?? 1) },
+    camera: {
+      projection: Number(camera.projection ?? 0),
+      near: Number(camera.near),
+      far: Number(camera.far),
+    },
+  };
+}
+
+export type RenderCameraSchema = typeof Camera;
+export type RenderDirectionalLightSchema = typeof DirectionalLight;