@oasys/oecs 0.5.4 → 0.6.0

package/dist/core/ecs/query_terms.d.ts

@@ -0,0 +1,126 @@
+import { ComponentDef, ComponentID } from './component.js';
+import { SparseComponentID } from './sparse_store.js';
+import { RelationDef } from './relation.js';
+import { BitSet } from '../../type_primitives/index.js';
+/** The non-dense query terms, carried as one frozen record.
+ *
+ * Every term here leaves the dense component mask alone, so a query that
+ * carries one still shares its parent's live archetype list. They travel
+ * together through each derive (`and`, `not`, `or`) and through each
+ * driver seam below, so one parameter replaces the run of positional lists
+ * those signatures used to repeat.
+ *
+ * A query that carries none of them holds `NO_TERMS`. That is why
+ * `_carryNondense` decides with one reference comparison, where it used to
+ * test each term in turn. The old shape spread one term across a constructor
+ * parameter, a carry test and a `new Query` argument, and a term added to two
+ * of the three went unnoticed. Add a term by adding a field here and a line to
+ * `deriveTerms`.
+ *
+ * Cold path. Read once per `forEach` call, never per row. */
+/** An archetype-level term a plugin contributes.
+ *
+ * The engine already answers three archetype questions with a bit mask: hold
+ * these, hold none of these, hold one of these. A term answers a fourth in
+ * whatever way the plugin wants, over the same input. `or(and(A, B), C)` is
+ * one, and so is any predicate over the component mask.
+ *
+ * Where it runs. Once per archetype, per query, at the rebuild the store's
+ * dirty epoch triggers. Never per row, and never per drive. A query that
+ * carries no term reaches a rebuild body byte-identical to today's.
+ *
+ * What the caller guarantees. `matches` is pure and stable: one archetype
+ * gives one answer for the life of the world. The archetype list is rebuilt
+ * from scratch on each epoch, so an unstable term does not corrupt the list,
+ * but it does make the matched set depend on when the epoch last advanced,
+ * which nothing else in the query engine does.
+ *
+ * Cold path. Build the term once and hold it. */
+export interface ArchetypeTerm {
+    /** Names the term in a dev refusal. Diagnostics only, never a cache key. */
+    readonly name: string;
+    /** True when an archetype whose component mask is `mask` belongs. */
+    matches(mask: BitSet): boolean;
+}
+/** One operand of `and`, `or` or `not`. A component definition is a leaf, and
+ * holding it is the whole question. Any `ArchetypeTerm` is a node, which is
+ * how one combinator nests inside another. */
+export type ArchetypeExpr = ComponentDef<any> | ArchetypeTerm;
+/** Every operand holds. `and()` over nothing matches every archetype, the
+ * identity of the conjunction, so a fold over an empty list narrows nothing.
+ *
+ * Pair it with `where`: `q.where(and(Pos, Vel))`. Prefer `q.and(Pos, Vel)`
+ * when the operands are a flat list of definitions, because a dense term sets
+ * a mask bit and picks the archetypes, where an expression tests each one.
+ *
+ * Cold path. Build the expression once and hold it, because `where` caches on
+ * the term's identity. */
+export declare function and(...terms: ArchetypeExpr[]): ArchetypeTerm;
+/** One operand holds, or more. `or()` over nothing matches no archetype, the
+ * identity of the disjunction. Cold path, same caching rule as `and`. */
+export declare function or(...terms: ArchetypeExpr[]): ArchetypeTerm;
+/** No operand holds. Several operands read as one negated disjunction, which
+ * is the same set as the conjunction of each negation, so `not(A, B)` matches
+ * exactly what `Query.not(A, B)` matches. `not()` over nothing matches every
+ * archetype. Cold path, same caching rule as `and`. */
+export declare function not(...terms: ArchetypeExpr[]): ArchetypeTerm;
+export interface QueryTerms {
+    /** Sparse membership a matched entity must hold. Also carries the backing
+     * sparse id of each `(R, *)` relation term, which is how the wildcard
+     * reuses the sparse-match driver unchanged. */
+    readonly sparseIncludes: readonly SparseComponentID[];
+    /** Sparse membership a matched entity must not hold. */
+    readonly sparseExcludes: readonly SparseComponentID[];
+    /** Fetch-if-present terms. Does not narrow the matched set. Authorizes
+     * `getOptionalColumnRead` under `DEV`. */
+    readonly optionalTerms: readonly ComponentID[];
+    /** Include disabled rows. Widens the iteration bound from the enabled
+     * count to the total count. */
+    readonly includesDisabled: boolean;
+    /** `(R, *)` terms, recorded for the `DEV` `relationReads` access check
+     * alone. The driver reads the backing sparse id off `sparseIncludes`. */
+    readonly relationIncludes: readonly RelationDef[];
+    readonly relationExcludes: readonly RelationDef[];
+    /** Depth-ordering term. Reorders the matched entities, parents first. */
+    readonly hierarchyTerm: HierarchyTerm | null;
+    /** Archetype-level terms a plugin contributed. Narrows the matched set
+     * without touching the dense mask, so the derived query still shares the
+     * parent's live archetype list and the narrowing happens at the rebuild.
+     * Empty for every query the core builds. */
+    readonly archetypeTerms: readonly ArchetypeTerm[];
+}
+/** The terms of a query that declares none. Shared by every dense-only query,
+ * so the common path allocates nothing and `_carryNondense` compares one
+ * reference. Frozen: a mutation here would reach every such query. */
+export declare const NO_TERMS: QueryTerms;
+/** Build the terms for a derived query.
+ *
+ * The result never equals `NO_TERMS`, and `_carryNondense` depends on that.
+ * Every caller adds a term and none removes one, so a derive always widens the
+ * record. The zero-argument forms (`optional()`, `andSparse()`) return the
+ * receiver before they reach here, which is what keeps the rule true. A future
+ * term that can be removed breaks it, and must collapse an emptied record back
+ * to `NO_TERMS` here.
+ *
+ * Cold path: one call per cache miss on a derive, never per row. */
+export declare function deriveTerms(base: QueryTerms, patch: Partial<QueryTerms>): QueryTerms;
+/** No depth limit on a `.hierarchy(R)` term, yield every matched entity
+ * regardless of its depth in the tree. The default `maxDepth`. */
+export declare const HIERARCHY_UNBOUNDED: number;
+/** A `.hierarchy(R)` depth-ordering term. Records the exclusive relation
+ * whose tree defines the order and the (optional) max depth to yield. Stored on
+ * the Query and consumed by the `forEachEntity` hierarchy match path. Absent
+ * (`null`) for the common case. */
+export interface HierarchyTerm {
+    /** The exclusive relation whose chain and tree defines the depth ordering. */
+    readonly relation: RelationDef;
+    /** Inclusive max depth to yield, where a root is 0. The walk skips an entity
+     * deeper than this. `HIERARCHY_UNBOUNDED` for no limit (bitECS `Hierarchy()`
+     * depth arg). */
+    readonly maxDepth: number;
+}
+export declare function termCacheKey(queryId: number, sparseId: number): number;
+export declare function appendSparse(terms: readonly SparseComponentID[], id: number): readonly SparseComponentID[];
+export declare function appendOptional(terms: readonly ComponentID[], id: number): readonly ComponentID[];
+export declare function appendRelation(terms: readonly RelationDef[], def: RelationDef): readonly RelationDef[];
+//# sourceMappingURL=query_terms.d.ts.map

