@forgeax/engine-render 0.1.6 → 0.1.7

package/src/render-system.ts

@@ -27,12 +27,18 @@ import {
   type Handle,
   type MaterialAsset,
   type MaterialTextureValue,
+  type MeshAsset,
   type RenderPipelineAsset,
   RenderQueue,
   type SamplerAsset,
+  toShared,
 } from '@forgeax/engine-types';
 import { createClusterBinScratch } from './cluster-binner';
-import type { ObservationUnavailableError, RenderError } from './errors/render';
+import {
+  type ObservationUnavailableError,
+  PointsLinesMaterialUnsupportedError,
+  type RenderError,
+} from './errors/render';
 import {
   type RenderFeaturePreparedGraphicsResolverInput,
   runRenderFeatureFrame,
@@ -51,10 +57,30 @@ import {
 } from './fullscreen-post-process-pass';
 import { GpuDrivenProduction } from './gpu-driven/production-raster';
 import type { RenderSceneInspection } from './inspection-types';
+import { admitPointsLines } from './points-lines/admission';
+import { PointsLinesExpansionCache } from './points-lines/expansion-cache';
+import {
+  inspectPointsLines,
+  type PointsLinesInspection,
+  type PointsLinesSourceError,
+} from './points-lines/inspection';
+import {
+  createPointsLinesLanePreparationAdapter,
+  type PointsLinesLanePreparationAdapter,
+} from './points-lines/prepare';
+import { createPointsLinesLaneAdapter, type PointsLinesBackend } from './points-lines/record';
+import type { PointsLinesRetainedSnapshot } from './points-lines/snapshot';
+import type { PointsLinesRecordOwner, PointsLinesRecordSubmission } from './record/render-context';
 
 export type { RenderSceneInspection } from './inspection-types';
 
-import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_UNIFORM,
+  GPU_BUFFER_USAGE_VERTEX,
+} from './gpu-usage';
 import { assembleMaterialWithSkylightEntries } from './ibl/skylight-bind-group';
 import { disposeInstanceBuffers, disposeTransientInstanceBuffers } from './instance-buffer-cache';
 import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
