@forgeax/engine-render 0.1.4 → 0.1.7

package/src/plugin.ts

@@ -1,23 +1,19 @@
 import type { Component, World } from '@forgeax/engine-ecs';
 import type { Plugin } from '@forgeax/engine-plugin';
-import {
-  SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY,
-  type SceneAssetSkinResolver,
-  worldSetSceneInstantiateHook,
-} from '@forgeax/engine-scene';
-
 import { Camera } from './components/camera';
 import { DirectionalLight } from './components/directional-light';
-import { SkyboxBackground, Skylight } from './components/environment';
-import { GlyphText } from './components/glyph-text';
 import { Instances } from './components/instances';
 import { Layer } from './components/layer';
+import { Lines } from './components/lines';
 import { MeshFilter } from './components/mesh-filter';
 import { MeshRenderer } from './components/mesh-renderer';
 import { PointLight } from './components/point-light';
 import { PointLightShadow } from './components/point-light-shadow';
+import { Points } from './components/points';
 import { PostProcessParams } from './components/post-process-params';
 import { SceneInstance } from './components/scene-instance';
+import { SkyboxBackground } from './components/skybox-background';
+import { Skylight } from './components/skylight';
 import { SortKey } from './components/sort-key';
 import { SpotLight } from './components/spot-light';
 import { SpriteAnimation } from './components/sprite-animation';
@@ -26,20 +22,18 @@ import { SpriteRegionOverride } from './components/sprite-region-override';
 import { TileLayer } from './components/tile-layer';
 import { Tilemap } from './components/tilemap';
 import { Visibility } from './components/visibility';
-import type { RenderFeature } from './features';
-import type { Renderer } from './renderer';
-import { postSpawnResolveJoints } from './scene-instances/post-spawn-resolve-joints';
 
 const RENDER_COMPONENTS: readonly Component[] = [
   Camera,
   DirectionalLight,
-  GlyphText,
   Instances,
   Layer,
   MeshFilter,
   MeshRenderer,
   PointLight,
   PointLightShadow,
+  Points,
+  Lines,
   PostProcessParams,
   SceneInstance,
   SkyboxBackground,
@@ -63,75 +57,13 @@ function registerRenderComponents(world: World): () => void {
   };
 }
 
-function installSceneInstantiateHook(world: World): () => void {
-  worldSetSceneInstantiateHook(world, (currentWorld, root) => {
-    if (!currentWorld.hasResource(SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY)) {
-      return { ok: true };
-    }
-    const resolver = currentWorld.getResource<SceneAssetSkinResolver>(
-      SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY,
-    );
-    return postSpawnResolveJoints(currentWorld, resolver, root);
-  });
-  return () => worldSetSceneInstantiateHook(world, null);
-}
-
-declare module '@forgeax/engine-plugin' {
-  interface EngineContextServices {
-    renderer?: Renderer;
-  }
-}
-
-/** Install the built-in render and authoring component vocabulary in one World. */
+/** Install the built-in render ECS vocabulary in one World. */
 export function renderComponentsPlugin(): Plugin {
   return {
     name: 'render-components',
     inject: ['world'],
     apply(ctx) {
       ctx.effect(() => registerRenderComponents(ctx.world), 'render/components');
-      ctx.effect(() => installSceneInstantiateHook(ctx.world), 'render/scene-instantiate-hook');
-    },
-  };
-}
-
-/** Provide the renderer without transferring its host-owned lifetime. */
-export function rendererPlugin(renderer: Renderer): Plugin {
-  return {
-    name: 'renderer',
-    provide: 'renderer',
-    apply(ctx) {
-      ctx.provide('renderer', renderer);
-    },
-  };
-}
-
-/** Provide an App/Worker-owned Renderer and release it after dependent Fibers. */
-export function ownedRendererPlugin(renderer: Renderer): Plugin {
-  return {
-    name: 'renderer',
-    provide: 'renderer',
-    apply(ctx) {
-      ctx.provide('renderer', renderer);
-      ctx.effect(() => () => renderer.dispose(), 'render/renderer');
-    },
-  };
-}
-
-/** Install a producer at Renderer safe points and remove it with the owning Fiber. */
-export function renderFeaturePlugin(feature: RenderFeature<unknown>): Plugin {
-  return {
-    name: `render-feature:${feature.identity}`,
-    inject: ['renderer'],
-    async apply(ctx) {
-      const renderer = ctx.renderer;
-      if (renderer === undefined)
-        throw new Error('render feature plugin requires the renderer service');
-      const installed = await renderer.installRenderFeature(feature);
-      if (!installed.ok) throw installed.error;
-      return async () => {
-        const removed = await renderer.uninstallRenderFeature(feature);
-        if (!removed.ok) throw removed.error;
-      };
     },
   };
 }

