@oasys/oecs 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,90 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] — 2026-07-06
+
+### Changed (breaking) — one attach grammar
+
+`addComponents` and `template` now take the same callable-bundle varargs as `spawnBundle`
+and `ctx.commands.spawn` / `add`, replacing the `{ def, values }[]` entry-object array — one
+grammar across every authoring surface:
+
+```ts
+// before
+ecs.addComponents(e, [{ def: Pos, values: { x, y } }, { def: Vel, values: { vx } }]);
+const Bullet = ecs.template([{ def: Pos, values: { x: 0, y: 0 } }]);
+// after
+ecs.addComponents(e, Pos({ x, y }), Vel({ vx }));
+const Bullet = ecs.template(Pos({ x: 0, y: 0 }));
+```
+
+To migrate: drop the array brackets, wrap a valued entry in its def's call
+(`{ def: X, values: V }` → `X(V)`), and leave a bare entry bare (`{ def: X }` → `X`).
+
+- Each item is schema-checked against its **own** def via the `StrictBundles` mapped tuple
+  (`{ [K in keyof Items]: … }`) — a misspelled or cross-component field, including a
+  hand-written raw `{ def, values }` literal, is a compile error. `spawnBundle` gains this
+  per-item checking (it previously had none).
+- `ctx.commands.spawn` / `ctx.commands.add` now schema-check their bundle values in
+  declared-access systems as well (the `DeclaredBundleOrDef` type distributes over the
+  declared add set); a permissive / `exclusive` context stays loose, as before.
+- The `TemplateEntry` / `TemplateEntries` public types are removed (they encoded the retired
+  entry-object grammar). The host command seam (`HostCommandQueue.spawn` — the record/replay
+  and editor-undo transport) deliberately keeps its entry-object + complete-values shape.
+
+### Changed — API vocabulary consistency
+
+Cheap alignments from a public-API vocabulary audit that followed the grammar unification:
+
+- `removeComponents(e, ...defs)` is now varargs, mirroring `addComponents` (was
+  `removeComponents(e, defs[])`).
+- `HostCommandQueue.pending()` is now a `pending` getter (matching every other count accessor).
+- `ReadonlyEntityIdArray` → `ReadonlyEntityIDArray` (acronym casing, matching `EntityID`).
+- The entity-id parameter is now uniformly `entityId` across the core surface (ECS lifecycle,
+  host-command queue, `ObserverFn`); the `HostCommand` wire-format field stays `eid`.
+- Source-compatible widenings: `ecs.despawn`, `ecs.removeSystem`, and the `HostCommandQueue`
+  mutators now return `this` for chaining.
+
+The `ref` / `refRead` argument order was reviewed and **deliberately kept** def-first
+(`ctx.ref(def, entityId)`): these are the outside-iteration members of the `cols.mut` /
+`cols.read` column-cursor family, so def-first is the cursor convention, not an inconsistency
+to fix — flipping it would align with `getField` while breaking alignment with `cols.mut`.
+Documented as such (`refs.md`, `queries.md`) rather than flipped.
+
+### Changed (breaking) — host-write-seam verb grammar
+
+The host-write-seam handles are namespaced command buffers, so they drop the component noun
+to match `ctx.commands.add` / `remove` — and their own already-bare
+`spawn`/`despawn`/`disable`/`enable`/`setField`:
+
+- `HostCommandQueue.addComponent` / `removeComponent` → `add` / `remove`.
+- `Editor` and `TransactionBuilder` `.addComponent` / `.removeComponent` → `add` / `remove`
+  (the two surfaces are designed to match, so they move together).
+- The editor extension's entity-id parameters and its `FieldReader` type now read `entityId`,
+  completing the core's `eid` → `entityId` pass.
+
+The wire-format `kind` discriminants (`"add_component"` / `"remove_component"`), the ring
+codecs, and the `HostCommand` record's `eid` field are unchanged — transport vocabulary.
+
+### Changed (breaking) — `ctx.getResource`
+
+The in-system resource getter is now `ctx.getResource(key)` (was the verb-less `ctx.resource(key)`),
+matching its flat-surface siblings `setResource` / `removeResource` / `hasResource` and the
+`getField` / `setField` / `hasComponent` convention. The rule is now explicit: the flat `ctx`
+surface verbs every accessor; the grouped `ecs.resources` facade drops the noun (`get` / `set` /
+`remove` / `has`) because its receiver already names it. `ConditionContext` (run-condition
+predicates) moves in lockstep.
+
+### Fixed
+
+- The immediate host spawn family (`spawn` / `spawnBundle` / `spawnMany`) now throws in DEV
+  when called from inside a system body — redirecting to `ctx.commands.spawn` — like every
+  other immediate host structural mutator. Previously it was silently unguarded (the archetype
+  iteration guard does not cover the append path), a live mid-iteration footgun; its guard
+  docstring's "one rule for every host mutator" claim is now true.
+- Added explicit public `QueryCache` cache-map type annotations so JSR publish passes
+  slow-type validation and can generate package declarations cleanly.
+
 ## [0.5.0] — 2026-07-06
 
 ### Changed (breaking) — lifecycle & naming unification
