@vworlds/vecs 1.0.45 → 1.0.47

package/README.md

@@ -66,13 +66,19 @@ The full documentation lives in [`docs/`](./docs/README.md). Recommended reading
 3. [Execution model](./docs/execution-model.md) — phases, deferred mutation, event routing.
 4. Subsystem guides: [Components and traits](./docs/components.md) · [Entities](./docs/entities.md) ·
    [Systems](./docs/systems.md) · [Queries and filters](./docs/queries-and-filters.md) ·
-   [Relationships, targets, and ownership](./docs/relationships.md) · [Modules](./docs/modules.md)
+   [Relationships, edges, targets, and ownership](./docs/relationships.md) · [Modules](./docs/modules.md) ·
+   [Subtree snapshots](./docs/snapshots.md)
 5. [Design guide](./docs/design-guide.md) — patterns and anti-patterns from real designs.
 
 Plus the [Utilities](./docs/utilities.md) guide for helper classes and the
 [Glossary](./docs/glossary.md) for terminology. The exhaustive per-symbol reference is the JSDoc on
 the source under [`src/`](./src/) — read it in your IDE.
 
+Networking is documented alongside the packages that own it:
+[Remote procedure calls](../vecs-protocol/docs/rpc.md) ·
+[Sessions and caller context](../vecs-server/docs/sessions.md) ·
+[Client world](../vecs-client/docs/client-world.md).
+
 ## Build & Test
 
 ```sh

package/dist/component.d.ts

@@ -1,75 +1,72 @@
 import { Entity } from "./entity/index.js";
-import type { ComponentType, HookHandler } from "./component_meta.js";
-export { CleanupPolicy, ComponentMeta, Implements, Relationship, type ComponentClass, type ComponentInstance, type ComponentRef, type ComponentRefArray, type ComponentType, type Hook, type HookHandler, type RetargetHandler, } from "./component_meta.js";
-/** A component entity created by {@link World.component}. */
+import { Relationship, type ComponentInstance, type ComponentType, type HookEvent, type HookHandler, type TargetHandler } from "./component_meta.js";
+import { type SnapshotCapture, type SnapshotMaterialize, ClonePublic, CustomSnapshot, DontSnapshot } from "./modules/snapshot_types.js";
+export { CleanupPolicy, ComponentMeta, Implements, Relationship, type ComponentClass, type ComponentInstance, type ComponentRef, type ComponentRefArray, type ComponentType, type HookEvent, type HookEventMap, type HookHandler, type TargetHandler, } from "./component_meta.js";
+/**
+ * A per-component event map that narrows `add` / `remove` / `set` handlers to
+ * the instance type `T` produces, and narrows `targetAdd` / `targetRemove` /
+ * `targetPolicyAdd` / `targetPolicyRemove` handlers to `T`'s relationship
+ * instance type when `T` produces a relationship.
+ */
+type ComponentEventMap<T extends ComponentType> = {
+    add: HookHandler<InstanceType<T>>;
+    remove: HookHandler<InstanceType<T>>;
+    set: HookHandler<InstanceType<T>>;
+    targetAdd: TargetHandler<InstanceType<T> & Relationship>;
+    targetRemove: TargetHandler<InstanceType<T> & Relationship>;
+    targetPolicyAdd: TargetHandler<InstanceType<T> & Relationship>;
+    targetPolicyRemove: TargetHandler<InstanceType<T> & Relationship>;
+    policyAdd: HookHandler;
+    policyRemove: HookHandler;
+};
+/** Callbacks declared alongside the {@link CustomSnapshot} policy value. */
+export interface CustomSnapshotOptions<T extends ComponentInstance = ComponentInstance> {
+    /** Convert a live component instance into detached, world-agnostic data. */
+    capture: SnapshotCapture;
+    /** Construct a fresh, destination-owned instance from previously captured data. */
+    materialize: SnapshotMaterialize;
+}
+/**
+ * A component entity created by {@link World.component}.
+ */
 export declare class Component<T extends ComponentType = ComponentType> extends Entity {
     /**
-     * Get or set the callback fired each time this component is **added** to an entity.
-     *
-     * The handler is called with the owning entity and the freshly created
-     * component instance. Use it to initialise external state (e.g. scene objects)
-     * that should exist for the lifetime of the component.
-     *
-     * Call without an argument to return the current handler. Pass `undefined` to remove it.
-     *
-     * @param handler - Callback invoked with `(entity, componentInstance)`, or `undefined`.
-     * @returns The current handler when called without an argument; otherwise this component.
-     *
-     * @example
-     * ```ts
-     * world.component(Sprite).onAdd((entity, sprite) => sprite.initialize(scene));
-     * ```
+     * Register a handler for a hook event, with the handler signature narrowed
+     * to this component's instance type (for `add` / `remove` / `set`) or its
+     * relationship instance type (for the `target*` events). See
+     * {@link ComponentMeta.on} for full semantics.
      */
-    onAdd(): HookHandler | undefined;
-    onAdd(handler: HookHandler<InstanceType<T>> | undefined): this;
-    onAdd(handler: HookHandler | undefined): this;
+    on<E extends HookEvent>(event: E, handler: ComponentEventMap<T>[E], insert?: boolean): this;
+    /** Remove a previously-registered handler by reference. See {@link ComponentMeta.off}. */
+    off<E extends HookEvent>(event: E, handler: ComponentEventMap<T>[E]): this;
     /**
-     * Get or set the callback fired each time this component is **removed** from an
-     * entity, or when the owning entity is destroyed.
-     *
-     * The handler is called with the owning entity and the component instance that
-     * is about to be detached. Use it to clean up any external state associated
-     * with the component.
+     * Declare how cross-world subtree snapshots capture this component type.
      *
-     * Call without an argument to return the current handler. Pass `undefined` to remove it.
+     * Callable at any time. The declaration affects future captures only:
+     * snapshots already captured retain the materializer their policy resolved to
+     * at capture time, so changing or revoking this policy cannot alter how they
+     * restore.
      *
-     * @param handler - Callback invoked with `(entity, componentInstance)`, or `undefined`.
-     * @returns The current handler when called without an argument; otherwise this component.
+     * `ClonePublic` — the default — captures a fresh instance with the source's
+     * own enumerable fields cloned. `DontSnapshot` never captures the type.
      *
-     * @example
-     * ```ts
-     * world.component(Sprite).onRemove((entity, sprite) => sprite.destroy(scene));
-     * ```
+     * @param policy - `ClonePublic` or `DontSnapshot`.
+     * @returns This component entity, for chaining.
      */
-    onRemove(): HookHandler | undefined;
-    onRemove(handler: HookHandler<InstanceType<T>> | undefined): this;
-    onRemove(handler: HookHandler | undefined): this;
+    snapshotPolicy(policy: typeof ClonePublic | typeof DontSnapshot): this;
     /**
-     * Get or set the callback fired each time this component's data is **set or
-     * modified**.
-     *
-     * Fires when:
-     * - `entity.set(C, props)` applies data to the component.
-     * - `entity.attach(instance)` stores an existing instance.
-     * - `entity.modified(C)` is called after in-place mutation.
-     * - A system's `getMut(C)` marks the component dirty.
-     * - `entity.ensure(C)` creates or marks the component dirty.
-     *
-     * The handler receives the owning entity and the current component instance.
-     * Component instances do not carry entity references, which is why the entity
-     * is passed explicitly.
+     * Declare a bespoke capture/materialize policy for this component type.
      *
-     * Call without an argument to return the current handler. Pass `undefined` to remove it.
+     * Use it when a component mixes declarative state with runtime state that must
+     * not cross worlds — a physics handle, a socket, a compiled shader.
      *
-     * @param handler - Callback invoked with `(entity, componentInstance)`, or `undefined`.
-     * @returns The current handler when called without an argument; otherwise this component.
+     * Callable at any time. It affects future captures only; existing snapshots
+     * restore through the materializer bound when they were captured.
      *
-     * @example
-     * ```ts
-     * world.component(Transform).onSet((entity, t) => renderer.syncTransform(entity.eid, t));
-     * ```
+     * @param CustomSnapshot - Selects the owner-supplied policy.
+     * @param options - The `capture` and `materialize` callbacks, stored on this
+     *   entity's own `OnSnapshot` edge so each component type keeps its policy.
+     * @returns This component entity, for chaining.
      */
-    onSet(): HookHandler | undefined;
-    onSet(handler: HookHandler<InstanceType<T>> | undefined): this;
-    onSet(handler: HookHandler | undefined): this;
+    snapshotPolicy(policy: typeof CustomSnapshot, options: CustomSnapshotOptions<InstanceType<T>>): this;
 }

package/dist/component.js

@@ -1,26 +1,33 @@
 import { Entity } from "./entity/index.js";
+import { CustomSnapshot, _declareSnapshotPolicy, } from "./modules/snapshot_types.js";
 export { CleanupPolicy, ComponentMeta, Implements, Relationship, } from "./component_meta.js";
-/** A component entity created by {@link World.component}. */
+/**
+ * A component entity created by {@link World.component}.
+ */
 export class Component extends Entity {
-    onAdd(handler) {
-        if (arguments.length === 0) {
-            return super.onAdd();
-        }
-        super.onAdd(handler);
-        return this;
+    /**
+     * Register a handler for a hook event, with the handler signature narrowed
+     * to this component's instance type (for `add` / `remove` / `set`) or its
+     * relationship instance type (for the `target*` events). See
+     * {@link ComponentMeta.on} for full semantics.
+     */
+    on(event, handler, insert = false) {
+        return super.on(event, handler, insert);
     }
-    onRemove(handler) {
-        if (arguments.length === 0) {
-            return super.onRemove();
-        }
-        super.onRemove(handler);
-        return this;
+    /** Remove a previously-registered handler by reference. See {@link ComponentMeta.off}. */
+    off(event, handler) {
+        return super.off(event, handler);
     }
-    onSet(handler) {
-        if (arguments.length === 0) {
-            return super.onSet();
+    snapshotPolicy(policy, options) {
+        if (policy === CustomSnapshot) {
+            if (options?.capture === undefined || options.materialize === undefined) {
+                throw new Error(`snapshotPolicy(CustomSnapshot) requires both capture and materialize callbacks for ${this.meta.Class.name}`);
+            }
+            _declareSnapshotPolicy(this, policy, options.capture, options.materialize);
+        }
+        else {
+            _declareSnapshotPolicy(this, policy);
         }
-        super.onSet(handler);
         return this;
     }
 }

package/dist/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,6DAA6D;AAC7D,MAAM,OAAO,SAAmD,SAAQ,MAAM;IAqB5D,KAAK,CAAC,OAAa;QACjC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAuBe,QAAQ,CAAC,OAAa;QACpC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IA8Be,KAAK,CAAC,OAAa;QACjC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAU3C,OAAO,EAKL,cAAc,EAEd,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,GAUb,MAAM,qBAAqB,CAAC;AA4B7B;;GAEG;AACH,MAAM,OAAO,SAAmD,SAAQ,MAAM;IAC5E;;;;;OAKG;IACa,EAAE,CAChB,KAAQ,EACR,OAAgC,EAChC,MAAM,GAAG,KAAK;QAEd,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAA0B,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAED,0FAA0F;IAC1E,GAAG,CAAsB,KAAQ,EAAE,OAAgC;QACjF,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAA0B,CAAC,CAAC;IACtD,CAAC;IAmCM,cAAc,CACnB,MAA0B,EAC1B,OAAgD;QAEhD,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;YAC9B,IAAI,OAAO,EAAE,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;gBACxE,MAAM,IAAI,KAAK,CACb,sFAAsF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAC7G,CAAC;YACJ,CAAC;YACD,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAC7E,CAAC;aAAM,CAAC;YACN,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/component_meta.d.ts

@@ -7,14 +7,36 @@ export declare enum CleanupPolicy {
 }
 /** Base class for relationship components that point at another entity. */
 export declare abstract class Relationship {
-    target: Entity;
+    private _targets;
 }
-/** Callback fired after a relationship moves from one existing target to another. */
-export type RetargetHandler = (source: Entity, oldTarget: Entity, newTarget: Entity) => void;
+/** Callback fired after one relationship edge is added or removed. */
+export type TargetHandler<C extends Relationship = Relationship> = (source: Entity, relationship: C, target: Entity) => void;
 /** Callback fired for a component lifecycle event. */
 export type HookHandler<C extends ComponentInstance = ComponentInstance> = (entity: Entity, component: C) => void;
 /** A component instance. Components are plain objects created with a no-arg constructor. */
 export type ComponentInstance = object;
+/**
+ * Event → handler signature map for the unified `on` / `off` hook API.
+ *
+ * Each key is a hook event name; its value is the handler signature accepted
+ * by {@link ComponentMeta.on} and {@link ComponentMeta.off} for that event.
+ * The `target*` events require a relationship meta; registering one on a
+ * non-relationship meta throws at registration time.
+ */
+export interface HookEventMap {
+    /** Fired when a component of this type is first attached to an entity. */
+    add: HookHandler;
+    /** Fired when a component of this type is removed from an entity. */
+    remove: HookHandler;
+    /** Fired when a component's data is set or modified. */
+    set: HookHandler;
+    /** Fired after a relationship edge is added. Relationship metas only. */
+    targetAdd: TargetHandler;
+    /** Fired after a relationship edge is removed. Relationship metas only. */
+    targetRemove: TargetHandler;
+}
+/** Event names accepted by {@link ComponentMeta.on} / {@link ComponentMeta.off}. */
+export type HookEvent = keyof HookEventMap;
 /** A component constructor used as a component key. */
 export type ComponentType<T extends ComponentInstance = ComponentInstance> = abstract new (...args: any[]) => T;
 /** A component class constructor that can be instantiated by entity.add/set. */
@@ -26,76 +48,33 @@ export declare class Implements {
     interfaces: ComponentType[];
 }
 /**
- * Lifecycle hook for a registered component class. Exposed by
- * {@link World.component}.
+ * Lifecycle hook registration for a registered component class. Exposed by
+ * {@link World.component} and on every entity.
  *
  * Hooks are a lightweight alternative to building a {@link System} when all
  * you need is a callback on add / remove / set for a single component type.
- * Component entities expose the same registration methods, so calls chain:
+ * Registration chains because `on` / `off` return the receiver:
  *
  * ```ts
  * world.component(Sprite)
