@forgeax/engine-render 0.1.34 → 0.1.36

package/src/publication/__tests__/derived-geometry.integration.test.ts

@@ -0,0 +1,177 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { Skin } from '@forgeax/engine-skinning';
+import { expect, it } from 'vitest';
+import { createSkinPaletteOwner } from '../../assembly/skin-palette-owner';
+import { Instances, MeshFilter, MeshRenderer } from '../../components';
+import { GlyphText } from '../../components/glyph-text';
+import { InstanceProjectionStore } from '../../instances';
+import { PersistentRenderScene } from '../../scene/render-scene';
+import { renderPublicationTransfers } from '../contract';
+import { preparePublicationGeometry } from '../prepare-geometry';
+import { createRenderPublisher } from '../publisher';
+import { RenderPublicationReceiver } from '../receiver';
+
+function required<T>(value: T | undefined): T {
+  if (value === undefined) throw new Error('Missing expected render projection');
+  return value;
+}
+
+function fixture() {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const identity = { source: 'derived-geometry', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity);
+  const receiver = new RenderPublicationReceiver(identity);
+  const scene = new PersistentRenderScene();
+  const instances = new InstanceProjectionStore();
+  const publish = (palette?: ReturnType<typeof createSkinPaletteOwner>) => {
+    world.update(0).unwrap();
+    const candidate = publisher.prepare(0).unwrap();
+    const packet = structuredClone(candidate.packet);
+    candidate.accept();
+    const received = receiver.accept(packet).unwrap();
+    const prepared = preparePublicationGeometry(received, scene, palette, assets, instances);
+    const frame = scene.consumePublication(prepared);
+    publisher.recycle(packet.revision, renderPublicationTransfers(packet)).unwrap();
+    return { packet, frame };
+  };
+  const spawn = () =>
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+  return { world, assets, publisher, receiver, scene, instances, publish, spawn };
+}
+const matrix = () => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+it('derives glyph meshes in the source World and republishes edits under the same mesh handle', () => {
+  const f = fixture();
+  const font = f.world.allocSharedRef('FontAsset', {
+    kind: 'font',
+    atlas: AssetGuid.random(),
+    sampler: AssetGuid.random(),
+    glyphs: {
+      65: {
+        advance: 10,
+        bearingX: 0,
+        bearingY: 8,
+        size: { w: 8, h: 8 },
+        region: { x: 0, y: 0, w: 8, h: 8 },
+      },
+    },
+    common: {
+      lineHeight: 12,
+      base: 8,
+      distanceRange: 4,
+      pxRange: 4,
+      atlasWidth: 8,
+      atlasHeight: 8,
+    },
+  });
+  const label = f.world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: GlyphText, data: { fontHandle: font, text: 'A', fontSize: 1 } },
+    )
+    .unwrap();
+  const initial = f.publish();
+  expect(initial.frame.renderables.map((row) => row.entityKey)).toContain(label);
+  const handle = f.world.get(label, MeshFilter).unwrap().assetHandle;
+  const mesh = initial.packet.assets.find((row) => row.handle === handle)?.value;
+  expect(mesh?.kind).toBe('mesh');
+  f.world.set(label, GlyphText, { text: 'AAA' }).unwrap();
+  const edited = f.publish();
+  expect(f.world.get(label, MeshFilter).unwrap().assetHandle).toBe(handle);
+  expect(edited.packet.invalidatedAssets).toContain(handle);
+  const next = edited.packet.assets.find((row) => row.handle === handle)?.value;
+  expect(
+    next?.kind === 'mesh' && mesh?.kind === 'mesh' && next.vertices.length > mesh.vertices.length,
+  ).toBe(true);
+  f.publisher.dispose();
+  const later = f.world
+    .spawn({ component: GlyphText, data: { fontHandle: font, text: 'A' } })
+    .unwrap();
+  f.world.update(0).unwrap();
+  expect(f.world.hasComponent(later, MeshFilter)).toBe(false);
+});
+
+it('retains instance history on pose edits and retires it across removal and topology changes', () => {
+  const f = fixture();
+  const entity = f.spawn();
+  f.world.addComponent(entity, { component: Instances, data: { transforms: matrix() } }).unwrap();
+  const initial = required(f.publish().frame.renderables[0]?.instances);
+  const moved = matrix();
+  moved[12] = 2;
+  f.world.set(entity, Instances, { transforms: moved }).unwrap();
+  const edited = required(f.publish().frame.renderables[0]?.instances);
+  expect(edited.collectionId).toBe(initial.collectionId);
+  expect(edited.generations).toEqual(initial.generations);
+  expect(edited.revision).toBe(required(initial.revision) + 1);
+  f.world
+    .set(entity, Instances, { transforms: new Float32Array([...matrix(), ...matrix()]) })
+    .unwrap();
+  const resized = required(f.publish().frame.renderables[0]?.instances);
+  expect(resized.generations?.[0]).not.toBe(initial.generations?.[0]);
+  f.world.removeComponent(entity, Instances).unwrap();
+  f.publish();
+  f.world.addComponent(entity, { component: Instances, data: { transforms: matrix() } }).unwrap();
+  const restored = required(f.publish().frame.renderables[0]?.instances);
+  expect(restored.collectionId).not.toBe(initial.collectionId);
+  f.publisher.dispose();
+});
+
+it.each([
+  true,
+  false,
+])('keeps untouched skin palettes and reclaims removed slices (storage=%s)', async (storage) => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const palette = createSkinPaletteOwner(device, storage);
+  const f = fixture();
+  const skeleton = f.world.allocSharedRef('SkeletonAsset', {
+    kind: 'skeleton',
+    jointCount: 1,
+    inverseBindMatrices: matrix(),
+  });
+  const joint = f.world.spawn({ component: Transform, data: {} }).unwrap();
+  const first = f.spawn(),
+    second = f.spawn();
+  for (const entity of [first, second])
+    f.world
+      .addComponent(entity, {
+        component: Skin,
+        data: { skeleton, joints: new Uint32Array([joint]) },
+      })
+      .unwrap();
+  const initial = f.publish(palette).frame;
+  const one = required(initial.renderables.find((row) => row.entityKey === first)?.skin);
+  const two = required(initial.renderables.find((row) => row.entityKey === second)?.skin);
+  expect(one).toBeDefined();
+  expect(two).toBeDefined();
+  f.world.removeComponent(first, Skin).unwrap();
+  const removed = f.publish(palette).frame;
+  expect(removed.renderables.find((row) => row.entityKey === first)?.skin).toBeUndefined();
+  expect(removed.renderables.find((row) => row.entityKey === second)?.skin?.fence).toBe(two.fence);
+  f.world.set(joint, Transform, { pos: [1, 0, 0] }).unwrap();
+  const moved = required(
+    f.publish(palette).frame.renderables.find((row) => row.entityKey === second)?.skin,
+  );
+  expect(moved.fence).toBe(two.fence);
+  expect(moved.uploadBytes).toBe(64);
+  f.world
+    .addComponent(first, { component: Skin, data: { skeleton, joints: new Uint32Array([joint]) } })
+    .unwrap();
+  const restored = required(
+    f.publish(palette).frame.renderables.find((row) => row.entityKey === first)?.skin,
+  );
+  expect(restored.fence).not.toBe(one.fence);
+  f.publisher.dispose();
+  palette.dispose();
+});

