@carbonenginejs/runtime-utils 0.1.3 → 0.1.5

package/docs/concepts/model-lifecycle.md

@@ -44,6 +44,49 @@ the ordinary settled event. Callers that need changed names use the
 may emit an immediate payload containing `properties`; that is not the normal
 settled-event shape.
 
+## Schema-backed child collections
+
+Domain containers expose named methods such as `CreateAttachment`,
+`AddAttachment`, `RemoveAttachment`, and `DeleteAttachment`. Those methods may
+delegate to the programmatic static helpers `CjsModel.createChild(owner, ...)`,
+`addChild`, `removeChild`, `deleteChild`, and `clearChildren`. Model instances do
+not inherit generic property-string child methods; the named methods explicitly
+defined by their domain class are their child-mutation API.
+
+The helpers accept only schema `array` and `list` fields backed by ordinary
+JavaScript arrays. They do not operate on typed arrays, maps, sets, or
+undeclared properties. `createChild` hydrates one value using the collection's
+declared item type before adding it.
+
+A collection mutation follows the same state rules as `SetValues`:
+
+- it marks the parent dirty unless `markDirty: false`;
+- it adds that collection field's declared `@io.flag(...)` and
+  `@io.rebuild(...)` tokens unless `notify: false`;
+- it settles the parent unless `skipUpdate: true`; and
+- it suppresses child and modified events when `skipEvents: true`.
+
+When the parent implements Carbon-shaped `OnListModified`, insertion and
+removal callbacks receive the mutated list. Clearing sends unload-start while
+the list is still populated, then empties it. Generic `childadded`,
+`childremoved`, `childdeleted`, and `childrencleared` events carry the property
+and affected child or count; named wrappers may also supply `onAdded`,
+`onRemoved`, `onDeleted`, or `onCleared` callbacks.
+
+Remove only detaches. Delete also emits the deletion event and may run an
+explicit domain-owned `delete` callback; it never guesses a generic `Destroy`
+operation. JavaScript lifetime management remains ordinary garbage collection
+when no teardown callback is supplied.
+
+Child-owned flags and rebuild tokens are deliberately not interpreted by these
+helpers. A child property may declare a token such as a deferred deletion
+request, but the current runtime context decides whether and when to consume
+it and which named parent method to call. That context must retain the exact
+relationship it owns: the same child may be reached through multiple parents,
+properties, or nested contexts, and graph traversal does not make those
+contexts interchangeable. No global deletion queue or child-management
+decorator is implied.
+
 ## Initialization
 
 `CjsModel.from()` constructs or imports the graph, resolves references, then

package/docs/core-types/README.md

@@ -187,6 +187,18 @@ They return the same changed-set, boolean, or `false` result as `SetValues`.
 `Copy`/`copy` instead require an instantiated
 `CjsModel` source and forward the supplied `SetValues` options.
 
