@carbonenginejs/runtime-utils 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonenginejs/runtime-utils",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
   "type": "module",
   "main": "src/index.js",

package/src/is.js

@@ -143,15 +143,77 @@ export function isError(a)
  * @param {*} a
  * @returns {Boolean}
  */
-export function isNumber(a)
-{
-    return isTag(a, "[object Number]");
-}
-
-/**
- * Checks if a value is a function
- * @param {*} a
- * @returns {Boolean}
+export function isNumber(a)
+{
+    return isTag(a, "[object Number]");
+}
+
+/**
+ * Checks if a value fits a signed 8-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt8(value)
+{
+    return Number.isInteger(value) && value >= -0x80 && value <= 0x7f;
+}
+
+/**
+ * Checks if a value fits an unsigned 8-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint8(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xff;
+}
+
+/**
+ * Checks if a value fits a signed 16-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt16(value)
+{
+    return Number.isInteger(value) && value >= -0x8000 && value <= 0x7fff;
+}
+
+/**
+ * Checks if a value fits an unsigned 16-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint16(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xffff;
+}
+
+/**
+ * Checks if a value fits a signed 32-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt32(value)
+{
+    return Number.isInteger(value)
+        && value >= -0x80000000
+        && value <= 0x7fffffff;
+}
+
+/**
+ * Checks if a value fits an unsigned 32-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint32(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+
+/**
+ * Checks if a value is a function
+ * @param {*} a
+ * @returns {Boolean}
  */
 export function isFunction(a)
 {

package/src/model/CjsModel.js

@@ -13,6 +13,15 @@ const MAX_UPDATE_PASSES = 32;
  */
 export class CjsModel extends CjsEventEmitter
 {
+    /**
+     * Identifies this class as a schema-backed model.
+     *
+     * Declared statically so CjsSchema can recognise a model class from a field
+     * declaration alone, without importing CjsModel - which it cannot do, since
+     * this module already imports CjsSchema. Mirrors `CjsResource.isResource`.
+     */
+    static isModel = true;
+
     /**
      * Creates a schema-backed model with initialized runtime state.
      */
@@ -208,16 +217,18 @@ export class CjsModel extends CjsEventEmitter
 
             if (descend)
             {
-                const fields = getModelFields(model);
-                const start = reverse ? fields.length - 1 : 0;
-                const end = reverse ? -1 : fields.length;
+                // Only the fields declared to hold child models, precomputed per
+                // class - not every field, type-tested per value per visit.
+                const children = CjsSchema.getSchema(model.constructor).children;
+                const start = reverse ? children.length - 1 : 0;
+                const end = reverse ? -1 : children.length;
                 const step = reverse ? -1 : 1;
 
                 for (let i = start; i !== end; i += step)
                 {
-                    const field = fields[i];
-                    if (options.ownedOnly === true && field.io?.ownership !== "owned") continue;
-                    const value = model[field.name];
+                    const child = children[i];
+                    if (options.ownedOnly === true && !child.owned) continue;
+                    const value = model[child.name];
 
                     if (Array.isArray(value))
                     {
@@ -242,19 +253,47 @@ export class CjsModel extends CjsEventEmitter
     /**
      * Collects unique resources reported by this model graph into an array.
      *
+     * Every model in the graph is visited: reporting resources does not hide a
+     * model's descendants, because an under-reported dependency set would let
+     * readiness checks pass while a child's resources were still loading.
+     *
+     * Resources held in schema fields are collected automatically - they are
+     * already declared, as `@type.objectRef("TriGeometryRes")` and friends, so
+     * restating them in a hook would be the hand-written relay chain this
+     * traversal exists to replace.
+     *
+     * `OnGetResources()` is the escape hatch for resources a model holds
+     * outside its schema, such as private fields. It takes no arguments and
+     * always returns an iterable of resources - never a bare resource and never
+     * nothing. Most models do not implement it.
+     *
      * @param {Array<*>} [out=[]] Output array, whose contents are replaced.
      * @returns {Array<*>} The supplied output array.
      */
     GetResources(out = [])
     {
         const resources = new Set();
-        AddResources(resources, out);
 
         this.Traverse(model =>
         {
-            if (typeof model.OnGetResources !== "function") return true;
-            AddResources(resources, model.OnGetResources(resources));
-            return false;
+            for (const field of CjsSchema.getSchema(model.constructor).resources)
+            {
+                const value = model[field.name];
+                if (Array.isArray(value))
+                {
+                    for (const item of value) AddResource(resources, item);
+                }
+                else
+                {
+                    AddResource(resources, value);
+                }
+            }
+
+            if (typeof model.OnGetResources === "function")
+            {
+                AddResources(resources, model.OnGetResources());
+            }
+            return true;
         });
 
         out.length = 0;
@@ -776,17 +815,23 @@ function initializeOwnedGraph(root, options = {})
     return root;
 }
 
+function AddResource(target, value)
+{
+    if (value?.isResource === true) target.add(value);
+}
+
+
 function AddResources(target, values)
 {
-    if (values === null || values === undefined) return;
-    if (values?.isResource === true)
+    if (typeof values === "string" || typeof values?.[Symbol.iterator] !== "function")
     {
-        target.add(values);
-        return;
+        throw new TypeError("CjsModel.OnGetResources must return an iterable of resources.");
     }
-    if (typeof values !== "string" && typeof values[Symbol.iterator] === "function")
+
+    // Empty slots are the model's own unset fields, not a contract violation.
+    for (const value of values)
     {
-        for (const value of values) AddResources(target, value);
+        if (value !== null && value !== undefined) target.add(value);
     }
 }
 

package/src/schema/CjsSchema.js

@@ -1,8 +1,15 @@
-const CLASS_SCHEMA = new WeakMap();
-const CONSTRUCTOR_BY_NAME = new Map();
-const ENUM_SCHEMA_BY_NAME = new Map();
-const ENUM_SCHEMA_BY_OBJECT = new WeakMap();
-const STAGE3_FIELD_METADATA = Symbol("carbonenginejs.schema.stage3Fields");
+const CLASS_SCHEMA = new WeakMap();
+
+// Exported schemas, memoized per class. SCHEMA_GENERATION is bumped by every
+// metadata definition (see getOrCreateClassSchema), which is what makes a stale
+// memo detectable without tracking which subclasses a base class change reaches.
+const SCHEMA_EXPORTS = new WeakMap();
+let SCHEMA_GENERATION = 0;
+
+const CONSTRUCTOR_BY_NAME = new Map();
+const ENUM_SCHEMA_BY_NAME = new Map();
+const ENUM_SCHEMA_BY_OBJECT = new WeakMap();
+const STAGE3_FIELD_METADATA = Symbol("carbonenginejs.schema.stage3Fields");
 
 export const CJS_ENUM_NAME = Symbol.for("carbonenginejs.enum.name");
 
@@ -56,32 +63,32 @@ export class CjsSchema
         return this;
     }
 
-    static defineMethod(Constructor, methodName, namespace, value)
-    {
-        defineMethodMetadata(Constructor, methodName, namespace, value);
-        return this;
-    }
-
-    static getField(Constructor, fieldName)
-    {
-        return getEffectiveFields(Constructor).find(field => field.name === fieldName) || null;
-    }
-
-    /**
-     * Excludes named inherited fields from the decorated class's schema surface.
-     */
-    static hideInherited(fieldNames)
-    {
-        return hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames));
-    }
-
-    /**
-     * Checks whether a field is hidden from a class by its inheritance chain.
-     */
-    static isFieldHidden(Constructor, fieldName)
-    {
-        return getHiddenInheritedFieldNames(Constructor).has(fieldName);
-    }
+    static defineMethod(Constructor, methodName, namespace, value)
+    {
+        defineMethodMetadata(Constructor, methodName, namespace, value);
+        return this;
+    }
+
+    static getField(Constructor, fieldName)
+    {
+        return getEffectiveFields(Constructor).find(field => field.name === fieldName) || null;
+    }
+
+    /**
+     * Excludes named inherited fields from the decorated class's schema surface.
+     */
+    static hideInherited(fieldNames)
+    {
+        return hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames));
+    }
+
+    /**
+     * Checks whether a field is hidden from a class by its inheritance chain.
+     */
+    static isFieldHidden(Constructor, fieldName)
+    {
+        return getHiddenInheritedFieldNames(Constructor).has(fieldName);
+    }
 
     static getMethod(Constructor, methodName)
     {
@@ -128,6 +135,9 @@ export class CjsSchema
         }
 
         CONSTRUCTOR_BY_NAME.set(name.trim(), Constructor);