@@ -27,7 +111,6 @@ rename/removal map:
 | `sourcesOf(def, tgt)` | `sourcesOf(tgt, def)` — matches `targetOf` / `targetsOf` |
 | `query.count()` | `query.entityCount` (getter, beside `archetypeCount`) |
 | `WorldRestoreError` / `WORLD_SNAPSHOT_VERSION` | `ECSRestoreError` / `ECS_SNAPSHOT_VERSION` |
-| `DestroyEntityArg` (type) | `DespawnArg` |
 
 - **Host `despawn` is immediate** — `ecs.despawn(e); ecs.isAlive(e)` is `false` on the next
   line, closing the audit's M1 finding (host `addComponent` immediate but destroy buffered).

package/README.md

@@ -114,13 +114,14 @@ ecs.getField(e, Pos, "x"); // ≈ 1.667
 **Structural changes**
 
 - **Deferred inside systems, immediate on the host** — `ctx.commands` (a Bevy-`Commands`-style
-  facade) buffers spawn / add / remove / despawn / enable / disable until the phase flush, so
-  iterators stay valid. Every host-side mutation (`ecs.addComponent` / `removeComponent` /
+  facade) buffers add / remove / despawn / enable / disable until the phase flush, so iterators
+  stay valid (`commands.spawn` returns the id immediately; its component attaches are deferred). Every host-side mutation (`ecs.addComponent` / `removeComponent` /
   `despawn` / `disable` / `enable`) applies immediately.
 - **Entity enable/disable** — `disable` / `enable` / `isDisabled`; disabled rows sit in a partitioned
   tail and are skipped by default queries.
-- **Templates & bundles** — `ecs.template([...])` blueprints consumed by `spawn` /
-  `spawnMany` for zero-transition spawns; `bundle(...)` + `spawnBundle(...)`.
+- **Templates & bundles** — `ecs.template(Pos({ x, y }), …)` blueprints consumed by `spawn` /
+  `spawnMany` for zero-transition spawns; the same callable-bundle varargs drive `spawnBundle(...)`
+  and `addComponents(...)`.
 
 **Reactivity & relationships**
 
@@ -139,8 +140,8 @@ ecs.getField(e, Pos, "x"); // ≈ 1.667
 
 **Determinism, persistence & integration**
 
-- **Determinism** (opt-in) — `new ECS({ deterministic: true })`, then `ecs.snapshots.stateHash()` (FNV-1a over
-  live dense bytes, sparse stores, and multi-relation target sets), `ecs.snapshots.capture()` /
+- **Determinism** (opt-in) — `new ECS({ deterministic: true })`, then `ecs.snapshots.stateHash()` (an FNV-1a-style
+  32-bit digest over live dense bytes, sparse stores, and multi-relation target sets), `ecs.snapshots.capture()` /
   `ecs.snapshots.restore(...)`, plus sparse variants. Backing-agnostic: a heap world and a shared world with identical history produce
   identical hashes.
 - **Host → ECS write seam** — `installHostCommandSeam(ecs)` applies typed `HostCommand`s off-schedule
@@ -174,13 +175,16 @@ The core is `@oasys/oecs`; everything else is opt-in and costs nothing until imp
 | `@oasys/oecs/editor` | undo/redo + field-handle layer over the host-write seam |
 | `@oasys/oecs/solid` | SolidJS adapter (`solid-js` is an **optional** peer dependency) |
 | `@oasys/oecs/primitives` | the standalone data structures oecs is built on |
