@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/feature-depth-material.fixture.ts

@@ -0,0 +1,473 @@
+import { createBoxGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack';
+import type { Renderer, RenderFeature } from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+import { ParticleEffectPlayer, type ParticleRendererSourceV3 } from '@forgeax/engine-vfx';
+import { cookParticleCodeEffect } from '@forgeax/engine-vfx-compiler';
+import { createVfxRuntimeHost } from '@forgeax/engine-vfx-render';
+import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
+import { expect } from 'vitest';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import { frameRequest, preparedWorld } from './render-feature-prepared-graphics.fixture';
+
+const manifest = await buildEngineShaderManifest();
+const schema = [
+  { name: 'tint', type: 'vec4' },
+  { name: 'selector', type: 'u32' },
+  { name: 'direction', type: 'i32' },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+export const particleDepthLayouts = [
+  { name: 'billboard-material-input-instance', location: 9, offset: 31, size: 35, mesh: false },
+  {
+    name: 'topology-segment-material-input-instance',
+    location: 4,
+    offset: 12,
+    size: 16,
+    mesh: false,
+  },
+  { name: 'mesh-geometry-material-input-instance', location: 10, offset: 18, size: 22, mesh: true },
+] as const;
+export async function verifyFeatureDepthMaterial(
+  layout: (typeof particleDepthLayouts)[number] & {
+    readonly particleKind?: ParticleRendererSourceV3['kind'];
+    readonly view: boolean;
+    readonly missing: 'none' | 'material' | 'depth';
+    readonly inputLane?: number;
+    readonly allInputs?: boolean;
+    readonly writeDepth?: boolean;
+  },
+): Promise<void> {
+  const { view, missing } = layout;
+  const inputLane = layout.inputLane ?? 0;
+  const identifier = `test::depth-material-${layout.name}-${view}-${missing}`;
+  const instance = new Float32Array(layout.size);
+  instance[layout.offset] = 0.5;
+  const source = `
+${view ? 'struct View { matrix: mat4x4<f32> }; @group(0) @binding(0) var<uniform> view: View;' : ''}
+@group(0) @binding(${view ? 1 : 0}) var scene_depth: texture_depth_2d;
+struct Material { tint: vec4<f32>, selector: u32, direction: i32 };
+@group(1) @binding(0) var<uniform> material: Material;
+@group(1) @binding(1) var material_sampler: sampler;
+@group(1) @binding(2) var material_texture: texture_2d<f32>;
+struct Input { @location(${layout.location + (layout.allInputs ? 3 : inputLane)}) particle: vec4<f32>,
+  ${layout.allInputs ? `@location(${layout.location}) first: vec4<f32>, @location(${layout.location + 1}) second: vec4<f32>, @location(${layout.location + 2}) third: vec4<f32>,` : ''}
+  ${layout.particleKind === 'mesh' ? '@location(0) geometry: vec3<f32>,' : ''}
+};
+struct Output { @builtin(position) position: vec4<f32>, @location(0) factor: f32 };
+@vertex fn vs_main(input: Input, @builtin(vertex_index) index: u32) -> Output {
+  let p = array<vec2<f32>, 3>(vec2(-1., -1.), vec2(3., -1.), vec2(-1., 3.));
+  let factor = ${layout.allInputs ? 'select(-1.0, input.particle.x, input.first.x == 3.0 && input.second.x == 1.0 && input.third.x == 2.0)' : 'input.particle.x'};
+  return Output(vec4(${layout.particleKind === 'mesh' ? 'input.geometry.xy * 2.0' : 'p[index % 3u]'}, 0.5, 1.), factor);
+}
+@fragment fn fs_main(input: Output) -> @location(0) vec4<f32> {
+  let depth = textureLoad(scene_depth, vec2<i32>(input.position.xy), 0);
+  let sampled = textureSampleLevel(material_texture, material_sampler, vec2(0.5), 0.);
+  if (material.selector != 3u || material.direction != -7) { return vec4(0., 1., 0., 1.); }
+  return vec4(material.tint.rgb * sampled.rgb * depth * input.factor, 1.);
+}`;
+  const shaderManifestUrl = `data:application/json,${encodeURIComponent(
+    JSON.stringify({
+      ...manifest,
+      materialShaders: [
+        ...manifest.materialShaders,
+        ...(layout.writeDepth
+          ? [
+              {
+                identifier: `${identifier}-writer`,
+                sourcePath: `${identifier}-writer`,
+                composedWgsl: `@vertex fn vs_main(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+                let p = array<vec2<f32>, 3>(vec2(-1., -1.), vec2(3., -1.), vec2(-1., 3.));
+                return vec4(p[index], 0.25, 1.);
+              }`,
+                paramSchema: '[]',
+                variants: [],
+              },
+            ]
+          : []),
+        {
+          identifier,
+          sourcePath: identifier,
+          composedWgsl: source,
+          paramSchema: JSON.stringify(schema),
+          variants: [],
+        },
+      ],
+    }),
+  )}`;
+  const materialGuid = AssetGuid.random();
+  const meshGuid = AssetGuid.random();
+  const particleInputs = layout.allInputs
+    ? ['heat', 'warm', 'hot', 'glow'].map((name, lane) => ({
+        name,
+        type: 'f32' as const,
+        visibility: 'fragment' as const,
+        lane,
+      }))
+    : [{ name: 'heat', type: 'f32' as const, visibility: 'fragment' as const, lane: inputLane }];
+  const vfx =
+    layout.particleKind === undefined
+      ? undefined
+      : createVfxRuntimeHost({
+          camera: {
+            read: () => ({
+              position: new Float32Array([0, 0, 3]),
+              right: new Float32Array([1, 0, 0]),
+              up: new Float32Array([0, 1, 0]),
+              viewProjection: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+            }),
+          },
+        });
+  const feature: RenderFeature<undefined> = {
+    identity: identifier,
+    extract: () => ok(undefined),
+    plan: (_, context) => {
+      const color = context.targets.find((target) => target.kind === 'color');
+      const depth = context.targets.find((target) => target.kind === 'depth');
+      if (color === undefined || depth === undefined) throw new Error('Missing scene targets');
+      return ok({
+        resources: [
+          ...(layout.writeDepth
+            ? [
+                {
+                  kind: 'graphics-program' as const,
+                  name: 'depth-writer',
+                  program: {
+                    shader: `${identifier}-writer`,
+                    vertexLayout: 'none',
+                    colorFormats: [],
+                    depthFormat: depth.format,
+                    sampleCount: depth.sampleCount,
+                    renderState: {
+                      depthWriteEnabled: true,
+                      depthCompare: 'always' as const,
+                      cullMode: 'none' as const,
+                    },
+                  },
+                },
+                {
+                  kind: 'graphics-bindings' as const,
+                  name: 'depth-bindings',
+                  program: 'depth-writer',
+                  values: { group: 0 },
+                },
+              ]
+            : []),
+          {
+            kind: 'graphics-program',
+            name: 'program',
+            program: {
+              shader: identifier,
+              vertexLayout: layout.name,
+              particleInputLanes: 1,
+              colorFormats: [color.format],
+              sampleCount: color.sampleCount,
+            },
+          },
+          {
+            kind: 'graphics-bindings',
+            name: 'scene',
+            program: 'program',
+            values: { group: 0, sceneDepthBinding: view ? 1 : 0 },
+            ...(missing === 'depth' ? {} : { logicalTargets: { sceneDepth: depth.name } }),
+          },
+          {
+            kind: 'graphics-bindings',
+            name: 'material',
+            program: 'program',
+            values: { group: 1, material: { world: 0, guid: AssetGuid.format(materialGuid) } },
+          },
+          { kind: 'vertex-data', name: 'instance', layout: layout.name, data: instance },
+          ...(layout.mesh
+            ? [
+                {
+                  kind: 'vertex-data' as const,
+                  name: 'geometry',
+                  layout: layout.name,
+                  data: new Float32Array(36),
+                },
+              ]
+            : []),
+        ],
+        passes: [
+          ...(layout.writeDepth
+            ? [
+                {
+                  kind: 'raster' as const,
+                  name: 'write-depth',
+                  colorAttachments: [],
+                  depthStencilAttachment: {
+                    target: depth.name,
+                    depthLoadOp: 'load' as const,
+                    depthStoreOp: 'store' as const,
+                  },
+                  draws: [
+                    {
+                      program: 'depth-writer',
+                      bindings: ['depth-bindings'],
+                      vertexData: [],
+                      vertexLayout: 'none' as const,
+                      draw: { kind: 'draw' as const, vertexCount: 3, instanceCount: 1 },
+                    },
+                  ],
+                },
+              ]
+            : []),
+          {
+            kind: 'raster',
+            name: 'sample',
+            colorAttachments: [{ target: color.name, loadOp: 'load', storeOp: 'store' }],
+            sampledTargets: missing === 'depth' ? [] : [depth.name],
+            draws: [
+              {
+                program: 'program',
+                bindings: ['scene', 'material'],
+                vertexData: layout.mesh
+                  ? [
+                      { slot: 0, resource: 'geometry' },
+                      { slot: 1, resource: 'instance' },
+                    ]
+                  : [{ slot: 0, resource: 'instance' }],
+                draw: { kind: 'draw', vertexCount: 3, instanceCount: 1 },
+              },
+            ],
+          },
+        ],
+      });
+    },
+  };
+  const particleFeature =
+    vfx === undefined
+      ? undefined
+      : {
+          ...vfx.feature,
+          plan: (
+            data: Parameters<typeof vfx.feature.plan>[0],
+            context: Parameters<typeof vfx.feature.plan>[1],
+          ) =>
+            vfx.feature.plan(
+              data,
+              missing === 'depth'
+                ? {
+                    ...context,
+                    targets: context.targets.filter((target) => target.kind !== 'depth'),
+                  }
+                : context,
+            ),
+        };
+  let device: GPUDevice | undefined;
+  let target: GPUTexture | undefined;
+  const gpuErrors: string[] = [];
+  const canvas = {
+    width: 64,
+    height: 64,
+    getContext: () => ({
+      configure(descriptor: { device: GPUDevice; format: GPUTextureFormat }) {
+        device = descriptor.device;
+        device.addEventListener('uncapturederror', (event) => gpuErrors.push(event.error.message));
+        target = device.createTexture({
+          size: [64, 64],
+          format: descriptor.format,
+          viewFormats: ['rgba8unorm-srgb'],
+          usage: 0x10 | 0x01,
+        });
+      },
+      unconfigure() {},
+      getCurrentTexture: () => target,
+    }),
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  let renderer: Renderer | undefined;
+  let attachedWorld: ReturnType<typeof preparedWorld> | undefined;
+  try {
+    const constructed = await constructRuntimeRendererHost(
+      canvas,
+      { features: [particleFeature ?? feature] },
+      { shaderManifestUrl },
+    );
+    if (!constructed.ok) throw constructed.error;
+    const host = constructed.value;
+    renderer = host.renderer;
+    const textureGuid = AssetGuid.random();
+    if (vfx !== undefined) host.assets.catalog(meshGuid, createBoxGeometry(1, 1, 1).unwrap());
+    host.assets.catalog(textureGuid, {
+      kind: 'texture',
+      shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
+      format: 'rgba8unorm',
+      data: new Uint8Array([255, 0, 0, 255]),
+      colorSpace: 'linear',
+      mips: { kind: 'none' },
+    });
+    if (missing !== 'material')
+      host.assets.catalog(materialGuid, {
+        kind: 'material',
+        passes: [
+          {
+            name: layout.particleKind === undefined ? 'Forward' : `particle-${layout.particleKind}`,
+            program: { module: identifier },
+            renderState: { tags: { LightMode: 'Forward' }, queue: 3000, depthWriteEnabled: false },
+          },
+        ],
+        ...(vfx === undefined
+          ? {}
+          : {
+              parameters: [
+                { name: 'tint', type: 'vec4' },
+                { name: 'selector', type: 'u32' },
+                { name: 'direction', type: 'i32' },
+                { name: 'baseColorTexture', type: 'texture' },
+              ],
+              particleInputs,
+            }),
+        values: {
+          tint: [0.5, 1, 1, 1],
+          selector: 3,
+          direction: -7,
+          baseColorTexture: { texture: AssetGuid.format(textureGuid) as never },
+        },
+      });
+    const errors: unknown[] = [];
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error);
+    });
+    const world = preparedWorld();
+    const attached = renderer.attach(world);
+    if (!attached.ok) throw attached.error;
+    const lease = attached.value;
+    if (vfx !== undefined) {
+      const particleRenderer = {
+        kind: layout.particleKind,
+        material: AssetGuid.format(materialGuid),
+        materialInputs: particleInputs.map((input) => input.name),
+        ...(layout.particleKind === 'mesh' ? { mesh: AssetGuid.format(meshGuid) } : {}),
+        ...(layout.particleKind === 'ribbon' ? { stripKey: 'alive-index', capacity: 4 } : {}),
+        ...(layout.particleKind === 'trail' ? { historyLength: 3, capacity: 4 } : {}),
+        ...(layout.particleKind === 'beam' ? { endpointField: 'velocity', capacity: 4 } : {}),
+      } as ParticleRendererSourceV3;
+      const cooked = await cookParticleCodeEffect(
+        {
+          schemaVersion: 3,
+          emitters: [
+            {
+              id: 'combined',
+              capacity: 4,
+              backend: { required: 'gpu' },
+              space: 'world',
+              bounds: { kind: 'sphere', center: [0, 0, 0], radius: 4 },
+              schedule: { rate: 0, bursts: [{ time: 0, count: 2 }] },
+              program: { module: 'combined.wgsl' },
+              renderers: [particleRenderer],
+            },
+          ],
+        },
+        {
+          'combined.wgsl': {
+            entry: `
+#import forgeax_vfx::prelude::{VfxParticle, VfxSpawnContext, VfxUpdateContext}
+struct VfxParameters { heat: f32, }
+struct VfxCustom { heat: f32, ${layout.allInputs ? 'warm: f32, hot: f32, glow: f32,' : ''} }
+fn vfx_spawn(ctx: VfxSpawnContext, particle: ptr<function, VfxParticle>, custom: ptr<function, VfxCustom>) {
+  (*particle).position = vec3<f32>(f32(ctx.particleId) * 0.1, 0.0, 0.0);
+  (*particle).velocity = vec3<f32>(0.0, 1.0, 0.0);
+  (*particle).mesh_orientation = vec4<f32>(0.0, 0.0, 0.0, 1.0);
+  (*particle).mesh_scale = vec3<f32>(1.0);
+  (*particle).lifetime = 100.0;
+}
+fn vfx_update(ctx: VfxUpdateContext, particle: ptr<function, VfxParticle>, custom: ptr<function, VfxCustom>) {
+  (*particle).position.x += ctx.delta;
+  ${layout.allInputs ? '(*custom).heat = 3.0; (*custom).warm = 1.0; (*custom).hot = 2.0; (*custom).glow = forgeax_vfx_parameters.heat;' : '(*custom).heat = forgeax_vfx_parameters.heat;'}
+}`,
+          },
+        },
+        { [AssetGuid.format(materialGuid)]: particleInputs },
+      );
+      if (!cooked.ok) throw cooked.error;
+      const attachment = await vfx.attachWorld({ world, assets: host.assets });
+      if (!attachment.ok) throw attachment.error;
+      attachedWorld = world;
+      const player = world
+        .spawn({
+          component: ParticleEffectPlayer,
+          data: {
+            effect: world.allocSharedRef('ParticleEffectAsset', cooked.value.asset),
+            playing: true,
+            seed: 1,
+            timeScale: 1,
+          },
+        })
+        .unwrap();
+      world.update(1 / 60).unwrap();
+      const control = vfx.acquireControl(world).unwrap();
+      const patched = control.patchPlayerParameters({ player, values: { heat: 0.5 } });
+      if (!patched.ok) throw patched.error;
+    }
+    for (let frame = 0; frame < 5; frame += 1) {
+      expect(world.update(1 / 60).ok).toBe(true);
+      const submitted = renderer.draw(frameRequest(lease));
+      if (!submitted.ok) throw submitted.error;
+      const observed = await renderer.observe(submitted.value, { include: ['draws'] });
+      if (!observed.ok) throw observed.error;
+    }
+    expect(gpuErrors).toEqual([]);
+    if (missing !== 'none') {
+      expect(errors).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            detail: expect.objectContaining({
+              cause: expect.objectContaining({
+                code:
+                  vfx !== undefined && missing === 'material'
+                    ? 'render-feature-stage-failed'
+                    : 'render-feature-preparation-failed',
+              }),
+            }),
+          }),
+        ]),
+      );
+      return;
+    }
+    expect(errors).toEqual([]);
+    if (device === undefined || target === undefined) throw new Error('Missing GPU surface');
+    const readback = device.createBuffer({ size: 256 * 64, usage: 0x01 | 0x08 });
+    const encoder = device.createCommandEncoder();
+    encoder.copyTextureToBuffer(
+      { texture: target },
+      { buffer: readback, bytesPerRow: 256 },
+      [64, 64],
+    );
+    device.queue.submit([encoder.finish()]);
+    await readback.mapAsync(1);
+    const pixel = new Uint8Array(readback.getMappedRange()).slice(
+      32 * 256 + 32 * 4,
+      32 * 256 + 32 * 4 + 4,
+    );
+    readback.unmap();
+    readback.destroy();
+    if (layout.writeDepth) {
+      // Tint 0.5 * red texture 1 * instance 0.5 * written depth 0.25,
+      // encoded into the sRGB display surface. Clear depth 1 cannot pass.
+      const linearRed = 0.5 * 0.5 * 0.25;
+      const encodedRed = Math.round((1.055 * linearRed ** (1 / 2.4) - 0.055) * 255);
+      expect(Math.abs((pixel[0] ?? 0) - encodedRed)).toBeLessThanOrEqual(2);
+    } else expect(pixel[0]).toBeGreaterThan(50);
+    expect(pixel[1]).toBeLessThan(5);
+    expect(pixel[2]).toBeLessThan(5);
+  } finally {
+    // Negative material/depth cases return before a readback fence. Drain their
+    // submitted work before releasing this headless host's GPU resources.
+    if (device !== undefined) await device.queue.onSubmittedWorkDone();
+    if (vfx !== undefined && attachedWorld !== undefined)
+      await vfx.detachWorld({ world: attachedWorld });
+    renderer?.dispose();
+    target?.destroy();
+    // This headless fixture owns the raw device. Renderer.dispose releases
+    // renderer resources but deliberately leaves device lifetime to its host.
+    // Finish this case's device lifetime before starting the next combination.
+    if (device !== undefined) {
+      device.destroy();
+      expect((await device.lost).reason).toBe('destroyed');
+    }
+  }
+}

