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

package/dist/component-default-fallback.d.ts

@@ -0,0 +1,88 @@
+import type { Component, ComponentSchema } from './component';
+import { SpawnDataUnknownFieldError } from './errors';
+/**
+ * Layer-3 silent default for a single schema field type. Returned when
+ * the spawn-data raw input (layer 1) and the owner definition defaults
+ * map (layer 2) both omit a known schema field.
+ *
+ * Pure function — runs once per missing field per (component, spawn /
+ * instantiate) call. No `BufferPool` / `UniqueRefStore` / `World`
+ * dependency: the helper hands back raw column-shape values (u32 / bool
+ * / number array literal); the layer-4 silent fallback inside
+ * `writeRow` / `write{Buffer,Array,UniqueRef}Field` turns raw `0` into
+ * the live column-store value (unique-ref handle 0 / BufferPool slot
+ * id 0 / array slot length 0).
+ *
+ * Mapping is the same closed table the head-JSDoc table documents.
+ *
+ * @internal — helper-private; AI users call `fillComponentDefaults`.
+ */
+declare function typeDefault(fieldType: string): unknown;
+/**
+ * Fill missing schema fields on a partial spawn-data raw with their
+ * layer-2 / layer-3 defaults. Public surface used by:
+ *
+ *   - `World.spawn`                            (writeRow entry, M2)
+ *   - `World.addComponent`                     (writeRow entry, M2)
+ *
+ * Resolution order (matches scene-instance-container.ts JSDoc):
+ *
+ *   layer 1 — explicit raw value (caller passed `data[field] = v`).
+ *             Carrier: the raw input itself; not handled by this
+ *             helper — copied through the `if (key in raw)` branch.
+ *             SceneAsset.instantiate additionally remaps `entity` /
+ *             `array<entity>` LocalEntityId values BEFORE handing the raw
+ *             to the helper (the entity-remap layer is NOT this
+ *             helper's responsibility).
+ *
+ *   layer 2 — owner definition defaults (declared via
+ *             `defineComponent(name, schema, { defaults })`). Layer-2
+ *             defaults beat layer-3.
+ *
+ *   layer 3 — `typeDefault(fieldType)` (this file's private dispatch).
+ *
+ * Returns a fresh `Record<string, unknown>` carrying every schema
+ * field. The output is column-shape raw — the caller's writeRow path
+ * walks it field-by-field and applies layer-4 silent fallback when a
+ * raw `0` lands on a managed-family arm.
+ *
+ * Pure: no World / store side effect. Thread-safety irrelevant (single-
+ * thread JS engine), but the helper allocates one `Object.create(null)`
+ * per call so repeated invocations cannot share a mutable record.
+ *
+ * @param token  Component token (name + schema + optional defaults).
+ * @param raw    Partial spawn-data raw — caller's `Partial<ShapeOf<S>>`.
+ *               Keys not present in the schema are passed through
+ *               unchanged (the spawn write path will emit a write-time
+ *               error if applicable; helper does not validate keys).
+ * @returns      Record with every schema field populated by layer-1 /
+ *               layer-2 / layer-3 defaults in that order.
+ */
+export declare function fillComponentDefaults<S extends ComponentSchema>(token: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined): Record<string, unknown>;
+export { typeDefault };
+/**
+ * Validate that every key in `raw` is a declared schema field on `token`.
+ *
+ * Returned as a `SpawnDataUnknownFieldError` on the FIRST offending key
+ * (deterministic for AI users; subsequent unknown keys surface on the next
+ * spawn after the first is fixed). Pre-fix the unknown key was silently
+ * dropped inside `fillComponentDefaults` (which iterates only schema keys),
+ * routing typos like `MeshRenderer { material }` (singular legacy field name)
+ * into the empty-default path and producing invisible / mid-grey entities
+ * downstream.
+ *
+ * Pure: no World / store side effect; allocates no closure on the hot path
+ * (early-returns null when raw is undefined / empty).
+ *
+ * Call order at every spawn / addComponent / SceneAsset.instantiate /
+ * Commands.spawn site: validate FIRST, then `fillComponentDefaults`. The
+ * split keeps `fillComponentDefaults` pure (charter P3 SSOT — a fill helper
+ * never validates) while every layer-1 raw key reaches one validator gate.
+ *
+ * @param token  Component token (name + schema).
+ * @param raw    Caller's `Partial<ShapeOf<S>>` — raw spawn payload.
+ * @returns      `null` on success; `SpawnDataUnknownFieldError` on the first
+ *               key not declared in `componentSchema(token)`.
+ */
+export declare function validateComponentDataKeys<S extends ComponentSchema>(token: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined): SpawnDataUnknownFieldError | null;
+//# sourceMappingURL=component-default-fallback.d.ts.map

