@forgeax/engine-render 0.1.34 → 0.1.35

package/src/errors/render.ts

@@ -1,3 +1,4 @@
+import type { RenderPublicationError } from '../publication/contract';
 // @forgeax/engine-render -- render cluster error classes.
 //
 // feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the monolithic
@@ -562,7 +563,7 @@ export class PointShadowAtlasBoundsViolationError extends Error {
  * Fired by the per-frame record stage (`videoTextureView`) when a VideoPlayer
  * entity can reach neither video upload path this frame: the general
  * `copyExternalImageToTexture` path (no host HTMLVideoElement resolved via
- * `VideoElementProvider`) AND the high-perf `GPUExternalTexture` path
+ * `VideoSourceProvider`) AND the high-perf `GPUExternalTexture` path
  * (capability absent). The engine surfaces this explicit failure rather than
  * silently rendering a stale/garbage texture (charter P3, plan-strategy D-6).
  *   - `.code = 'video-upload-unsupported'`
@@ -1980,6 +1981,7 @@ export type RenderErrorCode = RenderError['code'];
  * `RenderErrorCode` discriminant on `.code`.
  */
 export type RenderError =
+  | RenderPublicationError
   | LifecycleConstructionError
   | AutoExposureError
   | RendererExpectedOperationError

package/src/extract/material-context.ts

@@ -0,0 +1,21 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/** The receiving device selects the immutable material program domain. */
+export function renderMaterialContext(caps: Pick<RhiCaps, 'backendKind' | 'storageBuffer'>): {
+  readonly materialContext?: MaterialCookProgramContext;
+} {
+  if (caps.backendKind === 'null') return {};
+  return {
+    materialContext: {
+      backend: caps.backendKind === 'wgpu-webgl2' ? 'webgl2' : caps.backendKind,
+      capability: caps.storageBuffer ? 'storage-buffer' : 'uniform-fallback',
+      pipeline: 'forward',
+      geometry: 'mesh',
+      pass: 'forward',
+      profile: 'forgeax-material-wgsl-v1',
+      toolchain: 'naga-oil',
+      instrumentation: 'none',
+    },
+  };
+}

package/src/features/host.ts

