iris-ecs 0.0.1

package/dist/actions.d.ts

@@ -0,0 +1,43 @@
+import type { World } from "./world.js";
+/**
+ * Actions record type.
+ *
+ * A record of functions that can be bound to a world via closure.
+ */
+export type Actions = Record<string, (...args: never[]) => unknown>;
+/**
+ * Action initializer function.
+ *
+ * Takes a world and returns an actions record with world captured in closure.
+ */
+export type ActionInitializer<T extends Actions> = (world: World) => T;
+/**
+ * Action getter function.
+ *
+ * Takes a world and returns cached actions (creating on first access).
+ */
+export type ActionGetter<T extends Actions> = (world: World) => T;
+/**
+ * Define reusable actions bound to a world via closure. Actions are initialized
+ * once per world and cached for subsequent access.
+ *
+ * @param initializer - Function that creates actions with world captured in closure
+ * @returns Getter function that returns cached actions for a world
+ *
+ * @example
+ * ```typescript
+ * const transformActions = defineActions((world) => ({
+ *   spawn(x: number, y: number): Entity {
+ *     const entity = createEntity(world);
+ *     addComponent(world, entity, Position, { x, y });
+ *     return entity;
+ *   },
+ * }));
+ *
+ * // In systems - getter returns cached actions for the world
+ * const transform = transformActions(world);
+ * const player = transform.spawn(100, 200);
+ * ```
+ */
+export declare function defineActions<T extends Actions>(initializer: ActionInitializer<T>): ActionGetter<T>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAanG"}

package/dist/actions.js