package/src/points-lines/__tests__/bounds.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { expandPointsLinesBounds } from '../bounds';
+
+describe('Points/Lines conservative transformed culling bounds', () => {
+  it('retains a physical-pixel raster margin around transformed edge geometry', () => {
+    const expanded = expandPointsLinesBounds(new Float32Array([10, 20, -1, 30, 40, 1]), {
+      kind: 'points',
+      sizePx: 16,
+      shape: 'circle',
+    });
+    expect([...expanded]).toEqual([2, 12, -9, 38, 48, 9]);
+  });
+
+  it('uses line width as the conservative envelope for off-edge segments', () => {
+    const expanded = expandPointsLinesBounds([-1, -1, 0, 1, 1, 0], {
+      kind: 'lines',
+      widthPx: 4,
+    });
+    expect([...expanded]).toEqual([-3, -3, -2, 3, 3, 2]);
+  });
+});

package/src/points-lines/__tests__/cache-recovery.unit.test.ts

@@ -0,0 +1,157 @@
+import { err, type MeshAsset, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { type PointsLinesExpandedGeometry, PointsLinesExpansionCache } from '../expansion-cache';
+import { type PointsLinesGpuResourceAdapter, PointsLinesPreparation } from '../prepare';
+import { createPointsLinesLaneContract, createPointsLinesRecordPlan } from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(generation = 1): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]),
+    indices: new Uint16Array([0, 1, 2, 3]),
+    attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]) },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 4, vertexCount: 4, topology: 'line-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: `lines-${generation}` }],
+  };
+}
+
+function snapshot(meshGeneration = 1, materialGeneration = 1) {
+  return createPointsLinesSnapshot({
+    worldId: 0,
+    entityKey: 4,
+    component: 'Lines',
+    meshHandle: 9,
+    meshGeneration,
+    materialHandle: 12,
+    materialGeneration,
+    style: { kind: 'lines', widthPx: 3 },
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+    viewport: { width: 320, height: 200, dpr: 1 },
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines expansion cache and LKG recovery', () => {
+  it('reuses geometry when style changes and keeps style out of the cache key', () => {
+    const cache = new PointsLinesExpansionCache();
+    const first = cache.getOrCreate(snapshot(), mesh());
+    const styled = cache.getOrCreate(
+      createPointsLinesSnapshot({
+        ...snapshot(),
+        style: { kind: 'lines', widthPx: 9 },
+      }),
+      mesh(),
+    );
+    const material = cache.getOrCreate(snapshot(1, 2), mesh());
+
+    expect(first).toBe(styled);
+    expect(first).toBe(material);
+    expect(first.key).toContain('mesh:9:1');
+    expect(styled.key).not.toContain('width=9');
+    expect(styled.vertices).toEqual(first.vertices);
+    expect(styled.positions).toEqual(first.positions);
+    expect(first).toEqual<PointsLinesExpandedGeometry>(
+      expect.objectContaining({ sourceVertexCount: 4, segmentCount: 2 }),
+    );
+  });
+
+  it('destroys only a failed candidate and retains the previous live resource', () => {
+    const calls: string[] = [];
+    let failValidation = false;
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => {
+        calls.push('create');
+        return ok(`resource-${calls.filter((call) => call === 'create').length}`);
+      },
+      upload: (resource) => {
+        calls.push(`upload:${resource}`);
+        return ok(64);
+      },
+      validate: (resource) => {
+        calls.push(`validate:${resource}`);
+        return failValidation ? err(new Error('candidate validation fault')) : ok(undefined);
+      },
+      destroy: (resource) => calls.push(`destroy:${resource}`),
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+
+    const first = preparation.prepare(snapshot(), mesh());
+    expect(first.ok).toBe(true);
+    failValidation = true;
+    const failed = preparation.prepare(snapshot(2), mesh(2));
+
+    expect(failed.ok).toBe(false);
+    expect(calls).toContain('destroy:resource-2');
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      liveResource: 'resource-1',
+      candidateBytes: 0,
+    });
+    expect(preparation.inspect().liveBytes).toBe(
+      preparation.lastKnownGood()?.geometry.derivedBytes,
+    );
+    expect(preparation.lastKnownGood()?.resource).toBe('resource-1');
+  });
+
+  it('reuses geometry for a changed style and records its new physical-pixel draw plan', () => {
+    let uploads = 0;
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: (geometry) => ok(geometry.key),
+      upload: (_resource, geometry) => {
+        uploads += 1;
+        return ok(geometry.derivedBytes);
+      },
+      validate: () => ok(undefined),
+      destroy: () => undefined,
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+    const first = preparation.prepare(snapshot(), mesh()).unwrap();
+    const changedSnapshot = createPointsLinesSnapshot({
+      ...snapshot(),
+      style: { kind: 'lines', widthPx: 9 },
+    });
+    const changed = preparation.prepare(changedSnapshot, mesh()).unwrap();
+    const plan = createPointsLinesRecordPlan(
+      changedSnapshot,
+      changed.geometry,
+      createPointsLinesLaneContract('direct', 'webgpu'),
+    );
+
+    expect(uploads).toBe(1);
+    expect(changed.geometry).toBe(first.geometry);
+    expect(plan.conservativeMarginPx).toBe(4.5);
+    expect(changed.geometry.vertices).toEqual(first.geometry.vertices);
+  });
+
+  it('rebuilds from the retained snapshot after device loss without stale bytes', () => {
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => ok('fresh'),
+      upload: () => ok(64),
+      validate: () => ok(undefined),
+      destroy: () => undefined,
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    preparation.resetForDeviceLoss();
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    expect(preparation.inspect()).toMatchObject({ status: 'resident', lastKnownGood: true });
+  });
+});

