@forgeax/engine-render 0.1.26 → 0.1.28

package/dist/{chunk-KM2NOX2I.mjs → chunk-J52NMQKR.mjs}

@@ -1,9 +1,465 @@
-import { CUBE_CAMERA_FACE_ORDER, createVisibilityBudget, PointShapeValue, pointShapeFromU32 } from './chunk-ADHHVYLW.mjs';
-import { PointsLinesBudgetExceededError, PointsLinesStyleUnsupportedError, PointsLinesMaterialUnsupportedError, PointsLinesInvalidStyleError, PointsLinesTopologyMismatchError } from './chunk-ZZ4YQ474.mjs';
-import { err, ok } from '@forgeax/engine-types';
+import { CUBE_CAMERA_FACE_ORDER, createVisibilityBudget, PointShapeValue, pointShapeFromU32 } from './chunk-JAASCMXA.mjs';
+import { PointsLinesBudgetExceededError, PointsLinesStyleUnsupportedError, PointsLinesMaterialUnsupportedError, PointsLinesInvalidStyleError, PointsLinesTopologyMismatchError } from './chunk-J6KACNOH.mjs';
+import { ok, err } from '@forgeax/engine-types';
 import { mat4 } from '@forgeax/engine-math';
 import { validateR32FloatReceipt } from '@forgeax/engine-rhi';
 