+| `@oasys/oecs/internal` | unstable internals (codecs, ABI constants, access checker) — **no semver guarantees** |
 
 ## Dev vs prod
 
 A compile-time `__DEV__` flag gates every runtime check — bounds and liveness checks, duplicate-system
 detection, registration validation, and the system access checker (`reads`/`writes`). These are
 **tree-shaken out of production builds**, so treat "throws in dev" as a development tripwire, not a
-production guarantee. The scheduler's cycle detection is the one check that is always active.
+production guarantee. (Raw-source consumers — JSR/Deno — get `__DEV__ = true` by default; set
+`globalThis.__DEV__ = false` to opt out.) The scheduler's cycle detection and constructor-option
+validation (timestep, memory options, relation cardinality) are always active.
 
 ## Documentation
 

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

@@ -1,7 +1,7 @@
 import { Brand, AnyTypedArray, ColumnBacking, TypedArrayTag, BitSet } from '../../type_primitives/index.cjs';
 import { ColumnStore } from '../store/column_store.cjs';
 import { ComponentID, ComponentDef, ComponentSchema, SchemaOf, DeclaredQueryTerm, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn } from './component.cjs';
-import { EntityID, ReadonlyEntityIdArray } from './entity.cjs';
+import { EntityID, ReadonlyEntityIDArray } from './entity.cjs';
 export type ArchetypeID = Brand<number, "archetype_id">;
 export declare const asArchetypeId: (value: number) => ArchetypeID;
 export interface ArchetypeEdge {
@@ -86,7 +86,7 @@ export interface ArchetypeView<out Defs extends readonly ComponentDef<any>[] = r
     readonly disabledCount: number;
     /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
      * 0..totalCount-1 (enabled rows first, then disabled). */
-    readonly entityIds: ReadonlyEntityIdArray;
+    readonly entityIds: ReadonlyEntityIDArray;
     /** True if this archetype's mask includes the given component. */
     hasComponent(id: ComponentID): boolean;
     /** Get a single field's column (read-only). Valid data: indices
@@ -243,7 +243,7 @@ export declare class Archetype implements ArchetypeView {
     get disabledCount(): number;
     /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
      * 0..totalCount-1 (enabled rows first, then disabled). */
-    get entityIds(): ReadonlyEntityIdArray;
+    get entityIds(): ReadonlyEntityIDArray;
     /**
      * Swap the two rows `a` and `b` — entity ids and every column. Does NOT touch
      * `entityRow`; the caller updates the entity→row map for whichever rows it

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

@@ -1,7 +1,7 @@
 import { Brand, AnyTypedArray, ColumnBacking, TypedArrayTag, BitSet } from '../../type_primitives/index.js';
 import { ColumnStore } from '../store/column_store.js';
 import { ComponentID, ComponentDef, ComponentSchema, SchemaOf, DeclaredQueryTerm, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn } from './component.js';
-import { EntityID, ReadonlyEntityIdArray } from './entity.js';
+import { EntityID, ReadonlyEntityIDArray } from './entity.js';
 export type ArchetypeID = Brand<number, "archetype_id">;
 export declare const asArchetypeId: (value: number) => ArchetypeID;
 export interface ArchetypeEdge {
@@ -86,7 +86,7 @@ export interface ArchetypeView<out Defs extends readonly ComponentDef<any>[] = r
     readonly disabledCount: number;
     /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
      * 0..totalCount-1 (enabled rows first, then disabled). */
-    readonly entityIds: ReadonlyEntityIdArray;
+    readonly entityIds: ReadonlyEntityIDArray;
     /** True if this archetype's mask includes the given component. */
     hasComponent(id: ComponentID): boolean;
     /** Get a single field's column (read-only). Valid data: indices
@@ -243,7 +243,7 @@ export declare class Archetype implements ArchetypeView {
     get disabledCount(): number;
     /** Raw entity ID buffer (packed `EntityID`s). Valid data at indices
      * 0..totalCount-1 (enabled rows first, then disabled). */
-    get entityIds(): ReadonlyEntityIdArray;
+    get entityIds(): ReadonlyEntityIDArray;
     /**
      * Swap the two rows `a` and `b` — entity ids and every column. Does NOT touch
      * `entityRow`; the caller updates the entity→row map for whichever rows it

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

@@ -142,6 +142,31 @@ export interface Bundle<S extends ComponentSchema = ComponentSchema> {
 }
 /** Either a populated bundle or a bare def (tag / all-fields-zero). */
 export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
+/** Re-validate one bundle-or-def item against its OWN def's schema. A bare def
+ * (the callable) passes as-is; a bundle is re-stated as `Bundle<S>` for its
+ * def's `S`, so a hand-written `{ def, values }` literal whose fields don't
+ * match the def is rejected — closing the raw-literal leak that `bundle(Pos,…)`
+ * / `Pos(…)` never had (those validate at their own call site). Per-element
+ * mapper for `StrictBundles`. */
+export type StrictBundle<T> = T extends ComponentDef ? T : T extends {
+    def: ComponentDef<infer S>;
+} ? Bundle<S> : never;
+/** Mapped tuple over a bundle-or-def varargs list — each element re-checked
+ * against its own def's schema. The SolidJS-`on` per-element pattern (pull the
+ * tuple apart, map every element), over callable bundles instead of
+ * `{ def, values }` entry-objects. The one strictness mechanism shared by
+ * `spawnBundle`, `addComponents`, and `template`. */
+export type StrictBundles<Items extends readonly BundleOrDef[]> = {
+    [K in keyof Items]: StrictBundle<Items[K]>;
+};
+/** Recover the def tuple from a bundle-or-def varargs list, so `template(...)`
+ * still returns `Template<[Pos, Vel]>` — the typed key set that `spawn`'s
+ * `overrides` (`TemplateOverrides`) maps over. Also a per-element tuple map. */
+export type DefsOf<Items extends readonly BundleOrDef[]> = {
+    [K in keyof Items]: Items[K] extends {
+        def: infer D extends ComponentDef;
+    } ? D : Items[K] extends ComponentDef ? Items[K] : never;
+};
 /** Pair a component def with field values to attach. Omitted fields zero-fill;
  * a tag def takes no values (see `ValuesArg`). */
 export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, ...values: ValuesArg<S>): Bundle<S>;

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