package/src/__tests__/fullscreen-post-process-pass.dawn.test.ts

@@ -581,21 +581,21 @@ describe('feat-20260604 M2 w10: FullscreenPostProcessPass dawn tests', () => {
       rgbByteDiffCount,
       `paired readback must expose the existing FXAA difference; diagnostics=${JSON.stringify(diagnostics)}; ` +
         `noneSurface=${JSON.stringify({
-          displayEncoded: inspectionNone.displayEncoded,
-          intermediateFormat: inspectionNone.intermediateFormat,
-          surfaceStorage: inspectionNone.surfaceStorage,
-          surfaceDisplay: inspectionNone.surfaceDisplay,
-          endpoint: inspectionNone.endpoint,
-          capability: inspectionNone.capability,
-          error: inspectionNone.error,
+          displayEncoded: inspectionNone.output.displayEncoded,
+          intermediateFormat: inspectionNone.output.intermediateFormat,
+          surfaceStorage: inspectionNone.output.surfaceStorage,
+          surfaceDisplay: inspectionNone.output.surfaceDisplay,
+          endpoint: inspectionNone.output.endpoint,
+          capability: inspectionNone.output.capability,
+          error: inspectionNone.output.error,
         })}; fxaaSurface=${JSON.stringify({
-          displayEncoded: inspectionFxaa.displayEncoded,
-          intermediateFormat: inspectionFxaa.intermediateFormat,
-          surfaceStorage: inspectionFxaa.surfaceStorage,
-          surfaceDisplay: inspectionFxaa.surfaceDisplay,
-          endpoint: inspectionFxaa.endpoint,
-          capability: inspectionFxaa.capability,
-          error: inspectionFxaa.error,
+          displayEncoded: inspectionFxaa.output.displayEncoded,
+          intermediateFormat: inspectionFxaa.output.intermediateFormat,
+          surfaceStorage: inspectionFxaa.output.surfaceStorage,
+          surfaceDisplay: inspectionFxaa.output.surfaceDisplay,
+          endpoint: inspectionFxaa.output.endpoint,
+          capability: inspectionFxaa.output.capability,
+          error: inspectionFxaa.output.error,
           standardOutputNone,
           standardOutputFxaa,
         })}`,

package/src/__tests__/geometry.unit.test.ts

@@ -51,6 +51,7 @@ import { MeshRenderer } from '../../../render/src/components/mesh-renderer';
 import type { MeshGpuHandles } from '../../../render/src/device/gpu-residency';
 import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
 import type { GpuBuffer } from '../../../render/src/gpu-resource';
+import { InstanceCollectionStore } from '../../../render/src/instances';
 import type {
   PipelineBuilderContext,
   PipelineBuilderShaderModuleFactory,
@@ -380,7 +381,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       kind: 'mesh',
       vertices,
       indices: new Uint16Array([0, 1, 2]),
-      attributes: { position: positions },
+      attributes: { ...buildMeshAttributeMapForUvSets(1), position: positions },
       aabb,
       materialSlots: [{ slotName: 'Default' }],
       submeshes: [
@@ -683,23 +684,10 @@ function drawPublished(renderer: RendererType, world: WorldType) {
 
 {
   // --- from instances.test.ts ---
-  // w14 - Instances component schema migration to `array<f32>` (M3, AC-06).
+  // Renderer-owned Instances association (E1 large-instance cutover).
   //
-  // Locks AC-06 (requirements.md): the `transforms: 'array<f32>'` field
-  // resolves to a fresh `Float32Array` snapshot at the get-site. The stride
-  // contract (length must be a non-zero multiple of 16) lives at the
-  // RenderSystem extract entry (`packages/runtime/src/render-system-extract.ts`)
-  // + the AI user set-site -- the ECS layer is stride-agnostic
-  // post-feat-20260515-buffer-array-vocab-collapse (decision §2.3).
-  //
-  // feat-20260515-buffer-array-vocab-collapse M3 / w16: the legacy
-  // component-level per-component stride defineComponent option was retired;
-  // stride violations now route the runtime-side
-  // `instance-transforms-stride-mismatch` error through the Layer-3
-  // ErrorHandler from the RenderSystem extract entry rather than from the
-  // ECS write paths. The runtime defensive coverage lives in
-  // `render-system-stride.test.ts` (w14); this file covers the ECS-side
-  // schema + happy-path read invariants only.
+  // ECS keeps only the collection identity; Render validates and owns the
+  // matrix payload, revision and dirty ranges in InstanceCollectionStore.
   //
   // Test path note: project convention places runtime tests under
   // `src/__tests__/` (see `instances.test-d.ts` header for the rationale).
@@ -709,20 +697,25 @@ function drawPublished(renderer: RendererType, world: WorldType) {
     readonly detail: unknown;
   }
 
-  function makeHarness(): { world: World; collected: CollectedError[] } {
+  function makeHarness(): {
+    world: World;
+    collected: CollectedError[];
+    instanceCollections: InstanceCollectionStore;
+  } {
     const collected: CollectedError[] = [];
     const world = new World();
-    return { world, collected };
+    return { world, collected, instanceCollections: new InstanceCollectionStore() };
   }
 
-  describe('w14 - Instances { transforms: array<f32> } schema (AC-06)', () => {
-    it('Instances.schema.transforms is the array<f32> keyword (no legacy buffer/count fields)', () => {
+  describe('renderer-owned Instances association', () => {
+    it('Instances schema carries only collectionId (no managed payload fields)', () => {
       expect(Instances.name).toBe('Instances');
       expect(Object.keys(Instances.fields).length).toBe(1);
-      expect(Instances.fields.transforms?.type).toBe('array<f32>');
-      // Legacy fields retired in M3.
+      expect(Instances.fields.collectionId?.type).toBe('u32');
+      expect(Instances.fields.collectionId?.default).toBe(0);
       expect(Instances.fields.buffer).toBeUndefined();
       expect(Instances.fields.count).toBeUndefined();
+      expect(Instances.fields.transforms).toBeUndefined();
     });
 
     it('Instances component carries no per-component stride option (decision §2.3 migration)', () => {
@@ -732,8 +725,8 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       expect((Instances as unknown as Record<string, unknown>).arrayStride).toBeUndefined();
     });
 
-    it('(legal) spawn with 16 f32 multiples succeeds; snapshot length reflects element count', () => {
-      const { world, collected } = makeHarness();
+    it('(legal) collection creation and ECS association preserve the matrix payload', () => {
+      const { world, collected, instanceCollections } = makeHarness();
       const N = 4;
       const transforms = new Float32Array(N * 16);
       // Fill column 3 with distinguishable translations so the read path can
@@ -742,27 +735,29 @@ function drawPublished(renderer: RendererType, world: WorldType) {
         transforms[i * 16 + 12] = i + 1;
         transforms[i * 16 + 15] = 1;
       }
-      const e = world.spawn({ component: Instances, data: { transforms } }).unwrap();
-      // No stride error fires on the ECS write path post-feat-20260515.
-      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
-        0,
-      );
-      const snap = world.get(e, Instances).unwrap().transforms;
+      const collection = instanceCollections.create({ transforms }).unwrap();
+      const e = world
+        .spawn({
+          component: Instances,
+          data: { collectionId: collection.collectionId },
+        })
+        .unwrap();
+      expect(collected).toHaveLength(0);
+      const association = world.get(e, Instances).unwrap();
+      expect(association.collectionId).toBe(collection.collectionId);
+      const snap = instanceCollections.snapshot(collection.collectionId).unwrap().transforms;
       expect(snap.length).toBe(N * 16);
       // Sanity: column 3 translation x of instance 2 reads back as 3.
       expect(snap[2 * 16 + 12]).toBe(3);
     });
 
-    it('(ECS layer is stride-agnostic) spawn with 17 f32 does NOT route a stride error from ECS', () => {
-      const { world, collected } = makeHarness();
-      world.spawn({ component: Instances, data: { transforms: new Float32Array(17) } });
-      // The runtime-side defensive lives in render-system-extract; the ECS
-      // write path itself MUST NOT route any stride error code.
-      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
-        0,
-      );
-      // Negative anchor for the retired ECS-layer code.
-      expect(collected.filter((c) => c.code === 'managed-array-stride-mismatch').length).toBe(0);
+    it('rejects malformed matrix payloads before publishing an ECS association', () => {
+      const { world, collected, instanceCollections } = makeHarness();
+      const malformed = instanceCollections.create({ transforms: new Float32Array(17) });
+      expect(malformed.ok).toBe(false);
+      expect(collected).toHaveLength(0);
+      const e = world.spawn({ component: Instances, data: {} }).unwrap();
+      expect(world.get(e, Instances).unwrap().collectionId).toBe(0);
     });
   });
 }
@@ -879,7 +874,6 @@ function drawPublished(renderer: RendererType, world: WorldType) {
         iboBytes: 0,
         indexCount: 0,
         indexFormat: 'uint16',
-        layout: '12F',
         vertexCount: 2,
         indexed: false,
         topology: 'line-list',
@@ -2341,7 +2335,11 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       { component: C.MeshRenderer, data: { materials: materialHandles } },
       { component: C.MeshFilter, data: { assetHandle: meshHandle } },
       { component: C.Transform, data: originTransform() },
-      { component: C.Instances, data: { transforms } },
+      { component: C.GlobalTransform, data: {} },
+      {
+        component: C.Instances,
+        data: { collectionId: _renderer.instances.create({ transforms }).unwrap().collectionId },
+      },
     );
     return world;
   }
@@ -2518,6 +2516,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       vertices: new Float32Array(4 * 12), // 4 verts x 12 floats
       indices,
       attributes: {
+        ...buildMeshAttributeMapForUvSets(1),
         position: new Float32Array(4 * 3),
       },
       materialSlots: [{ slotName: 'Default' }],