@@ -133,6 +133,8 @@ export interface RenderFeatureStageEvent {
 }
 
 export interface RenderFeatureFrameInput {
+  readonly publishedFeatures?: readonly { readonly identity: string; readonly data: unknown }[];
+  readonly onFeatureSourceSubmitted?: (identity: string, feedback: unknown) => void;
   readonly worlds: readonly import('@forgeax/engine-ecs').World[];
   readonly owner: number;
   readonly frameNumber: number;
@@ -1454,7 +1456,10 @@ export function runRenderFeatureFrame(
     const extracted = invokeStage(
       slot,
       'extract',
-      () => slot.feature.extract(extractContext),
+      () => {
+        const published = input.publishedFeatures?.find((row) => row.identity === identity);
+        return published === undefined ? slot.feature.extract(extractContext) : ok(published.data);
+      },
       stageEvents,
       errors,
     );
@@ -1655,11 +1660,14 @@ export function runRenderFeatureFrame(
       continue;
     }
     planExecutionProjections.set(plannedFrame, projected.value);
-    if (feature.onFrameSubmitted !== undefined) {
+    if (feature.onFrameSubmitted !== undefined || feature.onSourceFrameSubmitted !== undefined) {
       submissionSensitivePlans.add(plannedFrame);
-      submissionAcknowledgments.set(plannedFrame, () =>
-        feature.onFrameSubmitted?.(extracted.value, projected.value),
-      );
+      submissionAcknowledgments.set(plannedFrame, () => {
+        feature.onFrameSubmitted?.(extracted.value, projected.value);
+        if (input.publishedFeatures?.some((row) => row.identity === identity))
+          input.onFeatureSourceSubmitted?.(identity, declared.value.sourceFeedback);
+        else feature.onSourceFrameSubmitted?.(extracted.value, declared.value.sourceFeedback);
+      });
     }
     plans.push(plannedFrame);
     if (feature.onFrameAborted !== undefined) {

package/src/features/plan.ts

@@ -237,6 +237,8 @@ export type RenderFeaturePassDeclaration =
  * access is derived from these roles rather than duplicated as reads/writes.
  */
 export interface RenderFeaturePlan {
+  /** Source acknowledgment facts; never part of GPU resource or graph identity. */
+  readonly sourceFeedback?: unknown;
   readonly resources: readonly RenderFeatureResourceDeclaration[];
   readonly passes: readonly RenderFeaturePassDeclaration[];
 }

package/src/features/types.ts

@@ -171,6 +171,8 @@ export interface RenderFeature<FrameData> {
     readonly source: string;
   }[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
+  /** GUID roots needed by the declarative plan; the publisher carries their asset closure. */
+  assetDependencies?(data: FrameData): readonly string[];
   plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
   /**
    * Consume frame-owned producer state only after the compiled graph reached
@@ -178,6 +180,8 @@ export interface RenderFeature<FrameData> {
    * extracted frame and never during declarative planning.
    */
   onFrameSubmitted?(data: FrameData, submission?: RenderFeatureSubmission): void;
+  /** Consume source-owned intents after submission; feedback must be structured-cloneable. */
+  onSourceFrameSubmitted?(data: FrameData, feedback: unknown): void;
   /**
    * Discard frame-owned producer state when graph admission or submission is
    * rejected.  This is the symmetric recovery path for onFrameSubmitted.

package/src/glyph-text-layout-system.ts

@@ -158,7 +158,7 @@ interface GlyphTextData {
  */
 export function glyphTextLayoutSystem(
   world: World,
-  gpuStore: GpuResidencyCache,
+  gpuStore: Pick<GpuResidencyCache, 'updateMesh'>,
 ): Result<void, TextError> {
   resetFontConcurrency();
 
@@ -200,7 +200,7 @@ function collectGlyphEntities(world: World): EntityHandle[] {
  */
 function processEntity(
   world: World,
-  gpuStore: GpuResidencyCache,
+  gpuStore: Pick<GpuResidencyCache, 'updateMesh'>,
   entity: EntityHandle,
 ): TextError | null {
   const gtRes = world.get(entity, GlyphText);

package/src/gpu-driven/shadow-ownership.ts

@@ -1,5 +1,5 @@
-import type { World } from '@forgeax/engine-ecs';
 import { gpuDrivenShadowDrawKey } from '../extract/gpu-driven';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import { worldEntityKey } from '../record/frame-snapshot';
 import type { ShadowCasterMembership } from '../render-system-extract';
 
@@ -7,12 +7,12 @@ const WORLD_ENTITY_KEY_STRIDE = 4294967296;
 
 /**
  * Extract emits world/entity keys in the transient `worlds[]` index domain,
- * while PersistentRenderScene owns stable renderer-local World keys for the
+ * while PersistentRenderScene owns stable renderer-local RenderResourceScope keys for the
  * retained GPU scene. Rebase ShadowCaster ownership at this orchestration
  * boundary before both GPU projection and CPU residual recording consume it.
  */
 export function rebaseShadowCasterOwnership(
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   stableWorldKeys: readonly number[],
   entityKeys: ReadonlySet<number>,
   drawKeys: ReadonlySet<string>,

package/src/ibl/frame-resources.ts

@@ -32,7 +32,6 @@ export function resolveFrameSkylightResources(
     prefilterView: resident?.prefilterView ?? fallback.prefilterView,
     prefilterSampler: fallback.sampler,
     brdfLutView: resident?.brdfLutView ?? fallback.brdfLutView,
-    brdfLutSampler: fallback.sampler,
     intensityBuffer: fallback.intensityBuffer,
   });
 }

package/src/ibl/skylight-bind-group.ts

@@ -1,20 +1,20 @@
 // skylight-bind-group.ts -- Skylight resources merged into @group(1) PBR
-// material BGL (binding 7..13) + fallback identity resource bundle. The
+// material BGL (binding 7..12) + fallback identity resource bundle. The
 // complete Standard material group appends transmission entries.
 //
 // Plan-strategy D-5 (round-4 REVISED): the round-2 stand-alone @group(4)
 // Skylight BindGroupLayout collided with WebGPU's default maxBindGroups=4
 // limit, blocking pbr-pl pipeline-layout creation in chrome-beta. Round-4
-// rewrites the contract: Skylight 7 entries are **appended** to the
-// existing PBR material BindGroupLayout at bindings 7..13; pipeline layout
+// rewrites the contract: Skylight 6 entries are **appended** to the
+// existing PBR material BindGroupLayout at bindings 7..12; pipeline layout
 // stays at 4 slots `[view, material, mesh, instances]`; unlit pipeline is
 // untouched (it uses its own material BGL).
 //
 // Surface (M2 round-4 / t40 amend):
 //   - mergeSkylightIntoMaterialBgl(materialBglEntries): given the existing
 //     7 PBR material BindGroupLayout entries (binding 0..6), returns the
-//     merged 14-entry array with Skylight resources at binding 7..13
-//     [irrTex, irrSampler, prefTex, prefSampler, brdfTex, brdfSampler,
+//     merged 13-entry array with Skylight resources at binding 7..12
+//     [irrTex, irrSampler, prefTex, prefSampler, brdfTex,
 //     uniform { intensity: f32 }]. The merge is a pure function -- caller
 //     (createRenderer) is responsible for passing the result to
 //     `device.createBindGroupLayout`.
@@ -124,13 +124,13 @@ export interface SkylightQueue {
  */
 export interface SkylightBindGroupResources {
   readonly irradianceView: TextureView;
+  /** Shared by diffuse irradiance and the BRDF lookup table. */
   readonly irradianceSampler: Sampler;
   readonly prefilterView: TextureView;
   /** Present only when the per-draw prefilter slot was replaced by a local probe. */
   readonly skylightPrefilterView?: TextureView;
   readonly prefilterSampler: Sampler;
   readonly brdfLutView: TextureView;
-  readonly brdfLutSampler: Sampler;
   readonly intensityBuffer: Buffer;
 }
 
@@ -143,7 +143,7 @@ export interface SkylightBindGroupResources {
  *
  * No stand-alone `bindGroup` field: the round-2 stand-alone Skylight BG
  * is gone (D-5 round-4); the fallback resources flow into the PBR
- * material BG at binding 7..13.
+ * material BG at binding 7..12.
  */
 export interface SkylightFallback {
   readonly irradianceTexture: Texture;
@@ -159,7 +159,7 @@ export interface SkylightFallback {
 // ─── Pure merger: BindGroupLayout entries (D-5 round-4) ─────────────────────
 
 /**
- * Append the 7 Skylight BindGroupLayout entries after the existing PBR
+ * Append the 6 Skylight BindGroupLayout entries after the existing PBR
  * user-region entries. Pure function -- the
  * caller passes the result to `device.createBindGroupLayout`. Charter P4
  * consistent abstraction: one BGL holds material + Skylight together,
@@ -208,16 +208,10 @@ export function mergeSkylightIntoMaterialBgl(
     visibility: GPU_SHADER_STAGE_FRAGMENT,
     texture: { sampleType: 'float', viewDimension: '2d' },
   } as BglEntry);
-  // binding 12: brdfLutSampler
+  // binding 12: uniform { intensity: f32 }
   merged.push({
     binding: skylightBindingStart + 5,
     visibility: GPU_SHADER_STAGE_FRAGMENT,
-    sampler: { type: 'filtering' },
-  } as BglEntry);
-  // binding 13: uniform { intensity: f32 }
-  merged.push({
-    binding: skylightBindingStart + 6,
-    visibility: GPU_SHADER_STAGE_FRAGMENT,
     buffer: { type: 'uniform' },
   } as BglEntry);
   return merged;
@@ -226,7 +220,7 @@ export function mergeSkylightIntoMaterialBgl(
 // ─── Pure merger: BindGroupEntry values (assembly site) ─────────────────────
 
 /**
- * Append the 7 Skylight BindGroupEntry resources (binding 7..13) onto the
+ * Append the 6 Skylight BindGroupEntry resources (binding 7..12) onto the
  * existing PBR material BindGroupEntry values (binding 0..6). The caller
  * passes the result to `device.createBindGroup` as part of the merged
  * material BG.
@@ -301,10 +295,6 @@ export function assembleMaterialWithSkylightEntries(
     },
     {
       binding: iblStart + 5,
-      resource: { kind: 'sampler', value: skylight.brdfLutSampler },
-    },
-    {
-      binding: iblStart + 6,
       resource: { kind: 'buffer', value: { buffer: skylight.intensityBuffer } },
     },
   ];
@@ -413,11 +403,9 @@ export function createSkylightFallback(
   device: SkylightDevice,
   queue: SkylightQueue,
 ): SkylightFallback {
-  // One sampler shared across the three texture slots. The PBR material
-  // BindGroup still declares 3 separate sampler bindings (D-5 round-4
-  // ordering at binding 8/10/12), so we pass the same handle three times
-  // in assembleMaterialWithSkylightEntries; WebGPU spec permits sampler
-  // reuse across BindGroupEntry slots.
+  // Diffuse IBL and the BRDF LUT share one binding; prefilter remains a
+  // separate binding so per-draw reflection probes can replace it. Both
+  // bindings use this linear-clamp sampler for the global environment.
   const samplerResult = device.createSampler({
     label: 'skylight-fallback-sampler',
     magFilter: 'linear',

package/src/index.ts

@@ -560,6 +560,15 @@ export {
   type PointsStyleInput,
 } from './points-lines/admission.js';
 export type { PointsLinesInspection } from './points-lines/inspection.js';
+export {
+  type PublishedRenderFrameInput,
+  type RenderPublication,
+  RenderPublicationError,
+  type RenderPublicationIdentity,
+  renderPublicationTransfers,
+} from './publication/contract';
+export { createRenderPublisher, type RenderPublicationCandidate } from './publication/publisher';
+export { RenderPublicationTargetOwner, type RenderTargetAuthoring } from './publication/targets';
 /**
  * Public bounded GPU pass facts. Use the single `gpuPassTiming` opt-in,
  * `draw()` receipt, and `observe(receipt, { include: ['timings'] })` route.

package/src/instances.ts

@@ -1,4 +1,3 @@
-import type { World } from '@forgeax/engine-ecs';
 import { InstanceTransformsStrideMismatchError } from '@forgeax/engine-ecs/projection';
 import type { RhiErrorCode } from '@forgeax/engine-rhi';
 
@@ -93,7 +92,7 @@ export function instanceUploadRangesForResident(
 }
 
 interface Projection extends InstanceCollectionSnapshot {
-  readonly world: World;
+  readonly world: object;
   readonly entity: number;
 }
 interface Residency {
@@ -112,11 +111,15 @@ interface Residency {
 export class InstanceProjectionStore {
   private nextId = 1;
   private nextGeneration = 1;
-  private identities = new WeakMap<World, Map<number, InstanceCollectionId>>();
+  private identities = new WeakMap<object, Map<number, InstanceCollectionId>>();
   private readonly records = new Map<InstanceCollectionId, Projection>();
   private readonly residency = new Map<InstanceCollectionId, Residency>();
 
-  project(world: World, entity: number, transforms: ArrayLike<number>): InstanceCollectionSnapshot {
+  project(
+    world: object,
+    entity: number,
+    transforms: ArrayLike<number>,
+  ): InstanceCollectionSnapshot {
     const collectionId =
       this.identities.get(world)?.get(entity) ?? (this.nextId++ as InstanceCollectionId);
     const previous = this.records.get(collectionId);
@@ -147,7 +150,7 @@ export class InstanceProjectionStore {
 
   /** Called only after the owning RenderScene accepts its prepared changes. */
   accept(
-    world: World,
+    world: object,
     entity: number,
     snapshot: {
       readonly collectionId?: InstanceCollectionId;
@@ -175,7 +178,7 @@ export class InstanceProjectionStore {
     });
   }
 
-  release(world: World, entity: number): void {
+  release(world: object, entity: number): void {
     const entities = this.identities.get(world);
     const id = entities?.get(entity);
     if (id === undefined) return;

package/src/pbr-pipeline.ts

@@ -6,7 +6,7 @@
 //     material BGL grows from the derived user region by appending the 7
 //     Skylight resources via `mergeSkylightIntoMaterialBgl`. The
 //     unlit pipeline keeps its 7-entry material BGL (no Skylight binding
-//     7..13 contamination) so unlit demos don't carry IBL state.
+//     7..12 contamination) so unlit demos don't carry IBL state.
 //   - charter P4: same pipeline layout shape drives Skylight present +
 //     absent paths -- AI users do not branch on Skylight existence.
 //   - feat-20260520-skylight-ibl-cubemap M4 / t59 (round-4): the
@@ -209,8 +209,8 @@ export function buildPbrMaterialUserRegionEntries(
 //                (group(0) bindings 3..7); this kind is the seam for
 //                each per-material shadow override surface a future feat
 //                wires onto group(1).
-//   - 'ibl'      the 7 IBL / Skylight entries (irradiance / prefilter
-//                cube + brdfLut 2d + 3 samplers + intensity uniform).
+//   - 'ibl'      the 6 IBL / Skylight entries (irradiance / prefilter
+//                cube + brdfLut 2d + 2 samplers + intensity uniform).
 //                Used by `buildPbrPipelineLayouts` after the user-region
 //                user paramSchema entries are emitted.
 //   - 'lightmap' the 4 emissive + occlusion entries (sampler + texture
@@ -224,7 +224,7 @@ export function buildPbrMaterialUserRegionEntries(
 //                placeholders because their shaders do not read these slots.
 export type InjectionKind = keyof typeof INJECTION_KIND_LENGTHS;
 
-const IBL_INJECTION_LENGTH = 7;
+const IBL_INJECTION_LENGTH = 6;
 const LIGHTMAP_INJECTION_LENGTH = 4;
 const SHADOW_INJECTION_LENGTH = 2;
 const TRANSMISSION_INJECTION_LENGTH = 2;
@@ -283,16 +283,10 @@ export function appendInjection(
           visibility: GPU_SHADER_STAGE_FRAGMENT,
           texture: { sampleType: 'float', viewDimension: '2d' },
         },
-        // binding start+5: brdfLutSampler
+        // binding start+5: uniform { intensity: f32 }
         {
           binding: start + 5,
           visibility: GPU_SHADER_STAGE_FRAGMENT,
-          sampler: { type: 'filtering' },
-        },
-        // binding start+6: uniform { intensity: f32 }
-        {
-          binding: start + 6,
-          visibility: GPU_SHADER_STAGE_FRAGMENT,
           buffer: { type: 'uniform' },
         },
       ];
@@ -1119,13 +1113,13 @@ export function pbrSkinMeshDynamicOffsets(
 
 /**
  * Build a stand-alone 7-entry unlit material BGL. Round-4 D-5 keeps unlit
- * material BG isolated from Skylight binding 7..13 -- unlit demos do not
+ * material BG isolated from Skylight binding 7..12 -- unlit demos do not
  * pay for IBL state. The unlit pipeline still binds material at slot 1,
  * just with a 7-entry layout.
  *
  * Note: at the moment the runtime still routes both unlit + standard
  * through a single 14-entry pipeline layout; the unlit material BG
- * carries fallback identity resources at binding 7..13. This factory is
+ * carries fallback identity resources at binding 7..12. This factory is
  * exported as a future-proof seam for the moment when unlit demos own
  * their own pipeline layout (t57 (e) test pins the contract today so the
  * eventual split has a green target).
@@ -1241,7 +1235,7 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *
  * Three groups by derivation source:
  * 1. Shader-derived (paramSchema reflection + injection chain):
- *    - `'pbr-material-merged'` — derived user region + Skylight 7 + transmission 2
+ *    - `'pbr-material-merged'` — derived user region + Skylight 6 + transmission 2
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
@@ -1638,11 +1632,11 @@ export function buildBindGroupLayoutDescriptor(
     }
     case 'pbr-material-merged': {
       // Material BGL: per-shader user-region (derive(paramSchema).bglEntries)
-      // + IBL injection (7) + transmission injection (2). The user-region
+      // + IBL injection (6) + transmission injection (2). The user-region
       // size is the only variable; injection start = userRegion.length so a
       // custom schema shifts IBL/transmission by its sampler/texture pairs.
-      // The built-in standard-PBR schema is 17 + 7 + 2 = 26 entries;
-      // clearcoat texture pairs are derived from the effective root schema.
+      // The built-in standard-PBR user region has 15 entries;
+      // scene rows follow injection, and physical texture pairs follow the effective root schema.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.

package/src/pipeline/standard-output/lut-gpu.ts

@@ -1,6 +1,5 @@
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
 import type {
   BindGroup,
@@ -13,6 +12,7 @@ import type {
 } from '@forgeax/engine-rhi';
 import { err, type Handle, ok, type Result, type TextureAsset } from '@forgeax/engine-types';
 import type { GpuResidencyCache, TextureGpuEntry } from '../../device/gpu-residency';
+import type { RenderResourceScope } from '../../publication/resource-scope';
 import type { RenderPipelineFrame, RenderPipelineTarget } from '../../render-pipeline';
 import {
   admitStandardColorLut,
@@ -41,7 +41,7 @@ export interface StandardLutGraphProjection {
 }
 
 export interface StandardLutGpuPreparationInput {
-  readonly world: World;
+  readonly world: RenderResourceScope;
   readonly handle: Handle<'TextureAsset', 'shared'>;
   readonly strength: number;
   readonly assets: AssetRegistry;
@@ -125,7 +125,7 @@ export function prepareStandardLutGpu(
   if (!asset.ok) {
     return failure(
       'standard-lut-residency-failed',
-      'the authored TextureAsset handle resolves in the active World',
+      'the authored TextureAsset handle resolves in the active RenderResourceScope',
       'register or rebuild the TextureAsset, then retry the same camera generation',
       causeDetail(asset.error),
     );

package/src/pipeline/standard-output/resources.ts

@@ -1,6 +1,6 @@
-import type { World } from '@forgeax/engine-ecs';
 import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
 import { toShared } from '@forgeax/engine-types';
+import type { RenderResourceScope } from '../../publication/resource-scope';
 import type { RenderFrameState } from '../../record/frame-snapshot';
 import type { RenderSystemInternals } from '../../record/render-context';
 import type { CameraSnapshot } from '../../render-contract';
@@ -17,7 +17,7 @@ export function prepareStandardOutputResources(
   state: RenderFrameState,
   internals: RenderSystemInternals,
   camera: CameraSnapshot | undefined,
-  world: World,
+  world: RenderResourceScope,
 ): Result<void, RhiError> {
   const output = camera?.output;
   if (output?.exposure.kind === 'auto') {

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();
+});