package/src/publication/__tests__/features.integration.test.ts

@@ -0,0 +1,173 @@
+import { AssetRegistry, HANDLE_CUBE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { type MeshAsset, ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { MeshFilter, MeshRenderer } from '../../components';
+import type { RenderFeature } from '../../features/types';
+import { renderPublicationTransfers } from '../contract';
+import { createRenderPublisher } from '../publisher';
+import { RenderPublicationReceiver } from '../receiver';
+
+it('acknowledges only submitted source data, rejecting stale and duplicate receipts atomically', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const consumed: unknown[] = [];
+  let value = 1;
+  const feature: RenderFeature<unknown> = {
+    identity: 'source-events',
+    extract: () => ok({ value }),
+    plan: () => ok({ resources: [], passes: [] }),
+    onSourceFrameSubmitted: (data, feedback) => consumed.push({ data, feedback }),
+  };
+  const publisher = createRenderPublisher(world, assets, { source: 'ack', epoch: 1 }, undefined, [
+    feature,
+  ]);
+  const candidate = publisher.prepare(0).unwrap();
+  const packet = structuredClone(candidate.packet, {
+    transfer: renderPublicationTransfers(candidate.packet),
+  });
+  candidate.accept();
+  value = 2;
+  expect(consumed).toEqual([]);
+  expect(publisher.acknowledgeFeatures(0, [{ identity: feature.identity, feedback: 1 }]).ok).toBe(
+    false,
+  );
+  expect(
+    publisher.acknowledgeFeatures(1, [
+      { identity: feature.identity, feedback: 1 },
+      { identity: 'unknown', feedback: 1 },
+    ]).ok,
+  ).toBe(false);
+  expect(consumed).toEqual([]);
+  publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: 1 }]).unwrap();
+  expect(consumed).toEqual([{ data: { value: 1 }, feedback: 1 }]);
+  expect(publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: 1 }]).ok).toBe(
+    false,
+  );
+  publisher.recycle(1, renderPublicationTransfers(packet)).unwrap();
+  const next = publisher.prepare(1).unwrap();
+  next.discard();
+  expect(consumed).toHaveLength(1);
+  publisher.dispose();
+});
+
+it('publishes feature-only GUID resources and retires them when the producer drops the root', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const guid = '12345678-1234-1234-1234-123456789abc';
+  const mesh = resolveAssetHandle<MeshAsset>(world, HANDLE_CUBE).unwrap();
+  assets.catalog(guid, mesh);
+  let roots = [guid];
+  const feature: RenderFeature<unknown> = {
+    identity: 'guid-consumer',
+    extract: () => ok({}),
+    assetDependencies: () => roots,
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+  const identity = { source: 'feature-assets', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity, undefined, [feature]);
+  const receiver = new RenderPublicationReceiver(identity);
+  const first = publisher.prepare(0).unwrap();
+  const packet = structuredClone(first.packet);
+  first.accept();
+  const accepted = receiver.accept(packet).unwrap();
+  expect(accepted.resources.lookupAsset(guid)).toEqual(mesh);
+  expect(packet.assets.filter((row) => row.guid === guid)).toHaveLength(1);
+  publisher.recycle(1, renderPublicationTransfers(packet)).unwrap();
+  roots = [];
+  const next = publisher.prepare(1).unwrap();
+  expect(next.packet.retiredAssets).toContain(accepted.resources.handleForGuid(guid));
+  receiver.accept(next.packet).unwrap();
+  expect(accepted.resources.lookupAsset(guid)).toBeUndefined();
+  next.discard();
+  publisher.dispose();
+});
+
+it('publishes LOD GUID dependencies and rejects a missing lower-detail asset before acceptance', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const guid = '12345678-1234-1234-1234-123456789abc';
+  const mesh = resolveAssetHandle<MeshAsset>(world, HANDLE_CUBE).unwrap();
+  assets.catalog(guid, mesh);
+  const parsed = AssetGuid.parse(guid);
+  if (!parsed.ok) throw parsed.error;
+  const assetHandle = world.allocSharedRef('MeshAsset', {
+    ...mesh,
+    lods: [{ mesh: parsed.value, screenCoverage: 0.5 }],
+  });
+  world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+  const identity = { source: 'lod-assets', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity);
+  const receiver = new RenderPublicationReceiver(identity);
+  const candidate = publisher.prepare(0).unwrap();
+  expect(candidate.packet.assets.some((row) => row.guid === guid)).toBe(true);
+  const missing = {
+    ...candidate.packet,
+    assets: candidate.packet.assets.filter((row) => row.guid !== guid),
+  };
+  expect(receiver.accept(missing).ok).toBe(false);
+  expect(receiver.acceptedRevision).toBe(0);
+  expect(receiver.accept(structuredClone(candidate.packet)).ok).toBe(true);
+  candidate.discard();
+  publisher.dispose();
+});
+
+it('keeps two sealed publications and their feedback independent of later source mutation', async () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  let value = 1;
+  const consumed: unknown[] = [];
+  const feature: RenderFeature<unknown> = {
+    identity: 'sealed-events',
+    extract: () => ok({ value }),
+    plan: () => ok({ resources: [], passes: [] }),
+    onSourceFrameSubmitted: (data) => consumed.push(data),
+  };
+  const publisher = createRenderPublisher(
+    world,
+    assets,
+    { source: 'sealed', epoch: 1 },
+    undefined,
+    [feature],
+  );
+  const seal = () => {
+    const candidate = publisher.prepare(value).unwrap();
+    const packet = structuredClone(candidate.packet, {
+      transfer: renderPublicationTransfers(candidate.packet),
+    });
+    candidate.accept();
+    return packet;
+  };
+  try {
+    const first = seal();
+    value = 2;
+    const second = seal();
+    await Promise.resolve();
+    value = 99;
+    expect(second.features[0]?.data).toEqual({ value: 2 });
+    expect(publisher.prepare(3).ok).toBe(false);
+    expect(publisher.recycle(2, renderPublicationTransfers(second)).ok).toBe(false);
+    publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: null }]).unwrap();
+    publisher.recycle(1, renderPublicationTransfers(first)).unwrap();
+    expect(
+      publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: null }]).ok,
+    ).toBe(false);
+    publisher.acknowledgeFeatures(2, [{ identity: feature.identity, feedback: null }]).unwrap();
+    expect(consumed).toEqual([{ value: 1 }, { value: 2 }]);
+    publisher.recycle(2, renderPublicationTransfers(second)).unwrap();
+    const third = seal();
+    expect(third.base).toBe(2);
+    expect(third.features[0]?.data).toEqual({ value: 99 });
+  } finally {
+    publisher.dispose();
+  }
+});