package/src/points-lines/__tests__/inspection-lanes.integration.test.ts

@@ -0,0 +1,146 @@
+import { type MeshAsset, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { PointsLinesMaterialUnsupportedError } from '../../errors/render';
+import { PointsLinesExpansionCache } from '../expansion-cache';
+import { inspectPointsLines, pointsLinesInspectionToJson } from '../inspection';
+import { type PointsLinesGpuResourceAdapter, PointsLinesPreparation } from '../prepare';
+import { createPointsLinesLaneContract, createPointsLinesRecordPlan } from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(): MeshAsset {
+  const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]);
+  return {
+    kind: 'mesh',
+    vertices: positions,
+    indices: new Uint16Array([0, 1, 2, 3]),
+    attributes: { position: positions },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 4, vertexCount: 4, topology: 'line-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'points-lines' }],
+  };
+}
+
+function snapshot(viewport = { width: 320, height: 200, dpr: 1 }) {
+  return createPointsLinesSnapshot({
+    worldId: 2,
+    entityKey: 7,
+    component: 'Lines',
+    meshHandle: 9,
+    meshGeneration: 3,
+    materialHandle: 12,
+    materialGeneration: 4,
+    style: { kind: 'lines', widthPx: 4 },
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+    viewport,
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines inspection and recovery integration', () => {
+  it('publishes typed and JSON inspection for each shared lane', () => {
+    const geometry = new PointsLinesExpansionCache().getOrCreate(snapshot(), mesh());
+    for (const lane of ['direct', 'clustered', 'cpu-webgl2'] as const) {
+      const plan = createPointsLinesRecordPlan(
+        snapshot(),
+        geometry,
+        createPointsLinesLaneContract(lane, 'webgpu'),
+      );
+      const inspection = inspectPointsLines({
+        snapshot: snapshot(),
+        topology: 'line-list',
+        lane,
+        pointCount: geometry.pointCount,
+        segmentCount: geometry.segmentCount,
+        sourceBytes: geometry.sourceBytes,
+        derivedBytes: geometry.derivedBytes,
+        cache: { hit: false, rebuilds: 1, evictions: 0 },
+        drawCount: plan.drawCount,
+        uploadBytes: geometry.derivedBytes,
+        lastKnownGood: true,
+      });
+      const json = JSON.parse(pointsLinesInspectionToJson(inspection)) as typeof inspection;
+      expect(json).toMatchObject({
+        entityKey: 7,
+        worldId: 2,
+        topology: 'line-list',
+        lane,
+        segmentCount: 2,
+        drawCount: 1,
+        lastKnownGood: true,
+      });
+      expect(json.derivedBytes).toBeGreaterThan(json.sourceBytes);
+    }
+  });
+
+  it('keeps the same retained expansion through resize and recovers one LKG', () => {
+    const resources: string[] = [];
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => {
+        const resource = `resource-${resources.length + 1}`;
+        resources.push(resource);
+        return ok(resource);
+      },
+      upload: () => ok(648),
+      validate: () => ok(undefined),
+      destroy: (resource) => resources.splice(resources.indexOf(resource), 1),
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+    const first = preparation.prepare(snapshot(), mesh()).unwrap();
+    const resized = preparation
+      .prepare(snapshot({ width: 640, height: 360, dpr: 2 }), mesh())
+      .unwrap();
+
+    expect(resized.geometry).toBe(first.geometry);
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      rebuilds: 1,
+    });
+    preparation.resetForDeviceLoss();
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+    preparation.prepare(snapshot({ width: 640, height: 360, dpr: 2 }), mesh()).unwrap();
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      rebuilds: 2,
+    });
+    expect(resources).toEqual(['resource-1']);
+  });
+
+  it('keeps executable refusal hints on the same inspection surface', () => {
+    const inspection = inspectPointsLines({
+      snapshot: snapshot(),
+      topology: 'line-list',
+      lane: 'refused',
+      pointCount: 0,
+      segmentCount: 0,
+      sourceBytes: 0,
+      derivedBytes: 0,
+      cache: { hit: false, rebuilds: 0, evictions: 0 },
+      drawCount: 0,
+      uploadBytes: 0,
+      lastKnownGood: false,
+      refusal: {
+        ...new PointsLinesMaterialUnsupportedError({
+          entity: 7,
+          material: 'mat',
+          pass: 'forward',
+          module: 'test',
+          reason: 'unsupported test material',
+        }),
+        generation: 4,
+        lastKnownGood: false,
+      },
+    });
+    expect(JSON.parse(pointsLinesInspectionToJson(inspection)).refusal.hint).toContain(
+      'Materials.unlit',
+    );
+  });
+});