package/dist/core/ecs/query_terms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_terms.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/query_terms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;KAcK;AAEL,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAmBpD;;;;;;;;;;;;;;;6DAe6D;AAC7D;;;;;;;;;;;;;;;;;iDAiBiD;AACjD,MAAM,WAAW,aAAa;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAQD;;8CAE8C;AAC9C,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;AAoB9D;;;;;;;;0BAQ0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,CAY5D;AAED;yEACyE;AACzE,wBAAgB,EAAE,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,CAY3D;AAED;;;uDAGuD;AACvD,wBAAgB,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,CAY5D;AAED,MAAM,WAAW,UAAU;IAC1B;;mDAE+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD;8CAC0C;IAC1C,QAAQ,CAAC,aAAa,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/C;mCAC+B;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;6EACyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,WAAW,EAAE,CAAC;IAClD,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C;;;gDAG4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;CAClD;AAED;;sEAEsE;AACtE,eAAO,MAAM,QAAQ,EAAE,UASrB,CAAC;AAEH;;;;;;;;;oEASoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAWpF;AAED;kEACkE;AAClE,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D;;;mCAGmC;AACnC,MAAM,WAAW,aAAa;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;;qBAEiB;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAaD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQtE;AAMD,wBAAgB,YAAY,CAC3B,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,EAAE,EAAE,MAAM,GACR,SAAS,iBAAiB,EAAE,CAK9B;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAKhG;AAID,wBAAgB,cAAc,CAC7B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,GAAG,EAAE,WAAW,GACd,SAAS,WAAW,EAAE,CAKxB"}