package/src/publication/__tests__/programs.unit.test.ts

@@ -0,0 +1,25 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { expect, it } from 'vitest';
+import { installPublicationPrograms } from '../programs';
+
+it('rejects conflicting programs atomically and preserves the installed shader', () => {
+  const shaders = new ShaderRegistry({ manifestUrl: undefined });
+  const assets = new AssetRegistry(shaders);
+  const first = { key: 'forgeax::publication-test', shader: { source: 'first', paramSchema: [] } };
+  installPublicationPrograms(assets, [first]);
+  expect(() =>
+    installPublicationPrograms(assets, [
+      { key: 'forgeax::new-test', shader: { source: 'new', paramSchema: [] } },
+      { ...first, shader: { ...first.shader, source: 'conflict' } },
+    ]),
+  ).toThrow('conflicting immutable shader');
+  expect(shaders.findMaterialArtifact('forgeax::new-test').ok).toBe(false);
+  expect(shaders.findMaterialArtifact(first.key).unwrap().source).toBe('first');
+  expect(() => installPublicationPrograms(assets, [first, first])).toThrow('duplicate');
+  expect(() =>
+    installPublicationPrograms(assets, [
+      { ...first, artifact: { key: 'wrong', bytes: new Uint8Array() } },
+    ]),
+  ).toThrow('mismatched');
+});