@vworlds/vecs 1.0.61 → 1.0.62

package/dist/reflection/vecs_struct.js

@@ -0,0 +1,259 @@
+import { assertMemberType, elementType, formatMemberType, isBigIntType, isNumericType, memberTypesEqual, } from "./member_types.js";
+/**
+ * Core component holding a component class's member reflection metadata.
+ *
+ * `world.component(C)` attaches it to the **component entity** of `C` as soon
+ * as `C` or a base class declares a member, through decorators ({@link type},
+ * {@link range}, …) or the fluent {@link Component.member} API. Query it like
+ * any component:
+ *
+ * ```ts
+ * world.component(Position).get(VecsStruct)?.members.x; // { type: "i32", range: [-100, 100] }
+ * ```
+ *
+ * The definition is per class for the whole process: every world attaches the
+ * same frozen instance, so `getMut(VecsStruct, …)` on it throws. Members are
+ * inherited, whichever way the base class declared them, and are listed base
+ * class first, then in declaration order. A declaration that contradicts the
+ * definition throws, naming the class and the member.
+ */
+export class VecsStruct {
+    constructor() {
+        /** Member metadata keyed by member name. */
+        this.members = {};
+    }
+}
+const definitions = new WeakMap();
+/** Base class → definitions of its subclasses that declare members of their own. */
+const descendants = new WeakMap();
+/** Bumped by every change, so composed caches along any class chain stay correct. */
+let version = 0;
+/**
+ * @internal The class and its base classes, base class first.
+ */
+export function _classChain(Class) {
+    const chain = [];
+    for (let current = Class; current !== null && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        chain.push(current);
+    }
+    return chain.reverse();
+}
+/**
+ * @internal The composed members of `Class`, base class first, or `undefined`
+ * when neither it nor a base class declares any. Reads the live definition.
+ */
+export function _structMembers(Class) {
+    const members = composed(Class);
+    return members.size === 0 ? undefined : members;
+}
+/**
+ * @internal The frozen `VecsStruct` instance of `Class`, or `undefined` when it
+ * has no members.
+ */
+export function _structInstance(Class) {
+    if (_structMembers(Class) === undefined) {
+        return undefined;
+    }
+    return (definitions.get(Class) ?? createDefinition(Class)).instance;
+}
+/**
+ * @internal Merge member declarations into the definition of `Class`.
+ *
+ * @returns `true` when the definition changed.
+ * @throws When a declaration contradicts the definition of `Class`, of a base
+ *   class, or of a subclass, or is malformed.
+ */
+export function _declareMembers(Class, declarations) {
+    let changed = false;
+    for (const [name, declaration] of declarations) {
+        const current = composed(Class).get(name);
+        const merged = mergeMember(Class, name, current, declaration);
+        if (merged === current) {
+            continue;
+        }
+        for (const descendant of descendants.get(Class) ?? []) {
+            const own = descendant.own.get(name);
+            if (own !== undefined) {
+                mergeMember(descendant.Class, name, merged, own);
+            }
+        }
+        const definition = definitions.get(Class) ?? createDefinition(Class);
+        if (definition.own.size === 0) {
+            for (const base of _classChain(Class).slice(0, -1)) {
+                let set = descendants.get(base);
+                if (set === undefined) {
+                    set = new Set();
+                    descendants.set(base, set);
+                }
+                set.add(definition);
+            }
+        }
+        definition.own.set(name, merged);
+        version++;
+        changed = true;
+    }
+    return changed;
+}
+function composed(Class) {
+    const definition = definitions.get(Class);
+    if (definition?.cache?.version === version) {
+        return definition.cache.members;
+    }
+    const members = new Map();
+    for (const C of _classChain(Class)) {
+        definitions.get(C)?.own.forEach((member, name) => {
+            const inherited = members.get(name);
+            members.set(name, inherited === undefined ? member : combine(inherited, member));
+        });
+    }
+    if (definition !== undefined) {
+        definition.cache = { version, members, view: freezeMembers(members) };
+    }
+    return members;
+}
+/** Fill a subclass's member with fields a base class declared after it. */
+function combine(inherited, member) {
+    const next = { ...member };
+    next.range ?? (next.range = inherited.range);
+    next.description ?? (next.description = inherited.description);
+    next.unit ?? (next.unit = inherited.unit);
+    next.values ?? (next.values = inherited.values);
+    return membersEqual(next, member) ? member : Object.freeze(next);
+}
+function createDefinition(Class) {
+    const instance = Object.create(VecsStruct.prototype);
+    const definition = { Class, own: new Map(), instance, cache: undefined };
+    definitions.set(Class, definition);
+    // One instance per class: worlds that attached it before a later declaration,
+    // here or on a base class, read the extended definition through it.
+    Object.defineProperty(instance, "members", {
+        enumerable: true,
+        get: () => {
+            composed(Class);
+            return definition.cache.view;
+        },
+    });
+    Object.freeze(instance);
+    return definition;
+}
+function freezeMembers(members) {
+    const view = {};
+    for (const [name, member] of members) {
+        view[name] = member;
+    }
+    return Object.freeze(view);
+}
+function mergeMember(Class, name, existing, declaration) {
+    const where = `VecsStruct ${Class.name || "anonymous class"}.${name}`;
+    const type = declaration.type ?? existing?.type;
+    if (type === undefined) {
+        throw new TypeError(`${where}: member metadata needs a type`);
+    }
+    assertMemberType(type, where);
+    const next = { ...existing, type };
+    if (existing !== undefined && !memberTypesEqual(existing.type, type)) {
+        throw contradiction(where, "type", formatMemberType(type), formatMemberType(existing.type));
+    }
+    if (declaration.range !== undefined) {
+        const range = normalizeRange(where, type, declaration.range);
+        if (existing?.range !== undefined) {
+            if (existing.range[0] !== range[0] || existing.range[1] !== range[1]) {
+                throw contradiction(where, "range", formatRange(range), formatRange(existing.range));
+            }
+        }
+        else {
+            next.range = range;
+        }
+    }
+    for (const field of ["description", "unit"]) {
+        const value = declaration[field];
+        if (value === undefined) {
+            continue;
+        }
+        if (typeof value !== "string") {
+            throw new TypeError(`${where}: ${field} must be a string`);
+        }
+        if (existing?.[field] !== undefined && existing[field] !== value) {
+            throw contradiction(where, field, JSON.stringify(value), JSON.stringify(existing[field]));
+        }
+        next[field] = value;
+    }
+    if (declaration.values !== undefined) {
+        const values = normalizeValues(where, type, declaration.values);
+        if (existing?.values !== undefined) {
+            if (!valuesEqual(existing.values, values)) {
+                throw contradiction(where, "values", formatValues(values), formatValues(existing.values));
+            }
+        }
+        else {
+            next.values = values;
+        }
+    }
+    if (existing !== undefined && membersEqual(existing, next)) {
+        return existing;
+    }
+    return Object.freeze(next);
+}
+function normalizeRange(where, type, range) {
+    const element = elementType(type);
+    if (!isNumericType(element)) {
+        throw new TypeError(`${where}: range needs a numeric type, not ${formatMemberType(type)}`);
+    }
+    if (!Array.isArray(range) || range.length !== 2) {
+        throw new TypeError(`${where}: range must be [min, max]`);
+    }
+    let [min, max] = range;
+    if (isBigIntType(element)) {
+        min = toBigInt(where, min);
+        max = toBigInt(where, max);
+    }
+    else if (typeof min !== "number" || typeof max !== "number" || isNaN(min) || isNaN(max)) {
+        throw new TypeError(`${where}: range bounds of a ${formatMemberType(type)} must be numbers`);
+    }
+    if (min > max) {
+        throw new RangeError(`${where}: range min ${min} is above max ${max}`);
+    }
+    return Object.freeze([min, max]);
+}
+function toBigInt(where, value) {
+    if (typeof value === "bigint") {
+        return value;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new TypeError(`${where}: range bounds of a 64-bit member must be integers`);
+    }
+    return BigInt(value);
+}
+function normalizeValues(where, type, values) {
+    if (elementType(type) !== "enum") {
+        throw new TypeError(`${where}: values needs an enum type, not ${formatMemberType(type)}`);
+    }
+    if (!Array.isArray(values) || !values.every((value) => Number.isInteger(value))) {
+        throw new TypeError(`${where}: enum values must be integers`);
+    }
+    return Object.freeze([...values]);
+}
+function membersEqual(left, right) {
+    return (memberTypesEqual(left.type, right.type) &&
+        left.range?.[0] === right.range?.[0] &&
+        left.range?.[1] === right.range?.[1] &&
+        left.description === right.description &&
+        left.unit === right.unit &&
+        (left.values === right.values ||
+            (left.values !== undefined &&
+                right.values !== undefined &&
+                valuesEqual(left.values, right.values))));
+}
+function valuesEqual(left, right) {
+    return left.length === right.length && left.every((value, i) => value === right[i]);
+}
+function contradiction(where, field, declared, current) {
+    return new Error(`${where}: ${field} ${declared} contradicts the existing ${field} ${current}`);
+}
+function formatRange(range) {
+    return `[${range[0]}, ${range[1]}]`;
+}
+function formatValues(values) {
+    return `[${values.join(", ")}]`;
+}
+//# sourceMappingURL=vecs_struct.js.map