+        // Buckets resolve class references by name, so a late registration
+        // changes how already-built schemas should have been bucketed.
+        SCHEMA_GENERATION += 1;
         return this;
     }
 
@@ -151,49 +161,40 @@ export class CjsSchema
         return name ? ENUM_SCHEMA_BY_NAME.get(name) || null : null;
     }
 
-    static getSchema(Constructor, options = {})
-    {
-        const schema = CLASS_SCHEMA.get(Constructor);
-        const namespaces = normalizeNamespaces(options.namespaces);
-        const fields = [];
-        const methods = [];
-
-        for (const field of getEffectiveFields(Constructor))
-        {
-            fields.push(enrichEnumField(exportField(field, namespaces), Constructor));
-        }
-
-        for (const method of schema?.methods || [])
-        {
-            methods.push(exportField(method, namespaces));
-        }
-
-        const result = {
-            className: CjsSchema.getClassName(Constructor),
-            fields: Object.freeze(fields)
-        };
-
-        const family = schema?.family || CjsSchema.getClassFamily(Constructor);
-        if (family)
-        {
-            result.family = family;
-        }
-
-        if (schema?.sourceClass && schema.sourceClass !== result.className)
-        {
-            result.sourceClass = schema.sourceClass;
-        }
-
-        if (schema?.aliases?.length)
-        {
-            result.aliases = Object.freeze([...schema.aliases]);
-        }
+    /**
+     * Return the exported schema for a class.
+     *
+     * The schema is the precomputed answer - collapsing the inheritance
+     * lineage and merging metadata - so building it per call would defeat its
+     * purpose. Callers traverse model graphs and ask once per node, so this is
+     * memoized per class and rebuilt only when class metadata is defined.
+     *
+     * Namespace-filtered exports are not memoized: they are a projection of the
+     * full schema requested by tooling, not the hot read path.
+     *
+     * The result is shared, not copied - treat it as read-only. It is not
+     * frozen: deep-cloning and freezing every field on the way out cost far
+     * more than the mistakes it guarded against.
+     *
+     * @param {Function} Constructor
+     * @param {object} [options={}]
+     * @param {string|Array<string>} [options.namespaces] Restricts exported metadata namespaces.
+     * @returns {object} Shared schema export.
+     */
+    static getSchema(Constructor, options = {})
+    {
+        const namespaces = normalizeNamespaces(options.namespaces);
+        if (namespaces) return buildSchema(Constructor, namespaces);
 
-        if (methods.length) result.methods = Object.freeze(methods);
+        const memo = SCHEMA_EXPORTS.get(Constructor);
+        if (memo && memo.generation === SCHEMA_GENERATION) return memo.schema;
 
-        return Object.freeze(result);
+        const schema = buildSchema(Constructor, null);
+        SCHEMA_EXPORTS.set(Constructor, { generation: SCHEMA_GENERATION, schema });
+        return schema;
     }
 
+
     static type = Object.freeze({
         array: itemType => fieldDecorator("type", { kind: "array", itemType }),
         boolean: fieldDecorator("type", { kind: "boolean" }),
@@ -338,17 +339,17 @@ function createComponentsNamespace()
     return Object.freeze(components);
 }
 
-function fieldDecorator(namespace, value)
-{
-    return function schemaFieldDecorator(targetOrValue, contextOrFieldName)
-    {
-        if (contextOrFieldName && typeof contextOrFieldName === "object")
-        {
-            const context = contextOrFieldName;
-            if (context.kind !== "field") throw new TypeError("CjsSchema decorators only support class fields.");
-            recordStage3FieldMetadata(context, namespace, value);
-
-            // Register field metadata on instance construction. addInitializer covers
+function fieldDecorator(namespace, value)
+{
+    return function schemaFieldDecorator(targetOrValue, contextOrFieldName)
+    {
+        if (contextOrFieldName && typeof contextOrFieldName === "object")
+        {
+            const context = contextOrFieldName;
+            if (context.kind !== "field") throw new TypeError("CjsSchema decorators only support class fields.");
+            recordStage3FieldMetadata(context, namespace, value);
+
+            // Register field metadata on instance construction. addInitializer covers
             // spec-compliant runtimes; the returned field initializer covers runtimes (e.g.
             // Deno/SWC) that do NOT fire field-decorator addInitializer. Both register the same
             // metadata (idempotent via mergeNamespace), so whichever the runtime honours, the
@@ -376,44 +377,44 @@ function fieldDecorator(namespace, value)
     };
 }
 
-function classDefinitionDecorator(definition)
-{
-    return function schemaClassDefinitionDecorator(value, context)
-    {
-        if (context && typeof context === "object")
-        {
-            if (context.kind !== "class") throw new TypeError("CjsSchema type.define only supports classes.");
-            registerStage3FieldMetadata(value, context.metadata);
-            defineClassMetadata(value, normalizeClassDefinition(value, definition));
-            return;
-        }
+function classDefinitionDecorator(definition)
+{
+    return function schemaClassDefinitionDecorator(value, context)
+    {
+        if (context && typeof context === "object")
+        {
+            if (context.kind !== "class") throw new TypeError("CjsSchema type.define only supports classes.");
+            registerStage3FieldMetadata(value, context.metadata);
+            defineClassMetadata(value, normalizeClassDefinition(value, definition));
+            return;
+        }
 
         if (typeof value !== "function")
         {
             throw new TypeError("CjsSchema type.define requires a class constructor.");
         }
 
-        defineClassMetadata(value, normalizeClassDefinition(value, definition));
-    };
-}
-
-function hiddenInheritedFieldsDecorator(fieldNames)
-{
-    return function schemaHiddenInheritedFieldsDecorator(value, context)
-    {
-        if (context && typeof context === "object")
-        {
-            if (context.kind !== "class") throw new TypeError("CjsSchema.hideInherited only supports classes.");
-            registerStage3FieldMetadata(value, context.metadata);
-        }
-        else if (typeof value !== "function")
-        {
-            throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
-        }
-
-        defineHiddenInheritedFields(value, fieldNames);
-    };
-}
+        defineClassMetadata(value, normalizeClassDefinition(value, definition));
+    };
+}
+
+function hiddenInheritedFieldsDecorator(fieldNames)
+{
+    return function schemaHiddenInheritedFieldsDecorator(value, context)
+    {
+        if (context && typeof context === "object")
+        {
+            if (context.kind !== "class") throw new TypeError("CjsSchema.hideInherited only supports classes.");
+            registerStage3FieldMetadata(value, context.metadata);
+        }
+        else if (typeof value !== "function")
+        {
+            throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
+        }
+
+        defineHiddenInheritedFields(value, fieldNames);
+    };
+}
 
 const CONTEXT_FIRST_PARAMETER = /^\(?\s*_?(context|updateContext)\b/;
 
@@ -523,10 +524,10 @@ function defineMethodMetadata(Constructor, methodName, namespace, value)
     defineMemberMetadata(Constructor, "methods", "methodsByName", methodName, namespace, value);
 }
 
-function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, value)
-{
-    const schema = getOrCreateClassSchema(Constructor);
-    let item = schema[mapKey].get(name);
+function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, value)
+{
+    const schema = getOrCreateClassSchema(Constructor);
+    let item = schema[mapKey].get(name);
 
     if (!item)
     {
@@ -534,188 +535,307 @@ function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, val
         schema[listKey].push(item);
         schema[mapKey].set(name, item);
     }
-
-    item[namespace] = mergeNamespace(item[namespace], value);
-}
-
-function defineHiddenInheritedFields(Constructor, fieldNames)
-{
-    if (typeof Constructor !== "function")
-    {
-        throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
-    }
-
-    const Parent = Object.getPrototypeOf(Constructor);
-    const inheritedFields = new Set(getEffectiveFields(Parent).map(field => field.name));
-    const className = CLASS_SCHEMA.get(Constructor)?.className || Constructor.name || "<anonymous>";
-
-    for (const fieldName of fieldNames)
-    {
-        if (!inheritedFields.has(fieldName))
-        {
-            throw new TypeError(
-                `CjsSchema.hideInherited cannot hide "${fieldName}" on ${className}: ` +
-                "the parent schema does not expose that field."
-            );
-        }
-    }
-
-    const schema = getOrCreateClassSchema(Constructor);
-    for (const fieldName of fieldNames)
-    {
-        schema.hiddenInherited.add(fieldName);
-    }
-}
-
-function getEffectiveFields(Constructor)
-{
-    const ordered = [];
-    const byName = new Map();
-    const hidden = new Set();
-
-    for (const current of getSchemaLineage(Constructor))
-    {
-        const schema = CLASS_SCHEMA.get(current);
-        for (const field of schema?.fields || [])
-        {
-            const existing = byName.get(field.name);
-            if (existing)
-            {
-                mergeMemberMetadata(existing, field);
-            }
-            else
-            {
-                const merged = mergeMemberMetadata({ name: field.name }, field);
-                ordered.push(merged);
-                byName.set(field.name, merged);
-            }
-        }
-
-        for (const fieldName of schema?.hiddenInherited || [])
-        {
-            hidden.add(fieldName);
-        }
-    }
-
-    return ordered.filter(field => !hidden.has(field.name));
-}
-
-function getHiddenInheritedFieldNames(Constructor)
-{
-    const hidden = new Set();
-    for (const current of getSchemaLineage(Constructor))
-    {
-        for (const fieldName of CLASS_SCHEMA.get(current)?.hiddenInherited || [])
-        {
-            hidden.add(fieldName);
-        }
-    }
-    return hidden;
-}
-
-function getSchemaLineage(Constructor)
-{
-    const lineage = [];
-    let current = Constructor;
-    while (typeof current === "function")
-    {
-        if (CLASS_SCHEMA.has(current)) lineage.push(current);
-        current = Object.getPrototypeOf(current);
-    }
-    return lineage.reverse();
-}
-
-function mergeMemberMetadata(target, source)
-{
-    for (const [namespace, value] of Object.entries(source))
-    {
-        if (namespace === "name") continue;
-        target[namespace] = mergeNamespace(target[namespace], value);
-    }
-    return target;
-}
-
-function getOrCreateClassSchema(Constructor)
-{
-    let schema = CLASS_SCHEMA.get(Constructor);
-    if (!schema)
+
+    item[namespace] = mergeNamespace(item[namespace], value);
+}
+
+function defineHiddenInheritedFields(Constructor, fieldNames)
+{
+    if (typeof Constructor !== "function")
+    {
+        throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
+    }
+
+    const Parent = Object.getPrototypeOf(Constructor);
+    const inheritedFields = new Set(getEffectiveFields(Parent).map(field => field.name));
+    // Declared name only: Constructor.name does not survive minification, and a
+    // mangled name in an error reads as a real one and sends you chasing it.
+    const className = CLASS_SCHEMA.get(Constructor)?.className || "<undeclared>";
+
+    for (const fieldName of fieldNames)
+    {
+        if (!inheritedFields.has(fieldName))
+        {
+            throw new TypeError(
+                `CjsSchema.hideInherited cannot hide "${fieldName}" on ${className}: ` +
+                "the parent schema does not expose that field."
+            );
+        }
+    }
+
+    const schema = getOrCreateClassSchema(Constructor);
+    for (const fieldName of fieldNames)
+    {
+        schema.hiddenInherited.add(fieldName);
+    }
+}
+
+function getEffectiveFields(Constructor)
+{
+    const ordered = [];
+    const byName = new Map();
+    const hidden = new Set();
+
+    for (const current of getSchemaLineage(Constructor))
+    {
+        const schema = CLASS_SCHEMA.get(current);
+        for (const field of schema?.fields || [])
+        {
+            const existing = byName.get(field.name);
+            if (existing)
+            {
+                mergeMemberMetadata(existing, field);
+            }
+            else
+            {
+                const merged = mergeMemberMetadata({ name: field.name }, field);
+                ordered.push(merged);
+                byName.set(field.name, merged);
+            }
+        }
+
+        for (const fieldName of schema?.hiddenInherited || [])
+        {
+            hidden.add(fieldName);
+        }
+    }
+
+    return ordered.filter(field => !hidden.has(field.name));
+}
+
+function getHiddenInheritedFieldNames(Constructor)
+{
+    const hidden = new Set();
+    for (const current of getSchemaLineage(Constructor))
+    {
+        for (const fieldName of CLASS_SCHEMA.get(current)?.hiddenInherited || [])
+        {
+            hidden.add(fieldName);
+        }
+    }
+    return hidden;
+}
+
+function getSchemaLineage(Constructor)
+{
+    const lineage = [];
+    let current = Constructor;
+    while (typeof current === "function")
+    {
+        if (CLASS_SCHEMA.has(current)) lineage.push(current);
+        current = Object.getPrototypeOf(current);
+    }
+    return lineage.reverse();
+}
+
+function mergeMemberMetadata(target, source)
+{
+    for (const [namespace, value] of Object.entries(source))
+    {
+        if (namespace === "name") continue;
+        target[namespace] = mergeNamespace(target[namespace], value);
+    }
+    return target;
+}
+
+function buildSchema(Constructor, namespaces)
+{
+    const schema = CLASS_SCHEMA.get(Constructor);
+    const fields = [];
+    const methods = [];
+
+    for (const field of getEffectiveFields(Constructor))
+    {
+        fields.push(enrichEnumField(exportField(field, namespaces), Constructor));
+    }
+
+    for (const method of schema?.methods || [])
+    {
+        methods.push(exportField(method, namespaces));
+    }
+
+    const result = {
+        className: CjsSchema.getClassName(Constructor),
+        fields
+    };
+
+    const family = schema?.family || CjsSchema.getClassFamily(Constructor);
+    if (family)
+    {
+        result.family = family;
+    }
+
+    if (schema?.sourceClass && schema.sourceClass !== result.className)
+    {
+        result.sourceClass = schema.sourceClass;
+    }
+
+    if (schema?.aliases?.length)
+    {
+        result.aliases = [ ...schema.aliases ];
+    }
+
+    if (methods.length) result.methods = methods;
+
+    addSchemaBuckets(result);
+    return result;
+}
+
+
+// Kinds that hold many values rather than one. `map` and `set` are included
+// because they are iterable collections of the referenced class, same as a list.
+const MANY_KINDS = new Set([ "list", "array", "set", "map" ]);
+
+// Kinds that can hold a child model. Bucketing on the KIND rather than on a
+// resolvable class reference keeps traversal conservative: `type.struct(Class)`
+// drops the reference during normalization, and a raw defineField may omit the
+// item type, so requiring a reference would silently stop visiting those.
+// Scalar and math kinds are excluded, which is where the saving comes from.
+const MODEL_KINDS = new Set([
+    "struct", "model", "rawStruct", "objectRef", "unknown",
+    "list", "array", "set", "map"
+]);
+
+
+/**
+ * Precompute the answers consumers would otherwise recompute per traversal.
+ *
+ * Graph walks ask the same two questions of every node - which fields hold
+ * child models, which hold resources - and answering them by scanning the field
+ * list and type-testing each value costs more than the walk itself. The class
+ * cannot change without rebuilding its schema, so this is solved once.
+ */
+function addSchemaBuckets(schema)
+{
+    const byName = new Map();
+    const children = [];
+    const resources = [];
+
+    for (const field of schema.fields)
+    {
+        byName.set(field.name, field);
+
+        const type = field.type;
+        // An undeclared field could hold anything, so it stays traversable.
+        const kind = type?.kind;
+        if (kind && !MODEL_KINDS.has(kind)) continue;
+
+        const entry = { name: field.name, many: MANY_KINDS.has(kind) };
+
+        if (type && resolveFieldClass(type)?.isResource === true)
+        {
+            resources.push(entry);
+            continue;
+        }
+
+        entry.owned = field.io?.ownership === "owned";
+        children.push(entry);
+    }
+
+    schema.byName = byName;
+    schema.children = children;
+    schema.resources = resources;
+}
+
+
+// Only string references survive normalization - type.struct(SomeClass) drops
+// the reference entirely - so a field can only be bucketed when it names a
+// class. The one field in the tree that named nothing was a missing
+// declaration, not a deliberate escape.
+function resolveFieldClass(type)
+{
+    const ref = type.className || type.itemType || type.valueType;
+    return typeof ref === "string" && ref ? CONSTRUCTOR_BY_NAME.get(ref) || null : null;
+}
+
+
+function getOrCreateClassSchema(Constructor)
+{
+    // The only route by which class metadata is mutated, and therefore the only
+    // place exported schemas can go stale. A single global counter rather than
+    // per-class invalidation because a base class change invalidates every
+    // subclass, and lineage is not tracked in reverse.
+    SCHEMA_GENERATION += 1;
+
+    let schema = CLASS_SCHEMA.get(Constructor);
+    if (!schema)
     {
         schema = {
             className: null,
             family: null,
             sourceClass: null,
-            aliases: null,
-            fields: [],
-            fieldsByName: new Map(),
-            hiddenInherited: new Set(),
-            methods: [],
-            methodsByName: new Map()
-        };
+            aliases: null,
+            fields: [],
+            fieldsByName: new Map(),
+            hiddenInherited: new Set(),
+            methods: [],
+            methodsByName: new Map()
+        };
         CLASS_SCHEMA.set(Constructor, schema);
     }
-    return schema;
-}
-
-function normalizeHiddenInheritedFields(fieldNames)
-{
-    if (!Array.isArray(fieldNames) || !fieldNames.length)
-    {
-        throw new TypeError("CjsSchema.hideInherited requires a non-empty array of field names.");
-    }
-
-    const normalized = fieldNames.map((fieldName, index) =>
-    {
-        if (typeof fieldName !== "string" || !fieldName.trim())
-        {
-            throw new TypeError(`CjsSchema.hideInherited fieldNames[${index}] must be a non-empty string.`);
-        }
-        return fieldName.trim();
-    });
-
-    return Object.freeze([...new Set(normalized)]);
-}
-
-function recordStage3FieldMetadata(context, namespace, value)
-{
-    const metadata = context?.metadata;
-    if (!metadata || typeof metadata !== "object") return;
-
-    let fields;
-    if (Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA))
-    {
-        fields = metadata[STAGE3_FIELD_METADATA];
-    }
-    else
-    {
-        fields = [];
-        Object.defineProperty(metadata, STAGE3_FIELD_METADATA, {
-            configurable: false,
-            enumerable: false,
-            value: fields,
-            writable: false
-        });
-    }
-
-    fields.push({
-        name: context.name,
-        namespace,
-        value
-    });
-}
-
-function registerStage3FieldMetadata(Constructor, metadata)
-{
-    if (!metadata || typeof metadata !== "object") return;
-    if (!Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA)) return;
-
-    for (const field of metadata[STAGE3_FIELD_METADATA])
-    {
-        defineFieldMetadata(Constructor, field.name, field.namespace, field.value);
-    }
-}
-
-function normalizeClassDefinition(Constructor, definition)
-{
+    return schema;
+}
+
+function normalizeHiddenInheritedFields(fieldNames)
+{
+    if (!Array.isArray(fieldNames) || !fieldNames.length)
+    {
+        throw new TypeError("CjsSchema.hideInherited requires a non-empty array of field names.");
+    }
+
+    const normalized = fieldNames.map((fieldName, index) =>
+    {
+        if (typeof fieldName !== "string" || !fieldName.trim())
+        {
+            throw new TypeError(`CjsSchema.hideInherited fieldNames[${index}] must be a non-empty string.`);
+        }
+        return fieldName.trim();
+    });
+
+    return Object.freeze([...new Set(normalized)]);
+}
+
+function recordStage3FieldMetadata(context, namespace, value)
+{
+    const metadata = context?.metadata;
+    if (!metadata || typeof metadata !== "object") return;
+
+    let fields;
+    if (Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA))
+    {
+        fields = metadata[STAGE3_FIELD_METADATA];
+    }
+    else
+    {
+        fields = [];
+        Object.defineProperty(metadata, STAGE3_FIELD_METADATA, {
+            configurable: false,
+            enumerable: false,
+            value: fields,
+            writable: false
+        });
+    }
+
+    fields.push({
+        name: context.name,
+        namespace,
+        value
+    });
+}
+
+function registerStage3FieldMetadata(Constructor, metadata)
+{
+    if (!metadata || typeof metadata !== "object") return;
+    if (!Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA)) return;
+
+    for (const field of metadata[STAGE3_FIELD_METADATA])
+    {
+        defineFieldMetadata(Constructor, field.name, field.namespace, field.value);
+    }
+}
+
+function normalizeClassDefinition(Constructor, definition)
+{
     if (typeof definition === "string")
     {
         definition = { className: definition };
@@ -937,9 +1057,8 @@ function componentIndex(char)
 
 function mergeNamespace(existing, value)
 {
-    if (!existing) return cloneSchemaValue(value);
-    if (isPlainObject(existing) && isPlainObject(value)) return Object.freeze({ ...existing, ...value });
-    return cloneSchemaValue(value);
+    if (isPlainObject(existing) && isPlainObject(value)) return { ...existing, ...value };
+    return value;
 }
 
 // Resolves @schema.enum("X") through the owning class's PascalCase static so
@@ -984,10 +1103,10 @@ function exportField(field, namespaces)
     {
         if (key === "name") continue;
         if (namespaces && !namespaces.has(key)) continue;
-        result[key] = cloneSchemaValue(value);
+        result[key] = value;
     }
 
-    return Object.freeze(result);
+    return result;
 }
 
 function normalizeNamespaces(namespaces)

package/src/vec3.js

@@ -559,6 +559,21 @@ vec3.isEmpty = function (a)
     return a[0] === 0 && a[1] === 0 && a[2] === 0;
 };
 
+/**
+ * The largest of the three components.
+ *
+ * A reduction to one number, unlike `max`, which is the component-wise maximum
+ * of two vectors. Carbon spells it `MaxVectorComponent`, and uses it to reduce a
+ * colour to the single value that decides how bright it counts as.
+ *
+ * @param {vec3} a
+ * @returns {Number}
+ */
+vec3.maxComponent = function (a)
+{
+    return Math.max(a[0], a[1], a[2]);
+};
+
 /**
  * Multiplies a vec3 by a scalar
  *
@@ -1097,6 +1112,7 @@ export const {
     length,
     lerp,
     max,
+    maxComponent,
     min,
     mul,
     multiply,