package/src/points-lines/__tests__/inspection.unit.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PointsLinesBudgetExceededError,
+  PointsLinesInvalidStyleError,
+  PointsLinesMaterialUnsupportedError,
+  PointsLinesPrepareFailedError,
+  PointsLinesStyleUnsupportedError,
+  PointsLinesTopologyMismatchError,
+} from '../../errors/render';
+import {
+  inspectPointsLines,
+  type PointsLinesInspection,
+  pointsLinesInspectionToJson,
+} from '../inspection';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function baseInput(): Parameters<typeof inspectPointsLines>[0] {
+  return {
+    snapshot: createPointsLinesSnapshot({
+      worldId: 2,
+      entityKey: 15,
+      component: 'Lines',
+      meshHandle: 5,
+      meshGeneration: 3,
+      materialHandle: 7,
+      materialGeneration: 4,
+      style: { kind: 'lines', widthPx: 2 },
+      layer: 1,
+      visible: true,
+      sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+      viewport: { width: 640, height: 480, dpr: 2 },
+      projection: new Float32Array(16),
+    }),
+    topology: 'line-list',
+    lane: 'pending',
+    pointCount: 0,
+    segmentCount: 2,
+    sourceBytes: 64,
+    derivedBytes: 48,
+    cache: { hit: false, rebuilds: 1, evictions: 0 },
+    drawCount: 1,
+    uploadBytes: 48,
+    lastKnownGood: true,
+  };
+}
+
+describe('bounded Points/Lines inspection', () => {
+  it('projects normal typed facts and a JSON-safe equivalent', () => {
+    const inspection = inspectPointsLines(baseInput());
+
+    expect(inspection).toEqual<PointsLinesInspection>({
+      entityKey: 15,
+      worldId: 2,
+      component: 'Lines',
+      meshHandle: 5,
+      meshGeneration: 3,
+      materialHandle: 7,
+      materialGeneration: 4,
+      style: { kind: 'lines', widthPx: 2 },
+      topology: 'line-list',
+      lane: 'pending',
+      pointCount: 0,
+      segmentCount: 2,
+      sourceBytes: 64,
+      derivedBytes: 48,
+      cache: { hit: false, rebuilds: 1, evictions: 0 },
+      drawCount: 1,
+      uploadBytes: 48,
+      lastKnownGood: true,
+    });
+    expect(JSON.parse(pointsLinesInspectionToJson(inspection))).toEqual(inspection);
+  });
+
+  it('keeps refusal and recovery provenance bounded and typed', () => {
+    const refusal = inspectPointsLines({
+      ...baseInput(),
+      lane: 'refused',
+      lastKnownGood: false,
+      drawCount: 0,
+      uploadBytes: 0,
+      refusal: {
+        ...new PointsLinesPrepareFailedError({
+          owner: 'test',
+          generation: 3,
+          stage: 'prepare',
+          cause: 'test failure',
+          lastKnownGood: false,
+        }),
+        generation: 3,
+        lastKnownGood: false,
+      },
+    });
+    const recovery = inspectPointsLines({
+      ...baseInput(),
+      lane: 'pending',
+      cache: { hit: true, rebuilds: 2, evictions: 1 },
+      lastKnownGood: true,
+    });
+
+    expect(refusal.refusal?.code).toBe('points-lines-prepare-failed');
+    expect(refusal.drawCount).toBe(0);
+    expect(recovery.cache).toEqual({ hit: true, rebuilds: 2, evictions: 1 });
+    expect(pointsLinesInspectionToJson(refusal)).not.toContain('RHI');
+  });
+
+  it('preserves source detail for all six Points/Lines refusal paths', () => {
+    const errors = [
+      new PointsLinesInvalidStyleError({
+        entity: 15,
+        component: 'Lines',
+        field: 'widthPx',
+        value: 0,
+        expected: 'widthPx > 0',
+      }),
+      new PointsLinesTopologyMismatchError({
+        entity: 15,
+        submesh: 0,
+        expected: 'line-list',
+        actual: 'triangle-list',
+      }),
+      new PointsLinesStyleUnsupportedError({
+        lane: 'direct',
+        field: 'shape',
+        member: 'diamond',
+        supported: ['square', 'circle'],
+      }),
+      new PointsLinesMaterialUnsupportedError({
+        entity: 15,
+        material: 'mat',
+        pass: 'forward',
+        module: 'test',
+        reason: 'unsupported test material',
+      }),
+      new PointsLinesBudgetExceededError({
+        lane: 'direct',
+        requested: 9,
+        limit: 8,
+        unit: 'draws',
+      }),
+      new PointsLinesPrepareFailedError({
+        owner: 'test',
+        generation: 3,
+        stage: 'prepare',
+        cause: 'test failure',
+        lastKnownGood: false,
+      }),
+    ];
+
+    for (const error of errors) {
+      const inspection = inspectPointsLines({
+        ...baseInput(),
+        lane: 'refused',
+        drawCount: 0,
+        uploadBytes: 0,
+        lastKnownGood: false,
+        refusal: {
+          ...error,
+          generation: 3,
+          lastKnownGood: false,
+        },
+      });
+      expect(inspection.refusal).toMatchObject({
+        code: error.code,
+        expected: error.expected,
+        hint: error.hint,
+        detail: error.detail,
+      });
+      expect(JSON.parse(pointsLinesInspectionToJson(inspection)).refusal.detail).toEqual(
+        error.detail,
+      );
+    }
+  });
+});