@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/dist/entity-handle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Branded `number` representing an Entity handle. Stored as a JS `number` but
+ * holds the u32 bit pattern (generation << 24) | index.
+ *
+ * The phantom `__entity` brand prevents accidental mixing with other numbers.
+ *
+ * Naming: the type-space alias is `EntityHandle` (the branded number that
+ * identifies a row). The same-named value-space `Entity` re-exported from the
+ * package barrel is the id=0 component token (see `./entity`).
+ */
+export type EntityHandle = number & {
+    readonly __entity: unique symbol;
+};
+/** Maximum representable entity index (2^24 - 1 = 16_777_215). Re-exports codec MAX_SLOT. */
+export declare const ENTITY_MAX_INDEX: number;
+/** Maximum representable generation (2^8 - 1 = 255). Re-exports codec MAX_GEN. */
+export declare const ENTITY_MAX_GENERATION = 255;
+/**
+ * Sentinel u32 value reserved for the "null entity" slot in `entity`-typed
+ * component fields.
+ *
+ * The encoding `(gen << 24) | index` yields `0xFFFFFFFF` only at the very
+ * last valid (gen=255, index=0xFFFFFF) entity, which retires permanently on
+ * its first despawn (D-08). Carving out this single bit pattern as the null
+ * sentinel costs at most one slot at the far edge of the entity space.
+ *
+ * Stored u32 column reads compare against `ENTITY_NULL_RAW` first; the
+ * column-level `Entity | null` decode lives in `world.readRow`.
+ *
+ * Scene-as-World-Blueprint anchor (feat-20260514 w12, R-8 lockdown):
+ *   This module (`packages/ecs/src/entity.ts`) is the canonical export site
+ *   for the entity null sentinel. Downstream consumers (M2 instantiate
+ *   layer 3 fallback for `'entity'`-typed component fields, w22) must import
+ *   from the package barrel:
+ *
+ *     import { ENTITY_NULL_RAW } from '@forgeax/engine-ecs'
+ *
+ *   The raw `0xFFFFFFFF` literal MUST NOT be duplicated at consumer sites
+ *   (charter proposition 1: SSOT lives here). The decoded JS-side value is
+ *   `null` (returned by `world.get(e, C).<entityField>`). Layer 3 default
+ *   for `'entity'` keyword fields stores `ENTITY_NULL_RAW` into the u32
+ *   column, which decodes back to `null` on read. ecs-managed-buffer feat
+ *   export verification (w12 grep): see `packages/ecs/src/index.ts` line
+ *   re-exporting this constant alongside `ENTITY_MAX_GENERATION /
+ *   ENTITY_MAX_INDEX`. No add-only fallback re-export is required at this
+ *   time.
+ */
+export declare const ENTITY_NULL_RAW = 4294967295;
+/**
+ * Encode (index, generation) into a u32 entity handle.
+ *
+ * Delegates to shared codec `pack(index, generation)` after ecs-specific
+ * overflow validation. The `>>> 0` anti-ToInt32 guard is inherited from the
+ * codec (D-7 hard constraint).
+ *
+ * @throws EntityIndexOverflowError when `index > ENTITY_MAX_INDEX` or `index < 0`.
+ */
+export declare function encodeEntity(index: number, generation: number): EntityHandle;
+/** Decode a u32 entity handle into its (index, generation) pair via shared codec. */
+export declare function decodeEntity(entity: EntityHandle): {
+    index: number;
+    generation: number;
+};
+/** Extract just the index slot from an entity handle via shared codec. */
+export declare function entityIndex(entity: EntityHandle): number;
+/** Extract just the generation slot from an entity handle via shared codec. */
+export declare function entityGeneration(entity: EntityHandle): number;
+//# sourceMappingURL=entity-handle.d.ts.map

package/dist/entity-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-handle.d.ts","sourceRoot":"","sources":["../src/entity-handle.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEzE,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,QAAW,CAAC;AAEzC,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,MAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAK5E;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAMxF;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAE7D"}

package/dist/entity.d.ts