package/dist/component-default-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-default-fallback.d.ts","sourceRoot":"","sources":["../src/component-default-fallback.ts"],"names":[],"mappings":"AAkFA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAgB/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,eAAe,EAC7D,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC3B,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzB;AAMD,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,eAAe,EACjE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC3B,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAChD,0BAA0B,GAAG,IAAI,CAUnC"}

package/dist/component-schema.d.ts

@@ -0,0 +1,34 @@
+import type { Component, FieldReflection, SchemaFieldType } from './component';
+/** The complete storage placement vocabulary owned by ECS schema. */
+export type ComponentStorageKind = 'table' | 'sparse';
+/** The stable public facts needed to describe a component schema offline. */
+export interface ComponentSchemaDefinition {
+    readonly name: string;
+    readonly fields: Readonly<Record<string, SchemaFieldType>>;
+    readonly storage: ComponentStorageKind;
+}
+/**
+ * Serialization facts owned beside schema registration, not carried by the
+ * public component token. Queries and storage only need the token's schema
+ * vocabulary; domain validation and lifecycle belong to their owners.
+ */
+export interface ComponentPolicy {
+    readonly transient: boolean;
+    readonly meta: Record<string, unknown>;
+}
+/** Immutable schema reflection plus non-token policy projection. */
+export interface ComponentDefinition {
+    readonly fields: Readonly<Record<string, FieldReflection>>;
+    readonly defaults: Readonly<Record<string, unknown>> | undefined;
+    readonly policy: ComponentPolicy;
+}
+export declare function registerComponentDefinition(component: Component, definition: ComponentDefinition): void;
+/** Read the definition-time schema/policy projection for a component token. */
+export declare function componentDefinition(component: Component): ComponentDefinition;
+/**
+ * Freeze a schema value recursively.  Component descriptors are authored data,
+ * so nested defaults and enum label maps must not become mutation channels.
+ */
+export declare function deepFreeze<T>(value: T): Readonly<T>;
+export declare function assertComponentStorage(value: string): asserts value is ComponentStorageKind;
+//# sourceMappingURL=component-schema.d.ts.map

package/dist/component-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-schema.d.ts","sourceRoot":"","sources":["../src/component-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/E,qEAAqE;AACrE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtD,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAmBD,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,mBAAmB,GAC9B,IAAI,CAEN;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAM7E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAmBnD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,oBAAoB,CAI3F"}

package/dist/component-value-validate.d.ts

@@ -0,0 +1,29 @@
+import type { Component, ComponentSchema } from './component';
+import { ManagedArrayInvalidValueError, SharedFieldInvalidValueError } from './errors';
+/**
+ * Validate the outer value shape for every managed `array<T>` field present in
+ * a write payload. This is deliberately a preflight-only check: element
+ * coercion remains owned by the column writer, while arbitrary objects are
+ * rejected before any row, buffer slot, retain, or epoch mutation can occur.
+ */
+export declare function validateManagedArrayValues<S extends ComponentSchema>(token: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined): ManagedArrayInvalidValueError | null;
+/**
+ * Validate that every `shared<T>` scalar / `array<shared<T>>` element present in
+ * `raw` is a resolved numeric Handle. Returns the FIRST offending field's
+ * `SharedFieldInvalidValueError` (deterministic for AI users), or `null` on
+ * success.
+ *
+ * Pure: no World / store side effect. Only fields PRESENT in `raw` are checked
+ * (an omitted shared field takes its schema default — a numeric sentinel — via
+ * `fillComponentDefaults`, so it is never a non-handle). `undefined` / `null`
+ * values are treated as "omitted" (the write path routes them to the sentinel
+ * intentionally); only a concrete non-numeric value (string / object) is a
+ * mis-bound GUID and fails fast.
+ *
+ * @param token  Component token (name + schema).
+ * @param raw    Caller's raw payload (spawn / addComponent / set value).
+ * @returns      `null` on success; `SharedFieldInvalidValueError` on the first
+ *               shared field bound to a non-handle value.
+ */
+export declare function validateSharedFieldValues<S extends ComponentSchema>(token: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined): SharedFieldInvalidValueError | null;
+//# sourceMappingURL=component-value-validate.d.ts.map

package/dist/component-value-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-value-validate.d.ts","sourceRoot":"","sources":["../src/component-value-validate.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,6BAA6B,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAiCvF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,eAAe,EAClE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC3B,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAChD,6BAA6B,GAAG,IAAI,CAoBtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,eAAe,EACjE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC3B,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAChD,4BAA4B,GAAG,IAAI,CAyBrC"}