+Schema-backed containers expose domain-named child methods and delegate their
+ordinary `array` or `list` mutations to the programmatic static
+`CjsModel.createChild(owner, ...)`, `addChild`, `removeChild`, `deleteChild`, and
+`clearChildren` helpers. Instances expose only child methods explicitly defined
+by their domain class. The static helpers hydrate declared item types, preserve
+Carbon `OnListModified` notifications, and apply the collection field's normal
+flag/rebuild tokens. They do not manage typed arrays or interpret tokens owned
+by a child; the active domain context remains responsible for consuming child
+work requests.
+See [Model lifecycle](../concepts/model-lifecycle.md#schema-backed-child-collections)
+for removal, deletion, event, and nested-context rules.
+
 ### Enum-backed fields
 
 Enum metadata resolves lazily from the concrete model constructor's PascalCase

package/package.json

@@ -1,139 +1,139 @@
-{
-  "name": "@carbonenginejs/runtime-utils",
-  "version": "0.1.3",
-  "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
-  "type": "module",
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js",
-    "./arrays": "./src/arrays.js",
-    "./bytes": "./src/bytes.js",
-    "./compression": "./src/compression.js",
-    "./const": "./src/constants/index.js",
-    "./const/trinity": "./src/constants/trinity.js",
-    "./const/media": "./src/media/index.js",
-    "./const/graphics": "./src/graphics/index.js",
-    "./const/render-context": "./src/renderContext/index.js",
-    "./const/audio": "./src/audio/index.js",
-    "./const/shader": "./src/shader/index.js",
-    "./const/d3d": "./src/d3d/index.js",
-    "./const/webgpu": "./src/webgpu/index.js",
-    "./media": "./src/media/index.js",
-    "./graphics": "./src/graphics/index.js",
-    "./render-context": "./src/renderContext/index.js",
-    "./audio": "./src/audio/index.js",
-    "./shader": "./src/shader/index.js",
-    "./d3d": "./src/d3d/index.js",
-    "./webgpu": "./src/webgpu/index.js",
-    "./document": "./src/document/index.js",
-    "./errors": "./src/errors/index.js",
-    "./hydration": "./src/document/hydrationAdapter.js",
-    "./lifecycle": "./src/lifecycle/index.js",
-    "./schema": "./src/schema/index.js",
-    "./types": "./src/types/index.js",
-    "./model": "./src/model/index.js",
-    "./is": "./src/is.js",
-    "./json": "./src/json.js",
-    "./lookup": "./src/lookup.js",
-    "./object": "./src/object.js",
-    "./math": "./src/math/index.js",
-    "./math/scalar": "./src/math/scalar.js",
-    "./math/num": "./src/num.js",
-    "./math/vec2": "./src/vec2.js",
-    "./math/vec3": "./src/vec3.js",
-    "./math/vec4": "./src/vec4.js",
-    "./math/quat": "./src/quat.js",
-    "./math/mat3": "./src/mat3.js",
-    "./math/mat4": "./src/mat4.js",
-    "./math/box3": "./src/box3.js",
-    "./math/tri3": "./src/tri3.js",
-    "./math/lne3": "./src/lne3.js",
-    "./math/pln": "./src/pln.js",
-    "./math/ray3": "./src/ray3.js",
-    "./math/sph3": "./src/sph3.js",
-    "./math/pool": "./src/pool.js",
-    "./math/utils": "./src/utils.js",
-    "./math/noise": "./src/noise.js",
-    "./math/curve": "./src/curve.js",
-    "./math/vertex": "./src/vertex.js",
-    "./math/mesh": "./src/mesh.js",
-    "./math/tangent": "./src/tangent.js",
-    "./math/geometry": "./src/geometry/index.js",
-    "./num": "./src/num.js",
-    "./vec2": "./src/vec2.js",
-    "./vec3": "./src/vec3.js",
-    "./vec4": "./src/vec4.js",
-    "./quat": "./src/quat.js",
-    "./mat3": "./src/mat3.js",
-    "./mat4": "./src/mat4.js",
-    "./box3": "./src/box3.js",
-    "./tri3": "./src/tri3.js",
-    "./lne3": "./src/lne3.js",
-    "./pln": "./src/pln.js",
-    "./ray3": "./src/ray3.js",
-    "./sph3": "./src/sph3.js",
-    "./pool": "./src/pool.js",
-    "./utils": "./src/utils.js",
-    "./noise": "./src/noise.js",
-    "./curve": "./src/curve.js",
-    "./vertex": "./src/vertex.js",
-    "./mesh": "./src/mesh.js",
-    "./tangent": "./src/tangent.js",
-    "./geometry": "./src/geometry/index.js",
-    "./path": "./src/path.js",
-    "./text": "./src/text.js",
-    "./validation": "./src/validation.js"
-  },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint --ext .js,.mjs src test",
-    "lint:fix": "eslint --fix --ext .js,.mjs src test",
-    "check": "npm run lint && npm test"
-  },
-  "keywords": [
-    "carbonenginejs",
-    "runtime",
-    "utilities",
-    "gl-matrix",
-    "constants",
-    "schema",
-    "types",
-    "errors",
-    "geometry",
-    "tangent",
-    "browser"
-  ],
-  "files": [
-    "src",
-    "docs",
-    "README.md",
-    "LICENSE",
-    "NOTICE",
-    "THIRD-PARTY-NOTICES.md"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "gl-matrix": "^3.4.4"
-  },
-  "devDependencies": {
-    "eslint": "^8.57.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/carbonenginejs/runtime-utils.git"
-  },
-  "homepage": "https://github.com/carbonenginejs/runtime-utils#readme",
-  "bugs": {
-    "url": "https://github.com/carbonenginejs/runtime-utils/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "overrides": {
-    "brace-expansion": "^5.0.8"
-  }
-}
+{
+  "name": "@carbonenginejs/runtime-utils",
+  "version": "0.1.5",
+  "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./arrays": "./src/arrays.js",
+    "./bytes": "./src/bytes.js",
+    "./compression": "./src/compression.js",
+    "./const": "./src/constants/index.js",
+    "./const/trinity": "./src/constants/trinity.js",
+    "./const/media": "./src/media/index.js",
+    "./const/graphics": "./src/graphics/index.js",
+    "./const/render-context": "./src/renderContext/index.js",
+    "./const/audio": "./src/audio/index.js",
+    "./const/shader": "./src/shader/index.js",
+    "./const/d3d": "./src/d3d/index.js",
+    "./const/webgpu": "./src/webgpu/index.js",
+    "./media": "./src/media/index.js",
+    "./graphics": "./src/graphics/index.js",
+    "./render-context": "./src/renderContext/index.js",
+    "./audio": "./src/audio/index.js",
+    "./shader": "./src/shader/index.js",
+    "./d3d": "./src/d3d/index.js",
+    "./webgpu": "./src/webgpu/index.js",
+    "./document": "./src/document/index.js",
+    "./errors": "./src/errors/index.js",
+    "./hydration": "./src/document/hydrationAdapter.js",
+    "./lifecycle": "./src/lifecycle/index.js",
+    "./schema": "./src/schema/index.js",
+    "./types": "./src/types/index.js",
+    "./model": "./src/model/index.js",
+    "./is": "./src/is.js",
+    "./json": "./src/json.js",
+    "./lookup": "./src/lookup.js",
+    "./object": "./src/object.js",
+    "./math": "./src/math/index.js",
+    "./math/scalar": "./src/math/scalar.js",
+    "./math/num": "./src/num.js",
+    "./math/vec2": "./src/vec2.js",
+    "./math/vec3": "./src/vec3.js",
+    "./math/vec4": "./src/vec4.js",
+    "./math/quat": "./src/quat.js",
+    "./math/mat3": "./src/mat3.js",
+    "./math/mat4": "./src/mat4.js",
+    "./math/box3": "./src/box3.js",
+    "./math/tri3": "./src/tri3.js",
+    "./math/lne3": "./src/lne3.js",
+    "./math/pln": "./src/pln.js",
+    "./math/ray3": "./src/ray3.js",
+    "./math/sph3": "./src/sph3.js",
+    "./math/pool": "./src/pool.js",
+    "./math/utils": "./src/utils.js",
+    "./math/noise": "./src/noise.js",
+    "./math/curve": "./src/curve.js",
+    "./math/vertex": "./src/vertex.js",
+    "./math/mesh": "./src/mesh.js",
+    "./math/tangent": "./src/tangent.js",
+    "./math/geometry": "./src/geometry/index.js",
+    "./num": "./src/num.js",
+    "./vec2": "./src/vec2.js",
+    "./vec3": "./src/vec3.js",
+    "./vec4": "./src/vec4.js",
+    "./quat": "./src/quat.js",
+    "./mat3": "./src/mat3.js",
+    "./mat4": "./src/mat4.js",
+    "./box3": "./src/box3.js",
+    "./tri3": "./src/tri3.js",
+    "./lne3": "./src/lne3.js",
+    "./pln": "./src/pln.js",
+    "./ray3": "./src/ray3.js",
+    "./sph3": "./src/sph3.js",
+    "./pool": "./src/pool.js",
+    "./utils": "./src/utils.js",
+    "./noise": "./src/noise.js",
+    "./curve": "./src/curve.js",
+    "./vertex": "./src/vertex.js",
+    "./mesh": "./src/mesh.js",
+    "./tangent": "./src/tangent.js",
+    "./geometry": "./src/geometry/index.js",
+    "./path": "./src/path.js",
+    "./text": "./src/text.js",
+    "./validation": "./src/validation.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint --ext .js,.mjs src test",
+    "lint:fix": "eslint --fix --ext .js,.mjs src test",
+    "check": "npm run lint && npm test"
+  },
+  "keywords": [
+    "carbonenginejs",
+    "runtime",
+    "utilities",
+    "gl-matrix",
+    "constants",
+    "schema",
+    "types",
+    "errors",
+    "geometry",
+    "tangent",
+    "browser"
+  ],
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "gl-matrix": "^3.4.4"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carbonenginejs/runtime-utils.git"
+  },
+  "homepage": "https://github.com/carbonenginejs/runtime-utils#readme",
+  "bugs": {
+    "url": "https://github.com/carbonenginejs/runtime-utils/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.8"
+  }
+}