@@ -0,0 +1,86 @@
+import type { ComponentId } from './component';
+/**
+ * The id=0 essential `Entity` component. Its single `self` field carries the
+ * full packed entity handle for the row it sits on (written at spawn time).
+ *
+ * Naming convention (feat-20260611-ecs-storage-naming-ssot):
+ *
+ *   - Value-space `Entity` (this const) is the id=0 component token. It is
+ *     looked up by name (`'Entity'`) at component-registration time and used
+ *     as a value (`world.spawn`, `world.get(entity, Entity)`).
+ *   - Type-space `EntityHandle` (the branded number, exported from `../entity`)
+ *     is the row-identifier handle type. It is used in `: EntityHandle`
+ *     annotations.
+ *
+ * The two no longer share a name -- the prior intentional coexistence (a
+ * single `Entity` symbol carrying both meanings via TS namespace merging) was
+ * dropped because two-roles-one-name created repeated AI-user confusion when
+ * reading `: Entity` annotations (is this the handle or the token?). The id=0
+ * component token's name (the literal string `'Entity'`) is preserved for
+ * runtime stability; only the type-space alias was renamed.
+ *
+ * @example Read an entity's own handle through a query:
+ *   const query = world.query({ read: [Transform] }).unwrap();
+ *   for (const row of query) {
+ *     const handle = row.entity;
+ *   }
+ *
+ * @example Use `world.get` as a general liveness probe:
+ *   const r = world.get(e, Entity);
+ *   if (!r.ok) { // r.error.code === 'stale-entity' for a despawned handle
+ *   }
+ */
+export declare const Entity: import("./component").Component<"Entity", {
+    readonly self: "entity";
+}>;
+/**
+ * Marks an entity as disabled.
+ *
+ * Queries exclude this tag by default. Add `Disabled` to a query's `with`
+ * tuple when the query must inspect or re-enable disabled entities.
+ */
+export declare const Disabled: import("./component").Component<"Disabled", {}>;
+/**
+ * SSOT for component ids that are essential to every archetype. Every archetype
+ * carries the columns named by these ids unconditionally (they cannot be added
+ * or removed via `addComponent` / `removeComponent`). Currently only `Entity`
+ * is essential -- the row-identity column that lets every entity read its own
+ * packed handle (`world.get(e, Entity).self === e`) through the same column
+ * path as any other component (feat-20260602 / charter P4).
+ *
+ * Frozen so consumers cannot mutate the SSOT. The barrel
+ * (`packages/ecs/src/index.ts`) re-exports this constant so the AI-facing
+ * `import { ESSENTIAL_COMPONENT_IDS } from '@forgeax/engine-ecs'` works.
+ *
+ * Physical location is `packages/ecs/src/entity.ts` -- the module that owns
+ * the `defineComponent('Entity', ...)` call, so reading the owner identity
+ * immediately after registration is well-defined. tweak-20260612-ecs-concept-
+ * compression lifted this file back from the historical `components/entity.ts`
+ * after `entity-handle.ts` freed up the `entity.ts` slot.
+ */
+export declare const ESSENTIAL_COMPONENT_IDS: ReadonlyArray<ComponentId>;
+/**
+ * Fold the essential component ids (currently `[componentId(Entity)]`) into a caller-
+ * supplied id list. Returns a NEW array; never mutates the input.
+ *
+ *   - If `ids` already contains every essential id, returns a deduped copy
+ *     (idempotent under repeated folding).
+ *   - Otherwise, returns `[...essential, ...ids]` with duplicates of the
+ *     essential ids removed.
+ *
+ * The empty input maps to `[componentId(Entity)]` -- the bare-archetype shape that a
+ * `world.spawn()` (no components) materialises.
+ *
+ * Single SSOT consumed by both `archetypeKey` (string-key fold) and
+ * `createArchetype` (column-build fold) so the two sites can never disagree
+ * on which ids are essential. Hot-path correctness is on `createArchetype`'s
+ * side: misalignment between key and columns silently drops fields.
+ *
+ * @example
+ *   foldEssentials([2, 5, 7])              // [componentId(Entity), 2, 5, 7]
+ *   foldEssentials([componentId(Entity), 2, 5]) // [componentId(Entity), 2, 5]
+ *   foldEssentials([componentId(Entity), componentId(Entity)]) // [componentId(Entity)]
+ *   foldEssentials([])                     // [componentId(Entity)]
+ */
+export declare function foldEssentials(ids: ReadonlyArray<ComponentId>): ComponentId[];
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,MAAM;;EAKjB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,iDAAkC,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,WAAW,CAE7D,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,EAAE,CAgB7E"}

