@forgeax/engine-ecs 0.1.33 → 0.1.34

package/dist/projection/index.d.ts

@@ -1,13 +1,9 @@
 import type { Result } from '@forgeax/engine-types';
 import type { Component } from '../component';
 import type { EntityHandle } from '../entity-handle';
-import type { SharedRefMutationRead } from '../shared-ref-store';
-import type { StructuralEvidenceRead } from '../storage/structural-evidence';
 import type { EcsError, World } from '../world';
 export { fillComponentDefaults } from '../component-default-fallback';
 export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, } from '../errors';
-/** Read producer-owned typed structural facts without inferring from a World scan. */
-export declare function readStructuralEvidence(world: World, cursor: number): StructuralEvidenceRead;
 export interface RenderProjectionComponentRequest {
     readonly component: Component;
     readonly fields: readonly string[];
@@ -21,29 +17,17 @@ export interface RenderProjectionSpan {
 }
 export interface RenderProjectionSpans {
     readonly generation: number;
-    readonly sharedRefEpoch: number;
     readonly spans: readonly RenderProjectionSpan[];
 }
-export interface RenderChangeBatchOk {
-    readonly status: 'ok';
+export interface RenderChangeBatch {
     readonly version: RenderReadVersion;
     readonly world: RenderWorldChanges;
-    readonly sharedRefs: SharedRefMutationRead;
-}
-export interface RenderChangeBatchRebuild {
-    readonly status: 'rebuild';
-    readonly version: RenderReadVersion;
-    readonly resync: true;
-    readonly reason: 'structure-changed';
-    readonly world: RenderWorldChanges;
-    readonly sharedRefs: SharedRefMutationRead;
 }
 export interface RenderWorldChanges {
     readonly fromEpoch: number;
     readonly toEpoch: number;
     readonly changedComponentIds: readonly number[];
 }
-export type RenderChangeBatch = RenderChangeBatchOk | RenderChangeBatchRebuild;
 export interface RenderReadLease {
     readonly worldIdentity: string;
     readonly generation: number;
@@ -61,7 +45,6 @@ export declare function readRenderArrayView(world: World, entity: EntityHandle,
 export interface RenderReadVersion {
     readonly mutationEpoch: number;
     readonly structureEpoch: number;
-    readonly sharedRefEpoch: number;
 }
 /** Create the render-owned lease from the ECS projection boundary. */
 export declare function createRenderReadLease(world: World, token?: object): RenderReadLease;
@@ -75,4 +58,5 @@ export declare function setDerivedComponent(world: World, entity: EntityHandle,
 export declare function routeWorldError(world: World, error: unknown, context?: {
     readonly systemName: string;
 }): void;
+export { createStateProjection, type StateProjection, type StateProjectionBatch, StateProjectionExpiredError, } from './state-projection';
 //# sourceMappingURL=index.d.ts.map

package/dist/projection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/projection/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/projection/index.ts"],"names":[],"mappings":"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"}

package/dist/projection/index.mjs

@@ -1,4 +1,4 @@
-import '@forgeax/engine-types';
+import { unpackSlot, pack, MAX_SLOT } from '@forgeax/engine-types';
 
 // src/component.ts
 
@@ -10,6 +10,9 @@ var definitions = globalSymbols[COMPONENT_REGISTRY] ?? (() => {
   globalSymbols[COMPONENT_REGISTRY] = registry;
   return registry;
 })();
+function registerComponentDefinition(component, definition) {
+  definitions.definitions.set(component, definition);
+}
 function componentDefinition(component) {
   const definition = definitions.definitions.get(component);
   if (definition === void 0) {
@@ -17,6 +20,22 @@ function componentDefinition(component) {
   }
   return definition;
 }
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return value;
+  }
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return value;
+  }
+  const object = value;
+  for (const key of Reflect.ownKeys(object)) {
+    const child = object[key];
+    if (child !== null && (typeof child === "object" || typeof child === "function")) {
+      deepFreeze(child);
+    }
+  }
+  return Object.freeze(value);
+}
 
 // src/errors/query-and-component-errors.ts
 var ComponentNotDefinedError = class extends Error {
@@ -248,7 +267,56 @@ var worldInternal = /* @__PURE__ */ Symbol.for(
   "forgeax.ecs.worldInternal"
 );
 
+// src/execution/shared-kernel.ts
+var WorldPoisonedError = class extends Error {
+  code = "world-poisoned";
+  expected = "World health is healthy before update";
+  hint = "stop scheduling this World and explicitly bootstrap a new World identity";
+  detail;
+  constructor(worldIdentity, fault) {
+    super(`World ${worldIdentity} is poisoned and cannot update.`);
+    this.name = "WorldPoisonedError";
+    this.detail = { worldIdentity, fault };
+  }
+};
+
 // src/errors.ts
+var EntityIndexOverflowError = class extends RangeError {
+  name = "EntityIndexOverflowError";
+  code = "entity-index-overflow";
+  hint;
+  constructor(index) {
+    const hint = "Entity index exceeds 24-bit max (16777215). Reduce simultaneous entity count or investigate entity leaks.";
+    super(
+      `Entity index ${index} exceeds 24-bit max (16777215).
+  index: ${index}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+  }
+};
+var SchemaUnsupportedFieldError = class extends Error {
+  name = "SchemaUnsupportedFieldError";
+  code = "schema-unsupported-field";
+  hint;
+  constructor(fieldName, fieldType) {
+    let hint = "Supported types: f32 / f64 / i32 / u32 / i16 / u16 / i8 / u8 / bool / enum / ref.";
+    if (fieldType.startsWith("handle<") && fieldType.endsWith(">")) {
+      const tag = fieldType.slice(7, -1);
+      hint = `'handle<${tag}>' was removed in feat-20260614 M5; use 'shared<${tag}>' instead. The brand and storage layout are unchanged; only the keyword + write-barrier dispatch (SharedRefStore retain/release) is new.`;
+    } else if (fieldType.startsWith("ref<") && fieldType.endsWith(">")) {
+      const tag = fieldType.slice(4, -1);
+      hint = `'ref<${tag}>' was renamed in feat-20260614 M1; use 'unique<${tag}>' instead. The brand and storage layout are unchanged; the dispatch still routes through UniqueRefStore (single-holder direct release).`;
+    }
+    super(
+      `Schema field "${fieldName}" has unsupported type "${fieldType}".
+  field: ${fieldName}
+  type: ${fieldType}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+  }
+};
 var StaleEntityError = class extends Error {
   name = "StaleEntityError";
   code = "stale-entity";
@@ -325,6 +393,28 @@ var InstanceTransformsStrideMismatchError = class extends Error {
     this.detail = { actualLength, expectedStride: 16 };
   }
 };
+var ManagedArrayElementTypeNotAllowedError = class extends Error {
+  name = "ManagedArrayElementTypeNotAllowedError";
+  code = "managed-array-element-type-not-allowed";
+  hint;
+  expected;
+  detail;
+  constructor(fieldName, elementType) {
+    const hint = `array<T> element type must be a scalar (f32/f64/i32/u32/i16/u16/i8/u8/bool/enum/ref) or entity. ref<X> / handle<X> / buffer:N / nested array<...> are forbidden on field "${fieldName}".`;
+    const expected = "element type in {scalar | entity}";
+    super(
+      `managed-array: element type not allowed.
+  code: managed-array-element-type-not-allowed
+  field: ${fieldName}
+  elementType: ${elementType}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { fieldName, elementType, hint };
+  }
+};
 
 // src/component.ts
 var FIELD_SIZE_BYTES = {
@@ -340,6 +430,59 @@ var FIELD_SIZE_BYTES = {
   enum: 4,
   ref: 4
 };
+var MANAGED_ARRAY_ELEMENT_TYPES = /* @__PURE__ */ new Set([
+  "f32",
+  "f64",
+  "i32",
+  "u32",
+  "i16",
+  "u16",
+  "i8",
+  "u8",
+  "bool",
+  "enum",
+  "ref",
+  "entity"
+]);
+function isValidArrayElementType(elementType) {
+  if (MANAGED_ARRAY_ELEMENT_TYPES.has(elementType)) return true;
+  if (elementType.startsWith("shared<") && elementType.endsWith(">") && elementType.length > 9)
+    return true;
+  return false;
+}
+function parseManagedArraySchema(fieldType) {
+  if (!fieldType.startsWith("array<") || !fieldType.endsWith(">")) return null;
+  const inner = fieldType.slice(6, -1);
+  const commaIdx = inner.indexOf(",");
+  if (commaIdx === -1) {
+    if (!isValidArrayElementType(inner)) return null;
+    return { elementType: inner, length: void 0 };
+  }
+  const head = inner.slice(0, commaIdx).trim();
+  const tail = inner.slice(commaIdx + 1).trim();
+  if (!isValidArrayElementType(head)) return null;
+  if (!/^[1-9]\d*$/.test(tail)) return null;
+  return { elementType: head, length: Number.parseInt(tail, 10) };
+}
+function isSchemaVocabKeyword(s) {
+  if (s === "string") return true;
+  if (s === "entity") return true;
+  if (s === "buffer") return true;
+  if (s.startsWith("buffer<") && s.endsWith(">")) {
+    const tail = s.slice(7, -1);
+    return /^[1-9]\d*$/.test(tail);
+  }
+  if (s.startsWith("unique<") && s.endsWith(">")) {
+    return /^\w+$/.test(s.slice(7, -1));
+  }
+  if (s.startsWith("shared<") && s.endsWith(">")) {
+    return /^\w+$/.test(s.slice(7, -1));
+  }
+  if (s.startsWith("array<") && s.endsWith(">")) {
+    return parseManagedArraySchema(s) !== null;
+  }
+  return false;
+}
 var COMPONENT_OWNER_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentOwnerRegistry");
 var ownerSymbols = globalThis;
 var ownerRegistry = ownerSymbols[COMPONENT_OWNER_REGISTRY] ?? (() => {
@@ -388,7 +531,7 @@ function scalarRow(t) {
     isArray: false
   };
 }
-Object.freeze({
+var TYPE_METADATA = Object.freeze({
   f32: scalarRow("f32"),
   f64: scalarRow("f64"),
   i32: scalarRow("i32"),
@@ -460,7 +603,89 @@ Object.freeze({
     isArray: true
   }
 });
+function fieldSpecType(fieldName, spec) {
+  if (typeof spec === "string") return spec;
+  const t = spec.type;
+  if (typeof t !== "string") {
+    throw new SchemaUnsupportedFieldError(
+      fieldName,
+      `<field-descriptor missing 'type'> (expected { type, default?, meta? })`
+    );
+  }
+  return t;
+}
+function defineComponent(name, fields, options) {
+  const storage = "table";
+  const schema = {};
+  const reflectedFields = {};
+  const collectedMeta = {};
+  const collectedDefaults = {};
+  for (const fieldName of Object.keys(fields)) {
+    const spec = fields[fieldName];
+    const fieldType = fieldSpecType(fieldName, spec);
+    let arrayMeta;
+    if (TYPE_METADATA[fieldType]?.isScalar === true) ; else if (fieldType === "string") ; else if (fieldType.startsWith("array<") && fieldType.endsWith(">")) {
+      const parsed = parseManagedArraySchema(fieldType);
+      if (parsed === null) {
+        const elementType = fieldType.slice(6, -1);
+        throw new ManagedArrayElementTypeNotAllowedError(fieldName, elementType);
+      }
+      arrayMeta = deepFreeze(
+        parsed.length === void 0 ? { elementType: parsed.elementType } : { elementType: parsed.elementType, length: parsed.length }
+      );
+    } else if (!isSchemaVocabKeyword(fieldType)) {
+      throw new SchemaUnsupportedFieldError(fieldName, fieldType);
+    }
+    schema[fieldName] = fieldType;
+    const row = {
+      type: fieldType
+    };
+    if (typeof spec !== "string") {
+      const desc = spec;
+      if ("default" in desc) {
+        row.default = desc.default;
+        collectedDefaults[fieldName] = desc.default;
+      }
+      if (desc.shape !== void 0) row.shape = desc.shape;
+      if (desc.meta !== void 0) {
+        Object.assign(collectedMeta, desc.meta);
+      }
+      if (desc.transient !== void 0) row.transient = desc.transient;
+      if (desc.labels !== void 0) row.labels = deepFreeze({ ...desc.labels });
+    }
+    if (arrayMeta !== void 0) row.arrayMeta = arrayMeta;
+    reflectedFields[fieldName] = Object.freeze(row);
+  }
+  const id = name === "Entity" ? 0 : ownerRegistry.nextId++;
+  const frozenDefaults = Object.keys(collectedDefaults).length === 0 ? void 0 : deepFreeze(collectedDefaults);
+  const frozenSchema = deepFreeze(schema);
+  const frozenFields = deepFreeze(reflectedFields);
+  const meta = collectedMeta;
+  const token = Object.freeze({ name, fields: frozenFields, storage });
+  ownerRegistry.ids.set(token, id);
+  ownerRegistry.schemas.set(token, frozenSchema);
+  registerComponentDefinition(token, {
+    fields: frozenFields,
+    defaults: frozenDefaults,
+    policy: {
+      transient: false,
+      meta,
+      requires: Object.freeze([...[]])
+    }
+  });
+  return Object.freeze(token);
+}
+var ENTITY_MAX_INDEX = MAX_SLOT;
 var ENTITY_NULL_RAW = 4294967295;
+function encodeEntity(index, generation) {
+  if (index < 0 || index > ENTITY_MAX_INDEX) {
+    throw new EntityIndexOverflowError(index);
+  }
+  return pack(index, generation);
+}
+function entityIndex(entity) {
+  return unpackSlot(entity);
+}
 
 // src/component-default-fallback.ts
 function typeDefault(fieldType) {
@@ -490,10 +715,210 @@ function fillComponentDefaults(token, raw) {
   return out;
 }
 
-// src/projection/index.ts
-function readStructuralEvidence(world, cursor) {
-  return world[worldInternal].getStructuralEvidence().readAfter(cursor);
+// src/entity.ts
+var Entity = defineComponent("Entity", {
+  // Layer-2 default is never observed: `world.spawn` always overwrites `self`
+  // with the freshly encoded handle for the row. `null` is the type-correct
+  // "no handle yet" placeholder (`'entity'` decodes to `EntityHandle | null`).
+  self: { type: "entity", default: null }
+});
+defineComponent("Disabled", {});
+Object.freeze([
+  componentId(Entity)
+]);
+
+// src/storage/change-detection.ts
+var PROJECTION_BLOCK_SIZE = 256;
+
+// src/projection/state-projection.ts
+var StateProjectionExpiredError = class extends Error {
+  code = "state-projection-expired";
+  expected = "an unmodified source and the latest valid projection candidate";
+  hint = "Read and apply the current state again before accepting the candidate.";
+  constructor() {
+    super("State projection candidate expired; read and apply the current state again.");
+    this.name = "StateProjectionExpiredError";
+  }
+};
+function createStateProjection(world, components, candidates = components) {
+  const owner = world[worldInternal];
+  const graph = owner.getGraph();
+  const ids = components.map(componentId);
+  const candidateIds = candidates.map(componentId);
+  const sparseCandidates = candidates.some((component) => component.storage === "sparse");
+  const baseline = /* @__PURE__ */ new Map();
+  let acceptedEpoch = -1;
+  let acceptedStructure = -1;
+  let invalid = true;
+  let readToken = 0;
+  let stamp = new Uint32Array(64);
+  let serial = 0;
+  const work = [];
+  function enqueue(index) {
+    if (index >= stamp.length) {
+      let size = stamp.length;
+      while (size <= index) size *= 2;
+      const next = new Uint32Array(size);
+      next.set(stamp);
+      stamp = next;
+    }
+    if (stamp[index] === serial) return;
+    stamp[index] = serial;
+    work.push(index);
+  }
+  return {
+    isCurrent() {
+      return world.execution.health !== "poisoned" && !invalid && acceptedEpoch === owner.getMutationEpoch() && acceptedStructure === owner.getStructureEpoch();
+    },
+    entity(index) {
+      const record = owner.getRecords()[index];
+      if (record === void 0 || record.archetypeId < 0) return void 0;
+      return encodeEntity(index, record.generation);
+    },
+    changed(entity, component) {
+      const id = componentId(component);
+      if ((owner.getComponentMutationEpochs()[id] ?? 0) <= acceptedEpoch) return false;
+      return (owner.getComponentChange(entity, id)?.changed ?? -1) > acceptedEpoch;
+    },
+    invalidate() {
+      readToken++;
+      invalid = true;
+    },
+    read() {
+      if (world.execution.health === "poisoned")
+        throw new WorldPoisonedError(world.identity, world.execution.fault);
+      const token = ++readToken;
+      const epoch = owner.getMutationEpoch();
+      const structure = owner.getStructureEpoch();
+      const changedComponents = components.filter(
+        (component) => (owner.getComponentMutationEpochs()[componentId(component)] ?? 0) > acceptedEpoch
+      );
+      const membershipChanged = invalid || structure !== acceptedStructure;
+      const changedRoots = invalid || structure !== acceptedStructure || ids.some((id) => (owner.getComponentMutationEpochs()[id] ?? 0) > acceptedEpoch);
+      work.length = 0;
+      serial = serial + 1 >>> 0;
+      if (serial === 0) {
+        stamp.fill(0);
+        serial = 1;
+      }
+      let scannedRows = 0;
+      let checkedBlocks = 0;
+      const updates = [];
+      const visited = /* @__PURE__ */ new Set();
+      if (changedRoots) {
+        const tables = /* @__PURE__ */ new Set();
+        if (sparseCandidates) {
+          for (const table of graph.activeTables) tables.add(table);
+        } else {
+          for (const id of candidateIds)
+            for (const table of graph.activeTablesByComponent.get(id) ?? []) tables.add(table);
+        }
+        for (const table of tables) {
+          visited.add(table);
+          const prior = baseline.get(table);
+          const entities = table.storage.get(componentId(Entity))?.fields.get("self")?.view;
+          if (entities === void 0) continue;
+          const columns = ids.flatMap((id) => {
+            const epochs = table.storage.get(id)?.epochs;
+            return epochs === void 0 ? [] : [epochs];
+          });
+          const blocks = Math.ceil(table.size / PROJECTION_BLOCK_SIZE);
+          for (let block = 0; block < blocks; block++) {
+            checkedBlocks++;
+            const previous = prior?.get(block);
+            const membership = table.membership[block] ?? 0;
+            const start = block * PROJECTION_BLOCK_SIZE;
+            const end = Math.min(table.size, start + PROJECTION_BLOCK_SIZE);
+            if (invalid || previous === void 0 || previous.membership !== membership) {
+              if (previous !== void 0) {
+                for (const index of previous.ids) enqueue(index);
+                scannedRows += previous.ids.length;
+              }
+              const current = new Uint32Array(end - start);
+              for (let row = start; row < end; row++) {
+                const index = entityIndex(entities[row]);
+                current[row - start] = index;
+                enqueue(index);
+              }
+              scannedRows += end - start;
+              updates.push({ table, block, value: { ids: current, membership } });
+            } else {
+              let changedBlock = false;
+              for (const column of columns) {
+                if ((column.blocks[block] ?? 0) <= acceptedEpoch) continue;
+                changedBlock = true;
+                for (let row = start; row < end; row++) {
+                  if ((column.changed[row] ?? 0) > acceptedEpoch)
+                    enqueue(entityIndex(entities[row]));
+                }
+              }
+              if (!changedBlock) continue;
+              scannedRows += end - start;
+            }
+          }
+          if (prior !== void 0) {
+            for (const [block, previous] of prior) {
+              if (block < blocks) continue;
+              checkedBlocks++;
+              for (const index of previous.ids) enqueue(index);
+              scannedRows += previous.ids.length;
+              updates.push({ table, block, value: void 0 });
+            }
+          }
+        }
+        for (const [table, prior] of baseline) {
+          if (visited.has(table)) continue;
+          for (const [block, previous] of prior) {
+            checkedBlocks++;
+            for (const index of previous.ids) enqueue(index);
+            scannedRows += previous.ids.length;
+            updates.push({ table, block, value: void 0 });
+          }
+        }
+      }
+      let accepted = false;
+      const validate = () => {
+        if (world.execution.health === "poisoned")
+          throw new WorldPoisonedError(world.identity, world.execution.fault);
+        if (token !== readToken || epoch !== owner.getMutationEpoch() || structure !== owner.getStructureEpoch()) {
+          throw new StateProjectionExpiredError();
+        }
+      };
+      return {
+        indices: work,
+        epoch,
+        scannedRows,
+        checkedBlocks,
+        membershipChanged,
+        changedComponents,
+        validate,
+        accept() {
+          if (accepted) return;
+          validate();
+          for (const update of updates) {
+            let blocks = baseline.get(update.table);
+            if (update.value === void 0) {
+              blocks?.delete(update.block);
+              if (blocks?.size === 0) baseline.delete(update.table);
+            } else {
+              if (blocks === void 0) {
+                blocks = /* @__PURE__ */ new Map();
+                baseline.set(update.table, blocks);
+              }
+              blocks.set(update.block, update.value);
+            }
+          }
+          acceptedEpoch = epoch;
+          acceptedStructure = structure;
+          invalid = false;
+          accepted = true;
+        }
+      };
+    }
+  };
 }
+
+// src/projection/index.ts
 function readRenderArrayView(world, entity, component, fieldName) {
   return world[worldInternal].getArrayView(entity, component, fieldName);
 }
@@ -522,12 +947,10 @@ function readProjectionSpans(world, generation, request) {
   }
   return {
     generation,
-    sharedRefEpoch: world[worldInternal].getSharedRefs().getMutationEpoch(),
     spans: Object.freeze(spans)
   };
 }
 function createRenderReadLease(world, token = {}) {
-  const sharedRefs = world[worldInternal].getSharedRefs();
   let disposed = false;
   const assertLive = () => {
     if (disposed) throw new Error("RenderReadLease is disposed.");
@@ -535,8 +958,7 @@ function createRenderReadLease(world, token = {}) {
   const captureVersion = () => {
     return {
       mutationEpoch: world[worldInternal].getMutationEpoch(),
-      structureEpoch: world[worldInternal].getStructureEpoch(),
-      sharedRefEpoch: sharedRefs.getMutationEpoch()
+      structureEpoch: world[worldInternal].getStructureEpoch()
     };
   };
   return {
@@ -562,20 +984,8 @@ function createRenderReadLease(world, token = {}) {
         toEpoch,
         changedComponentIds
       };
-      const sharedRead = sharedRefs.readChangesSince(start.sharedRefEpoch);
       const version = captureVersion();
-      const structureChanged = start.structureEpoch !== world[worldInternal].getStructureEpoch();
-      if (structureChanged) {
-        return {
-          status: "rebuild",
-          version,
-          resync: true,
-          reason: "structure-changed",
-          world: worldRead,
-          sharedRefs: sharedRead
-        };
-      }
-      return { status: "ok", version, world: worldRead, sharedRefs: sharedRead };
+      return { version, world: worldRead };
     },
     querySpans(request) {
       assertLive();
@@ -600,6 +1010,6 @@ function routeWorldError(world, error, context) {
   world[worldInternal].routeError(error, context);
 }
 
-export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, createRenderReadLease, fillComponentDefaults, readRenderArrayView, readStructuralEvidence, routeWorldError, setDerivedComponent };
+export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, StateProjectionExpiredError, createRenderReadLease, createStateProjection, fillComponentDefaults, readRenderArrayView, routeWorldError, setDerivedComponent };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map