package/src/model/CjsModel.js

@@ -4,7 +4,13 @@ import { getRuntimeState } from "../runtime/CjsRuntimeState.js";
 import { CjsModelState } from "./CjsModelState.js";
 import { CjsEventEmitter } from "./CjsEventEmitter.js";
 
-const MAX_UPDATE_PASSES = 32;
+const MAX_UPDATE_PASSES = 32;
+const CHILD_COLLECTION_KINDS = new Set([ "array", "list" ]);
+const CHILD_LIST_EVENT = {
+    UNLOAD_START: 0x07,
+    INSERTED: 0x08,
+    REMOVED: 0x09
+};
 
 /**
  * Shared base for schema-backed CarbonEngineJS runtime classes.
@@ -92,13 +98,180 @@ export class CjsModel extends CjsEventEmitter
      * @param {object} [options={}]
      * @returns {Set<string>|boolean} The result returned by {@link CjsModel.set}.
      */
-    Merge(values = [], options = {})
-    {
-        return CjsModel.merge(this, values, options);
-    }
-
-    /**
-     * Applies pending changes: drives the OnModified hook until the model
+    Merge(values = [], options = {})
+    {
+        return CjsModel.merge(this, values, options);
+    }
+
+    /**
+     * Constructs one item from a schema-backed child collection's declared
+     * item type, then adds it through the ordinary child-mutation path.
+     *
+     * Domain classes expose named factories such as `CreateAttachment`; this
+     * programmatic helper keeps property-string mutation out of their instance
+     * API.
+     *
+     * @param {CjsModel} target Owning model instance.
+     * @param {string} property Schema `array` or `list` field name.
+     * @param {object} [values={}] Plain child values.
+     * @param {object} [options={}] Hydration and mutation options.
+     * @returns {*} The constructed and added child.
+     */
+    static createChild(target, property, values = {}, options = {})
+    {
+        const { field } = getChildCollection(target, property);
+        const imported = importSourceValue([ values ], field, {
+            ...options,
+            ownerConstructor: target.constructor
+        });
+        const child = imported[0];
+
+        assertChildObject(child, field.name);
+        CjsModel.addChild(target, field.name, child, options);
+        return child;
+    }
+
+    /**
+     * Appends an existing object to a schema-backed child collection.
+     *
+     * The mutation invokes Carbon-shaped `OnListModified` when present,
+     * records the field's declared flag/rebuild consequences, emits one
+     * `childadded` event, and settles the parent unless suppressed by options.
+     *
+     * @param {CjsModel} target Owning model instance.
+     * @param {string} property Schema `array` or `list` field name.
+     * @param {object} child Existing child object.
+     * @param {object} [options={}]
+     * @returns {object} The appended child.
+     */
+    static addChild(target, property, child, options = {})
+    {
+        const { field, collection } = getChildCollection(target, property);
+
+        assertChildObject(child, field.name);
+        assertChildCallback(options.onAdded, "onAdded");
+
+        const index = collection.length;
+        collection.push(child);
+        recordChildMutation(target, field, options);
+        notifyListModified(target, CHILD_LIST_EVENT.INSERTED, index, 0, child, collection);
+
+        const payload = createChildEventPayload(target, field.name, child, index, options);
+        invokeChildCallback(options.onAdded, target, payload, "onAdded");
+        emitChildEvent(target, "childadded", payload, options);
+        settleChildMutation(target, field, options);
+        return child;
+    }
+
+    /**
+     * Detaches the first matching object from a schema-backed child collection.
+     * Removal never destroys the child.
+     *
+     * @param {CjsModel} target Owning model instance.
+     * @param {string} property Schema `array` or `list` field name.
+     * @param {object} child Existing child object.
+     * @param {object} [options={}]
+     * @returns {boolean} Whether the child was present and removed.
+     */
+    static removeChild(target, property, child, options = {})
+    {
+        const { field, collection } = getChildCollection(target, property);
+        const index = collection.indexOf(child);
+
+        if (index === -1) return false;
+        assertChildCallback(options.onRemoved, "onRemoved");
+
+        collection.splice(index, 1);
+        recordChildMutation(target, field, options);
+        notifyListModified(target, CHILD_LIST_EVENT.REMOVED, index, 0, child, collection);
+
+        const payload = createChildEventPayload(target, field.name, child, index, options);
+        invokeChildCallback(options.onRemoved, target, payload, "onRemoved");
+        emitChildEvent(target, "childremoved", payload, options);
+        settleChildMutation(target, field, options);
+        return true;
+    }
+
+    /**
+     * Removes a child and then performs an explicit deletion action.
+     *
+     * `options.delete` owns domain-specific teardown when supplied. Without
+     * that explicit hook the child is detached and left to ordinary
+     * JavaScript lifetime management. Deletion emits both `childremoved` and
+     * `childdeleted`.
+     *
+     * @param {CjsModel} target Owning model instance.
+     * @param {string} property Schema `array` or `list` field name.
+     * @param {object} child Existing child object.
+     * @param {object} [options={}]
+     * @param {Function} [options.delete] Explicit child teardown callback.
+     * @returns {boolean} Whether the child was present and deleted.
+     */
+    static deleteChild(target, property, child, options = {})
+    {
+        const { field, collection } = getChildCollection(target, property);
+        const index = collection.indexOf(child);
+
+        if (index === -1) return false;
+
+        if (options.delete !== undefined && typeof options.delete !== "function")
+        {
+            throw new TypeError("CjsModel child delete option must be a function.");
+        }
+        assertChildCallback(options.onDeleted, "onDeleted");
+
+        CjsModel.removeChild(target, field.name, child, { ...options, skipUpdate: true });
+
+        if (typeof options.delete === "function")
+        {
+            options.delete.call(target, child, options);
+        }
+
+        const payload = createChildEventPayload(target, field.name, child, index, options);
+        invokeChildCallback(options.onDeleted, target, payload, "onDeleted");
+        emitChildEvent(target, "childdeleted", payload, options);
+        settleChildMutation(target, field, options);
+        return true;
+    }
+
+    /**
+     * Detaches every object from a schema-backed child collection without
+     * destroying the children.
+     *
+     * Carbon-shaped `OnListModified` receives its unload-start callback while
+     * the collection is still populated. The public domain method decides
+     * whether clearing or per-child deletion is appropriate.
+     *
+     * @param {CjsModel} target Owning model instance.
+     * @param {string} property Schema `array` or `list` field name.
+     * @param {object} [options={}]
+     * @returns {boolean} Whether any children were cleared.
+     */
+    static clearChildren(target, property, options = {})
+    {
+        const { field, collection } = getChildCollection(target, property);
+        const count = collection.length;
+
+        if (!count) return false;
+        assertChildCallback(options.onCleared, "onCleared");
+
+        recordChildMutation(target, field, options);
+        notifyListModified(target, CHILD_LIST_EVENT.UNLOAD_START, 0, 0, null, collection);
+        collection.length = 0;
+
+        const payload = {
+            property: field.name,
+            count,
+            source: options.source ?? target
+        };
+        invokeChildCallback(options.onCleared, target, payload, "onCleared");
+        emitChildEvent(target, "childrencleared", payload, options);
+        settleChildMutation(target, field, options);
+        return true;
+    }
+
+    /**
+     * Applies pending changes: drives the OnModified hook until the model
      * settles, clears the dirty mark, and emits one final modified event.
      *
      * Calling this IS the "I made changes, apply please" contract: it always
@@ -862,15 +1035,123 @@ function findIncomingKey(values, field)
     return null;
 }
 
-function incomingKeyCandidates(field)
-{
+function incomingKeyCandidates(field)
+{
     const aliases = field.aliases === undefined
         ? field.alias === undefined ? [] : [field.alias]
         : Array.isArray(field.aliases) ? field.aliases : [field.aliases];
-    return [field.name, ...aliases].filter(value => typeof value === "string" && value.length);
-}
-
-// Adds one field's declared @io.flag / @io.rebuild tokens to their stores.
+    return [field.name, ...aliases].filter(value => typeof value === "string" && value.length);
+}
+
+function getChildCollection(target, property)
+{
+    if (!(target instanceof CjsModel))
+    {
+        throw new TypeError("CjsModel child collection target must be a CjsModel instance.");
+    }
+
+    if (typeof property !== "string" || !property)
+    {
+        throw new TypeError("CjsModel child collection property must be a non-empty string.");
+    }
+
+    const field = CjsSchema.getField(target.constructor, property);
+    if (!field)
+    {
+        throw new TypeError(`${CjsSchema.getClassName(target.constructor)} has no schema field named ${JSON.stringify(property)}.`);
+    }
+
+    const fieldType = field.type || field.jsType;
+    if (!CHILD_COLLECTION_KINDS.has(fieldType?.kind))
+    {
+        throw new TypeError(`${field.name} must be a schema array or list child collection.`);
+    }
+
+    const collection = target[field.name];
+    if (!Array.isArray(collection))
+    {
+        throw new TypeError(`${field.name} must contain an ordinary JavaScript Array.`);
+    }
+
+    return { field, collection };
+}
+
+function assertChildObject(child, property)
+{
+    if (!child || typeof child !== "object" || Array.isArray(child) || ArrayBuffer.isView(child))
+    {
+        throw new TypeError(`${property} requires a non-null child object.`);
+    }
+}
+
+function assertChildCallback(callback, optionName)
+{
+    if (callback !== undefined && callback !== null && typeof callback !== "function")
+    {
+        throw new TypeError(`CjsModel child ${optionName} option must be a function.`);
+    }
+}
+
+function recordChildMutation(target, field, options)
+{
+    if (options.markDirty === false) return;
+    target.__state.dirty = true;
+    if (options.notify !== false) addDeclaredFieldTokens(target, field);
+}
+
+function notifyListModified(target, event, index, secondIndex, child, collection)
+{
+    if (typeof target.OnListModified === "function")
+    {
+        target.OnListModified(event, index, secondIndex, child, collection);
+    }
+}
+
+function createChildEventPayload(target, property, child, index, options)
+{
+    return {
+        property,
+        child,
+        index,
+        source: options.source ?? target
+    };
+}
+
+function invokeChildCallback(callback, target, payload, optionName)
+{
+    if (callback === undefined || callback === null) return;
+    assertChildCallback(callback, optionName);
+    callback.call(target, payload);
+}
+
+function emitChildEvent(target, eventName, payload, options)
+{
+    if (options.skipEvents !== true && target.__state.suppressEvents === 0)
+    {
+        target.EmitEvent(eventName, target, payload);
+    }
+}
+
+function settleChildMutation(target, field, options)
+{
+    if (options.skipUpdate === true) return;
+
+    if (options.markDirty === false)
+    {
+        if (options.skipEvents !== true && target.__state.suppressEvents === 0)
+        {
+            target.EmitEvent("modified", target, createModifiedPayload(
+                new Set([ field.name ]),
+                options.source ?? target
+            ));
+        }
+        return;
+    }
+
+    if (!target.__state.updating) target.UpdateValues(options);
+}
+
+// Adds one field's declared @io.flag / @io.rebuild tokens to their stores.
 // Duplicate adds are no-ops (Sets). Nothing in the model layer ever clears
 // these stores - getters clear flags, work methods clear rebuild tokens.
 function addDeclaredFieldTokens(target, field)

package/src/schema/CjsSchema.js

@@ -232,7 +232,19 @@ export class CjsSchema
         unknown: fieldDecorator("type", { kind: "unknown" }),
         vec2: fieldDecorator("type", { kind: "vec2" }),
         vec3: fieldDecorator("type", { kind: "vec3" }),
-        vec4: fieldDecorator("type", { kind: "vec4" })
+        vec4: fieldDecorator("type", { kind: "vec4" }),
+
+        // An enum names the vocabulary a field's values are drawn from, which
+        // is part of its type - it belongs here beside int32 and string rather
+        // than under a separate namespace. define and hideInherited show this
+        // namespace already carries class decorators as well as field ones.
+        enum: values => fieldDecorator("enum", normalizeEnumDefinition(values)),
+
+        /**
+         * Hides named inherited fields from a subclass's schema, for a subclass
+         * that genuinely does not carry part of its parent's shape.
+         */
+        hideInherited: fieldNames => hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames))
     });
 
     static io = Object.freeze({