@@ -142,6 +142,31 @@ export interface Bundle<S extends ComponentSchema = ComponentSchema> {
 }
 /** Either a populated bundle or a bare def (tag / all-fields-zero). */
 export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
+/** Re-validate one bundle-or-def item against its OWN def's schema. A bare def
+ * (the callable) passes as-is; a bundle is re-stated as `Bundle<S>` for its
+ * def's `S`, so a hand-written `{ def, values }` literal whose fields don't
+ * match the def is rejected — closing the raw-literal leak that `bundle(Pos,…)`
+ * / `Pos(…)` never had (those validate at their own call site). Per-element
+ * mapper for `StrictBundles`. */
+export type StrictBundle<T> = T extends ComponentDef ? T : T extends {
+    def: ComponentDef<infer S>;
+} ? Bundle<S> : never;
+/** Mapped tuple over a bundle-or-def varargs list — each element re-checked
+ * against its own def's schema. The SolidJS-`on` per-element pattern (pull the
+ * tuple apart, map every element), over callable bundles instead of
+ * `{ def, values }` entry-objects. The one strictness mechanism shared by
+ * `spawnBundle`, `addComponents`, and `template`. */
+export type StrictBundles<Items extends readonly BundleOrDef[]> = {
+    [K in keyof Items]: StrictBundle<Items[K]>;
+};
+/** Recover the def tuple from a bundle-or-def varargs list, so `template(...)`
+ * still returns `Template<[Pos, Vel]>` — the typed key set that `spawn`'s
+ * `overrides` (`TemplateOverrides`) maps over. Also a per-element tuple map. */
+export type DefsOf<Items extends readonly BundleOrDef[]> = {
+    [K in keyof Items]: Items[K] extends {
+        def: infer D extends ComponentDef;
+    } ? D : Items[K] extends ComponentDef ? Items[K] : never;
+};
 /** Pair a component def with field values to attach. Omitted fields zero-fill;
  * a tag def takes no values (see `ValuesArg`). */
 export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, ...values: ValuesArg<S>): Bundle<S>;

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

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

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