package/dist/errors/query-and-component-errors.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Returned via `Result.err` from `world.removeComponent` when the caller tries
+ * to remove an essential (undeletable) component
+ * (feat-20260602-archetype-stores-full-packed-entity M1 / w3, plan-strategy
+ * D-3). The only essential component today is the id=0 `Entity` component: every
+ * archetype carries it unconditionally as the row's own packed handle, so
+ * removing it is structurally meaningless. The code name is deliberately
+ * generic (`remove-essential-component`, not entity-specific) so a future second
+ * essential component reuses it without a rename.
+ *
+ * `.code = 'remove-essential-component'`
+ * `.detail = { componentName }`
+ * `.hint` — names the essential component + states it cannot be removed.
+ */
+export declare class RemoveEssentialComponentError extends Error {
+    readonly name = "RemoveEssentialComponentError";
+    readonly code: "remove-essential-component";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly componentName: string;
+    };
+    constructor(componentName: string);
+}
+/**
+ * Returned via the `Result` err branch when `instantiate` encounters a
+ * SceneAsset entity whose `components` map references a component name that was
+ * never passed to `defineComponent`.
+ *
+ * `.code = 'component-not-defined'`
+ * `.detail.name` — the offending component name.
+ *
+ * Promoting this to a class (rather than a bare object literal) keeps the
+ * scene-instantiate failure surface inside the `EcsError` class union, so the
+ * documented two-level narrow `cause instanceof EcsError` actually matches it
+ * (docs/feedbacks/2026-06-03 §6.2 Tier 4.2). `expected` / `hint` accept
+ * per-call overrides because the parent-passthrough (ChildOf) site needs a
+ * distinct message from the generic entity-component site.
+ */
+export declare class ComponentNotDefinedError extends Error {
+    readonly name = "ComponentNotDefinedError";
+    readonly code: "component-not-defined";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly name: string;
+    };
+    constructor(componentName: string, opts?: {
+        expected?: string;
+        hint?: string;
+    });
+}
+/**
+ * Returned via `Result.err` from `world.spawn` / `world.addComponent` /
+ * `world.instantiateScene` / `Commands.spawn` when the caller-supplied
+ * data payload carries a key that is not declared in the target component's
+ * schema. The pre-fix behaviour silently dropped unknown keys inside
+ * `fillComponentDefaults` (which walked schema keys, never raw keys), so a
+ * typo like `MeshRenderer { material: h }` (singular legacy field name; the
+ * current schema has `materials: array<...>`) produced an empty-defaults row
+ * + an invisible / mid-grey entity downstream. Surfacing the typo at the
+ * spawn boundary collapses a class of "renders wrong, looks like a graphics
+ * bug" reports into a single explicit error.
+ *
+ * `.code = 'spawn-data-unknown-field'`
+ * `.detail = { component, field, knownFields }`
+ * `.hint` — names the offending field and lists the schema's known fields.
+ */
+export declare class SpawnDataUnknownFieldError extends Error {
+    readonly name = "SpawnDataUnknownFieldError";
+    readonly code: "spawn-data-unknown-field";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly field: string;
+        readonly knownFields: readonly string[];
+    };
+    constructor(componentName: string, fieldName: string, knownFields: readonly string[]);
+}
+export type QuerySpanUnavailableReason = 'optional-data' | 'row-change-filter' | 'sparse-component';
+export declare class QueryDescriptorConflictError extends Error {
+    readonly name = "QueryDescriptorConflictError";
+    readonly code: "query-descriptor-conflict";
+    readonly expected = "each component occupies one descriptor role";
+    readonly hint: string;
+    readonly detail: {
+        readonly componentName: string;
+        readonly roles: readonly string[];
+    };
+    constructor(componentName: string, roles: readonly string[]);
+}
+export declare class QueryDataRequiresFieldsError extends Error {
+    readonly name = "QueryDataRequiresFieldsError";
+    readonly code: "query-data-requires-fields";
+    readonly expected = "a component with at least one data field";
+    readonly hint: string;
+    readonly detail: {
+        readonly componentName: string;
+    };
+    constructor(componentName: string);
+}
+export declare class QuerySpanUnavailableError extends Error {
+    readonly name = "QuerySpanUnavailableError";
+    readonly code: "query-span-unavailable";
+    readonly expected = "a descriptor whose rows form contiguous table ranges";
+    readonly hint = "Use row iteration or split the query.";
+    readonly detail: {
+        readonly reason: QuerySpanUnavailableReason;
+    };
+    constructor(reason: QuerySpanUnavailableReason);
+}
+export declare class QueryIterationInvalidatedError extends Error {
+    readonly name = "QueryIterationInvalidatedError";
+    readonly code: "query-iteration-invalidated";
+    readonly expected: string;
+    readonly hint = "Use deferred Commands for structural mutation, then restart iteration.";
+    readonly detail: {
+        readonly expectedStructureEpoch: number;
+        readonly actualStructureEpoch: number;
+    };
+    constructor(expectedStructureEpoch: number, actualStructureEpoch: number);
+}
+export declare class QueryIterationActiveError extends Error {
+    readonly name = "QueryIterationActiveError";
+    readonly code: "query-iteration-active";
+    readonly expected = "one active iterator per Query";
+    readonly hint = "Complete the active iterator or create an independent Query.";
+    readonly detail: {};
+    constructor();
+}
+//# sourceMappingURL=query-and-component-errors.d.ts.map