+var DynamicGeometryError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(code, expected, hint, detail = {}) {
+    super(`${code}: ${expected}`);
+    this.name = "DynamicGeometryError";
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = Object.freeze({ code, ...detail });
+  }
+};
+function sameCandidateCredential(candidate, committed) {
+  return candidate.candidateId === committed.candidateId && candidate.owner === committed.owner && candidate.world === committed.world && candidate.generation === committed.generation && candidate.entity === committed.entity && candidate.physicsEntity === committed.physicsEntity && candidate.gpuReady === committed.gpuReady && candidate.meshBytes === committed.meshBytes && candidate.revision === committed.revision && candidate.topologyRevision === committed.topologyRevision && candidate.materialIdentity === committed.materialIdentity && candidate.meshHandle === committed.meshHandle && candidate.fixedStep === committed.fixedStep;
+}
+function cloneTypedArray(value) {
+  return new value.constructor(value);
+}
+function cloneMesh(mesh) {
+  const attributes = Object.fromEntries(
+    Object.entries(mesh.attributes).map(([key, value]) => [
+      key,
+      value instanceof ArrayBuffer ? value.slice(0) : value === void 0 ? void 0 : cloneTypedArray(value)
+    ])
+  );
+  return Object.freeze({
+    ...mesh,
+    vertices: new Float32Array(mesh.vertices),
+    ...mesh.indices === void 0 ? {} : { indices: cloneTypedArray(mesh.indices) },
+    attributes,
+    ...mesh.aabb === void 0 ? {} : { aabb: new Float32Array(mesh.aabb) },
+    submeshes: Object.freeze(mesh.submeshes.map((submesh) => Object.freeze({ ...submesh }))),
+    materialSlots: Object.freeze(mesh.materialSlots.map((slot) => Object.freeze({ ...slot })))
+  });
+}
+function cloneCandidate(candidate) {
+  return Object.freeze({ ...candidate, mesh: cloneMesh(candidate.mesh) });
+}
+function validateMesh(mesh) {
+  if (mesh.kind !== "mesh") return "MeshAsset.kind must be mesh";
+  if (!(mesh.vertices instanceof Float32Array) || mesh.vertices.length === 0 || mesh.vertices.length % 3 !== 0) {
+    return "MeshAsset.vertices must be a non-empty Float32Array with xyz triples";
+  }
+  if (mesh.indices !== void 0 && !(mesh.indices instanceof Uint16Array || mesh.indices instanceof Uint32Array)) {
+    return "MeshAsset.indices must be Uint16Array or Uint32Array";
+  }
+  if (mesh.submeshes.length === 0)
+    return "MeshAsset.submeshes must contain at least one topology range";
+  if (mesh.materialSlots.length < mesh.submeshes.length) {
+    return "MeshAsset.materialSlots must cover every submesh";
+  }
+  if (mesh.vertices.some((value) => !Number.isFinite(value)))
+    return "MeshAsset.vertices must be finite";
+  return void 0;
+}
+function meshByteSize(mesh) {
+  let bytes = mesh.vertices.byteLength + (mesh.indices?.byteLength ?? 0);
+  for (const value of Object.values(mesh.attributes)) {
+    if (value instanceof ArrayBuffer) bytes += value.byteLength;
+    else if (value !== void 0 && ArrayBuffer.isView(value)) bytes += value.byteLength;
+  }
+  if (mesh.aabb !== void 0) bytes += mesh.aabb.byteLength;
+  return bytes;
+}
+function createDynamicGeometryLifecycle(maxCandidates = 32, maxMeshBytes = 64 * 1024 * 1024) {
+  const records = /* @__PURE__ */ new Map();
+  const owner = {};
+  let sequence = 0;
+  let currentGeneration = 0;
+  let disposed = false;
+  let historyInvalidations = 0;
+  let latestRevision;
+  let latestFrameId;
+  let retired = 0;
+  let invalidated = 0;
+  let meshBytes = 0;
+  const latestRevisionByWorld = /* @__PURE__ */ new WeakMap();
+  const latestTopologyRevisionByWorld = /* @__PURE__ */ new WeakMap();
+  const publishedReceipts = /* @__PURE__ */ new Map();
+  const failure2 = (code, expected, hint, detail = {}) => err(new DynamicGeometryError(code, expected, hint, detail));
+  const current = (candidate) => {
+    const record = records.get(candidate.candidateId);
+    if (record === void 0 || candidate.owner !== owner || record.candidate.owner !== candidate.owner || record.candidate.world !== candidate.world || record.candidate.generation !== candidate.generation)
+      return void 0;
+    return record;
+  };
+  return {
+    prepare(input, generation) {
+      if (disposed)
+        return failure2("dynamic-geometry-disposed", "renderer is alive", "rebuild the Renderer");
+      if (input.world === null || typeof input.world !== "object") {
+        return failure2(
+          "dynamic-geometry-world-not-attached",
+          "candidate belongs to an attached World",
+          "attach the World before preparing geometry"
+        );
+      }
+      if (!Number.isInteger(input.revision) || input.revision < 0) {
+        return failure2(
+          "dynamic-geometry-invalid",
+          "geometry revision is a non-negative integer",
+          "advance the consumer revision monotonically",
+          { revision: input.revision }
+        );
+      }
+      if (generation !== currentGeneration && currentGeneration !== 0) {
+        return failure2(
+          "dynamic-geometry-generation-mismatch",
+          "candidate uses the active renderer generation",
+          "discard stale generation work and prepare again",
+          { generation, actual: currentGeneration }
+        );
+      }
+      if (records.size >= maxCandidates) {
+        return failure2(
+          "dynamic-geometry-budget-exceeded",
+          "candidate count remains within the bounded renderer budget",
+          "cancel or retire an earlier candidate before retrying",
+          { actual: records.size }
+        );
+      }
+      const invalid = validateMesh(input.mesh);
+      if (invalid !== void 0)
+        return failure2(
+          "dynamic-geometry-invalid",
+          "MeshAsset satisfies the standard geometry contract",
+          invalid
+        );
+      const candidateBytes = meshByteSize(input.mesh);
+      if (!Number.isSafeInteger(candidateBytes) || candidateBytes < 0 || meshBytes > maxMeshBytes - candidateBytes) {
+        return failure2(
+          "dynamic-geometry-budget-exceeded",
+          "candidate mesh bytes remain within the bounded renderer resource budget",
+          "cancel or retire an earlier candidate before retrying",
+          { actual: { meshBytes, candidateBytes, maxMeshBytes } }
+        );
+      }
+      const candidateId = `mesh:${generation}:${++sequence}:${input.revision}`;
+      const candidate = Object.freeze({
+        candidateId,
+        generation,
+        owner,
+        world: input.world,
+        ...input.entity === void 0 ? {} : { entity: input.entity },
+        ...input.physicsEntity === void 0 ? {} : { physicsEntity: input.physicsEntity },
+        gpuReady: input.meshHandle !== void 0,
+        meshBytes: candidateBytes,
+        revision: input.revision,
+        topologyRevision: input.topologyRevision ?? input.revision,
+        ...input.materialIdentity === void 0 ? {} : { materialIdentity: input.materialIdentity },
+        ...input.meshHandle === void 0 ? {} : { meshHandle: input.meshHandle },
+        ...input.fixedStep === void 0 ? {} : { fixedStep: input.fixedStep },
+        mesh: cloneMesh(input.mesh),
+        state: "prepared"
+      });
+      records.set(candidateId, {
+        world: input.world,
+        candidate,
+        historyInvalidated: false
+      });
+      meshBytes += candidateBytes;
+      currentGeneration = generation;
+      return ok(cloneCandidate(candidate));
+    },
+    accept(candidate, ordering) {
+      if (disposed)
+        return failure2("dynamic-geometry-disposed", "renderer is alive", "rebuild the Renderer");
+      const record = current(candidate);
+      if (record === void 0)
+        return failure2(
+          "dynamic-geometry-candidate-not-found",
+          "candidate is owned by this renderer",
+          "discard the stale credential"
+        );
+      if (candidate.generation !== currentGeneration) {
+        return failure2(
+          "dynamic-geometry-generation-mismatch",
+          "candidate generation matches the active renderer generation",
+          "prepare against the current renderer generation",
+          { candidateId: candidate.candidateId }
+        );
+      }
+      if (record.candidate.state !== "prepared") {
+        return failure2(
+          "dynamic-geometry-candidate-state",
+          "candidate is prepared exactly once before acceptance",
+          "retain the accepted or published receipt",
+          { candidateId: candidate.candidateId }
+        );
+      }
+      if (!sameCandidateCredential(candidate, record.candidate)) {
+        return failure2(
+          "dynamic-geometry-receipt-mismatch",
+          "acceptance uses the exact prepared candidate credential",
+          "discard the altered credential and use the value returned by prepare",
+          { candidateId: candidate.candidateId }
+        );
+      }
+      if (ordering !== void 0) {
+        if (ordering.world !== record.world || !Number.isInteger(ordering.fixedStep) || ordering.fixedStep < 0) {
+          return failure2(
+            "dynamic-geometry-ordering-required",
+            "acceptance ordering names the candidate World and a non-negative fixed step",
+            "submit the PhysicsWorld publication ordering for the same attached World",
+            { candidateId: candidate.candidateId, actual: ordering }
+          );
+        }
+      }
+      const newest = [...records.values()].filter(
+        (entry) => entry.candidate.candidateId !== candidate.candidateId && entry.world === record.world && entry.candidate.entity === record.candidate.entity && (entry.candidate.state === "prepared" || entry.candidate.state === "accepted")
+      ).map((entry) => entry.candidate.revision).concat(latestRevisionByWorld.get(record.world)?.get(record.candidate.entity) ?? -1).sort((a, b) => b - a)[0];
+      if (newest !== void 0 && record.candidate.revision <= newest) {
+        return failure2(
+          "dynamic-geometry-stale",
+          "accepted geometry revision is newer than the active candidate",
+          "advance topology revision before accepting",
+          { candidateId: candidate.candidateId }
+        );
+      }
+      const accepted = Object.freeze({
+        ...record.candidate,
+        ...ordering === void 0 ? {} : { fixedStep: ordering.fixedStep },
+        state: "accepted"
+      });
+      const previousTopologies = [...records.values()].filter(
+        (entry) => entry.candidate.candidateId !== candidate.candidateId && entry.world === record.world && entry.candidate.entity === record.candidate.entity
+      ).map((entry) => entry.candidate.topologyRevision);
+      const previousLatestTopology = latestTopologyRevisionByWorld.get(record.world)?.get(record.candidate.entity);
+      const newestTopology = previousTopologies.concat(previousLatestTopology === void 0 ? [] : [previousLatestTopology]).sort((a, b) => b - a)[0];
+      if (newestTopology !== void 0 && accepted.topologyRevision < newestTopology) {
+        return failure2(
+          "dynamic-geometry-stale",
+          "accepted topology revision is not older than the active geometry history",
+          "advance topology revision before accepting a replacement candidate",
+          { candidateId: candidate.candidateId }
+        );
+      }
+      if (newestTopology !== void 0 && accepted.topologyRevision > newestTopology) {
+        historyInvalidations += 1;
+        for (const previous of records.values()) {
+          if (previous.world !== record.world || previous.candidate.entity !== record.candidate.entity || previous.candidate.candidateId === candidate.candidateId || previous.candidate.topologyRevision >= accepted.topologyRevision)
+            continue;
+          if (!previous.historyInvalidated) {
+            previous.historyInvalidated = true;
+            invalidated += 1;
+          }
+        }
+      }
+      record.candidate = accepted;
+      return ok(cloneCandidate(accepted));
+    },
+    cancel(candidate, completion) {
+      const record = current(candidate);
+      if (record === void 0)
+        return failure2(
+          "dynamic-geometry-candidate-not-found",
+          "candidate is owned by this renderer",
+          "discard the stale credential"
+        );
+      if (!sameCandidateCredential(candidate, record.candidate))
+        return failure2(
+          "dynamic-geometry-receipt-mismatch",
+          "cancellation uses the exact prepared candidate credential",
+          "discard the altered credential and use the value returned by prepare",
+          { candidateId: candidate.candidateId }
+        );
+      if (record.candidate.state !== "prepared" && record.candidate.state !== "accepted") {
+        return failure2(
+          "dynamic-geometry-candidate-state",
+          "only prepared or accepted geometry can be cancelled once",
+          "retire published geometry or await the existing terminal cleanup"
+        );
+      }
+      record.candidate = Object.freeze({ ...record.candidate, state: "cancelled" });
+      const release = () => {
+        if (records.get(candidate.candidateId) !== record) return;
+        records.delete(candidate.candidateId);
+        meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
+      };
+      if (completion === void 0) release();
+      else void completion.then(release, release);
+      return ok(void 0);
+    },
+    retire(candidate) {
+      const record = current(candidate);
+      if (record === void 0)
+        return failure2(
+          "dynamic-geometry-candidate-not-found",
+          "retirement uses a published candidate owned by this renderer",
+          "discard the stale credential and do not evict any unrelated mesh",
+          { candidateId: candidate.candidateId }
+        );
+      if (!sameCandidateCredential(candidate, record.candidate))
+        return failure2(
+          "dynamic-geometry-receipt-mismatch",
+          "retirement uses the exact published candidate credential",
+          "discard the altered credential and use the value returned by publish",
+          { candidateId: candidate.candidateId }
+        );
+      if (record.candidate.state !== "published") {
+        return failure2(
+          "dynamic-geometry-candidate-state",
+          "only published geometry can enter receipt-bound retirement",
+          "publish the candidate from a submitted frame first"
+        );
+      }
+      record.candidate = Object.freeze({ ...record.candidate, state: "retired" });
+      publishedReceipts.delete(candidate.candidateId);
+      retired += 1;
+      return ok(void 0);
+    },
+    finalizeRetirement(candidate) {
+      const record = current(candidate);
+      if (record === void 0)
+        return failure2(
+          "dynamic-geometry-candidate-not-found",
+          "retirement finalization uses a candidate retained by this lifecycle",
+          "discard the stale credential or finish the current receipt-bound retirement"
+        );
+      if (!sameCandidateCredential(candidate, record.candidate))
+        return failure2(
+          "dynamic-geometry-receipt-mismatch",
+          "retirement finalization uses the exact published candidate credential",
+          "discard the altered credential and use the value returned by publication",
+          { candidateId: candidate.candidateId }
+        );
+      if (record.candidate.state !== "retired")
+        return failure2(
+          "dynamic-geometry-candidate-state",
+          "only a retired candidate can release its deferred budget",
+          "retire the published candidate before finalizing its receipt-bound cleanup",
+          { candidateId: candidate.candidateId }
+        );
+      records.delete(candidate.candidateId);
+      meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
+      return ok(void 0);
+    },
+    publishFrame(frame, worlds, fixedStep, canPublish) {
+      if (disposed || frame.deviceGeneration !== currentGeneration) return [];
+      const receipts = [];
+      for (const record of records.values()) {
+        const canRepeatPublished = record.candidate.state === "published" && // Attached Renderer publication revalidates the entity binding in
+        // `canPublish`, so a history-invalidated candidate can still record
+        // a real draw for its live entity. Detached lifecycle publication
+        // remains one-shot once that history is invalidated.
+        (canPublish !== void 0 || !record.historyInvalidated);
+        if (record.candidate.state !== "accepted" && !canRepeatPublished) continue;
+        if (worlds !== void 0 && !worlds.includes(record.world)) continue;
+        if (record.candidate.fixedStep !== void 0 && (fixedStep === void 0 || record.candidate.fixedStep > fixedStep)) {
+          continue;
+        }
+        if (canPublish !== void 0 && !canPublish(record.candidate)) continue;
+        record.candidate = Object.freeze({ ...record.candidate, state: "published" });
+        const receipt = Object.freeze({
+          candidateId: record.candidate.candidateId,
+          generation: record.candidate.generation,
+          revision: record.candidate.revision,
+          topologyRevision: record.candidate.topologyRevision,
+          ...record.candidate.fixedStep === void 0 ? {} : { fixedStep: record.candidate.fixedStep },
+          frameId: frame.frameId,
+          deviceGeneration: frame.deviceGeneration,
+          recordStageConsumed: canPublish !== void 0,
+          ...fixedStep === void 0 ? {} : { publicationFixedStep: fixedStep },
+          frame: Object.freeze({ ...frame })
+        });
+        receipts.push(receipt);
+        publishedReceipts.set(record.candidate.candidateId, receipt);
+        latestRevision = record.candidate.revision;
+        latestFrameId = frame.frameId;
+        if (!latestRevisionByWorld.has(record.world))
+          latestRevisionByWorld.set(record.world, /* @__PURE__ */ new Map());
+        latestRevisionByWorld.get(record.world)?.set(record.candidate.entity, record.candidate.revision);
+        if (!latestTopologyRevisionByWorld.has(record.world))
+          latestTopologyRevisionByWorld.set(record.world, /* @__PURE__ */ new Map());
+        latestTopologyRevisionByWorld.get(record.world)?.set(record.candidate.entity, record.candidate.topologyRevision);
+      }
+      return receipts;
+    },
+    invalidateWorld(world, completion) {
+      for (const [id, record] of records) {
+        if (record.world !== world) continue;
+        if (record.candidate.state === "cancelled" || record.candidate.state === "retired")
+          continue;
+        publishedReceipts.delete(id);
+        record.candidate = Object.freeze({ ...record.candidate, state: "cancelled" });
+        const release = () => {
+          if (records.get(id) !== record) return;
+          records.delete(id);
+          meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
+        };
+        if (completion === void 0) release();
+        else void completion.then(release, release);
+        invalidated += 1;
+      }
+      latestRevisionByWorld.delete(world);
+      latestTopologyRevisionByWorld.delete(world);
+    },
+    invalidateGeneration(generation) {
+      if (generation === currentGeneration) return;
+      currentGeneration = generation;
+      const invalidatedWorlds = /* @__PURE__ */ new Set();
+      for (const [id, record] of records) {
+        if (record.candidate.generation !== generation) {
+          records.delete(id);
+          publishedReceipts.delete(id);
+          meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
+          invalidatedWorlds.add(record.world);
+          invalidated += 1;
+        }
+      }
+      for (const world of invalidatedWorlds) {
+        latestRevisionByWorld.delete(world);
+        latestTopologyRevisionByWorld.delete(world);
+      }
+    },
+    receipt(candidate) {
+      const receipt = publishedReceipts.get(candidate.candidateId);
+      const record = records.get(candidate.candidateId);
+      if (record === void 0 || !sameCandidateCredential(candidate, record.candidate)) {
+        return void 0;
+      }
+      return receipt?.generation === candidate.generation ? receipt : void 0;
+    },
+    inspect() {
+      let prepared = 0;
+      let accepted = 0;
+      let published = 0;
+      for (const record of records.values()) {
+        if (record.candidate.state === "prepared") prepared += 1;
+        else if (record.candidate.state === "accepted") accepted += 1;
+        else if (record.candidate.state === "published") published += 1;
+      }
+      return Object.freeze({
+        generation: currentGeneration,
+        prepared,
+        accepted,
+        published,
+        retired,
+        ...latestRevision === void 0 ? {} : { latestRevision },
+        ...latestFrameId === void 0 ? {} : { latestFrameId },
+        historyInvalidations,
+        invalidated,
+        meshBytes,
+        maxMeshBytes
+      });
+    },
+    dispose() {
+      disposed = true;
+      records.clear();
+      publishedReceipts.clear();
+      meshBytes = 0;
+    }
+  };
+}
 function invalidStyle(input, component, field, value, expected) {
   return err(new PointsLinesInvalidStyleError({ entity: input.entity, component, field, value, expected }));
 }