- *   .onAdd((e, c) => initSprite(e, c))
- *   .onRemove((e, c) => destroySprite(e, c))
- *   .onSet((e, c) => syncSprite(e, c));
+ *   .on("add", (e, c) => initSprite(e, c))
+ *   .on("remove", (e, c) => destroySprite(e, c))
+ *   .on("set", (e, c) => syncSprite(e, c));
  * ```
  *
+ * Multiple handlers may be registered for the same event: they fire in
+ * registration order (or in reverse registration order when `insert` is `true`).
+ * Remove a handler with {@link ComponentMeta.off} by the same reference used
+ * to register it. Callers rarely need to remove handlers.
+ *
  * Callbacks fire synchronously when the corresponding entity command is
  * applied: inline outside deferred mode, or while the world drains its command
- * queue inside a system / `forEach` / `defer` block.
- *
- * @typeParam C - Component class this hook is bound to.
+ * queue inside a system / `forEach` / `defer` block. An invariant violation
+ * thrown from a handler propagates out of the applying call (or out of
+ * `progress()` / `flush()` in deferred mode) and leaves the world partially
+ * mutated — treat it as a programming error and discard the world.
  */
-export interface Hook<C extends ComponentInstance = ComponentInstance> {
-    /** Return the current add handler, or `undefined` when none is set. */
-    onAdd(): HookHandler<C> | undefined;
-    /**
-     * Set the handler invoked when a component of this type is first attached to
-     * an entity (`entity.add(C)` or `entity.set(C, ...)` on an entity that does
-     * not yet have the component). Pass `undefined` to remove the current handler.
-     *
-     * @param handler - Receives the entity and freshly created component instance.
-     * @returns This hook, for chaining.
-     */
-    onAdd(handler: HookHandler<C> | undefined): Hook<C>;
-    /** Return the current remove handler, or `undefined` when none is set. */
-    onRemove(): HookHandler<C> | undefined;
-    /**
-     * Set the handler invoked when a component of this type is removed from an
-     * entity (explicit `entity.remove(C)` or implicit removal during
-     * `entity.destroy()`). Pass `undefined` to remove the current handler.
-     *
-     * @param handler - Receives the entity and component instance that was removed.
-     * @returns This hook, for chaining.
-     */
-    onRemove(handler: HookHandler<C> | undefined): Hook<C>;
-    /** Return the current set handler, or `undefined` when none is set. */
-    onSet(): HookHandler<C> | undefined;
-    /**
-     * Set the handler invoked when a component's data is set or modified. Pass
-     * `undefined` to remove the current handler.
-     *
-     * Fires when:
-     * - `entity.set(C, props)` applies data to the component.
-     * - `entity.attach(instance)` stores an existing instance.
-     * - `entity.modified(C)` is called after in-place mutation.
-     * - A system's `getMut(C)` marks the component dirty.
-     * - `entity.ensure(C)` creates or marks the component dirty.
-     *
-     * @param handler - Receives the entity and component instance whose data changed.
-     * @returns This hook, for chaining.
-     */
-    onSet(handler: HookHandler<C> | undefined): Hook<C>;
-}
-/**
- * Bookkeeping record produced for each component eid.
- *
- * Holds the constructor, component eid, and pre-computed
- * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
- * lifecycle handlers attached via `world.component(C)` are stored directly on
- * the meta object.
- */
-export declare class ComponentMeta implements Hook<ComponentInstance> {
+export declare class ComponentMeta {
     /** The component class constructor this meta represents. */
     readonly Class: ComponentType;
     /** Component entity id assigned at registration time. */
@@ -104,33 +83,42 @@ export declare class ComponentMeta implements Hook<ComponentInstance> {
     readonly bitPtr: BitPtr;
     /** Whether this component is a relationship pointing at another entity. */
     readonly isRelationship: boolean;
+    /** Whether this relationship permits only one target. */
+    relationshipExclusive: boolean;
     /** Applied to entities carrying this component when this component entity is deleted. */
     onDelete: CleanupPolicy;
     /** Applied to entities targeting a deleted entity through this relationship. */
     onDeleteTarget: CleanupPolicy;
-    private _usageCount;
     constructor(Class: ComponentType, ceid: EID);
     /** Number of entities currently carrying this component eid. */
     get usageCount(): number;
-    /** @inheritdoc */
-    onAdd(): HookHandler | undefined;
-    onAdd(handler: HookHandler | undefined): ComponentMeta;
-    /** @inheritdoc */
-    onRemove(): HookHandler | undefined;
-    onRemove(handler: HookHandler | undefined): ComponentMeta;
     /**
-     * Return the current retarget handler, or `undefined` when none is set.
+     * Register a handler for a hook event.
+     *
+     * Multiple handlers may be registered for the same event; they fire in
+     * registration order. Pass `insert: true` to prepend the handler ahead of
+     * any already-registered handlers. Removing a handler is via {@link off} with
+     * the same reference.
+     *
+     * The `targetAdd`, `targetRemove`, `targetPolicyAdd`, and `targetPolicyRemove`
+     * events require this meta to be a relationship; registering one on a
+     * non-relationship meta throws at registration time.
+     *
+     * @param event - One of `add`, `remove`, `set`, `targetAdd`, `targetRemove`,
+     *   `policyAdd`, `policyRemove`, `targetPolicyAdd`, `targetPolicyRemove`.
+     * @param handler - Handler whose signature is constrained by `event`.
+     * @param insert - When `true`, prepend the handler; when `false` (default), append.
+     * @returns This meta, for chaining.
      */
-    onRetarget(): RetargetHandler | undefined;
+    on<E extends HookEvent>(event: E, handler: HookEventMap[E], insert?: boolean): this;
     /**
-     * Set the handler fired after this relationship changes between two existing targets. Pass
-     * `undefined` to remove the current handler.
+     * Remove a previously-registered handler by reference. Idempotent: removing
+     * an unregistered handler is a no-op.
      *
-     * @param handler - Receives the source entity, previous target, and current target.
-     * @returns This metadata object, for chaining.
+     * @param event - The event the handler was registered for.
+     * @param handler - The exact handler reference passed to {@link on}.
+     * @returns This meta, for chaining.
      */
-    onRetarget(handler: RetargetHandler | undefined): ComponentMeta;
-    /** @inheritdoc */
-    onSet(): HookHandler | undefined;
-    onSet(handler: HookHandler | undefined): ComponentMeta;
+    off<E extends HookEvent>(event: E, handler: HookEventMap[E]): this;
+    private _requireRelationship;
 }