@@ -0,0 +1,35 @@
+/**
+ * Define reusable actions bound to a world via closure. Actions are initialized
+ * once per world and cached for subsequent access.
+ *
+ * @param initializer - Function that creates actions with world captured in closure
+ * @returns Getter function that returns cached actions for a world
+ *
+ * @example
+ * ```typescript
+ * const transformActions = defineActions((world) => ({
+ *   spawn(x: number, y: number): Entity {
+ *     const entity = createEntity(world);
+ *     addComponent(world, entity, Position, { x, y });
+ *     return entity;
+ *   },
+ * }));
+ *
+ * // In systems - getter returns cached actions for the world
+ * const transform = transformActions(world);
+ * const player = transform.spawn(100, 200);
+ * ```
+ */
+export function defineActions(initializer) {
+    return (world) => {
+        // Use the initializer function itself as a cache key for identity-based lookup
+        let actions = world.actions.byInitializer.get(initializer);
+        if (actions === undefined) {
+            // First access for this world - initialize and cache
+            actions = initializer(world);
+            world.actions.byInitializer.set(initializer, actions);
+        }
+        return actions;
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAAoB,WAAiC;IAChF,OAAO,CAAC,KAAY,EAAK,EAAE;QACzB,+EAA+E;QAC/E,IAAI,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAkB,CAAC;QAE5E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,qDAAqD;YACrD,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YAC7B,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC"}

package/dist/archetype.d.ts

@@ -0,0 +1,194 @@
+import type { EntityId } from "./encoding.js";
+import type { SchemaRecord } from "./schema.js";
+import type { World } from "./world.js";
+/**
+ * Column storage type.
+ *
+ * Union of typed arrays (numeric values) and regular arrays (primitives/objects).
+ */
+export type Column = Int8Array | Int16Array | Int32Array | Uint32Array | Float32Array | Float64Array | unknown[];
+/**
+ * Field columns map.
+ *
+ * Maps field names to their storage columns for a single component.
+ */
+export type FieldColumns = {
+    [fieldName: string]: Column;
+};
+/**
+ * Component tick storage for change detection.
+ *
+ * Parallel arrays to entity rows tracking when components were added/changed.
+ */
+export type ComponentTicks = {
+    added: Uint32Array;
+    changed: Uint32Array;
+};
+/**
+ * Archetype structure.
+ *
+ * Groups entities with identical component sets for cache-efficient iteration.
+ */
+export type Archetype = {
+    types: EntityId[];
+    typesSet: Set<EntityId>;
+    hash: string;
+    entities: EntityId[];
+    columns: Map<EntityId, FieldColumns>;
+    schemas: Map<EntityId, SchemaRecord>;
+    edges: Map<EntityId, Archetype>;
+    capacity: number;
+    ticks: Map<EntityId, ComponentTicks>;
+};
+/**
+ * Hashes a sorted array of type IDs into a unique archetype key.
+ *
+ * @param types - Sorted type IDs
+ * @returns Colon-delimited hash key (e.g., "1:5:12")
+ *
+ * @example
+ * ```ts
+ * const hash = hashArchetypeTypes([1, 5, 12]); // "1:5:12"
+ * ```
+ */
+export declare function hashArchetypeTypes(types: EntityId[]): string;
+/**
+ * Creates an archetype from sorted type IDs and their schemas.
+ * Columns are allocated lazily on first entity insertion to avoid
+ * memory allocation for transitional archetypes (graph traversal nodes).
+ *
+ * @param sortedTypes - Type IDs in ascending order
+ * @param schemas - Map of type ID to field schemas
+ * @returns New archetype with empty entity storage
+ *
+ * @example
+ * ```ts
+ * const archetype = createArchetype([positionId, velocityId], schemas);
+ * ```
+ */
+export declare function createArchetype(sortedTypes: EntityId[], schemas: Map<EntityId, SchemaRecord>): Archetype;
+/**
+ * Registers an archetype in the world's lookup table, updates entity records,
+ * and fires the archetypeCreated observer event.
+ *
+ * @param world - World to register archetype in
+ * @param archetype - Archetype to register
+ *
+ * @example
+ * ```ts
+ * const archetype = createArchetype(types, schemas);
+ * registerArchetype(world, archetype);
+ * ```
+ */
+export declare function registerArchetype(world: World, archetype: Archetype): void;
+/**
+ * Creates an archetype and registers it in the world.
+ *
+ * @param world - World to register archetype in
+ * @param types - Sorted type IDs for the archetype
+ * @param schemas - Map of type ID to field schemas
+ * @returns Newly created and registered archetype
+ *
+ * @example
+ * ```ts
+ * const archetype = createAndRegisterArchetype(world, [positionId], schemas);
+ * ```
+ */
+export declare function createAndRegisterArchetype(world: World, types: EntityId[], schemas: Map<EntityId, SchemaRecord>): Archetype;
+/**
+ * Adds an entity to an archetype, initializing tick tracking for change detection.
+ *
+ * @param archetype - Target archetype
+ * @param entityId - Entity to add
+ * @param tick - Current world tick for change detection (defaults to 0)
+ * @returns Row index where entity was inserted
+ *
+ * @example
+ * ```ts
+ * const row = addEntityToArchetype(archetype, entityId, world.tick);
+ * ```
+ */
+export declare function addEntityToArchetype(archetype: Archetype, entityId: EntityId, tick?: number): number;
+/**
+ * Removes an entity from an archetype using swap-and-pop for O(1) removal.
+ * The last entity in the archetype is moved into the vacated row.
+ *
+ * @param archetype - Archetype to remove entity from
+ * @param row - Row index of entity to remove
+ * @returns Entity ID that was swapped into the row, or undefined if row was last
+ *
+ * @example
+ * ```ts
+ * const swapped = removeEntityFromArchetypeByRow(archetype, row);
+ * if (swapped) updateEntityRecord(world, swapped, archetype, row);
+ * ```
+ */
+export declare function removeEntityFromArchetypeByRow(archetype: Archetype, row: number): EntityId | undefined;
+/**
+ * Transfers an entity between archetypes, copying shared component data and ticks.
+ * Used when adding/removing components causes an entity to move archetypes.
+ *
+ * @param fromArchetype - Source archetype
+ * @param fromRow - Row index in source archetype
+ * @param toArchetype - Target archetype
+ * @param tick - Current world tick for new component ticks (defaults to 0)
+ * @returns New row index and swapped entity ID (if any was moved during removal)
+ *
+ * @example
+ * ```ts
+ * const { toRow, swappedEntityId } = transferEntityToArchetypeByRow(
+ *   fromArchetype, fromRow, toArchetype, world.tick
+ * );
+ * ```
+ */
+export declare function transferEntityToArchetypeByRow(fromArchetype: Archetype, fromRow: number, toArchetype: Archetype, tick?: number): {
+    toRow: number;
+    swappedEntityId: EntityId | undefined;
+};
+/**
+ * Destroys an archetype and cleans up all references.
+ * Removes from world lookup, fires observer event, and clears bidirectional edges.
+ *
+ * @param world - World containing the archetype
+ * @param archetype - Archetype to destroy (root archetype is protected)
+ *
+ * @example
+ * ```ts
+ * if (archetype.entities.length === 0) {
+ *   destroyArchetype(world, archetype);
+ * }
+ * ```
+ */
+export declare function destroyArchetype(world: World, archetype: Archetype): void;
+/**
+ * Traverses the archetype graph to find or create an archetype with a type added.
+ * Uses edge caching for O(1) repeated traversals.
+ *
+ * @param world - World containing archetype graph
+ * @param from - Starting archetype
+ * @param typeId - Type ID to add
+ * @param schema - Schema for the type (required if type is new to graph)
+ * @returns Archetype with the type added, or same archetype if type already present
+ *
+ * @example
+ * ```ts
+ * const newArchetype = archetypeTraverseAdd(world, archetype, velocityId, velocitySchema);
+ * ```
+ */
+export declare function archetypeTraverseAdd(world: World, from: Archetype, typeId: EntityId, schema?: SchemaRecord): Archetype;
+/**
+ * Traverses the archetype graph to find or create an archetype with a type removed.
+ * Uses edge caching for O(1) repeated traversals.
+ *
+ * @param world - World containing archetype graph
+ * @param from - Starting archetype
+ * @param typeId - Type ID to remove
+ * @returns Archetype with the type removed, or same archetype if type not present
+ *
+ * @example
+ * ```ts
+ * const newArchetype = archetypeTraverseRemove(world, archetype, velocityId);
+ * ```
+ */
+export declare function archetypeTraverseRemove(world: World, from: Archetype, typeId: EntityId): Archetype;
+//# sourceMappingURL=archetype.d.ts.map

package/dist/archetype.d.ts.map

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

package/dist/archetype.js

@@ -0,0 +1,412 @@
+import { addEntityRecord, removeEntityRecord } from "./entity.js";
+import { fireObserverEvent } from "./observer.js";
+import { Type } from "./schema.js";
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Initial capacity when first entity is added to an archetype.
+ */
+const INITIAL_CAPACITY = 16;
+/**
+ * Schema for tick columns (Uint32Array).
+ */
+const TICK_SCHEMA = Type.u32();
+// ============================================================================
+// Column Utilities
+// ============================================================================
+/**
+ * Allocates a column based on schema type (TypedArray for primitives, Array for objects).
+ */
+function allocateColumn(schema, capacity) {
+    if (schema.kind === "typed") {
+        const TypedArrayCtor = schema.arrayConstructor;
+        return new TypedArrayCtor(capacity);
+    }
+    return [];
+}
+/**
+ * Resizes a column to new capacity, preserving existing data. Regular arrays need no resize.
+ */
+function resizeColumn(column, newCapacity) {
+    if (Array.isArray(column)) {
+        return column;
+    }
+    const TypedArrayCtor = column.constructor;
+    const newColumn = new TypedArrayCtor(newCapacity);
+    const copyLength = Math.min(column.length, newCapacity);
+    newColumn.set(column.subarray(0, copyLength));
+    return newColumn;
+}
+/**
+ * Clears a column slot (undefined for arrays, 0 for typed arrays).
+ */
+function clearColumn(column, index) {
+    if (Array.isArray(column)) {
+        column[index] = undefined;
+    }
+    else {
+        column[index] = 0;
+    }
+}
+// ============================================================================
+// Hashing
+// ============================================================================
+/**
+ * Hashes a sorted array of type IDs into a unique archetype key.
+ *
+ * @param types - Sorted type IDs
+ * @returns Colon-delimited hash key (e.g., "1:5:12")
+ *
+ * @example
+ * ```ts
+ * const hash = hashArchetypeTypes([1, 5, 12]); // "1:5:12"
+ * ```
+ */
+export function hashArchetypeTypes(types) {
+    return types.join(":");
+}
+// ============================================================================
+// Archetype Creation
+// ============================================================================
+/**
+ * Creates an archetype from sorted type IDs and their schemas.
+ * Columns are allocated lazily on first entity insertion to avoid
+ * memory allocation for transitional archetypes (graph traversal nodes).
+ *
+ * @param sortedTypes - Type IDs in ascending order
+ * @param schemas - Map of type ID to field schemas
+ * @returns New archetype with empty entity storage
+ *
+ * @example
+ * ```ts
+ * const archetype = createArchetype([positionId, velocityId], schemas);
+ * ```
+ */
+export function createArchetype(sortedTypes, schemas) {
+    return {
+        types: sortedTypes,
+        typesSet: new Set(sortedTypes),
+        hash: hashArchetypeTypes(sortedTypes),
+        entities: [],
+        columns: new Map(),
+        schemas,
+        edges: new Map(),
+        capacity: 0,
+        ticks: new Map(),
+    };
+}
+/**
+ * Registers an archetype in the world's lookup table, updates entity records,
+ * and fires the archetypeCreated observer event.
+ *
+ * @param world - World to register archetype in
+ * @param archetype - Archetype to register
+ *
+ * @example
+ * ```ts
+ * const archetype = createArchetype(types, schemas);
+ * registerArchetype(world, archetype);
+ * ```
+ */
+export function registerArchetype(world, archetype) {
+    world.archetypes.byId.set(archetype.hash, archetype);
+    addEntityRecord(world, archetype);
+    fireObserverEvent(world, "archetypeCreated", archetype);
+}
+/**
+ * Creates an archetype and registers it in the world.
+ *
+ * @param world - World to register archetype in
+ * @param types - Sorted type IDs for the archetype
+ * @param schemas - Map of type ID to field schemas
+ * @returns Newly created and registered archetype
+ *
+ * @example
+ * ```ts
+ * const archetype = createAndRegisterArchetype(world, [positionId], schemas);
+ * ```
+ */
+export function createAndRegisterArchetype(world, types, schemas) {
+    const archetype = createArchetype(types, schemas);
+    registerArchetype(world, archetype);
+    return archetype;
+}
+// ============================================================================
+// Capacity Management
+// ============================================================================
+/**
+ * Ensures archetype has capacity for requiredCapacity entities.
+ * Allocates columns and tick arrays on first entity, grows 4x thereafter.
+ */
+function ensureArchetypeCapacity(archetype, requiredCapacity) {
+    if (archetype.capacity >= requiredCapacity)
+        return;
+    if (archetype.capacity === 0) {
+        const initialCapacity = Math.max(INITIAL_CAPACITY, requiredCapacity);
+        for (const [componentId, fieldSchemas] of archetype.schemas.entries()) {
+            const fieldColumns = {};
+            for (const fieldName in fieldSchemas) {
+                fieldColumns[fieldName] = allocateColumn(fieldSchemas[fieldName], initialCapacity);
+            }
+            archetype.columns.set(componentId, fieldColumns);
+        }
+        for (const componentId of archetype.types) {
+            archetype.ticks.set(componentId, {
+                added: allocateColumn(TICK_SCHEMA, initialCapacity),
+                changed: allocateColumn(TICK_SCHEMA, initialCapacity),
+            });
+        }
+        archetype.capacity = initialCapacity;
+        return;
+    }
+    let newCapacity = archetype.capacity;
+    while (newCapacity < requiredCapacity) {
+        newCapacity *= 4;
+    }
+    for (const fieldColumns of archetype.columns.values()) {
+        for (const fieldName in fieldColumns) {
+            fieldColumns[fieldName] = resizeColumn(fieldColumns[fieldName], newCapacity);
+        }
+    }
+    for (const componentTicks of archetype.ticks.values()) {
+        componentTicks.added = resizeColumn(componentTicks.added, newCapacity);
+        componentTicks.changed = resizeColumn(componentTicks.changed, newCapacity);
+    }
+    archetype.capacity = newCapacity;
+}
+// ============================================================================
+// Entity Movement
+// ============================================================================
+/**
+ * Adds an entity to an archetype, initializing tick tracking for change detection.
+ *
+ * @param archetype - Target archetype
+ * @param entityId - Entity to add
+ * @param tick - Current world tick for change detection (defaults to 0)
+ * @returns Row index where entity was inserted
+ *
+ * @example
+ * ```ts
+ * const row = addEntityToArchetype(archetype, entityId, world.tick);
+ * ```
+ */
+export function addEntityToArchetype(archetype, entityId, tick = 0) {
+    const row = archetype.entities.length;
+    ensureArchetypeCapacity(archetype, row + 1);
+    archetype.entities.push(entityId);
+    for (const componentTicks of archetype.ticks.values()) {
+        componentTicks.added[row] = tick;
+        componentTicks.changed[row] = tick;
+    }
+    return row;
+}
+/**
+ * Removes an entity from an archetype using swap-and-pop for O(1) removal.
+ * The last entity in the archetype is moved into the vacated row.
+ *
+ * @param archetype - Archetype to remove entity from
+ * @param row - Row index of entity to remove
+ * @returns Entity ID that was swapped into the row, or undefined if row was last
+ *
+ * @example
+ * ```ts
+ * const swapped = removeEntityFromArchetypeByRow(archetype, row);
+ * if (swapped) updateEntityRecord(world, swapped, archetype, row);
+ * ```
+ */
+export function removeEntityFromArchetypeByRow(archetype, row) {
+    const lastIdx = archetype.entities.length - 1;
+    let swappedEntityId;
+    if (row !== lastIdx) {
+        swappedEntityId = archetype.entities[lastIdx];
+        archetype.entities[row] = swappedEntityId;
+        for (const fieldColumns of archetype.columns.values()) {
+            for (const fieldName in fieldColumns) {
+                fieldColumns[fieldName][row] = fieldColumns[fieldName][lastIdx];
+            }
+        }
+        for (const componentTicks of archetype.ticks.values()) {
+            componentTicks.added[row] = componentTicks.added[lastIdx];
+            componentTicks.changed[row] = componentTicks.changed[lastIdx];
+        }
+    }
+    archetype.entities.pop();
+    for (const fieldColumns of archetype.columns.values()) {
+        for (const fieldName in fieldColumns) {
+            clearColumn(fieldColumns[fieldName], lastIdx);
+        }
+    }
+    for (const componentTicks of archetype.ticks.values()) {
+        clearColumn(componentTicks.added, lastIdx);
+        clearColumn(componentTicks.changed, lastIdx);
+    }
+    return swappedEntityId;
+}
+/**
+ * Transfers an entity between archetypes, copying shared component data and ticks.
+ * Used when adding/removing components causes an entity to move archetypes.
+ *
+ * @param fromArchetype - Source archetype
+ * @param fromRow - Row index in source archetype
+ * @param toArchetype - Target archetype
+ * @param tick - Current world tick for new component ticks (defaults to 0)
+ * @returns New row index and swapped entity ID (if any was moved during removal)
+ *
+ * @example
+ * ```ts
+ * const { toRow, swappedEntityId } = transferEntityToArchetypeByRow(
+ *   fromArchetype, fromRow, toArchetype, world.tick
+ * );
+ * ```
+ */
+export function transferEntityToArchetypeByRow(fromArchetype, fromRow, toArchetype, tick = 0) {
+    const entityId = fromArchetype.entities[fromRow];
+    const toRow = addEntityToArchetype(toArchetype, entityId, tick);
+    for (let t = 0; t < toArchetype.types.length; t++) {
+        const type = toArchetype.types[t];
+        const destFieldColumns = toArchetype.columns.get(type);
+        const sourceFieldColumns = fromArchetype.columns.get(type);
+        if (!destFieldColumns || !sourceFieldColumns)
+            continue;
+        for (const fieldName in destFieldColumns) {
+            destFieldColumns[fieldName][toRow] = sourceFieldColumns[fieldName][fromRow];
+        }
+    }
+    for (const componentId of toArchetype.types) {
+        const fromTicks = fromArchetype.ticks.get(componentId);
+        const toTicks = toArchetype.ticks.get(componentId);
+        if (fromTicks && toTicks) {
+            toTicks.added[toRow] = fromTicks.added[fromRow];
+            toTicks.changed[toRow] = fromTicks.changed[fromRow];
+        }
+    }
+    const swappedEntityId = removeEntityFromArchetypeByRow(fromArchetype, fromRow);
+    return { toRow, swappedEntityId };
+}
+// ============================================================================
+// Archetype Graph Traversal
+// ============================================================================
+/**
+ * Finds insertion index in sorted array using binary search.
+ */
+function findInsertionIndex(types, typeId) {
+    let low = 0;
+    let high = types.length;
+    while (low < high) {
+        const mid = Math.floor((low + high) / 2);
+        if (types[mid] < typeId) {
+            low = mid + 1;
+        }
+        else {
+            high = mid;
+        }
+    }
+    return low;
+}
+/**
+ * Finds or creates an archetype with a type added, checking cache first to avoid Map allocation.
+ */
+function ensureArchetypeWithType(world, from, typeId, schema) {
+    const insertIdx = findInsertionIndex(from.types, typeId);
+    const newTypes = from.types.toSpliced(insertIdx, 0, typeId);
+    const hashKey = hashArchetypeTypes(newTypes);
+    const existing = world.archetypes.byId.get(hashKey);
+    if (existing)
+        return existing;
+    const schemas = new Map(from.schemas);
+    if (schema)
+        schemas.set(typeId, schema);
+    return createAndRegisterArchetype(world, newTypes, schemas);
+}
+/**
+ * Finds or creates an archetype with a type removed, checking cache first to avoid Map allocation.
+ */
+function ensureArchetypeWithoutType(world, from, typeId) {
+    const newTypes = from.types.filter((id) => id !== typeId);
+    const hashKey = hashArchetypeTypes(newTypes);
+    const existing = world.archetypes.byId.get(hashKey);
+    if (existing)
+        return existing;
+    const schemas = new Map(from.schemas);
+    schemas.delete(typeId);
+    return createAndRegisterArchetype(world, newTypes, schemas);
+}
+/**
+ * Destroys an archetype and cleans up all references.
+ * Removes from world lookup, fires observer event, and clears bidirectional edges.
+ *
+ * @param world - World containing the archetype
+ * @param archetype - Archetype to destroy (root archetype is protected)
+ *
+ * @example
+ * ```ts
+ * if (archetype.entities.length === 0) {
+ *   destroyArchetype(world, archetype);
+ * }
+ * ```
+ */
+export function destroyArchetype(world, archetype) {
+    if (archetype === world.archetypes.root)
+        return;
+    removeEntityRecord(world, archetype);
+    fireObserverEvent(world, "archetypeDestroyed", archetype);
+    world.archetypes.byId.delete(archetype.hash);
+    for (const [typeId, targetArchetype] of archetype.edges) {
+        targetArchetype.edges.delete(typeId);
+    }
+}
+/**
+ * Traverses the archetype graph to find or create an archetype with a type added.
+ * Uses edge caching for O(1) repeated traversals.
+ *
+ * @param world - World containing archetype graph
+ * @param from - Starting archetype
+ * @param typeId - Type ID to add
+ * @param schema - Schema for the type (required if type is new to graph)
+ * @returns Archetype with the type added, or same archetype if type already present
+ *
+ * @example
+ * ```ts
+ * const newArchetype = archetypeTraverseAdd(world, archetype, velocityId, velocitySchema);
+ * ```
+ */
+export function archetypeTraverseAdd(world, from, typeId, schema) {
+    if (from.typesSet.has(typeId))
+        return from;
+    const cachedArchetype = from.edges.get(typeId);
+    if (cachedArchetype)
+        return cachedArchetype;
+    const to = ensureArchetypeWithType(world, from, typeId, schema);
+    // Bidirectional edges enable O(1) traversal in both add and remove directions
+    from.edges.set(typeId, to);
+    to.edges.set(typeId, from);
+    return to;
+}
+/**
+ * Traverses the archetype graph to find or create an archetype with a type removed.
+ * Uses edge caching for O(1) repeated traversals.
+ *
+ * @param world - World containing archetype graph
+ * @param from - Starting archetype
+ * @param typeId - Type ID to remove
+ * @returns Archetype with the type removed, or same archetype if type not present
+ *
+ * @example
+ * ```ts
+ * const newArchetype = archetypeTraverseRemove(world, archetype, velocityId);
+ * ```
+ */
+export function archetypeTraverseRemove(world, from, typeId) {
+    if (!from.typesSet.has(typeId))
+        return from;
+    const cachedArchetype = from.edges.get(typeId);
+    if (cachedArchetype)
+        return cachedArchetype;
+    const to = ensureArchetypeWithoutType(world, from, typeId);
+    // Bidirectional edges enable O(1) traversal in both add and remove directions
+    from.edges.set(typeId, to);
+    to.edges.set(typeId, from);
+    return to;
+}
+//# sourceMappingURL=archetype.js.map