@@ -283,6 +309,8 @@ export interface RenderSystem {
   readonly visibilityStats: { explicitlyHidden: number };
   /** Persistent scene maintenance evidence from the ordinary single-World path. */
   readonly renderScene: RenderSceneInspection;
+  /** Retained Points/Lines authoring facts from the single scene projection. */
+  readonly pointsLinesSnapshots: readonly PointsLinesRetainedSnapshot[];
   /** Current mesh-slot provenance and active diagnostics from the last frame. */
   readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
   /**
@@ -398,6 +426,273 @@ function makePreparedPipelinePendingError(): RhiError {
   });
 }
 
+type PointsLinesGpuResources = {
+  readonly vertexBuffer: Buffer;
+  readonly indexBuffer: Buffer;
+};
+type PointsLinesPreparationAdapter = PointsLinesLanePreparationAdapter<PointsLinesGpuResources>;
+
+/**
+ * The Standard renderer's single Points/Lines prepare owner.
+ *
+ * The retained snapshot is the identity boundary; this owner only resolves
+ * the source assets, runs admission, and publishes the existing preparation
+ * and record contracts to the main geometry loop. The expansion cache is
+ * shared across lanes and this owner keeps the one prepared vertex/index
+ * resource pair for each retained identity.
+ */
+class StandardPointsLinesOwner implements PointsLinesRecordOwner {
+  private readonly cache = new PointsLinesExpansionCache();
+  private readonly preparations = new Map<string, PointsLinesPreparationAdapter>();
+  private readonly active = new Map<string, PointsLinesInspection>();
+  private readonly layoutProjection = deriveVertexLayoutProjection({
+    position: new Float32Array(0),
+    normal: new Float32Array(0),
+    uv: new Float32Array(0),
+    tangent: new Float32Array(0),
+  });
+
+  constructor(private readonly internals: RenderSystemInternals) {}
+
+  beginFrame(): void {
+    this.active.clear();
+  }
+
+  prepare(
+    entry: import('./record/frame-snapshot').ValidatedRenderable,
+    clustered: boolean,
+  ): PointsLinesRecordSubmission | undefined {
+    const snapshot = entry.source.pointsLines;
+    if (snapshot === undefined || snapshot.component === undefined || entry.world === undefined) {
+      return undefined;
+    }
+    const key = `${snapshot.worldId}:${snapshot.entityKey}`;
+    const topology = snapshot.component === 'Points' ? 'point-list' : 'line-list';
+    const backend = this.backend();
+    const lane = backend === 'wgpu-webgl2' ? 'cpu-webgl2' : clustered ? 'clustered' : 'direct';
+    const meshResult = resolveAssetHandle<MeshAsset>(
+      entry.world,
+      toShared<'MeshAsset'>(entry.source.assetHandle),
+    );
+    const materialResult = resolveAssetHandle<MaterialAsset>(
+      entry.world,
+      toShared<'MaterialAsset'>(snapshot.materialHandle),
+    );
+    if (!meshResult.ok || !materialResult.ok) {
+      this.publishRefusal(
+        snapshot,
+        new PointsLinesMaterialUnsupportedError({
+          entity: snapshot.entityKey,
+          material: 'unresolved',
+          pass: 'forward',
+          module: 'asset-resolution',
+          reason: 'source MeshAsset or MaterialAsset could not be resolved',
+        }),
+      );
+      return undefined;
+    }
+    const admission = admitPointsLines({
+      entity: snapshot.entityKey,
+      mesh: meshResult.value,
+      material: materialResult.value,
+      ...(snapshot.style?.kind === 'points'
+        ? {
+            points: {
+              sizePx: snapshot.style.sizePx,
+              shape: snapshot.style.shape === 'circle' ? 1 : 0,
+            },
+          }
+        : { lines: { widthPx: snapshot.style?.widthPx ?? 1 } }),
+    });
+    if (!admission.ok) {
+      this.publishRefusal(snapshot, admission.error);
+      return undefined;
+    }
+    const geometryKey = this.cache.getOrCreate(snapshot, meshResult.value).key;
+    const prepKey = `${geometryKey}:${lane}:${backend}`;
+    let preparation = this.preparations.get(prepKey);
+    if (preparation === undefined) {
+      preparation = createPointsLinesLanePreparationAdapter(lane, backend, {
+        cache: this.cache,
+        adapter: {
+          create: (geometry) => {
+            const vertex = this.internals.device.createBuffer({
+              label: `points-lines-vertices:${geometryKey}`,
+              size: Math.max(4, geometry.vertices.byteLength),
+              usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+              mappedAtCreation: false,
+            });
+            if (!vertex.ok) return err(vertex.error);
+            const index = this.internals.device.createBuffer({
+              label: `points-lines-indices:${geometryKey}`,
+              size: Math.max(4, geometry.indices.byteLength),
+              usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+              mappedAtCreation: false,
+            });
+            if (!index.ok) {
+              this.internals.device.destroyBuffer(vertex.value);
+              return err(index.error);
+            }
+            return ok({ vertexBuffer: vertex.value, indexBuffer: index.value });
+          },
+          upload: (resource, geometry) => {
+            if (geometry.vertices.byteLength > 0) {
+              const vertexWrite = this.internals.device.queue.writeBuffer(
+                resource.vertexBuffer,
+                0,
+                geometry.vertices,
+              );
+              if (!vertexWrite.ok) return err(vertexWrite.error);
+            }
+            if (geometry.indices.byteLength > 0) {
+              const indexWrite = this.internals.device.queue.writeBuffer(
+                resource.indexBuffer,
+                0,
+                geometry.indices,
+              );
+              if (!indexWrite.ok) return err(indexWrite.error);
+            }
+            return ok(geometry.derivedBytes);
+          },
+          validate: (_resource, geometry) =>
+            geometry.expandedVertexCount > 0 && geometry.expandedIndexCount > 0
+              ? ok(undefined)
+              : err(new Error('Points/Lines expansion contains no drawable triangles')),
+          destroy: (resource) => {
+            this.internals.device.destroyBuffer(resource.vertexBuffer);
+            this.internals.device.destroyBuffer(resource.indexBuffer);
+          },
+        },
+      });
+      this.preparations.set(prepKey, preparation);
+    }
+    const prepared = preparation.prepare(snapshot, meshResult.value);
+    if (!prepared.ok) {
+      const lkg = preparation.lastKnownGood();
+      if (lkg !== undefined) {
+        const lkgPlan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+          lkg.snapshot,
+          lkg.geometry,
+        );
+        const state = preparation.inspect();
+        this.active.set(
+          key,
+          inspectPointsLines({
+            snapshot,
+            topology,
+            lane,
+            pointCount: lkg.geometry.pointCount,
+            segmentCount: lkg.geometry.segmentCount,
+            sourceBytes: lkg.geometry.sourceBytes,
+            derivedBytes: lkg.geometry.derivedBytes,
+            cache: { hit: true, rebuilds: state.rebuilds, evictions: 0 },
+            drawCount: lkgPlan.drawCount,
+            uploadBytes: 0,
+            lastKnownGood: true,
+            refusal: {
+              code: prepared.error.code,
+              expected: prepared.error.expected,
+              hint: prepared.error.hint,
+              detail: prepared.error.detail,
+              generation: prepared.error.detail.generation,
+              lastKnownGood: true,
+            },
+          }),
+        );
+        return {
+          plan: lkgPlan,
+          vertexBuffer: lkg.resource.vertexBuffer,
+          indexBuffer: lkg.resource.indexBuffer,
+          layoutProjection: this.layoutProjection,
+        };
+      }
+      this.publishRefusal(snapshot, prepared.error);
+      return undefined;
+    }
+    const plan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+      snapshot,
+      prepared.value.geometry,
+    );
+    const state = preparation.inspect();
+    this.active.set(
+      key,
+      inspectPointsLines({
+        snapshot,
+        topology,
+        lane,
+        pointCount: prepared.value.geometry.pointCount,
+        segmentCount: prepared.value.geometry.segmentCount,
+        sourceBytes: prepared.value.geometry.sourceBytes,
+        derivedBytes: prepared.value.geometry.derivedBytes,
+        cache: {
+          hit: prepared.value.uploadedBytes === 0,
+          rebuilds: state.rebuilds,
+          evictions: 0,
+        },
+        drawCount: plan.drawCount,
+        uploadBytes: prepared.value.uploadedBytes,
+        lastKnownGood: prepared.value.lastKnownGood,
+      }),
+    );
+    return {
+      plan,
+      vertexBuffer: prepared.value.resource.vertexBuffer,
+      indexBuffer: prepared.value.resource.indexBuffer,
+      layoutProjection: this.layoutProjection,
+    };
+  }
+
+  resetForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) preparation.resetForDeviceLoss();
+    this.active.clear();
+  }
+
+  inspections(): readonly PointsLinesInspection[] {
+    return [...this.active.values()];
+  }
+
+  private backend(): PointsLinesBackend {
+    switch (this.internals.device.caps.backendKind) {
+      case 'wgpu-webgl2':
+        return 'wgpu-webgl2';
+      case 'null':
+        return 'null';
+      default:
+        return 'webgpu';
+    }
+  }
+
+  private publishRefusal(
+    snapshot: PointsLinesRetainedSnapshot,
+    error: PointsLinesSourceError,
+  ): void {
+    this.active.set(
+      `${snapshot.worldId}:${snapshot.entityKey}`,
+      inspectPointsLines({
+        snapshot,
+        topology: snapshot.component === 'Points' ? 'point-list' : '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: {
+          code: error.code,
+          expected: error.expected,
+          hint: error.hint,
+          detail: error.detail,
+          generation: snapshot.meshGeneration,
+          lastKnownGood: false,
+        },
+      }),
+    );
+  }
+}
+
 export function createRenderSystem(internals: RenderSystemInternals): RenderSystem {
   const phaseCatalogRegistration = internals.profiler?.registerPhaseCatalog(
     'render',
@@ -406,6 +701,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
   let releaseProfilerCatalog =
     phaseCatalogRegistration?.ok === true ? phaseCatalogRegistration.value : undefined;
   let preparedWorlds: readonly World[] = [];
+  const pointsLinesOwner = new StandardPointsLinesOwner(internals);
   const persistentRenderScene = new PersistentRenderScene({
     getDevice: () => internals.device,
     onGpuError: (error) => internals.errorRegistry.fire(error),
@@ -1071,6 +1367,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         gpuDriven: gpuDrivenProduction.inspect(),
       };
     },
+    get pointsLinesSnapshots(): readonly PointsLinesRetainedSnapshot[] {
+      return persistentRenderScene.pointsLinesSnapshots();
+    },
     detachScene(world: World): void {
       persistentRenderScene.detach(world);
     },
@@ -1091,6 +1390,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         }
       }
       try {
+        pointsLinesOwner.beginFrame();
         // cameraOwner drives the surfaced cameras + frustum
         // cull; resourceOwner drives skylight/skybox/postProcess + per-world
         // record config.
@@ -1333,8 +1633,10 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             },
             renderReadLeases,
             featureGraphCandidate,