package/dist/core/ecs/ref.d.cts

@@ -1,50 +1,29 @@
 import { ComponentSchema } from './component.cjs';
-import { ArchetypeColumnLayout } from './archetype.cjs';
-import { AnyTypedArray, ColumnBacking } from '../../type_primitives/index.cjs';
-/** Maps component schema to scalar get/set properties: { x: number, y: number }. */
+import { AnyTypedArray, TypedArrayTag } from '../../type_primitives/index.cjs';
+/** Maps component schema to scalar get and set properties: { x: number, y: number }. */
 export type ComponentRef<S extends ComponentSchema> = {
     -readonly [K in keyof S]: number;
 };
 /**
  * Read-only view of a component reference. This is an **advisory** barrier,
  * not a runtime safety boundary: the `readonly` properties block field writes
- * at the type layer, but `createRef` installs working get/set on the shared
- * prototype for both `ref()` and `refRead()`, so a deliberate cast can
- * still write through (and would skip the change-tick bump `ref()` performs).
- * Treat it as "I promise I am only reading," enforced by the escape-hatch lint
- * (`bun run lint:escape-hatches`), not by the runtime.
+ * at the type layer, but the shared prototype installs working get and set for
+ * both `ref()` and `refRead()`, so a deliberate cast can still write through
+ * (and would skip the change-tick bump `ref()` performs). Treat it as "I
+ * promise I am only reading". The typechecker holds the promise. Nothing else
+ * does: no lint and no runtime check enforces it.
  */
 export type ReadonlyComponentRef<S extends ComponentSchema> = {
     readonly [K in keyof S]: number;
 };