@@ -1,4 +1,4 @@
-import { Template, TemplateEntries, TemplateOverrides } from './store.cjs';
+import { Template, TemplateOverrides } from './store.cjs';
 import { FrameTraceSink } from './frame_trace.cjs';
 import { ObserverHandle, EntitySetObserverConfig, ArchetypeSetObserverConfig, StructuralObserverConfig } from './observer.cjs';
 import { ColumnStore, ColumnStoreRegionHandle, StoreRegionSpec } from '../store/index.cjs';
@@ -8,7 +8,7 @@ import { Archetype, ArchetypeID } from './archetype.cjs';
 import { SystemContext, Query, QueryBuilder, QueryCache, QueryResolver } from './query.cjs';
 import { EntityID } from './entity.cjs';
 import { ReadonlyComponentRef } from './ref.cjs';
-import { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, CompleteFieldValues, Bundle, BundleOrDef } from './component.cjs';
+import { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, CompleteFieldValues, Bundle, BundleOrDef, StrictBundles, DefsOf } from './component.cjs';
 import { SparseComponentDef, SparseComponentID } from './sparse_store.cjs';
 import { RelationDef } from './relation.cjs';
 import { SystemFn, SystemConfig, SystemDescriptor, TypedSystemConfig, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.cjs';
@@ -193,22 +193,40 @@ export declare class ECS implements QueryResolver {
     spawn<Defs extends readonly ComponentDef[]>(template: Template<Defs>, overrides?: TemplateOverrides<Defs>): EntityID;
     /**
      * Spawn an entity from varargs bundles (§bundles) — the immediate
-     * host-side analog of `ctx.commands.spawn`. `ecs.spawnBundle(bundle(Pos,{x,y}),
-     * bundle(Vel,{vx:1}), IsEnemy)` collapses the five attach shapes into one. Each
-     * bundle is applied immediately; a single combined-archetype insertion (one
-     * transition instead of one-per-component) is a later optimization — for the
-     * prototype this mirrors the existing per-component `addComponent` path.
+     * host-side analog of `ctx.commands.spawn`, and the same callable-bundle
+     * grammar as `addComponents` / `template`. `ecs.spawnBundle(Pos({x,y}),
+     * Vel({vx:1}), IsEnemy)` collapses the attach shapes into one; each item is
+     * checked against its own def's schema (`StrictBundles`). Bundles are applied
+     * immediately; a single combined-archetype insertion (one transition instead
+     * of one-per-component) is a later optimization — for now this mirrors the
+     * per-component `addComponent` path (unlike `addComponents`, which batches).
+     *
+     * Immediate — inside a system use the deferred `ctx.commands.spawn(...)`
+     * (calling this from a system body throws in DEV). Note the redirect trades
+     * timing: `commands.spawn` returns the id now but defers the attaches to the
+     * phase flush, so the entity sits in its empty/partial archetype until then —
+     * unlike `spawnBundle`'s immediate, fully-populated archetype.
      */
-    spawnBundle(...items: BundleOrDef[]): EntityID;
+    spawnBundle<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): EntityID;
+    /** Bulk-spawn `count` entities from `template`, optionally applying one
+     * shared `overrides` object to every spawned row (same typed keys as
+     * `spawn`). Field writes are O(columns) (one `TypedArray.fill` per
+     * column), not O(count×columns). Returns the new ids in spawn order.
+     * Immediate — inside a system use `ctx.commands.spawn` per entity (calling
+     * this from a system body throws in DEV). */
+    spawnMany<Defs extends readonly ComponentDef[]>(template: Template<Defs>, count: number, overrides?: TemplateOverrides<Defs>): EntityID[];
     /** DEV-only: throw when an *immediate* host structural mutator is called
      * from inside one of THIS world's system bodies (or an observer / onAdded
      * hook — they run in the same access spans). One rule for every host
-     * mutator, not just despawn: an immediate structural op mid-schedule can
-     * move or swap rows a running query is walking, and it is invisible to
-     * observers. The archetype-level `_iterDepth` guard only catches mutations
-     * touching the archetype currently being iterated — an op landing elsewhere
-     * would silently skip observers, so the receiver rule ("inside a system,
-     * use ctx.commands") is enforced wholesale here.
+     * structural mutator — despawn, add/remove(Components), batchAdd/Remove,
+     * disable/enable, AND the spawn family (spawn/spawnBundle/spawnMany): an
+     * immediate structural op mid-schedule can move or swap rows a running query
+     * is walking — or, for a spawn-append into that archetype, trip a column
+     * realloc under it — and it is invisible to observers. The archetype-level
+     * `_iterDepth` guard only catches mutations touching the archetype currently
+     * being iterated (and the append paths skip even that), so an op landing
+     * elsewhere would silently skip observers; the receiver rule ("inside a
+     * system, use ctx.commands") is enforced wholesale here.
      *
      * `_updating` scopes the guard to THIS world: the accessCheck slot is
      * process-global, so without it a system of world A mutating world B (a
@@ -220,11 +238,11 @@ export declare class ECS implements QueryResolver {
      *  `ctx.commands.despawn` (applied at the phase flush); calling this from
      *  a system body throws in DEV, since an immediate destroy mid-iteration
      *  can invalidate rows the running query is walking. */
-    despawn(id: EntityID): void;
-    /** Disable `id` (idempotent). Excluded from default queries until re-enabled. */
-    disable(id: EntityID): this;
-    /** Re-enable a disabled `id` (idempotent). */
-    enable(id: EntityID): this;
+    despawn(entityId: EntityID): this;
+    /** Disable `entityId` (idempotent). Excluded from default queries until re-enabled. */
+    disable(entityId: EntityID): this;
+    /** Re-enable a disabled `entityId` (idempotent). */
+    enable(entityId: EntityID): this;
     /**
      * Attach a component to an entity, immediately (inside a system, use the
      * deferred `ctx.commands.add`). Three shapes: a bare def attaches a tag; a
@@ -240,13 +258,16 @@ export declare class ECS implements QueryResolver {
     addComponent(entityId: EntityID, def: ComponentDef<Record<string, never>>): this;
     addComponent<S extends ComponentSchema>(entityId: EntityID, bundle: Bundle<S>): this;
     addComponent<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
-    /** Batch-attach several components in one archetype transition. Each
-     * entry's `values` is checked against its own def's schema (a misspelled
-     * field is a compile error; tags refuse `values`) — same typing as
-     * `ECS.template` entries. Omitted fields zero-fill. */
-    addComponents<Defs extends readonly ComponentDef[]>(entityId: EntityID, entries: TemplateEntries<Defs>): this;
+    /** Batch-attach several components in one archetype transition. Takes the
+     * same callable-bundle varargs as `spawnBundle` — `world.addComponents(e,
+     * Pos({ x, y }), Vel({ vx }), Frozen)` — each item checked against its own
+     * def's schema (a misspelled or cross-component field is a compile error;
+     * tags refuse values). Omitted fields zero-fill. */
+    addComponents<Items extends readonly BundleOrDef[]>(entityId: EntityID, ...items: StrictBundles<Items>): this;
     removeComponent(entityId: EntityID, def: ComponentDef): this;
-    removeComponents(entityId: EntityID, defs: ComponentDef[]): this;
+    /** Detach several components in one archetype transition — the varargs
+     * mirror of `addComponents` (bare defs; removing needs no values). */
+    removeComponents(entityId: EntityID, ...defs: ComponentDef[]): this;
     /**
      * Bulk add a component to ALL entities in the given archetype.
      * O(columns) via TypedArray.set() instead of O(N×columns).
@@ -351,7 +372,7 @@ export declare class ECS implements QueryResolver {
      * access record. Escape hatch: annotate `fn(ctx: SystemContext, dt)`
      * explicitly to keep a system permissive at compile time. */
     registerSystem<R extends DenseAccessDecl, W extends DenseAccessDecl, Sp extends SpawnsAccessDecl = readonly never[], De extends DespawnsAccessDecl = readonly never[], Tr extends TransitionsAccessDecl = readonly never[], SR extends SparseAccessDecl = readonly never[], SW extends SparseAccessDecl = readonly never[], RR extends RelationsAccessDecl = readonly never[], RW extends RelationsAccessDecl = readonly never[], QR extends ResourcesAccessDecl = readonly never[], QW extends ResourcesAccessDecl = readonly never[]>(config: TypedSystemConfig<R, W, Sp, De, Tr, SR, SW, RR, RW, QR, QW>): SystemDescriptor;
-    removeSystem(system: SystemDescriptor): void;
+    removeSystem(system: SystemDescriptor): this;
     get systemCount(): number;
     /**
      * Run the startup phases, once, before the first `update()`. Prewarms
@@ -393,6 +414,23 @@ export declare class ECS implements QueryResolver {
      */
     update(dt: number): void;
     dispose(): void;
+    /** Register an archetype template (#462). Resolves the component set +
+     * default field values to a target archetype once (creating it if absent —
+     * fits the prewarm model), so later `spawn` / `spawnMany` calls land
+     * entities directly in that archetype with **zero archetype transitions**.
+     *
+     *   const Bullet = ecs.template(Position({ x: 0, y: 0 }), Velocity({ vx: 0, vy: 0 }));
+     *
+     * Takes the same callable-bundle varargs as `spawnBundle` / `addComponents`
+     * (each item schema-checked against its own def); the resulting
+     * `Template<[Position, Velocity]>` keeps the typed key set that `spawn`'s
+     * `overrides` map over. Not a pass-through — it normalizes bundles to the
+     * store's entry shape, so it lives here with the other real logic, not in the
+     * delegation band. The big win is multi-component entities and bulk spawns; a
+     * single-component spawn is no faster than `spawn` + `addComponent`, which
+     * already bump-allocates a fresh entity into the target archetype. See
+     * ADR-0010. */
+    template<Items extends readonly BundleOrDef[]>(...items: StrictBundles<Items>): Template<DefsOf<Items>>;
     /** Resolve a consumer-declared SAB region's byte offset by `region_id`, or
      * 0 when absent. Generic, de-gamed replacement (#623) for the removed
      * game-named accessors; pair with the consumer's own region module to
@@ -430,32 +468,12 @@ export declare class ECS implements QueryResolver {
     registerTag(): ComponentDef<Record<string, never>>;
     /** Register a sparse tag (empty schema) — membership only, no data. */
     registerSparseTag(): SparseComponentDef<Record<string, never>>;
-    /** Register an archetype template (#462). Resolves the component set +
-     * default field values to a target archetype once (creating it if absent —
-     * fits the prewarm model), so later `spawn` / `spawnMany` calls land
-     * entities directly in that archetype with **zero archetype transitions**.
-     *
-     *   const Bullet = ecs.template([
-     *     { def: Position, values: { x: 0, y: 0 } },
-     *     { def: Velocity, values: { vx: 0, vy: 0 } },
-     *   ]);
-     *
-     * The big win is multi-component entities and bulk spawns; a single-
-     * component spawn is no faster than `spawn` + `addComponent`, which
-     * already bump-allocates a fresh entity into the target archetype. See
-     * ADR-0010. */
-    template<Defs extends readonly ComponentDef[]>(entries: TemplateEntries<Defs>): Template<Defs>;
-    /** Bulk-spawn `count` entities from `template`, optionally applying one
-     * shared `overrides` object to every spawned row (same typed keys as
-     * `spawn`). Field writes are O(columns) (one `TypedArray.fill` per
-     * column), not O(count×columns). Returns the new ids in spawn order. */
-    spawnMany<Defs extends readonly ComponentDef[]>(template: Template<Defs>, count: number, overrides?: TemplateOverrides<Defs>): EntityID[];
-    isAlive(id: EntityID): boolean;
+    isAlive(entityId: EntityID): boolean;
     get entityCount(): number;
     hasComponent(entityId: EntityID, def: ComponentDef): boolean;
-    /** Whether `id` is currently disabled. Toggle via `disable` / `enable`
+    /** Whether `entityId` is currently disabled. Toggle via `disable` / `enable`
      * (immediate, above the band — they carry the in-system dev guard). */
-    isDisabled(id: EntityID): boolean;
+    isDisabled(entityId: EntityID): boolean;
     addSparse(entityId: EntityID, def: SparseComponentDef<Record<string, never>>): this;
     addSparse<S extends ComponentSchema>(entityId: EntityID, def: SparseComponentDef<S>, values: CompleteFieldValues<S>): this;
     removeSparse(entityId: EntityID, def: SparseComponentDef): this;