@ecsia/core 0.1.0

package/dist/component/define.js

@@ -0,0 +1,155 @@
+// defineComponent / defineTag runtime. Maps a schema to a resolved
+// FieldDescriptor set + a per-field ColumnLayout set, defaults options (tag → sparse, else
+// packed), and produces a frozen ComponentDef whose `id` is UNREGISTERED until a world interns it
+// The accessor factory is wired lazily once `id` is known.
+import { fieldToColumnLayout } from '../memory/index.js';
+import { resolveDescriptor } from './descriptors.js';
+import { makeAccessorFactory } from './accessor.js';
+export const UNREGISTERED = -1;
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function validateSchema(schema) {
+    if (!isPlainObject(schema))
+        throw new Error('defineComponent: schema must be a plain object');
+    const seen = new Set();
+    for (const name of Object.keys(schema)) {
+        if (!IDENT.test(name) || name.startsWith('__')) {
+            throw new Error(`defineComponent: invalid field name '${name}' (reserved __ prefix or non-identifier)`);
+        }
+        if (seen.has(name))
+            throw new Error(`defineComponent: duplicate field '${name}'`);
+        seen.add(name);
+        const token = schema[name];
+        validateToken(name, token);
+    }
+}
+function isFieldSpec(token) {
+    return typeof token === 'object' && token !== null && token.__fieldSpec === true;
+}
+function validateToken(name, token) {
+    // A FieldSpec wrapper carries a user default; validate its inner token.
+    if (isFieldSpec(token)) {
+        validateToken(name, token.token);
+        return;
+    }
+    if (typeof token === 'string')
+        return;
+    if (typeof token !== 'object' || token === null) {
+        throw new Error(`defineComponent: field '${name}' is not a valid field token`);
+    }
+    const kind = token.kind;
+    if (kind === 'vec') {
+        const t = token;
+        if (typeof t.elem !== 'string')
+            throw new Error(`defineComponent: vec field '${name}' needs a scalar elem`);
+        if (t.elem === 'bool' || t.elem === 'eid') {
+            throw new Error(`defineComponent: vec field '${name}' element must be numeric, not '${t.elem}'`);
+        }
+        if (!Number.isInteger(t.len) || t.len < 1) {
+            throw new Error(`defineComponent: vec field '${name}' len must be an integer >= 1`);
+        }
+    }
+    else if (kind === 'staticString') {
+        const choices = token.choices;
+        if (choices.length < 1)
+            throw new Error(`defineComponent: staticString field '${name}' needs >= 1 choice`);
+        if (new Set(choices).size !== choices.length) {
+            throw new Error(`defineComponent: staticString field '${name}' choices must be distinct`);
+        }
+        if (choices.length > 0xffffffff)
+            throw new Error(`defineComponent: staticString field '${name}' exceeds u32 index ceiling`);
+    }
+    else if (kind !== 'object') {
+        throw new Error(`defineComponent: field '${name}' has an unknown token kind`);
+    }
+}
+function validateOptions(options) {
+    if (options?.storage !== undefined && options.storage !== 'packed' && options.storage !== 'sparse') {
+        throw new Error(`defineComponent: storage must be 'packed' or 'sparse'`);
+    }
+    if (options?.maxHistory !== undefined && (!Number.isInteger(options.maxHistory) || options.maxHistory < 0)) {
+        throw new Error('defineComponent: maxHistory must be a non-negative integer');
+    }
+}
+// `B`/`N` capture the brand/name LITERALS so the returned def's `name` is the literal the query DSL
+// lifts to a precise element key (CompKey). The runtime `name` is
+// `brand ?? name`. A name (or brand) is REQUIRED: without it two anonymous defs would
+// both key the element surface as `'Component'` and collide — so the options arg now mandates one and
+// `defineComponent(schema)` is a compile error. defineTag and the relations runtime supply `brand`.
+export function defineComponent(schema, options) {
+    validateSchema(schema);
+    validateOptions(options);
+    if (options?.brand === undefined && options?.name === undefined) {
+        throw new Error("defineComponent: a 'name' (or 'brand') option is required — it keys the element surface (e.entity.<name>) and prevents anonymous defs from colliding");
+    }
+    const fields = [];
+    for (const name of Object.keys(schema)) {
+        const raw = schema[name];
+        if (isFieldSpec(raw)) {
+            fields.push(resolveDescriptor(name, raw.token, raw.default));
+        }
+        else {
+            fields.push(resolveDescriptor(name, raw));
+        }
+    }
+    const isTag = fields.length === 0;
+    const resolvedOptions = {
+        storage: options?.storage ?? (isTag ? 'sparse' : 'packed'),
+        maxHistory: options?.maxHistory ?? 0,
+    };
+    const columnLayouts = [];
+    for (const f of fields) {
+        const layout = fieldToColumnLayout(f);
+        if (layout !== null)
+            columnLayouts.push(layout);
+    }
+    const restrictedToMainThread = fields.some((f) => !f.shareable);
+    const hasRichFields = fields.some((f) => f.rich !== undefined);
+    const def = {
+        schema,
+        fields: Object.freeze(fields),
+        name: (options.brand ?? options.name),
+        options: Object.freeze(resolvedOptions),
+        columnLayouts: Object.freeze(columnLayouts),
+        defKind: 'component',
+        restrictedToMainThread,
+        hasRichFields,
+    };
+    // `id` and `accessorFactory` are the only mutable fields — the registry's single commit point
+    // Everything else is read-only; the object stays non-extensible.
+    Object.defineProperty(def, 'id', { value: UNREGISTERED, enumerable: true, writable: true, configurable: true });
+    Object.defineProperty(def, 'accessorFactory', {
+        value: null,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    if (options?.brand !== undefined) {
+        Object.defineProperty(def, '__nominalBrand', { value: options.brand, enumerable: true, writable: false });
+    }
+    // The runtime def is built as ComponentRuntime<S> (name: string); the captured literal lives only
+    // in the declared return type, so re-narrow here. The runtime value is unchanged.
+    return Object.preventExtensions(def);
+}
+// A name is REQUIRED: it keys the tag's element/membership identity, so an anonymous tag
+// can no longer collide with another on a default name.
+export function defineTag(name) {
+    if (name === undefined || name === '') {
+        throw new Error("defineTag: a 'name' argument is required — it keys the tag's identity and prevents anonymous tags from colliding");
+    }
+    return defineComponent({}, { storage: 'sparse', brand: name });
+}
+// Assign a dense ComponentId and wire the accessor factory now that `id` is known. The def
+// is frozen, so `id`/`accessorFactory` are mutated through defineProperty (the registry's single
+// commit point — analogous to the entity-record commit).
+export function registerComponentId(def, id) {
+    const rt = def;
+    if (rt.id !== UNREGISTERED) {
+        throw new Error(`component '${def.name}' is already registered to a world (id ${rt.id})`);
+    }
+    rt.id = id;
+    rt.accessorFactory = makeAccessorFactory(def);
+}
+//# sourceMappingURL=define.js.map

package/dist/component/define.js.map

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

package/dist/component/descriptors.d.ts

@@ -0,0 +1,3 @@
+import type { FieldDescriptor, FieldToken } from '@ecsia/schema';
+export declare function resolveDescriptor(name: string, token: FieldToken, userDefault?: unknown): FieldDescriptor;
+//# sourceMappingURL=descriptors.d.ts.map

package/dist/component/descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.d.ts","sourceRoot":"","sources":["../../src/component/descriptors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EAKX,MAAM,eAAe,CAAA;AAyDtB,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,eAAe,CAsGzG"}

package/dist/component/descriptors.js

@@ -0,0 +1,147 @@
+// Field-token → FieldDescriptor resolution: the value-level bodies for each token —
+// ctor, bytesPerElem, stride, shareable, encode/decode, choices,
+// default, needsExplicitInit. eid encode/decode forward to the normative memory-buffers helpers.
+import { encodeEid, decodeEid, EID_NULL } from '../memory/index.js';
+const SCALAR_ROWS = {
+    bool: { ctor: Uint8Array, bytes: 1, encode: (v) => (v ? 1 : 0), decode: (s) => s !== 0, default: false },
+    i8: { ctor: Int8Array, bytes: 1, encode: (v) => v | 0, decode: (s) => s, default: 0 },
+    u8: { ctor: Uint8Array, bytes: 1, encode: (v) => v & 0xff, decode: (s) => s, default: 0 },
+    u8c: { ctor: Uint8ClampedArray, bytes: 1, encode: (v) => v, decode: (s) => s, default: 0 },
+    i16: { ctor: Int16Array, bytes: 2, encode: (v) => v | 0, decode: (s) => s, default: 0 },
+    u16: { ctor: Uint16Array, bytes: 2, encode: (v) => v & 0xffff, decode: (s) => s, default: 0 },
+    i32: { ctor: Int32Array, bytes: 4, encode: (v) => v | 0, decode: (s) => s, default: 0 },
+    u32: { ctor: Uint32Array, bytes: 4, encode: (v) => v >>> 0, decode: (s) => s >>> 0, default: 0 },
+    f32: { ctor: Float32Array, bytes: 4, encode: (v) => +v, decode: (s) => s, default: 0 },
+    f64: { ctor: Float64Array, bytes: 8, encode: (v) => +v, decode: (s) => s, default: 0 },
+    eid: {
+        ctor: Int32Array,
+        bytes: 4,
+        encode: (v) => encodeEid(v),
+        decode: (s) => decodeEid(s),
+        default: EID_NULL,
+    },
+};
+function scalarRow(token) {
+    const row = SCALAR_ROWS[token];
+    if (row === undefined)
+        throw new Error(`unknown scalar token: ${String(token)}`);
+    return row;
+}
+function stringIndexCtor(n) {
+    if (n <= 256)
+        return Uint8Array;
+    if (n <= 65_536)
+        return Uint16Array;
+    return Uint32Array;
+}
+function isVecToken(t) {
+    return typeof t === 'object' && t.kind === 'vec';
+}
+function isStaticStringToken(t) {
+    return typeof t === 'object' && t.kind === 'staticString';
+}
+function isObjectToken(t) {
+    return typeof t === 'object' && t.kind === 'object';
+}
+function isZeroEquivalentDefault(d) {
+    return d === 0 || d === false;
+}
+export function resolveDescriptor(name, token, userDefault) {
+    // The free-form 'string' rich token MUST be matched before the scalar dispatch below (it is a
+    // `typeof === 'string'` value that scalarRow would reject as an unknown scalar token).
+    // Sidecar-backed: no column (ctor null), not shareable, identity encode/decode never invoked.
+    if (token === 'string') {
+        return {
+            name,
+            token,
+            ctor: null,
+            bytesPerElem: 0,
+            stride: 0,
+            shareable: false,
+            rich: 'string',
+            encode: (v) => v,
+            decode: (s) => s,
+            default: userDefault ?? '',
+            needsExplicitInit: false,
+        };
+    }
+    if (typeof token === 'string') {
+        const row = scalarRow(token);
+        const def = userDefault ?? row.default;
+        // eid is always non-zero-equivalent (its null is -1); other scalars only when user-overridden.
+        const needsExplicitInit = token === 'eid' ? true : userDefault !== undefined && !isZeroEquivalentDefault(def);
+        return {
+            name,
+            token,
+            ctor: row.ctor,
+            bytesPerElem: row.bytes,
+            stride: 1,
+            shareable: true,
+            encode: row.encode,
+            decode: row.decode,
+            default: def,
+            needsExplicitInit,
+        };
+    }
+    if (isVecToken(token)) {
+        const row = scalarRow(token.elem);
+        const def = userDefault ?? Array(token.len).fill(row.default);
+        const needsExplicitInit = userDefault !== undefined && def.some((axis) => !isZeroEquivalentDefault(axis));
+        return {
+            name,
+            token,
+            ctor: row.ctor,
+            bytesPerElem: row.bytes,
+            stride: token.len,
+            shareable: true,
+            encode: row.encode,
+            decode: row.decode,
+            default: def,
+            needsExplicitInit,
+        };
+    }
+    if (isStaticStringToken(token)) {
+        const choices = token.choices;
+        const ctor = stringIndexCtor(choices.length);
+        const idxOf = new Map();
+        choices.forEach((c, i) => idxOf.set(c, i));
+        const defaultIndex = userDefault !== undefined ? (idxOf.get(userDefault) ?? 0) : 0;
+        return {
+            name,
+            token,
+            ctor,
+            bytesPerElem: ctor.BYTES_PER_ELEMENT,
+            stride: 1,
+            shareable: true,
+            encode: (v) => {
+                const idx = idxOf.get(v);
+                if (idx === undefined)
+                    throw new Error(`staticString value '${String(v)}' not in choices for field '${name}'`);
+                return idx;
+            },
+            decode: (slot) => choices[slot],
+            choices,
+            default: defaultIndex,
+            // The stored slot 0 is choices[0]; only non-zero indices need an explicit fill.
+            needsExplicitInit: defaultIndex !== 0,
+        };
+    }
+    // object token: no column, not shareable.
+    if (isObjectToken(token)) {
+        return {
+            name,
+            token,
+            ctor: null,
+            bytesPerElem: 0,
+            stride: 0,
+            shareable: false,
+            rich: 'object',
+            encode: (v) => v,
+            decode: (s) => s,
+            default: userDefault,
+            needsExplicitInit: false,
+        };
+    }
+    throw new Error(`unknown field token for field '${name}'`);
+}
+//# sourceMappingURL=descriptors.js.map

package/dist/component/descriptors.js.map

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

package/dist/component/index.d.ts

@@ -0,0 +1,10 @@
+export { defineComponent, defineTag, registerComponentId, UNREGISTERED } from './define.js';
+export type { ComponentRuntime, DefKind } from './define.js';
+export { resolveDescriptor } from './descriptors.js';
+export { makeAccessorFactory, bindingsFor } from './accessor.js';
+export type { AccessorWorld, AccessorBinding, AccessorInstanceBase } from './accessor.js';
+export { buildColumnSet, bindAccessorRow } from './column-set.js';
+export type { ColumnSet, BuildColumnSetParams } from './column-set.js';
+export { SidecarStore, sidecarKey } from './sidecar.js';
+export type { SidecarKey, RichKind } from './sidecar.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC3F,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAEzF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACvD,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA"}

package/dist/component/index.js

@@ -0,0 +1,6 @@
+export { defineComponent, defineTag, registerComponentId, UNREGISTERED } from './define.js';
+export { resolveDescriptor } from './descriptors.js';
+export { makeAccessorFactory, bindingsFor } from './accessor.js';
+export { buildColumnSet, bindAccessorRow } from './column-set.js';
+export { SidecarStore, sidecarKey } from './sidecar.js';
+//# sourceMappingURL=index.js.map

package/dist/component/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAGhE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA"}

package/dist/component/sidecar.d.ts

@@ -0,0 +1,58 @@
+export type SidecarKey = number & {
+    readonly __sidecarKey: unique symbol;
+};
+export declare const sidecarKey: (componentId: number, fieldIndex: number) => SidecarKey;
+export type RichKind = 'string' | 'object';
+interface SidecarColumn {
+    /** Dense JS array indexed by entity index (handleIndex), NOT archetype row. */
+    data: unknown[];
+    /** Generation stamp per entity index (RF-HYGIENE). Parallel to `data`, grows on demand. */
+    gen: Uint32Array;
+    /** Whether `gen[index]` was ever stamped — distinguishes "written gen 0" from "never written". */
+    written: Uint8Array;
+    readonly def: unknown;
+    readonly kind: RichKind;
+}
+export declare class SidecarStore {
+    #private;
+    /** Allocate a column for a (componentId, fieldIndex) rich field (idempotent). */
+    ensureColumn(key: SidecarKey, kind: RichKind, def: unknown): void;
+    hasColumn(key: SidecarKey): boolean;
+    /** Read entity `index`'s value for `key`, applying the lazy default + generation guard (RF-HYGIENE). */
+    read(key: SidecarKey, index: number, gen: number): unknown;
+    /**
+     * Whether entity `index` has a WRITTEN value at `key` for its current generation (vs the lazy default).
+     * The serializer uses this to emit only present rich values (empty slots
+     * are skipped and re-defaulted on the receiver). A recycled index reads as not-present (RF-HYGIENE).
+     */
+    isPresent(key: SidecarKey, index: number, gen: number): boolean;
+    /** Write entity `index`'s value, stamping the current generation. */
+    write(key: SidecarKey, index: number, gen: number, value: unknown): void;
+    /**
+     * Observer-window read: during an onRemove/preDespawn drain the dying entity's
+     * generation has already been bumped, so a normal generation-guarded read would return the default.
+     * If a pending-clear entry exists for `index`, return its stashed value regardless of generation; else
+     * fall back to the generation-guarded read.
+     */
+    readForObserver(key: SidecarKey, index: number, gen: number): unknown;
+    /**
+     * Despawn handler. When no rich-carrying held component has a
+     * remove-observer, clear data[index] eagerly so the JS reference is released for GC. When one does,
+     * DEFER: stash the dying values so an onRemove handler can read them during the drain (RF-REMOVE-READ),
+     * then flush at the post-observer point (flushPending).
+     *
+     * `richKeysOnEntity` are the sidecar keys the entity actually held (its signature's rich fields); only
+     * those are stashed/cleared. `defer` is true iff any held component has a remove-observer.
+     */
+    onDespawn(index: number, richKeysOnEntity: readonly SidecarKey[], defer: boolean): void;
+    /**
+     * Flush the deferred-clear window. Called at the post-observerDrain serial slot,
+     * mirroring where storage's deferred row reclaim is finalized — after onRemove handlers have read the
+     * dying values, before the index is re-minted for a new tenant.
+     */
+    flushPending(): void;
+    hasPending(): boolean;
+    columns(): IterableIterator<[SidecarKey, SidecarColumn]>;
+}
+export {};
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/component/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/component/sidecar.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAE1E,eAAO,MAAM,UAAU,GAAI,aAAa,MAAM,EAAE,YAAY,MAAM,KAAG,UACM,CAAA;AAE3E,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE1C,UAAU,aAAa;IACrB,+EAA+E;IAC/E,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,2FAA2F;IAC3F,GAAG,EAAE,WAAW,CAAA;IAChB,kGAAkG;IAClG,OAAO,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CACxB;AASD,qBAAa,YAAY;;IAKvB,iFAAiF;IACjF,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAKjE,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAgBnC,wGAAwG;IACxG,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAU1D;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAM/D,qEAAqE;IACrE,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAUxE;;;;;OAKG;IACH,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAMrE;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAwBvF;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAIpB,UAAU,IAAI,OAAO;IAIrB,OAAO,IAAI,gBAAgB,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;CAGzD"}

package/dist/component/sidecar.js

@@ -0,0 +1,136 @@
+// The entity-index-keyed dense sidecar store for rich fields. One dense JS value
+// array + a parallel generation-stamp array per (componentId, fieldIndex), keyed by HANDLE INDEX (NOT
+// archetype row). This is the storage for 'string' and object<T> fields.
+//
+// Why entity-index-keyed (NOT per-archetype columns): a rich value lives at data[entityIndex], and the
+// entity index is invariant across archetype migrations — so RF-MIGRATE (zero migration carry) is
+// structural, the same way changeVersion follows an entity across relocations. The generation stamp
+// closes RF-HYGIENE: a recycled index never leaks the prior tenant's value (a stale slot reads the
+// field default). Main-thread-only by construction (rich components are restrictedToMainThread).
+const FIELD_BITS = 8; // up to 256 fields per component; schema arity is far below.
+export const sidecarKey = (componentId, fieldIndex) => (((componentId << FIELD_BITS) | (fieldIndex & 0xff)) >>> 0);
+export class SidecarStore {
+    #cols = new Map();
+    /** index → its pending-clear entry while a remove-observer window is open (RF-REMOVE-READ). */
+    #pending = new Map();
+    /** Allocate a column for a (componentId, fieldIndex) rich field (idempotent). */
+    ensureColumn(key, kind, def) {
+        if (this.#cols.has(key))
+            return;
+        this.#cols.set(key, { data: [], gen: new Uint32Array(0), written: new Uint8Array(0), def, kind });
+    }
+    hasColumn(key) {
+        return this.#cols.has(key);
+    }
+    #grow(col, index) {
+        if (index < col.gen.length)
+            return;
+        let next = col.gen.length === 0 ? 16 : col.gen.length;
+        while (next <= index)
+            next *= 2;
+        const g = new Uint32Array(next);
+        g.set(col.gen);
+        col.gen = g;
+        const w = new Uint8Array(next);
+        w.set(col.written);
+        col.written = w;
+    }
+    /** Read entity `index`'s value for `key`, applying the lazy default + generation guard (RF-HYGIENE). */
+    read(key, index, gen) {
+        const col = this.#cols.get(key);
+        if (col === undefined)
+            return undefined;
+        if (index < col.written.length && col.written[index] === 1 && col.gen[index] === gen) {
+            const v = col.data[index];
+            return v === undefined ? col.def : v;
+        }
+        return col.def;
+    }
+    /**
+     * Whether entity `index` has a WRITTEN value at `key` for its current generation (vs the lazy default).
+     * The serializer uses this to emit only present rich values (empty slots
+     * are skipped and re-defaulted on the receiver). A recycled index reads as not-present (RF-HYGIENE).
+     */
+    isPresent(key, index, gen) {
+        const col = this.#cols.get(key);
+        if (col === undefined)
+            return false;
+        return index < col.written.length && col.written[index] === 1 && col.gen[index] === gen;
+    }
+    /** Write entity `index`'s value, stamping the current generation. */
+    write(key, index, gen, value) {
+        const col = this.#cols.get(key);
+        if (col === undefined)
+            return;
+        this.#grow(col, index);
+        if (index >= col.data.length)
+            col.data.length = index + 1;
+        col.data[index] = value;
+        col.gen[index] = gen >>> 0;
+        col.written[index] = 1;
+    }
+    /**
+     * Observer-window read: during an onRemove/preDespawn drain the dying entity's
+     * generation has already been bumped, so a normal generation-guarded read would return the default.
+     * If a pending-clear entry exists for `index`, return its stashed value regardless of generation; else
+     * fall back to the generation-guarded read.
+     */
+    readForObserver(key, index, gen) {
+        const pend = this.#pending.get(index);
+        if (pend !== undefined && pend.values.has(key))
+            return pend.values.get(key);
+        return this.read(key, index, gen);
+    }
+    /**
+     * Despawn handler. When no rich-carrying held component has a
+     * remove-observer, clear data[index] eagerly so the JS reference is released for GC. When one does,
+     * DEFER: stash the dying values so an onRemove handler can read them during the drain (RF-REMOVE-READ),
+     * then flush at the post-observer point (flushPending).
+     *
+     * `richKeysOnEntity` are the sidecar keys the entity actually held (its signature's rich fields); only
+     * those are stashed/cleared. `defer` is true iff any held component has a remove-observer.
+     */
+    onDespawn(index, richKeysOnEntity, defer) {
+        if (richKeysOnEntity.length === 0)
+            return;
+        if (defer) {
+            const values = new Map();
+            for (const key of richKeysOnEntity) {
+                const col = this.#cols.get(key);
+                if (col === undefined)
+                    continue;
+                const v = index < col.written.length && col.written[index] === 1 ? col.data[index] : col.def;
+                values.set(key, v === undefined ? col.def : v);
+            }
+            this.#pending.set(index, { index, values });
+        }
+        // Whether deferred or not, the live slot is invalidated now: a recycled index must not read this
+        // tenant's value. The generation guard already protects correctness; clearing releases the GC ref.
+        for (const key of richKeysOnEntity)
+            this.#clearSlot(key, index);
+    }
+    #clearSlot(key, index) {
+        const col = this.#cols.get(key);
+        if (col === undefined)
+            return;
+        if (index < col.data.length)
+            col.data[index] = undefined;
+        if (index < col.written.length)
+            col.written[index] = 0;
+    }
+    /**
+     * Flush the deferred-clear window. Called at the post-observerDrain serial slot,
+     * mirroring where storage's deferred row reclaim is finalized — after onRemove handlers have read the
+     * dying values, before the index is re-minted for a new tenant.
+     */
+    flushPending() {
+        this.#pending.clear();
+    }
+    hasPending() {
+        return this.#pending.size > 0;
+    }
+    columns() {
+        return this.#cols.entries();
+    }
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/component/sidecar.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,55 @@
+export type ObserverCadence = 'frame-end' | 'per-system';
+export type ChangeTracking = 'component' | 'field';
+export type WorkerOption = number | 'no-sab';
+export interface ReactivityOptions {
+    maxWritesPerFrame?: number;
+    maxShapeChangesPerFrame?: number;
+    observerCadence?: ObserverCadence;
+    changeTrackingDefault?: ChangeTracking;
+    logEntryWords?: 1 | 2;
+    shrinkRings?: boolean;
+}
+export interface SchedulerOptions {
+    workers?: WorkerOption;
+}
+export interface WorldOptions {
+    components?: readonly unknown[];
+    relations?: readonly unknown[];
+    systems?: readonly unknown[];
+    maxEntities?: number;
+    generationBits?: number;
+    threaded?: boolean;
+    maxHotArchetypes?: number;
+    reactivity?: ReactivityOptions;
+    scheduler?: SchedulerOptions;
+}
+export interface ResolvedReactivityOptions {
+    readonly maxWritesPerFrame: number;
+    readonly maxShapeChangesPerFrame: number;
+    readonly observerCadence: ObserverCadence;
+    readonly changeTrackingDefault: ChangeTracking;
+    readonly logEntryWords: 1 | 2;
+    readonly shrinkRings: boolean;
+}
+export interface ResolvedWorldOptions {
+    readonly components: readonly unknown[];
+    readonly relations: readonly unknown[];
+    readonly systems: readonly unknown[];
+    readonly maxEntities: number;
+    readonly generationBits: number;
+    /** Derived: 32 - generationBits. */
+    readonly indexBits: number;
+    readonly threaded: boolean;
+    readonly maxHotArchetypes: number;
+    readonly reactivity: ResolvedReactivityOptions;
+    readonly scheduler: {
+        readonly workers: WorkerOption;
+    };
+}
+/** Thrown synchronously at construction for any invalid configuration. */
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+    constructor(message: string);
+}
+export declare function resolveOptions(options?: WorldOptions): ResolvedWorldOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAA;AACxD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,CAAA;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,qBAAqB,CAAC,EAAE,cAAc,CAAA;IACtC,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAE3B,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAC/B,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAC9B,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAG5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IAGvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAGlB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAGzB,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAA;IACxC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IACzC,QAAQ,CAAC,qBAAqB,EAAE,cAAc,CAAA;IAC9C,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAA;IAC9C,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAA;CACvD;AAED,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAkB,IAAI,iBAAgB;gBAC1B,OAAO,EAAE,MAAM;CAG5B;AAID,wBAAgB,cAAc,CAAC,OAAO,GAAE,YAAiB,GAAG,oBAAoB,CAoE/E"}