package/dist/errors/query-and-component-errors.d.ts.map

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

package/dist/errors/relationship-errors.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Returned via `Result.err` from `world.addChild` / `world.reparent` (M3) when
+ * a hierarchy write would form a cycle — either the child is its own parent
+ * (self-loop) or the proposed parent is already a descendant of the child
+ * (ancestor-walk hit). The `.detail` carries both the offending child entity
+ * and the ancestor entity that closed the cycle so AI users can locate the
+ * loop without re-walking the graph.
+ *
+ * `.code = 'relationship-self-cycle'`
+ * `.detail = { component, entity, ancestor }`
+ * `.hint` — names the child + ancestor that would close the cycle.
+ */
+export declare class RelationshipSelfCycleError extends Error {
+    readonly name = "RelationshipSelfCycleError";
+    readonly code: "relationship-self-cycle";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly entity: number;
+        readonly ancestor: number;
+    };
+    constructor(component: string, entity: number, ancestor: number);
+}
+/**
+ * Thrown by `defineComponent` (feat-20260602 M2) when a component declares a
+ * `relationship.mirror` naming a component that has not yet been defined
+ * (AC-09). AI users defineComponent the mirror before the holder (mirror-then-
+ * holder order).
+ *
+ * The `.code` literal `relationship-mirror-component-not-registered` is kept
+ * unchanged across the M2 migration (deliberate terminology trade-off:
+ * external `.code` stability over wording precision); only the `.hint` text
+ * drops the register/registered phrasing in favour of defineComponent ordering
+ * guidance.
+ *
+ * `.code = 'relationship-mirror-component-not-registered'`
+ * `.detail = { component, mirror }`
+ * `.hint` — names the holder + the undefined mirror component.
+ */
+export declare class RelationshipMirrorComponentNotRegisteredError extends Error {
+    readonly name = "RelationshipMirrorComponentNotRegisteredError";
+    readonly code: "relationship-mirror-component-not-registered";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly mirror: string;
+    };
+    constructor(component: string, mirror: string);
+}
+/**
+ * Thrown by `defineComponent` (feat-20260602 M2) when the
+ * `relationship.field` on the mirror component is missing or its schema type
+ * is not the only legal back-reference storage shape `array<entity>`
+ * (AC-11 b). AI users declare the mirror field as `'array<entity>'`.
+ *
+ * `.code = 'relationship-mirror-field-type-mismatch'`
+ * `.detail = { component, mirror, field, actualType }`
+ * `.hint` — names the holder + mirror field + the type observed.
+ */
+export declare class RelationshipMirrorFieldTypeMismatchError extends Error {
+    readonly name = "RelationshipMirrorFieldTypeMismatchError";
+    readonly code: "relationship-mirror-field-type-mismatch";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly mirror: string;
+        readonly field: string;
+        readonly actualType: string;
+    };
+    constructor(component: string, mirror: string, field: string, actualType: string);
+}
+/**
+ * Returned via `Result.err` from `world.removeChild` (M3) when the `parent`
+ * argument does not match the child's current relationship parent (the child
+ * lacks the relationship component, or it points at a different parent). The
+ * `.detail` carries the expected (argument) parent + the actual current parent
+ * so AI users can reconcile their model.
+ *
+ * `.code = 'relationship-detach-mismatch'`
+ * `.detail = { component, child, expectedParent, actualParent }`
+ *   `actualParent === ENTITY_NULL_RAW` (0) signals the child has no relationship.
+ * `.hint` — names the child + the parent mismatch.
+ */
+export declare class RelationshipDetachMismatchError extends Error {
+    readonly name = "RelationshipDetachMismatchError";
+    readonly code: "relationship-detach-mismatch";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly child: number;
+        readonly expectedParent: number;
+        readonly actualParent: number;
+    };
+    constructor(component: string, child: number, expectedParent: number, actualParent: number);
+}
+/** Returned when callers attempt to mutate an engine-maintained target list. */
+export declare class RelationshipTargetReadonlyError extends Error {
+    readonly name = "RelationshipTargetReadonlyError";
+    readonly code: "component-field-invalid-value";
+    readonly expected = "relationship source mutation";
+    readonly hint: string;
+    readonly detail: {
+        readonly component: string;
+        readonly operation: string;
+    };
+    constructor(component: string, operation: string);
+}
+//# sourceMappingURL=relationship-errors.d.ts.map