+            pointsLinesOwner,
           ),
         );
+        persistentRenderScene.setPointsLinesInspections(pointsLinesOwner.inspections());
         if (internals.featureHost !== undefined && preparedResourceBatches.length > 0) {
           const batches = preparedResourceBatches;
           if (submitted) {

package/src/scene/render-scene-types.ts

@@ -1,4 +1,5 @@
 import type { RenderSceneResyncReason } from '../inspection-types';
+import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
 import type { RenderableSnapshot } from '../render-system-extract';
 
 export type { RenderSceneResyncReason } from '../inspection-types';
@@ -23,6 +24,8 @@ export interface RenderSceneRecord extends RenderSceneIdentity {
 
 export interface RenderSceneSlot extends RenderSceneRecord {
   readonly snapshot: RenderableSnapshot;
+  /** Optional detached projection carried with the retained render slot. */
+  readonly pointsLines?: PointsLinesRetainedSnapshot;
 }
 
 export interface RenderSceneApplyResult {

package/src/scene/render-scene.ts

@@ -29,6 +29,8 @@ import {
 } from '../gpu-driven/batch-topology';
 import { GpuScene } from '../gpu-scene';
 import type { PersistentRenderSceneInspection } from '../inspection-types';
+import type { PointsLinesInspection } from '../points-lines/inspection';
+import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   DispatchEntry,
@@ -95,6 +97,21 @@ function ownSnapshot(snapshot: RenderableSnapshot): RenderableSnapshot {
             regions: new Float32Array(snapshot.spriteInstances.regions),
           },
         }),
+    ...(snapshot.pointsLines === undefined
+      ? {}
+      : { pointsLines: ownPointsLinesSnapshot(snapshot.pointsLines) }),
+  };
+}
+
+function ownPointsLinesSnapshot(
+  snapshot: PointsLinesRetainedSnapshot,
+): PointsLinesRetainedSnapshot {
+  return {
+    ...snapshot,
+    style: snapshot.style === undefined ? undefined : { ...snapshot.style },
+    sourceBounds: new Float32Array(snapshot.sourceBounds),
+    viewport: { ...snapshot.viewport },
+    projection: new Float32Array(snapshot.projection),
   };
 }
 