-/** Minimal column group shape needed by createRef. */
-export interface RefColumnGroup {
-    readonly layout: ArchetypeColumnLayout;
-    readonly columns: ColumnBacking<AnyTypedArray>[];
-}
-/**
- * Create a ComponentRef bound to a specific row in a column group.
- * The prototype is built once per column group and cached; subsequent
- * calls for the same group only allocate the lightweight ref object.
- */
-export declare function createRef<S extends ComponentSchema>(group: RefColumnGroup, row: number): ComponentRef<S>;
-interface CursorInternal {
-    /** The current archetype's row plane (`Archetype._bufs`), index-parallel with
-     * its `_flatColumns`. Re-read on every `at()`; safe to hold between `at()` and
-     * a field access because `_syncRowPlane` refills it in place. */
-    _bufs: AnyTypedArray[];
-    /** Where this component's columns start in `_bufs` for the current archetype. */
-    _off: number;
-    _row: number;
-}
-/** Mutable single-entity cursor: field get/set plus `at(entity)`. */
+/** Mutable single-entity cursor: field get and set plus `at(entity)`. */
 export type ComponentCursor<S extends ComponentSchema> = {
     -readonly [K in keyof S]: number;
 } & CursorSeek;
 /**
  * Read-only cursor. **Advisory**, exactly like `ReadonlyComponentRef`: the
  * prototype carries working setters for both variants, so a deliberate cast
- * can still write through — and would skip the change-tick bump the mutable
+ * can still write through, and would skip the change-tick bump the mutable
  * variant performs.
  */
 export type ReadonlyComponentCursor<S extends ComponentSchema> = {
@@ -57,27 +36,109 @@ export interface CursorSeek {
      *
      * Returns the cursor, so a single-expression read stays one expression:
      * `ecs.cursor(Pos).at(e).x`. In a loop, prefer calling it as a statement and
-     * reading fields off the cursor — that is the form the allocation-free path
+     * reading fields off the cursor, that is the form the allocation-free path
      * exists for.
      */
     at(entity: import('./entity.cjs').EntityID): this;
 }
+/**
+ * The columns an accessor reads: one component's columns in one archetype,
+ * indexed by the global id of each field's name (`internFieldName`), with holes at
+ * the ids of names the component does not have. The archetype owns one such
+ * array for each component it holds (`Archetype._accCols`) and refills it in
+ * place whenever a buffer moves (grow, refresh), so a held array stays current.
+ */
+export type AccessorColumns = AnyTypedArray[];
+/** The own state of an accessor: two reserved names that registration
+ * refuses as field names (`RESERVED_FIELD_NAMES`). Every accessor writes these
+ * two in the same order, and thus has the same shape. Write them as literals
+ * at a hot site. See the note at the top of the file. */
+export interface Accessor {
+    __cols: AccessorColumns;
+    __row: number;
+}
+/** Field names a component cannot have, because an accessor owns them. `at`
+ * is not here: it is the cursor's own method, and only a cursor over the
+ * component rejects it, so a component with such a field keeps every other
+ * path. */
+export declare const RESERVED_FIELD_NAMES: readonly string[];
 /**
  * `at()` needs the archetype and row for an entity, and only the Store can
  * resolve those. Passing the whole Store into the cursor would hand it (and its
- * users) the mutation surface; this is the one operation it actually needs,
+ * users) the mutation surface. This is the one operation it actually needs,
  * supplied as a closure by whoever creates the cursor.
  *
- * The binder also carries the mutable/read-only difference: `Store.cursorBinder`
+ * The binder also carries the mutable and read-only difference: `Store.cursorBinder`
  * closes over whether to stamp the change tick, so the variant is settled once
  * at creation instead of branched on per `at()`.
  */
-export type CursorBinder = (cursor: CursorInternal, entity: unknown) => void;
+export type CursorBinder = (cursor: Accessor, entity: unknown) => void;
+/** The DEV-only check a sparse cursor runs on `at()`: access, liveness and
+ * membership (`Store.sparseCursorCheck`). Production code never calls it, so
+ * the sparse `at` is one mask and one field write. */
+export type SparseCursorCheck = (entity: unknown) => void;
+/**
+ * The global id of field name `name`. The first call for a name assigns the
+ * id and installs the name's accessor on the shared prototype, with the
+ * literal that `kind` selects. A later call with a different `kind` replaces
+ * that accessor with the mixed one, one time. Every other call returns the id
+ * and changes nothing.
+ */
+export declare function internFieldName(name: string, kind: TypedArrayTag): number;
+/** The global name id of each field of a component, in schema order. Made one
+ * time at component registration. The archetype places the component's columns
+ * at these ids in its accessor column arrays. */
+export declare function fieldGids(fieldNames: readonly string[], fieldTypes: readonly TypedArrayTag[]): Int32Array;
+/** The column at every id of a name the component does not have. An
+ * `AccessorColumns` array is packed with it (no holes), so a column load in an
+ * accessor never has to test for a hole. It is empty, so a read through it
+ * gives `undefined` and a write is dropped: the same silence a wrong field
+ * read had before, and DEV names the mistake through `checkedCol`. */
+export declare const NO_COLUMN: AnyTypedArray;
 /**
- * Build a cursor over `fieldNames`, bound by `bind`. The prototype (field
- * accessors by ordinal, plus `at`) is built once per component and cached; each
- * call allocates one small object, and then nothing per entity.
+ * Create a ref bound to `row` of `cols`: one `Object.create` on the shared
+ * prototype and two field writes. Nothing else is allocated for each ref.
+ */
+export declare function createRef<S extends ComponentSchema>(cols: AccessorColumns, row: number): ComponentRef<S>;
+/**
+ * Build a cursor over a component whose fields are `fieldNames`, bound by
+ * `bind`. One small object, and then nothing per entity. `at` is an own data
+ * property defined directly, and not assigned, so that an accessor named `at`
+ * on the shared prototype (a field of some other component) cannot intercept
+ * the write. `cols` is the column array the cursor starts on: a dense cursor
+ * starts on `EMPTY_COLS` and its binder writes the archetype's array on each
+ * `at()`. A sparse cursor starts on its store's array, which never changes
+ * identity, so its binder writes the row alone.
+ */
+export declare function createCursor<S extends ComponentSchema>(fieldNames: readonly string[], bind: CursorBinder, cols?: AccessorColumns): ComponentCursor<S>;
+/** What a mutable sparse cursor stamps on each `at()`: the sparse store's
+ * row ticks, `null` until the component tracks them, and its component-level
+ * change tick. The store object itself, seen through this shape. */
+export interface SparseTickPlane {
+    ticks: Uint32Array | null;
+    changedTick: number;
+}
+/** Where the stamp's value comes from: the store's change tick. */
+export interface ChangeClock {
+    readonly changeTick: number;
+}
+/**
+ * Build a cursor over a sparse component. The columns are id-indexed, so
+ * `at()` is one mask and one field write, and the column array is the store's
+ * own, given at creation and never replaced (the store refills it in place).
+ *
+ * This is a separate function with its own `at` literal, and not
+ * `createCursor` with a different binder, on purpose. A dense cursor's `at`
+ * calls its binder through one call site, and that site inlines the binder as
+ * long as it sees one function. A sparse binder is a different function, so a
+ * world with both kinds of cursor would make that site megamorphic and cost
+ * both kinds a call on every `at()`. Separate literals keep separate sites,
+ * one for each kind. Measured.
+ *
+ * A mutable cursor (`plane` given) also records the entity for the row grain
+ * of change detection, on each `at()`, as the dense cursor does: one load and
+ * one branch while the component keeps no row ticks, two stores once it does.
+ * The read-only cursor keeps the bare literal.
  */
-export declare function createCursor<S extends ComponentSchema>(fieldNames: readonly string[], bind: CursorBinder): ComponentCursor<S>;
-export {};
+export declare function createSparseCursor<S extends ComponentSchema>(fieldNames: readonly string[], cols: AccessorColumns, check: SparseCursorCheck, plane?: SparseTickPlane | null, clock?: ChangeClock | null): ComponentCursor<S>;
 //# sourceMappingURL=ref.d.ts.map

package/dist/core/ecs/ref.d.ts

@@ -1,50 +1,29 @@
 import { ComponentSchema } from './component.js';
-import { ArchetypeColumnLayout } from './archetype.js';
-import { AnyTypedArray, ColumnBacking } from '../../type_primitives/index.js';
-/** Maps component schema to scalar get/set properties: { x: number, y: number }. */
+import { AnyTypedArray, TypedArrayTag } from '../../type_primitives/index.js';
+/** Maps component schema to scalar get and set properties: { x: number, y: number }. */
 export type ComponentRef<S extends ComponentSchema> = {
     -readonly [K in keyof S]: number;
 };
 /**
  * Read-only view of a component reference. This is an **advisory** barrier,
  * not a runtime safety boundary: the `readonly` properties block field writes
- * at the type layer, but `createRef` installs working get/set on the shared
- * prototype for both `ref()` and `refRead()`, so a deliberate cast can
- * still write through (and would skip the change-tick bump `ref()` performs).
- * Treat it as "I promise I am only reading," enforced by the escape-hatch lint
- * (`bun run lint:escape-hatches`), not by the runtime.
+ * at the type layer, but the shared prototype installs working get and set for
+ * both `ref()` and `refRead()`, so a deliberate cast can still write through
+ * (and would skip the change-tick bump `ref()` performs). Treat it as "I
+ * promise I am only reading". The typechecker holds the promise. Nothing else
+ * does: no lint and no runtime check enforces it.
  */
 export type ReadonlyComponentRef<S extends ComponentSchema> = {
     readonly [K in keyof S]: number;
 };
-/** Minimal column group shape needed by createRef. */
-export interface RefColumnGroup {
-    readonly layout: ArchetypeColumnLayout;
-    readonly columns: ColumnBacking<AnyTypedArray>[];
-}
-/**
- * Create a ComponentRef bound to a specific row in a column group.
- * The prototype is built once per column group and cached; subsequent
- * calls for the same group only allocate the lightweight ref object.
- */
-export declare function createRef<S extends ComponentSchema>(group: RefColumnGroup, row: number): ComponentRef<S>;
-interface CursorInternal {
-    /** The current archetype's row plane (`Archetype._bufs`), index-parallel with
-     * its `_flatColumns`. Re-read on every `at()`; safe to hold between `at()` and
-     * a field access because `_syncRowPlane` refills it in place. */
-    _bufs: AnyTypedArray[];
-    /** Where this component's columns start in `_bufs` for the current archetype. */
-    _off: number;
-    _row: number;
-}
-/** Mutable single-entity cursor: field get/set plus `at(entity)`. */
+/** Mutable single-entity cursor: field get and set plus `at(entity)`. */
 export type ComponentCursor<S extends ComponentSchema> = {
     -readonly [K in keyof S]: number;
 } & CursorSeek;
 /**
  * Read-only cursor. **Advisory**, exactly like `ReadonlyComponentRef`: the
  * prototype carries working setters for both variants, so a deliberate cast
- * can still write through — and would skip the change-tick bump the mutable
+ * can still write through, and would skip the change-tick bump the mutable
  * variant performs.
  */
 export type ReadonlyComponentCursor<S extends ComponentSchema> = {
@@ -57,27 +36,109 @@ export interface CursorSeek {
      *
      * Returns the cursor, so a single-expression read stays one expression:
      * `ecs.cursor(Pos).at(e).x`. In a loop, prefer calling it as a statement and
-     * reading fields off the cursor — that is the form the allocation-free path
+     * reading fields off the cursor, that is the form the allocation-free path
      * exists for.
      */
     at(entity: import('./entity.js').EntityID): this;
 }
+/**
+ * The columns an accessor reads: one component's columns in one archetype,
+ * indexed by the global id of each field's name (`internFieldName`), with holes at
+ * the ids of names the component does not have. The archetype owns one such
+ * array for each component it holds (`Archetype._accCols`) and refills it in
+ * place whenever a buffer moves (grow, refresh), so a held array stays current.
+ */
+export type AccessorColumns = AnyTypedArray[];
+/** The own state of an accessor: two reserved names that registration
+ * refuses as field names (`RESERVED_FIELD_NAMES`). Every accessor writes these
+ * two in the same order, and thus has the same shape. Write them as literals
+ * at a hot site. See the note at the top of the file. */
+export interface Accessor {
+    __cols: AccessorColumns;
+    __row: number;
+}
+/** Field names a component cannot have, because an accessor owns them. `at`
+ * is not here: it is the cursor's own method, and only a cursor over the
+ * component rejects it, so a component with such a field keeps every other
+ * path. */
+export declare const RESERVED_FIELD_NAMES: readonly string[];
 /**
  * `at()` needs the archetype and row for an entity, and only the Store can
  * resolve those. Passing the whole Store into the cursor would hand it (and its
- * users) the mutation surface; this is the one operation it actually needs,
+ * users) the mutation surface. This is the one operation it actually needs,
  * supplied as a closure by whoever creates the cursor.
  *
- * The binder also carries the mutable/read-only difference: `Store.cursorBinder`
+ * The binder also carries the mutable and read-only difference: `Store.cursorBinder`
  * closes over whether to stamp the change tick, so the variant is settled once
  * at creation instead of branched on per `at()`.
  */
-export type CursorBinder = (cursor: CursorInternal, entity: unknown) => void;
+export type CursorBinder = (cursor: Accessor, entity: unknown) => void;
+/** The DEV-only check a sparse cursor runs on `at()`: access, liveness and
+ * membership (`Store.sparseCursorCheck`). Production code never calls it, so
+ * the sparse `at` is one mask and one field write. */
+export type SparseCursorCheck = (entity: unknown) => void;
+/**
+ * The global id of field name `name`. The first call for a name assigns the
+ * id and installs the name's accessor on the shared prototype, with the
+ * literal that `kind` selects. A later call with a different `kind` replaces
+ * that accessor with the mixed one, one time. Every other call returns the id
+ * and changes nothing.
+ */
+export declare function internFieldName(name: string, kind: TypedArrayTag): number;
+/** The global name id of each field of a component, in schema order. Made one
+ * time at component registration. The archetype places the component's columns
+ * at these ids in its accessor column arrays. */
+export declare function fieldGids(fieldNames: readonly string[], fieldTypes: readonly TypedArrayTag[]): Int32Array;
+/** The column at every id of a name the component does not have. An
+ * `AccessorColumns` array is packed with it (no holes), so a column load in an
+ * accessor never has to test for a hole. It is empty, so a read through it
+ * gives `undefined` and a write is dropped: the same silence a wrong field
+ * read had before, and DEV names the mistake through `checkedCol`. */
+export declare const NO_COLUMN: AnyTypedArray;
 /**
- * Build a cursor over `fieldNames`, bound by `bind`. The prototype (field
- * accessors by ordinal, plus `at`) is built once per component and cached; each
- * call allocates one small object, and then nothing per entity.
+ * Create a ref bound to `row` of `cols`: one `Object.create` on the shared
+ * prototype and two field writes. Nothing else is allocated for each ref.
+ */
+export declare function createRef<S extends ComponentSchema>(cols: AccessorColumns, row: number): ComponentRef<S>;
+/**
+ * Build a cursor over a component whose fields are `fieldNames`, bound by
+ * `bind`. One small object, and then nothing per entity. `at` is an own data
+ * property defined directly, and not assigned, so that an accessor named `at`
+ * on the shared prototype (a field of some other component) cannot intercept
+ * the write. `cols` is the column array the cursor starts on: a dense cursor
+ * starts on `EMPTY_COLS` and its binder writes the archetype's array on each
+ * `at()`. A sparse cursor starts on its store's array, which never changes
+ * identity, so its binder writes the row alone.
+ */
+export declare function createCursor<S extends ComponentSchema>(fieldNames: readonly string[], bind: CursorBinder, cols?: AccessorColumns): ComponentCursor<S>;
+/** What a mutable sparse cursor stamps on each `at()`: the sparse store's
+ * row ticks, `null` until the component tracks them, and its component-level
+ * change tick. The store object itself, seen through this shape. */
+export interface SparseTickPlane {
+    ticks: Uint32Array | null;
+    changedTick: number;
+}
+/** Where the stamp's value comes from: the store's change tick. */
+export interface ChangeClock {
+    readonly changeTick: number;
+}
+/**
+ * Build a cursor over a sparse component. The columns are id-indexed, so
+ * `at()` is one mask and one field write, and the column array is the store's
+ * own, given at creation and never replaced (the store refills it in place).
+ *
+ * This is a separate function with its own `at` literal, and not
+ * `createCursor` with a different binder, on purpose. A dense cursor's `at`
+ * calls its binder through one call site, and that site inlines the binder as
+ * long as it sees one function. A sparse binder is a different function, so a
+ * world with both kinds of cursor would make that site megamorphic and cost
+ * both kinds a call on every `at()`. Separate literals keep separate sites,
+ * one for each kind. Measured.
+ *
+ * A mutable cursor (`plane` given) also records the entity for the row grain
+ * of change detection, on each `at()`, as the dense cursor does: one load and
+ * one branch while the component keeps no row ticks, two stores once it does.
+ * The read-only cursor keeps the bare literal.
  */
-export declare function createCursor<S extends ComponentSchema>(fieldNames: readonly string[], bind: CursorBinder): ComponentCursor<S>;
-export {};
+export declare function createSparseCursor<S extends ComponentSchema>(fieldNames: readonly string[], cols: AccessorColumns, check: SparseCursorCheck, plane?: SparseTickPlane | null, clock?: ChangeClock | null): ComponentCursor<S>;
 //# sourceMappingURL=ref.d.ts.map

package/dist/core/ecs/ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkCK;AAEL,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG1E,oFAAoF;AACpF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,IAAI;IACrD,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAChC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,IAAI;IAC7D,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAC/B,CAAC;AAMF,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,EAAE,CAAC;CACjD;AAWD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,eAAe,EAClD,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,MAAM,GACT,YAAY,CAAC,CAAC,CAAC,CAwBjB;AA2CD,UAAU,cAAc;IACvB;;qEAEiE;IACjE,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,qEAAqE;AACrE,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,eAAe,IAAI;IACxD,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAChC,GAAG,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,eAAe,IAAI;IAChE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAC/B,GAAG,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IAC1B;;;;;;;;OAQG;IACH,EAAE,CAAC,MAAM,EAAE,OAAO,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAU7E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,eAAe,EACrD,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,EAAE,YAAY,GAChB,eAAe,CAAC,CAAC,CAAC,CA8CpB"}
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/ref.ts"],"names":[],"mappings":"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"}