package/dist/errors/relationship-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-errors.d.ts","sourceRoot":"","sources":["../../src/errors/relationship-errors.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAkB,IAAI,gCAAgC;IACtD,QAAQ,CAAC,IAAI,EAAG,yBAAyB,CAAU;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;gBAEU,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAgBhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,6CAA8C,SAAQ,KAAK;IACtE,SAAkB,IAAI,mDAAmD;IACzE,QAAQ,CAAC,IAAI,EAAG,8CAA8C,CAAU;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;gBAE7D,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAe9C;AAED;;;;;;;;;GASG;AACH,qBAAa,wCAAyC,SAAQ,KAAK;IACjE,SAAkB,IAAI,8CAA8C;IACpE,QAAQ,CAAC,IAAI,EAAG,yCAAyC,CAAU;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;gBAEU,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAiBjF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAkB,IAAI,qCAAqC;IAC3D,QAAQ,CAAC,IAAI,EAAG,8BAA8B,CAAU;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;gBAEU,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAiB3F;AAED,gFAAgF;AAChF,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAkB,IAAI,qCAAqC;IAC3D,QAAQ,CAAC,IAAI,EAAG,+BAA+B,CAAU;IACzD,QAAQ,CAAC,QAAQ,kCAAkC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;gBAEU,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAMjD"}