@@ -156,6 +173,10 @@ export class RenderScene {
   private readonly freeSlots: number[] = [];
   private readonly slotsByWorld = new Map<number, Map<number, number>>();
   private readonly slotsByMaterial = new Map<number, Set<number>>();
+  // World bounds are a pure projection of each immutable snapshot. Cache the
+  // derived value by snapshot identity so repeated view queries do not redo
+  // the eight-corner transform for every view in the same frame.
+  private readonly worldBoundsCache = new WeakMap<RenderableSnapshot, RenderSceneBounds | null>();
   private orderedSlots: number[] = [];
   private materialized: readonly RenderableSnapshot[] | undefined;
   private slotSnapshot: readonly RenderSceneSlot[] | undefined;
@@ -365,6 +386,18 @@ export class RenderScene {
     return this.lookup(worldId, entityKey)?.snapshot;
   }
 
+  pointsLinesSnapshots(): readonly PointsLinesRetainedSnapshot[] {
+    const snapshots: PointsLinesRetainedSnapshot[] = [];
+    for (const slot of this.orderedSlots) {
+      const record = this.slots[slot];
+      const snapshot = record?.snapshot.pointsLines;
+      if (record !== undefined && snapshot !== undefined) {
+        snapshots.push(ownPointsLinesSnapshot({ ...snapshot, worldId: record.worldId }));
+      }
+    }
+    return Object.freeze(snapshots);
+  }
+
   slotsForMaterial(materialHandle: number): readonly RenderSceneSlot[] {
     const slots = this.slotsByMaterial.get(materialHandle);
     if (slots === undefined) return [];
@@ -381,8 +414,14 @@ export class RenderScene {
     for (const slot of this.orderedSlots) {
       const record = this.slots[slot];
       if (record === undefined) continue;
-      const candidate = worldBounds(record.snapshot);
-      if (candidate !== undefined && intersects(candidate, bounds)) records.push(record);
+      const snapshot = record.snapshot;
+      let candidate = this.worldBoundsCache.get(snapshot);
+      if (candidate === undefined && !this.worldBoundsCache.has(snapshot)) {
+        candidate = worldBounds(snapshot) ?? null;
+        this.worldBoundsCache.set(snapshot, candidate);
+      }
+      if (candidate === null || candidate === undefined) continue;
+      if (intersects(candidate, bounds)) records.push(record);
     }
     return records;
   }
@@ -654,6 +693,7 @@ export class PersistentRenderScene {
   private gpuDevice: RhiDevice | undefined;
   private gpuStatus: 'inactive' | 'unsupported' | 'resident' | 'rebuild-pending' | 'error' =
     'inactive';
+  private pointsLinesInspections: readonly PointsLinesInspection[] = [];
 
   constructor(private readonly options: PersistentRenderSceneOptions = {}) {}
 
@@ -841,6 +881,14 @@ export class PersistentRenderScene {
     this.gpuStatus = this.options.getDevice === undefined ? 'inactive' : 'rebuild-pending';
   }
 
+  setPointsLinesInspections(inspections: readonly PointsLinesInspection[]): void {
+    this.pointsLinesInspections = inspections.map((inspection) => ({
+      ...inspection,
+      cache: { ...inspection.cache },
+      ...(inspection.refusal === undefined ? {} : { refusal: { ...inspection.refusal } }),
+    }));
+  }
+
   dispose(): void {
     this.gpuScene?.dispose();
     this.gpuScene = undefined;
@@ -848,10 +896,12 @@ export class PersistentRenderScene {
     this.gpuDevice = undefined;
     this.gpuStatus = 'inactive';
     this.composition = undefined;
+    this.pointsLinesInspections = [];
   }
 
   inspect(): PersistentRenderSceneInspection {
     const entry = this.composition;
+    const pointsLines = this.pointsLinesInspections;
     return {
       worldEntitiesScanned: this.worldEntitiesScanned,
       fullRebuilds: this.fullRebuilds,
@@ -871,6 +921,7 @@ export class PersistentRenderScene {
           ineligible: 0,
         } satisfies BatchTopologyInspection),
       gpu: this.inspectGpu(),
+      pointsLines,
     };
   }
 
@@ -886,6 +937,10 @@ export class PersistentRenderScene {
     };
   }
 
+  pointsLinesSnapshots(): readonly PointsLinesRetainedSnapshot[] {
+    return this.composition?.projection.pointsLinesSnapshots() ?? [];
+  }
+
   private inspectGpu(): PersistentGpuSceneInspection {
     if (this.gpuStatus === 'resident' && this.gpuScene !== undefined) {
       return { status: 'resident', ...this.gpuScene.inspect() };

package/dist/chunk-QC4VW3XJ.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/glyph-text.ts","../src/components/sprite-playback-mode.ts","../src/systems/transparent-sort-config.ts"],"names":[],"mappings":";;;;;AAkDO,IAAM,SAAA,GAAY,gBAAgB,WAAA,EAAa;AAAA;AAAA;AAAA,EAGpD,UAAA,EAAY;AAAA,IACV,IAAA,EAAM,mBAAA;AAAA,IACN,OAAA,EAAS,CAAA;AAAA,IACT,mBAAA,EAAqB;AAAA,GACvB;AAAA,EACA,IAAA,EAAM,EAAE,IAAA,EAAM,QAAA,EAAU,SAAS,EAAA,EAAG;AAAA,EACpC,QAAA,EAAU,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,EAAA,EAAG;AAAA;AAAA;AAAA,EAGrC,KAAA,EAAO,EAAE,IAAA,EAAM,eAAA,EAAiB,OAAA,EAAS,IAAI,YAAA,CAAa,CAAC,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAC,CAAC,CAAA;AACxE,CAAC;;;ACXM,IAAM,yBAAA,GAA4B,CAAA;AAGlC,IAAM,0BAAA,GAA6B,CAAA;AAGnC,IAAM,cAAA,GAAiB,OAAO,MAAA,CAAO;AAAA,EAC1C,IAAA,EAAM,yBAAA;AAAA,EACN,KAAA,EAAO;AACT,CAAU;AAeH,SAAS,0BAA0B,KAAA,EAAmC;AAC3E,EAAA,OAAO,KAAA,KAAU,6BAA6B,OAAA,GAAU,MAAA;AAC1D;ACoBO,IAAM,2BAAA,GAA8B,uBAAA;AAGpC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,eAAA,GAAkB,OAAO,MAAA,CAAO;AAAA,EAC3C,MAAA,EAAQ,6BAAA;AAAA,EACR,MAAA,EAAQ,6BAAA;AAAA,EACR,OAAA,EAAS,8BAAA;AAAA,EACT,QAAA,EAAU,8BAAA;AAAA,EACV,SAAA,EAAW;AACb,CAAU;AAMV,IAAM,cAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,IAAA,EAAM,6BAAA;AAAA,EACN,OAAA,EAAS;AACX,CAAC,CAAA;AAED,IAAM,WAAA,uBAAuC,GAAA,CAAY;AAAA,EACvD,6BAAA;AAAA,EACA,6BAAA;AAAA,EACA,8BAAA;AAAA,EACA;AACF,CAAC,CAAA;AAOD,IAAM,aAAA,GAAgB,0BAAA;AACtB,IAAM,SAAA,GAAY,8CAAA;AA2BX,SAAS,yBAAyB,KAAA,EAAqC;AAC5E,EAAA,IAAI,CAAC,KAAA,CAAM,WAAA,CAAY,2BAA2B,CAAA,EAAG;AACnD,IAAA,OAAO,cAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,CAAM,YAAmC,2BAA2B,CAAA;AAC7E;AAwCO,SAAS,wBAAA,CACd,OACA,GAAA,EACyC;AACzC,EAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,GAAA,CAAI,IAAI,CAAA,EAAG;AAC9B,IAAA,OAAO,GAAA;AAAA,MACL,IAAI,yBAAA,CAA0B,aAAA,EAAe,SAAA,EAAW;AAAA,QACtD,cAAc,GAAA,CAAI,IAAA;AAAA,QAClB,WAAA,EAAa;AAAA,OACd;AAAA,KACH;AAAA,EACF;AACA,EAAA,KAAA,CAAM,eAAsC,2BAAA,EAA6B;AAAA,IACvE,MAAM,GAAA,CAAI,IAAA;AAAA,IACV,SAAS,GAAA,CAAI;AAAA,GACd,CAAA;AACD,EAAA,OAAO,GAAG,MAAS,CAAA;AACrB","file":"chunk-QC4VW3XJ.mjs","sourcesContent":["// @forgeax/engine-runtime - GlyphText component (feat-20260531-world-space-msdf-text-rendering M4 / w14).\n//\n// `GlyphText` is the authoring source component for world-space MSDF text\n// (requirements AC-06 / §domain model). It carries ONLY authoring data; the\n// glyph quad baking + MeshFilter / MeshRenderer attachment is the job of the\n// `glyphTextLayoutSystem` (plan-strategy D-2: GlyphText is pure authoring\n// data, baking is a system responsibility). There is NO `TextLayoutAsset`\n// intermediate (OOS-5) -- layout output lives directly in a baked MeshAsset.\n//\n// Naming: single-semantic component drops the `Component` suffix\n// (AGENTS.md §Component naming rule #1 -- Transform / Camera / GlyphText).\n//\n// Schema vocab:\n//   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`\n//     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users\n//     obtain the handle via `assets.loadByGuid<FontAsset>(guid)`.\n//   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same\n//     dispatch as `Name.value`).\n//   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.\n//   - `color: 'array<f32, 4>'` -> linear-space rgba tint (feat-20260709 M3:\n//     collapsed from four `colorR/G/B/A` scalar columns into one inline\n//     stride-4 SoA column, mirroring the DirectionalLight direction/color\n//     idiom). Explicit layer-2 default [1,1,1,1] (opaque white).\n//\n// charter mapping: P1 (single import surface from `@forgeax/engine-render`,\n// co-located with `glyphTextLayoutSystem` that consumes it) + P3\n// (machine-readable schema literal) + P5 (consistent abstraction: same\n// `'shared<T>'` idiom as MeshFilter.assetHandle / MeshRenderer.materials).\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Glyph text authoring component (world-space MSDF text).\n *\n * Spawn an entity with a `GlyphText` and the `glyphTextLayoutSystem`\n * (auto-wired by `createRenderer` / `createApp`) lays out the glyph quads,\n * bakes a `MeshAsset`, and attaches `MeshFilter` + `MeshRenderer` on the\n * next frame (Commands-deferred). Mutating `text` / `fontSize` / `color`\n * re-bakes the mesh in place (plan-strategy D-1 updateMesh; registry size\n * unchanged, AC-08).\n *\n * @example Spawn a world-space label:\n *   import { GlyphText } from '@forgeax/engine-render/authoring';\n *   const font = (await assets.loadByGuid(fontGuid)).unwrap();\n *   world.spawn({\n *     component: GlyphText,\n *     data: { fontHandle: font, text: 'Hello', fontSize: 32,\n *             color: [1, 1, 1, 1] },\n *   });\n */\nexport const GlyphText = defineComponent('GlyphText', {\n  // The layout/render owner re-resolves the font asset on the target world;\n  // authoring text and style remain portable simulation state.\n  fontHandle: {\n    type: 'shared<FontAsset>',\n    default: 0 as never,\n    simulationTransient: true,\n  },\n  text: { type: 'string', default: '' },\n  fontSize: { type: 'f32', default: 16 },\n  // color carries an explicit layer-2 default [1,1,1,1] (opaque white); the\n  // array layer-3 fallback is all-zero, so the default MUST be explicit (D-5).\n  color: { type: 'array<f32, 4>', default: new Float32Array([1, 1, 1, 1]) },\n});\n","// @forgeax/engine-runtime - SpritePlaybackMode (u32 column encoding + mapper).\n//\n// SSOT for the SpriteAnimation.playbackMode ECS column (M2 T-12) and the\n// runtime tick-system branch selector (M4 T-23). The shape mirrors the M1\n// `Tonemap` block in `./camera.ts:72-90` (TONEMAP_NONE = 0 /\n// TONEMAP_REINHARD_EXTENDED = 1 + `type Tonemap = 'none' |\n// 'reinhard-extended'` + `tonemapFromF32`) for charter P4 consistent\n// abstraction — AI users keep one mental model across all u32-encoded\n// closed-union schema columns.\n//\n// Why `'u32'` + constant + mapper instead of a string-literal column?\n// ECS schema whitelist `SchemaFieldType` (packages/ecs/src/component.ts\n// section schema-field-type) does not accept string-literal unions\n// (research F-2 + F-5). Storing a u32 + translating to a closed\n// `'loop' | 'clamp'` literal union at the tick-system seam preserves\n// AI-user-facing narrowing (`switch (mode) { case 'loop': ... }`)\n// without forcing the ECS column to learn a new field-type vocabulary.\n//\n// Naming convention (plan-strategy section 8.command naming):\n//   SPRITE_PLAYBACK_MODE_LOOP / SPRITE_PLAYBACK_MODE_CLAMP mirror M1\n//   TONEMAP_* / TRANSPARENT_SORT_MODE_*. `spritePlaybackModeFromU32`\n//   mirrors `tonemapFromF32` / `cameraProjectionFromF32`. AI users\n//   discover the trio via single-import barrel re-export from\n//   `@forgeax/engine-runtime` (wired in by M2 T-13).\n//\n// Anchors: plan-strategy section 2 D-5 + section 3.1 PR block SPM +\n//          section 4 risk R-SCHEMA-1 reaction; research F-2 + F-5;\n//          requirements section AC-02 + section 2.3 playbackMode row;\n//          plan-tasks.json T-07 acceptanceCheck (rg\n//          \"SPRITE_PLAYBACK_MODE_LOOP|SPRITE_PLAYBACK_MODE_CLAMP|\n//          spritePlaybackModeFromU32\" >= 3 hits in this file).\n\n/**\n * Playback mode discriminator literal union (requirements section AC-02 +\n * section 2.3). Two members for the MVP:\n *\n *   `'loop'`  — `currentFrame = (currentFrame + 1) % frameCount`; the\n *               sprite-animation-tick system wraps the index when\n *               `accumDt >= frameDuration` (default for hello-sprite-\n *               atlas demo \"100 sprites synchronised walk cycle\").\n *   `'clamp'` — `currentFrame = min(currentFrame + 1, frameCount - 1)`;\n *               holds the last frame for death / terminator-animation\n *               style sequences (requirements section 2.5 q8 lock).\n *\n * Future modes (`'pingpong'`, reverse playback, arbitrary frame index\n * jumps) are deferred per requirements OOS-03. The closed union shape\n * leaves room for additive growth without breaking the u32 enum encoding\n * (plan-strategy section 2 D-5).\n */\nexport type SpritePlaybackMode = 'loop' | 'clamp';\n\n/** Numeric encoding of the loop playback mode (schema value for `playbackMode`). */\nexport const SPRITE_PLAYBACK_MODE_LOOP = 0 as const;\n\n/** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */\nexport const SPRITE_PLAYBACK_MODE_CLAMP = 1 as const;\n\n/** Grouped authoring values; the numeric ECS encoding stays owner-local. */\nexport const SpritePlayback = Object.freeze({\n  loop: SPRITE_PLAYBACK_MODE_LOOP,\n  clamp: SPRITE_PLAYBACK_MODE_CLAMP,\n} as const);\n\n/**\n * Map a `SpriteAnimation.playbackMode` numeric column value to the closed\n * `SpritePlaybackMode` string-literal union. The defensive fallback mirrors\n * `cameraProjectionFromF32` / `tonemapFromF32` precedent — a value other\n * than `SPRITE_PLAYBACK_MODE_CLAMP` (1) maps to `'loop'`, so stale or\n * uninitialised entities surface a predictable playback shape through the\n * tick-system query (rather than throwing or returning `undefined`).\n * Validation of `playbackMode` happens at schema-write time, not here.\n *\n * The tick-system in M4 T-23 (`spriteAnimationTickSystem`) consumes the\n * return value via `switch (mode) { case 'loop': ...; case 'clamp': ... }`\n * to pick the per-branch frame-advance arithmetic.\n */\nexport function spritePlaybackModeFromU32(value: number): SpritePlaybackMode {\n  return value === SPRITE_PLAYBACK_MODE_CLAMP ? 'clamp' : 'loop';\n}\n","// @forgeax/engine-runtime - TransparentSortConfig KV resource + helpers.\n//\n// feat-20260520-2d-sprite-layer-mvp M-2 w14 / requirements AC-08 + AC-18\n// path (2)/(3) + AC-19 derivation audit (5).\n//\n// Surface:\n//   - interface  TransparentSortConfig { mode: number; yzAlpha: number }\n//   - constant   TRANSPARENT_SORT_CONFIG_KEY   = 'TransparentSortConfig'\n//   - constants  TRANSPARENT_SORT_MODE_LAYER_Z  = 0  (horizontal-z)\n//                TRANSPARENT_SORT_MODE_LAYER_Y  = 1  (Y-sort)\n//                TRANSPARENT_SORT_MODE_LAYER_YZ = 2  (Y-Z blend)\n//   - helper     getTransparentSortConfig(world): TransparentSortConfig\n//   - helper     setTransparentSortConfig(world, cfg):\n//                  Result<void, ResourceInvalidValueError>\n//\n// 5-view selection table (charter F1 progressive disclosure for AI users\n// reading IDE hover on this header; same SSOT mirrored in\n// apps/hello/sprite/README.md M-4 w33):\n//\n//   | view              | mode | yzAlpha | sortValue formula              |\n//   |:------------------|:----:|:-------:|:--------------------------------|\n//   | horizontal (side) |  0   |   ---   | posZ                            |\n//   | top-down          |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//   | Don't Starve      |  2   |   1.0   | (posY - pivot.y * size.y) + posZ|\n//   | isometric         |  2   |   0.5   | (posY - pivot.y * size.y) + 0.5*posZ |\n//   | JRPG (foot pivot) |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//\n// AC-18 path (2): @fallback getTransparentSortConfig KV missing returns\n//   default; no warn; no throw (legal default state, not an error state).\n// AC-18 path (3): @fallback setTransparentSortConfig mode out-of-range\n//   does NOT silently coerce to mode=0 — returns Result.err with the\n//   4 SSOT fields locked by plan-strategy D-4 so AI users can self-repair\n//   via .code / .expected / .hint / .detail property access (charter P3).\n// AC-18 path (3) carve-out: yzAlpha range is intentionally NOT validated;\n//   mode=0 / mode=1 ignore the field entirely, mode=2 reads it, mode=3\n//   (distance) also reads it for compat but ignores it (squared-distance\n//   formula does not use yzAlpha). The silent-ignore is the documented\n//   charter P3 \"legal default\" boundary.\n//\n// @new-surface KV resource: ECS has no defineResource factory at this\n//   feat's commit time; the TS POD interface + string KV key form is the\n//   minimum-new-surface route. The world resource store\n//   (insertResource / getResource / hasResource) is reused unchanged\n//   (requirements §2.2.G derivation row 5).\n// @derives world.hasResource / world.insertResource / world.getResource\n//   KV API (packages/ecs/src/resource.ts + world.ts: insertResource l.490,\n//   getResource l.498, hasResource l.503).\n// @fallback getTransparentSortConfig KV missing returns\n//   { mode: 0, yzAlpha: 1.0 }; no warn; no throw.\n// @fallback setTransparentSortConfig mode out-of-range returns Result.err\n//   with code='resource-invalid-value'; never silently coerced.\n//\n// charter mapping: F1 (single-import barrel + 5-view JSDoc table on\n// hover) + P3 (structured failure on mode out-of-range; legal-default\n// fallback distinguished from error fallback) + P4 (consistent\n// abstraction — same world.{has,get,insert}Resource KV API as every\n// other engine resource consumer).\n\nimport type { World } from '@forgeax/engine-ecs';\nimport { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';\nimport { err, ok, type Result } from '@forgeax/engine-types';\n\n// ────────────────────────────────────────────────────────────────────────────\n// POD interface + KV key + 3 named mode constants\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Transparent-bucket sort configuration (plain-data POD). Lives as a\n * world-level resource keyed by `TRANSPARENT_SORT_CONFIG_KEY`.\n *\n * Fields:\n *   - `mode \\u2208 {0, 1, 2, 3}` selects the sort formula\n *     (`TRANSPARENT_SORT_MODE_LAYER_Z` / `_LAYER_Y` / `_LAYER_YZ` / `_DISTANCE`).\n *   - `yzAlpha` (mode=2 only) blends Y-axis into Z-axis: 1.0 weights\n *     posZ equally with `posY - pivot.y * size.y` (Don't-Starve style),\n *     0.5 weights posZ at half (isometric). mode=0 / mode=1 ignore the\n *     field (documented charter P3 legal-default boundary).\n */\nexport interface TransparentSortConfig {\n  readonly mode: number;\n  readonly yzAlpha: number;\n}\n\n/** Extract-stage POD consumed by the transparent-sort owner. */\nexport interface TransparentEntry {\n  readonly entityIndex: number;\n  readonly materialHandle: number;\n  readonly layer: number;\n  readonly posX: number;\n  readonly posY: number;\n  readonly posZ: number;\n  readonly pivotY: number;\n  readonly sizeY: number;\n  readonly sortKey?: number | undefined;\n  readonly renderableIndex?: number | undefined;\n}\n\n/** World resource key for `TransparentSortConfig` KV entry. */\nexport const TRANSPARENT_SORT_CONFIG_KEY = 'TransparentSortConfig' as const;\n\n/** horizontal / side-scroller: sortValue = posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_Z = 0;\n\n/** top-down / JRPG: sortValue = -(posY - pivot.y * size.y) (foot pivot Y-sort). */\nexport const TRANSPARENT_SORT_MODE_LAYER_Y = 1;\n\n/** Don't-Starve / isometric: sortValue = (posY - pivot.y * size.y) + yzAlpha * posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;\n\n/** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */\nexport const TRANSPARENT_SORT_MODE_DISTANCE = 3;\n\n/** Grouped authoring values and the single configuration operation. */\nexport const TransparentSort = Object.freeze({\n  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,\n  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,\n  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,\n  distance: TRANSPARENT_SORT_MODE_DISTANCE,\n  configure: setTransparentSortConfig,\n} as const);\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internal: silent default + mode validity check\n// ────────────────────────────────────────────────────────────────────────────\n\nconst DEFAULT_CONFIG: TransparentSortConfig = Object.freeze({\n  mode: TRANSPARENT_SORT_MODE_LAYER_Z,\n  yzAlpha: 1.0,\n});\n\nconst VALID_MODES: ReadonlySet<number> = new Set<number>([\n  TRANSPARENT_SORT_MODE_LAYER_Z,\n  TRANSPARENT_SORT_MODE_LAYER_Y,\n  TRANSPARENT_SORT_MODE_LAYER_YZ,\n  TRANSPARENT_SORT_MODE_DISTANCE,\n]);\n\n// The expected / hint literals are the SSOT locked by plan-strategy D-4.\n// They MUST round-trip byte-for-byte into ResourceInvalidValueError so AI\n// users can read err.expected / err.hint for self-repair (charter P3).\n// `\\u2208` is the math \"is-element-of\" symbol; the ASCII source escape\n// keeps the file English-only per AGENTS.md §Conventions.\nconst EXPECTED_MODE = 'mode \\u2208 {0, 1, 2, 3}';\nconst HINT_MODE = '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance';\n\n// ────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Read the world's `TransparentSortConfig` resource.\n *\n * @fallback KV missing returns `{ mode: 0, yzAlpha: 1.0 }`\n * (`TRANSPARENT_SORT_MODE_LAYER_Z`, horizontal-z safe default).\n * NO warn, NO throw — KV missing is a legal state (not an error state),\n * mirroring how a sprite-free scene is a legal state for the renderer\n * even though render-system has a transparent bucket. plan-strategy D-2:\n * `hasResource` guard precedes the read so this helper never trips\n * `ResourceNotFoundError` from `world.getResource`.\n *\n * @example\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 0, cfg.yzAlpha === 1.0 when no resource inserted.\n *\n * @example\n *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 1, cfg.yzAlpha === 1.0 (yzAlpha ignored by mode=1).\n */\nexport function getTransparentSortConfig(world: World): TransparentSortConfig {\n  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {\n    return DEFAULT_CONFIG;\n  }\n  return world.getResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY);\n}\n\n/**\n * Write the world's `TransparentSortConfig` resource, validating `mode`.\n *\n * Returns `Result<void, ResourceInvalidValueError>`:\n *\n *   - `ok` — mode is in `{0, 1, 2, 3}`; the resource is inserted /\n *     overwritten via `world.insertResource`.\n *   - `err` — mode is out of range; the resource is NOT mutated;\n *     `err.error` is a `ResourceInvalidValueError` instance carrying:\n *       `.code === 'resource-invalid-value'`\n *       `.expected === 'mode \\u2208 {0, 1, 2, 3}'`\n *       `.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'`\n *       `.detail.receivedMode === <the rejected mode>`\n *\n * @fallback mode out-of-range is NEVER silently coerced to mode=0 —\n * `Result.err` is the only fail-mode (charter P3 structured failure).\n * AI users read `.code / .expected / .hint / .detail` properties to\n * self-repair, NOT the human-readable `.message` string.\n *\n * @fallback yzAlpha range is intentionally not validated; mode=0 / mode=1\n * ignore the field, mode=2 reads it. The silent-ignore is the\n * documented charter P3 \"legal default\" boundary (plan-strategy D-4 +\n * AC-18 path (3) carve-out).\n *\n * @example success path:\n *   const r = setTransparentSortConfig(world,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_YZ, yzAlpha: 0.5 });\n *   if (!r.ok) return r;\n *\n * @example failure path:\n *   const r = setTransparentSortConfig(world, { mode: 99, yzAlpha: 1.0 });\n *   if (!r.ok) {\n *     // r.error.code === 'resource-invalid-value'\n *     // r.error.expected === 'mode \\u2208 {0, 1, 2, 3}'\n *     // r.error.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'\n *     // r.error.detail.receivedMode === 99\n *   }\n */\nexport function setTransparentSortConfig(\n  world: World,\n  cfg: TransparentSortConfig,\n): Result<void, ResourceInvalidValueError> {\n  if (!VALID_MODES.has(cfg.mode)) {\n    return err(\n      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {\n        receivedMode: cfg.mode,\n        receivedKey: TRANSPARENT_SORT_CONFIG_KEY,\n      }),\n    );\n  }\n  world.insertResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY, {\n    mode: cfg.mode,\n    yzAlpha: cfg.yzAlpha,\n  });\n  return ok(undefined);\n}\n"]}