@@ -998,6 +1454,6 @@ function resolveSsrAdmissionGeneration(previousGeneration, nextGeneration) {
   };
 }
 
-export { DEFAULT_REFLECTION_PROBE_LIMITS, LOD_OCCLUSION_INSPECTION_MAX_BYTES, LOD_OCCLUSION_INSPECTION_SCHEMA, ReflectionProbeProjection, SSR_FORMAT_PROFILE, SSR_FORMAT_STAGES, admitPointsLines, admitReflectionProbe, admitSsrM0, advanceProbeFilter, boxProjectReflectionDirection, buildCubeCameraFaceViews, buildReflectionProbeTable, commitProbeFilterStep, consumeLodOcclusionInspection, createProbeFilterState, deriveReflectionFallbackProjection, estimateReflectionProbeBytes, inspectLodOcclusion, inspectPointShadow, inspectReflectionFallback, inspectVolumetricFog, probeFilterIsSteady, projectSsrDependencies, reflectionFallbackCoverage, reflectionFallbackProjectionSignature, reflectionFallbackSourceKey, reflectionProbeTableBytes, resolveReflectionFallbackSource, resolveSsrAdmissionGeneration, selectReflectionProbe, serializeLodOcclusionInspection, validateReflectionProbeInput, zeroSsrAdmissionWork };
-//# sourceMappingURL=chunk-KM2NOX2I.mjs.map
-//# sourceMappingURL=chunk-KM2NOX2I.mjs.map
+export { DEFAULT_REFLECTION_PROBE_LIMITS, DynamicGeometryError, LOD_OCCLUSION_INSPECTION_MAX_BYTES, LOD_OCCLUSION_INSPECTION_SCHEMA, ReflectionProbeProjection, SSR_FORMAT_PROFILE, SSR_FORMAT_STAGES, admitPointsLines, admitReflectionProbe, admitSsrM0, advanceProbeFilter, boxProjectReflectionDirection, buildCubeCameraFaceViews, buildReflectionProbeTable, commitProbeFilterStep, consumeLodOcclusionInspection, createDynamicGeometryLifecycle, createProbeFilterState, deriveReflectionFallbackProjection, estimateReflectionProbeBytes, inspectLodOcclusion, inspectPointShadow, inspectReflectionFallback, inspectVolumetricFog, probeFilterIsSteady, projectSsrDependencies, reflectionFallbackCoverage, reflectionFallbackProjectionSignature, reflectionFallbackSourceKey, reflectionProbeTableBytes, resolveReflectionFallbackSource, resolveSsrAdmissionGeneration, sameCandidateCredential, selectReflectionProbe, serializeLodOcclusionInspection, validateReflectionProbeInput, zeroSsrAdmissionWork };
+//# sourceMappingURL=chunk-J52NMQKR.mjs.map
+//# sourceMappingURL=chunk-J52NMQKR.mjs.map