package/dist/errors/sprite-and-shared-errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * feat-20260713-mount-override-component-add-and-shared-ref-round M2 / w9 —
+ * `.code = 'shared-field-invalid-value'`.
+ *
+ * A `shared<T>` scalar / `array<shared<T>>` element must be a resolved numeric
+ * Handle. A raw GUID string / `{ guid }` / `{ kind }` object (the
+ * pre-resolution shape a sidecar hands an AI user) used to be silently coerced
+ * to the all-zero sentinel by the column packer / scalar write path, so a
+ * mis-bound reference read back as `0` / `[0,0,0,0]` and rendered blank with no
+ * error. `validateComponentDataKeys` only checks key NAMES, not value types;
+ * this error closes the value-type gap at all three write entries
+ * (spawn / addComponent / set). `.detail.field` + `.detail.fieldType` name the
+ * offending field; `.detail.index` locates the array element (undefined for the
+ * scalar form).
+ *
+ * `.detail = { component, field, fieldType, actualValue, index? }`
+ * `.hint` — names the field and points at `AssetRegistry.load + allocSharedRef`.
+ */
+export declare class SharedFieldInvalidValueError extends Error {
+    readonly name = "SharedFieldInvalidValueError";
+    readonly code: "shared-field-invalid-value";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly component: string;
+        readonly field: string;
+        readonly fieldType: string;
+        readonly actualValue: unknown;
+        readonly index?: number;
+    };
+    constructor(componentName: string, fieldName: string, fieldType: string, actualValue: unknown, index?: number);
+}
+/**
+ * Thrown / returned via Layer-3 error route when `SpriteInstances.transforms`
+ * (stride 16 — column-major mat4 per instance) and `SpriteInstances.regions`
+ * (stride 4 — per-instance UV vec4) instance counts disagree at render-system-
+ * extract entry.
+ *
+ * `.code = 'sprite-instances-count-mismatch'`
+ * `.detail = { transformsLength, regionsLength, expectedStride: { transforms: 16, regions: 4 } }`
+ * `.hint` — instructs the AI user to enforce
+ *   `transforms.length / 16 === regions.length / 4`.
+ */
+export declare class SpriteInstancesCountMismatchError extends Error {
+    readonly name = "SpriteInstancesCountMismatchError";
+    readonly code: "sprite-instances-count-mismatch";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly code: 'sprite-instances-count-mismatch';
+        readonly transformsLength: number;
+        readonly regionsLength: number;
+        readonly expectedStride: {
+            readonly transforms: 16;
+            readonly regions: 4;
+        };
+    };
+    constructor(transformsLength: number, regionsLength: number);
+}
+/**
+ * Thrown / returned via Layer-3 error route when an entity carrying
+ * `SpriteInstances` references a MaterialAsset whose first pass shader is not
+ * `'forgeax::sprite'`. Detected at render-system-extract entry (M3 w13).
+ *
+ * `.code = 'sprite-instances-requires-sprite-shader'`
+ * `.detail = { entityId, observedMaterialShaderId }`
+ * `.hint` — instructs the AI user to bind a MaterialAsset whose first pass
+ *   `shader` is `'forgeax::sprite'` or `'forgeax::sprite-lit'`.
+ *
+ * feat-20260624-sprite-lit-shading-model-pure-2d-lighting M1' / t6:
+ * sprite-lit walks the same per-instance UV region vertex path as sprite
+ * (VsOut byte-identical, paramSchema mirror); both shader ids are accepted.
+ */
+export declare class SpriteInstancesRequiresSpriteShaderError extends Error {
+    readonly name = "SpriteInstancesRequiresSpriteShaderError";
+    readonly code: "sprite-instances-requires-sprite-shader";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly code: 'sprite-instances-requires-sprite-shader';
+        readonly entityId: number;
+        readonly observedMaterialShaderId: string;
+    };
+    constructor(entityId: number, observedMaterialShaderId: string);
+}
+/**
+ * Thrown / returned via Layer-3 error route when the same entity carries both
+ * `Instances` (3D per-instance mat4) and `SpriteInstances` (2D per-instance
+ * mat4 + UV region). The two primitives are peers — pick one. Detected at
+ * render-system-extract entry (M3 w13).
+ *
+ * `.code = 'sprite-instances-mutually-exclusive-with-instances'`
+ * `.detail = { entityId }`
+ * `.hint` — instructs the AI user to remove one of the two components.
+ */
+export declare class SpriteInstancesMutuallyExclusiveWithInstancesError extends Error {
+    readonly name = "SpriteInstancesMutuallyExclusiveWithInstancesError";
+    readonly code: "sprite-instances-mutually-exclusive-with-instances";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly code: 'sprite-instances-mutually-exclusive-with-instances';
+        readonly entityId: number;
+    };
+    constructor(entityId: number);
+}
+//# sourceMappingURL=sprite-and-shared-errors.d.ts.map

package/dist/errors/sprite-and-shared-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-and-shared-errors.d.ts","sourceRoot":"","sources":["../../src/errors/sprite-and-shared-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAkB,IAAI,kCAAkC;IACxD,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;gBAGA,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,OAAO,EACpB,KAAK,CAAC,EAAE,MAAM;CAyBjB;AA+BD;;;;;;;;;;GAUG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,SAAkB,IAAI,uCAAuC;IAC7D,QAAQ,CAAC,IAAI,EAAG,iCAAiC,CAAU;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;QACjD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,cAAc,EAAE;YAAE,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;YAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;SAAE,CAAC;KAC3E,CAAC;gBAEU,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAuB5D;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wCAAyC,SAAQ,KAAK;IACjE,SAAkB,IAAI,8CAA8C;IACpE,QAAQ,CAAC,IAAI,EAAG,yCAAyC,CAAU;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,yCAAyC,CAAC;QACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;KAC3C,CAAC;gBAEU,QAAQ,EAAE,MAAM,EAAE,wBAAwB,EAAE,MAAM;CAwB/D;AAED;;;;;;;;;GASG;AACH,qBAAa,kDAAmD,SAAQ,KAAK;IAC3E,SAAkB,IAAI,wDAAwD;IAC9E,QAAQ,CAAC,IAAI,EAAG,oDAAoD,CAAU;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,oDAAoD,CAAC;QACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;gBAEU,QAAQ,EAAE,MAAM;CAmB7B"}