package/dist/reflection/vecs_struct.js.map

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

package/dist/world/world.components.d.ts

@@ -1,5 +1,6 @@
-import { Component, type ComponentClass, type ComponentType } from "../component.js";
+import { Component, type ComponentClass, type ComponentInstance, type ComponentType } from "../component.js";
 import { type EID } from "../entity/index.js";
+import { type ValidationResult } from "../reflection/defaults.js";
 import { Entities } from "./world.entities.js";
 import { type World } from "./world.js";
 export declare class Components extends Entities {
@@ -15,6 +16,14 @@ export declare class Components extends Entities {
      * A newly registered definition inherits the current scope parent immediately.
      * Scopes must be entered outside deferred mode. Existing lookups do not reparent it.
      *
+     * On first registration the class's member decorators ({@link type},
+     * {@link range}, …) are read into its {@link VecsStruct} definition, which
+     * is attached to the component entity when the class declares any member.
+     * Static `vecs_<event>` methods (`vecs_add`, `vecs_set`, `vecs_remove`,
+     * `vecs_targetAdd`, `vecs_targetRemove`, `vecs_validate`, `vecs_normalize`)
+     * are registered as hooks for `<event>`, ahead of hooks added with `.on(…)`.
+     * A class without decorators or statics registers exactly as before.
+     *
      * Pass an explicit numeric `ceid` to pin the component to a server-assigned
      * stable id instead of auto-allocating one.
      *
@@ -61,6 +70,48 @@ export declare class Components extends Entities {
      * @returns The `Component` entity, for chaining.
      */
     set<C extends ComponentClass>(this: World, Class: C, props: Partial<InstanceType<C>>): Component<C>;
+    /**
+     * Check `component` with its class's `validate` hooks.
+     *
+     * Hooks run in registration order and the first failure is returned. When
+     * the class has no explicit hook but declares ranges or integer member
+     * types, a default hook is created on first use: it checks each such member
+     * against its range and its type's bounds (for example `u8` is 0–255), that
+     * integers are whole, and that an `enum` with `values` holds one of them. It
+     * reads the live definition, inherited members included. A class with
+     * neither ranges nor integer types is valid.
+     *
+     * Nothing calls this on `set`; call it where your code accepts external data.
+     *
+     * @param component - An instance of a class registered in this world.
+     * @returns `true`, or the violations: one message or a list of them.
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    validate(this: World, component: ComponentInstance): ValidationResult;
+    /**
+     * Return whether {@link validate} accepts `component`.
+     *
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    isValid(this: World, component: ComponentInstance): boolean;
+    /**
+     * Modify `component` in place with its class's `normalize` hooks, so it
+     * becomes valid.
+     *
+     * Hooks run in registration order, each on the result of the previous one.
+     * When the class has no explicit hook but declares ranges or integer member
+     * types, a default hook is created on first use: it truncates integers and
+     * clamps each such member to its range and its type's bounds. Values of the
+     * wrong JavaScript type and `enum` values outside their `values` are left as
+     * they are; `NaN` becomes `0` first.
+     *
+     * @param component - An instance of a class registered in this world.
+     * @returns `component`, for chaining.
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    normalize<C extends ComponentInstance>(this: World, component: C): C;
     /** Declare a group of mutually exclusive components. */
     setExclusiveComponents(this: World, ...components: ComponentClass[]): void;
+    /** Resolve the meta of a component instance's class for the reflection API. */
+    private _reflectedMeta;
 }

package/dist/world/world.components.js

@@ -1,7 +1,22 @@
-import { Component } from "../component.js";
+import { Component, } from "../component.js";
 import { ComponentDef, Trait } from "../component_def.js";
+import { Relationship, _slotHandlers } from "../component_meta.js";
+import { _defaultNormalize, _defaultValidate, _hasDefaultChecks, } from "../reflection/defaults.js";
+import { _ownDecoratedMembers } from "../reflection/decorators.js";
+import { _attachVecsStruct } from "../reflection/component_members.js";
+import { _classChain, _declareMembers } from "../reflection/vecs_struct.js";
 import { Entities } from "./world.entities.js";
 const RESERVED_EID = 0;
+/** Hook events a class can implement as a static `vecs_<event>` method. */
+const STATIC_HOOK_EVENTS = [
+    "add",
+    "set",
+    "remove",
+    "targetAdd",
+    "targetRemove",
+    "validate",
+    "normalize",
+];
 export class Components extends Entities {
     component(ComponentClassOrName, ceid) {
         if (typeof ComponentClassOrName === "string") {
@@ -41,6 +56,75 @@ export class Components extends Entities {
     set(Class, props) {
         return this.component(Class).set(Class, props);
     }
+    /**
+     * Check `component` with its class's `validate` hooks.
+     *
+     * Hooks run in registration order and the first failure is returned. When
+     * the class has no explicit hook but declares ranges or integer member
+     * types, a default hook is created on first use: it checks each such member
+     * against its range and its type's bounds (for example `u8` is 0–255), that
+     * integers are whole, and that an `enum` with `values` holds one of them. It
+     * reads the live definition, inherited members included. A class with
+     * neither ranges nor integer types is valid.
+     *
+     * Nothing calls this on `set`; call it where your code accepts external data.
+     *
+     * @param component - An instance of a class registered in this world.
+     * @returns `true`, or the violations: one message or a list of them.
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    validate(component) {
+        const meta = this._reflectedMeta(component, "validate");
+        if (meta._onValidate === undefined) {
+            if (!_hasDefaultChecks(meta.Class)) {
+                return true;
+            }
+            meta._onValidate = _defaultValidate(meta.Class);
+            meta._validateIsDefault = true;
+        }
+        for (const hook of _slotHandlers(meta._onValidate)) {
+            const result = hook(component);
+            if (result !== true) {
+                return result;
+            }
+        }
+        return true;
+    }
+    /**
+     * Return whether {@link validate} accepts `component`.
+     *
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    isValid(component) {
+        return this.validate(component) === true;
+    }
+    /**
+     * Modify `component` in place with its class's `normalize` hooks, so it
+     * becomes valid.
+     *
+     * Hooks run in registration order, each on the result of the previous one.
+     * When the class has no explicit hook but declares ranges or integer member
+     * types, a default hook is created on first use: it truncates integers and
+     * clamps each such member to its range and its type's bounds. Values of the
+     * wrong JavaScript type and `enum` values outside their `values` are left as
+     * they are; `NaN` becomes `0` first.
+     *
+     * @param component - An instance of a class registered in this world.
+     * @returns `component`, for chaining.
+     * @throws When `component.constructor` is not registered in this world.
+     */
+    normalize(component) {
+        const meta = this._reflectedMeta(component, "normalize");
+        if (meta._onNormalize === undefined) {
+            if (!_hasDefaultChecks(meta.Class)) {
+                return component;
+            }
+            meta._onNormalize = _defaultNormalize(meta.Class);
+            meta._normalizeIsDefault = true;
+        }
+        meta._onNormalize(component);
+        return component;
+    }
     /** Declare a group of mutually exclusive components. */
     setExclusiveComponents(...components) {
         const componentMetas = components.map((C) => this.entity(C).meta);
@@ -60,6 +144,12 @@ export class Components extends Entities {
             }
             throw new Error(`Component class ${ComponentClass.name} is already registered with eid ${existingComponent.eid}`);
         }
+        // Validate declarations before allocating an id, so a throw leaves no
+        // half-registered class behind.
+        for (const Class of _classChain(ComponentClass)) {
+            _declareMembers(Class, _ownDecoratedMembers(Class));
+        }
+        const staticHooks = staticHooksOf(ComponentClass);
         if (ceid === undefined) {
             ceid = pool.alloc();
         }
@@ -72,12 +162,16 @@ export class Components extends Entities {
         const component = new Constructor(this, ceid, ComponentClass);
         this._entities.set(ceid, component);
         this._classRegistry.set(ComponentClass, component);
+        for (const [event, hook] of staticHooks) {
+            component.meta.on(event, hook);
+        }
         // Publish the class before resolving core metadata: recursive registrations
         // find themselves, so bootstrap needs neither special ids nor a second pass.
         // Both metadata definitions exist before any module can claim their scope.
         this.component(ComponentDef);
         this.component(Trait);
         component.add(ComponentDef);
+        _attachVecsStruct(component);
         const parent = this._scope;
         if (parent !== undefined) {
             component.childOf(parent);
@@ -88,5 +182,34 @@ export class Components extends Entities {
         this._notifyEntityCreated(component);
         return component;
     }
+    /** Resolve the meta of a component instance's class for the reflection API. */
+    _reflectedMeta(component, api) {
+        const Class = component?.constructor;
+        const registered = Class === undefined ? undefined : this._classRegistry.get(Class);
+        if (registered === undefined) {
+            throw new Error(`world.${api}: component class ${Class?.name || "<unknown>"} is not registered in this world`);
+        }
+        return registered.meta;
+    }
+}
+/**
+ * Collect a class's static `vecs_<event>` methods, bound to the class.
+ *
+ * @throws When a class that is not a relationship declares a `target*` static.
+ */
+function staticHooksOf(Class) {
+    const statics = Class;
+    const hooks = [];
+    for (const event of STATIC_HOOK_EVENTS) {
+        const hook = statics[`vecs_${event}`];
+        if (typeof hook !== "function") {
+            continue;
+        }
+        if (event.startsWith("target") && !(Class.prototype instanceof Relationship)) {
+            throw new Error(`"${event}" hooks can only be registered on a Relationship component`);
+        }
+        hooks.push([event, hook.bind(Class)]);
+    }
+    return hooks;
 }
 //# sourceMappingURL=world.components.js.map

package/dist/world/world.components.js.map

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

package/docs/README.md

@@ -30,6 +30,8 @@ Read in this order the first time through:
    - [Modules](./modules.md) — packaging features, composition, scopes and module provenance, built-in modules.
    - [Subtree snapshots](./snapshots.md) — capturing, restoring, and moving an entity forest
      between two worlds.
+   - [Component reflection](./reflection.md) — member types, `VecsStruct`, and the `validate` /
+     `normalize` hooks.
 5. [Design guide](./design-guide.md) — opinionated patterns and anti-patterns distilled from real
    designs. Read it once you know the machinery.
 6. [Utilities](./utilities.md) — helper classes exported by `@vworlds/vecs` but not part of the ECS
@@ -60,6 +62,7 @@ after reading the execution-model and systems guides.
 | [relationships.md](./relationships.md)             | Relationships, target creation, projection and ownership, hierarchy, traversal, and cleanup.                            |
 | [modules.md](./modules.md)                         | `Module<Config>`, `world.module`, `world.scope`, hierarchy provenance, built-in modules.                                |
 | [snapshots.md](./snapshots.md)                     | `snapshotSubtree`, `restoreSubtree`, `moveSubtree`, and `OnSnapshot` capture policies.                                  |
+| [reflection.md](./reflection.md)                   | Member types and metadata, `VecsStruct`, `validate` / `normalize` hooks, `vecs_` static hooks.                          |
 | [design-guide.md](./design-guide.md)               | Patterns, anti-patterns, and a Phaser render-layer case study.                                                          |
 | [diagrams.md](./diagrams.md)                       | Mermaid notation and copyable schema, instance, and systems templates for ECS designs.                                  |
 | [utilities.md](./utilities.md)                     | Public helper classes: `Events`, `ArrayMap`, `IterableArrayMap`, plus `Bitset` cross-ref.                               |

package/docs/components.md

@@ -154,6 +154,12 @@ world
 | `set`    | `entity.set(C, props)` applies ordinary data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` / `ensure` marks it dirty. |
 | `remove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                                                 |
 
+Two more events, `validate` and `normalize`, check or fix a component instance. They run only
+through `world.validate` and `world.normalize`, never on a mutation; see
+[Component reflection](./reflection.md#validating-and-normalizing). A class can also declare any hook
+as a static `vecs_<event>` method, which runs ahead of hooks added with `on`; see
+[`vecs_` statics](./reflection.md#vecs_-statics).
+
 Relationship component entities additionally expose the `targetAdd` and `targetRemove` events. Both
 receive `(source, relationshipInstance, target)` after the edge and reverse index reach their new
 state. An exclusive replacement fires `targetRemove` for the old edge before `targetAdd` for
@@ -450,17 +456,20 @@ interface markers for polymorphic dispatch — is in the
 | `get(Class)`                         | Singleton read: `component(Class).get(Class)`.                                                     |
 | `set(Class, props)`                  | Singleton write: `component(Class).set(Class, props)`.                                             |
 | `setExclusiveComponents(...classes)` | Declare one mutually exclusive group.                                                              |
+| `validate(c)` / `isValid(c)`         | Run the class's `validate` hooks; see [Component reflection](./reflection.md).                     |
+| `normalize(c)`                       | Run the class's `normalize` hooks, modifying `c` in place.                                         |
 
 ### `Component` entity (`lib/vecs/src/component.ts`)
 
 A `Component<T>` is an `Entity` subclass, so the full [entity API](./entities.md#reference)
 applies. On top of it:
 
-| Member                        | Description                                                                                                                                                                                                                                                                                                      |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `on(event, handler, insert?)` | Register a handler for `add` / `remove` / `set` / `targetAdd` / `targetRemove` (plus the internal `policyAdd` / `policyRemove` / `targetPolicyAdd` / `targetPolicyRemove` events). `insert` defaults to `false` (append); `true` prepends. Rejects `target*` events on non-relationships. Returns the component. |
-| `off(event, handler)`         | Remove a previously-registered handler by reference. Idempotent. Returns the component.                                                                                                                                                                                                                          |
-| `meta`                        | The `ComponentMeta` bookkeeping record.                                                                                                                                                                                                                                                                          |
+| Member                        | Description                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `member(name, type)`          | Declare a member for [reflection](./reflection.md) and return the component; `.range` / `.description` / `.unit` / `.values` then apply to it.                                                                                                                                                                                              |
+| `on(event, handler, insert?)` | Register a handler for `add` / `remove` / `set` / `targetAdd` / `targetRemove` / `validate` / `normalize` (plus the internal `policyAdd` / `policyRemove` / `targetPolicyAdd` / `targetPolicyRemove` events). `insert` defaults to `false` (append); `true` prepends. Rejects `target*` events on non-relationships. Returns the component. |
+| `off(event, handler)`         | Remove a previously-registered handler by reference. Idempotent. Returns the component.                                                                                                                                                                                                                                                     |
+| `meta`                        | The `ComponentMeta` bookkeeping record.                                                                                                                                                                                                                                                                                                     |
 
 ### `ComponentMeta` (`lib/vecs/src/component_meta.ts`)
 

package/docs/diagrams.md

@@ -43,6 +43,19 @@ Quote edge labels containing emoji. Only `ChildOf` uses a dotted relationship ed
 (`child -. "1️⃣ChildOf" .-> parent`); every other relationship uses a solid edge
 (`ship -- "1️⃣TowedBy" --> tug`). Do not use dotted edges for other parent-like relationships.
 
+### Member types
+
+When a design depends on what a component holds, list its members under the component in a
+schema box, one indented line each. Use the [reflection member type](./reflection.md#member-types-libvecssrcreflectionmember_typests)
+names and add a range or unit only when it matters to the design:
+
+```mermaid
+flowchart BT
+  ship["<b>Ship</b><br/>📦 Position<br/>&nbsp;&nbsp;x: i32 [-100, 100] m<br/>&nbsp;&nbsp;y: i32 [-100, 100] m<br/>📦 Cargo<br/>&nbsp;&nbsp;items: [u16]<br/>🏷️ Networked"]
+```
+
+Leave members out where the component's name says enough. Tags have no members.
+
 ## Schema template
 
 Use a box for each entity kind: a **bold** name, then one line per component. Relationships live