@carbonenginejs/runtime-utils 0.1.2 → 0.1.4

package/src/renderContext/window.js

@@ -1,20 +1,20 @@
-// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
-//   trinity/UI/Tr2MainWindow.h (Tr2WindowMode, Tr2WindowShowState, Tr2ImeState_MacOS namespaces)
-
-export const Tr2WindowMode = Object.freeze({
-    FULL_SCREEN: 0,
-    WINDOWED: 1,
-    FIXED_WINDOW: 2
-});
-
-export const Tr2WindowShowState = Object.freeze({
-    NORMAL: 0,
-    MAXIMIZED: 1,
-    MINIMIZED: 2
-});
-
-export const Tr2ImeState_MacOS = Object.freeze({
-    DISABLED: 0,
-    READY: 1,
-    BLOCKING: 2
-});
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinity/UI/Tr2MainWindow.h (Tr2WindowMode, Tr2WindowShowState, Tr2ImeState_MacOS namespaces)
+
+export const Tr2WindowMode = Object.freeze({
+    FULL_SCREEN: 0,
+    WINDOWED: 1,
+    FIXED_WINDOW: 2
+});
+
+export const Tr2WindowShowState = Object.freeze({
+    NORMAL: 0,
+    MAXIMIZED: 1,
+    MINIMIZED: 2
+});
+
+export const Tr2ImeState_MacOS = Object.freeze({
+    DISABLED: 0,
+    READY: 1,
+    BLOCKING: 2
+});

package/src/runtime/CjsRuntimeState.js

@@ -1,50 +1,50 @@
-/**
- * Gets an object's own CarbonEngineJS runtime state without creating it.
- *
- * Runtime state is intentionally stored on the object for inspection while
- * remaining outside enumeration and serialization.
- *
- * @param {object|Function} target
- * @returns {object|null}
- */
-export function getRuntimeState(target)
-{
-    assertRuntimeStateTarget(target);
-    if (!Object.prototype.hasOwnProperty.call(target, "__state")) return null;
-
-    const state = target.__state;
-    if (!state || typeof state !== "object" || Array.isArray(state))
-    {
-        throw new TypeError("Existing __state must be an object.");
-    }
-    return state;
-}
-
-/**
- * Gets or creates an object's own non-enumerable runtime state.
- *
- * @param {object|Function} target
- * @returns {object}
- */
-export function ensureRuntimeState(target)
-{
-    const existing = getRuntimeState(target);
-    if (existing) return existing;
-
-    const state = {};
-    Object.defineProperty(target, "__state", {
-        value: state,
-        enumerable: false,
-        configurable: false,
-        writable: false
-    });
-    return state;
-}
-
-function assertRuntimeStateTarget(target)
-{
-    if ((typeof target !== "object" || target === null) && typeof target !== "function")
-    {
-        throw new TypeError("Runtime state requires an object or function.");
-    }
-}
+/**
+ * Gets an object's own CarbonEngineJS runtime state without creating it.
+ *
+ * Runtime state is intentionally stored on the object for inspection while
+ * remaining outside enumeration and serialization.
+ *
+ * @param {object|Function} target
+ * @returns {object|null}
+ */
+export function getRuntimeState(target)
+{
+    assertRuntimeStateTarget(target);
+    if (!Object.prototype.hasOwnProperty.call(target, "__state")) return null;
+
+    const state = target.__state;
+    if (!state || typeof state !== "object" || Array.isArray(state))
+    {
+        throw new TypeError("Existing __state must be an object.");
+    }
+    return state;
+}
+
+/**
+ * Gets or creates an object's own non-enumerable runtime state.
+ *
+ * @param {object|Function} target
+ * @returns {object}
+ */
+export function ensureRuntimeState(target)
+{
+    const existing = getRuntimeState(target);
+    if (existing) return existing;
+
+    const state = {};
+    Object.defineProperty(target, "__state", {
+        value: state,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return state;
+}
+
+function assertRuntimeStateTarget(target)
+{
+    if ((typeof target !== "object" || target === null) && typeof target !== "function")
+    {
+        throw new TypeError("Runtime state requires an object or function.");
+    }
+}

package/src/schema/CjsSchema.js

@@ -11,6 +11,11 @@ const ENUM_SCHEMA_BY_NAME = new Map();
 const ENUM_SCHEMA_BY_OBJECT = new WeakMap();
 const STAGE3_FIELD_METADATA = Symbol("carbonenginejs.schema.stage3Fields");
 
+// Declared here rather than beside describeDecorator: the CjsSchema class body
+// builds every decorator namespace in its static initializer, which runs before
+// any const declared after the class is initialized.
+const DECORATOR_METADATA = Symbol("carbonenginejs.schema.decoratorMetadata");
+
 export const CJS_ENUM_NAME = Symbol.for("carbonenginejs.enum.name");
 
 /**
@@ -308,7 +313,8 @@ export class CjsSchema
                 contextual: true,
                 contextTiers: Object.freeze(normalized)
             });
-            return function contextualMethodDecorator(targetOrValue, contextOrMethodName)
+            const described = getDecoratorMetadata(base);
+            return describeDecorator(function contextualMethodDecorator(targetOrValue, contextOrMethodName)
             {
                 // Contextual methods are validated context-first at decoration
                 // time: the first declared parameter must be the frame context.
@@ -321,7 +327,7 @@ export class CjsSchema
                     assertContextFirstMethod(targetOrValue[contextOrMethodName], contextOrMethodName);
                 }
                 return base(targetOrValue, contextOrMethodName);
-            };
+            }, described.namespace, described.value);
         }
     });
 
@@ -339,9 +345,33 @@ function createComponentsNamespace()
     return Object.freeze(components);
 }
 
+// Every decorator carries the namespace and value it would install. That is
+// what lets one vocabulary serve both forms: `type.uint32` applied as a
+// decorator, and `type.uint32` written as data in a CjsSchema.define() member.
+// Without it the object form would need its own spelling of every namespace
+// value, and two spellings of `impl.adapted` will eventually disagree.
+function describeDecorator(decorator, namespace, value)
+{
+    Object.defineProperty(decorator, DECORATOR_METADATA, {
+        value: { namespace, value }
+    });
+    return decorator;
+}
+
+/**
+ * The namespace/value a decorator installs, or null when it is not one.
+ *
+ * @param {*} candidate Possible decorator.
+ * @returns {{namespace:string, value:*}|null} Installed metadata.
+ */
+function getDecoratorMetadata(candidate)
+{
+    return typeof candidate === "function" ? candidate[DECORATOR_METADATA] || null : null;
+}
+
 function fieldDecorator(namespace, value)
 {
-    return function schemaFieldDecorator(targetOrValue, contextOrFieldName)
+    return describeDecorator(function schemaFieldDecorator(targetOrValue, contextOrFieldName)
     {
         if (contextOrFieldName && typeof contextOrFieldName === "object")
         {
@@ -349,12 +379,12 @@ function fieldDecorator(namespace, value)
             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
-            // schema is populated. Registration is lazy (first construction); the class decorator
-            // still registers the class eagerly at definition time.
+            // The class decorator replays the Stage-3 metadata recorded above, so
+            // schema inspection works before the first instance is constructed.
+            // Keep both runtime initializers as fallbacks: addInitializer covers
+            // spec-compliant runtimes, while the returned field initializer covers
+            // runtimes that do not fire field-decorator addInitializer. All paths
+            // register the same metadata idempotently through mergeNamespace.
             context.addInitializer(function initializeSchemaField()
             {
                 defineFieldMetadata(this.constructor, context.name, namespace, value);
@@ -374,7 +404,7 @@ function fieldDecorator(namespace, value)
         }
 
         defineFieldMetadata(Constructor, contextOrFieldName, namespace, value);
-    };
+    }, namespace, value);
 }
 
 function classDefinitionDecorator(definition)
@@ -437,7 +467,7 @@ function assertContextFirstMethod(fn, methodName)
 
 function methodDecorator(namespace, value)
 {
-    return function schemaMethodDecorator(targetOrValue, contextOrMethodName)
+    return describeDecorator(function schemaMethodDecorator(targetOrValue, contextOrMethodName)
     {
         if (contextOrMethodName && typeof contextOrMethodName === "object")
         {
@@ -459,14 +489,14 @@ function methodDecorator(namespace, value)
         }
 
         defineMethodMetadata(Constructor, contextOrMethodName, namespace, value);
-    };
+    }, namespace, value);
 }
 
 function memberDecorator(namespace, value)
 {
     const forMethods = methodDecorator(namespace, value);
     const forFields = fieldDecorator(namespace, value);
-    return function schemaMemberDecorator(targetOrValue, contextOrMemberName)
+    return describeDecorator(function schemaMemberDecorator(targetOrValue, contextOrMemberName)
     {
         if (contextOrMemberName && typeof contextOrMemberName === "object")
         {
@@ -480,7 +510,7 @@ function memberDecorator(namespace, value)
         return targetOrValue && contextOrMemberName && typeof targetOrValue[contextOrMemberName] === "function"
             ? forMethods(targetOrValue, contextOrMemberName)
             : forFields(targetOrValue, contextOrMemberName);
-    };
+    }, namespace, value);
 }
 
 function defineFieldMetadata(Constructor, fieldName, namespace, value)
@@ -649,6 +679,23 @@ function buildSchema(Constructor, namespaces)
         fields.push(enrichEnumField(exportField(field, namespaces), Constructor));
     }
 
+    // KNOWN DEFECT: methods are read from this class only, while fields resolve
+    // through the whole lineage above. A subclass therefore reports no inherited
+    // methods, and the decorated form hides that behind a second bug that
+    // cancels it out: method decorators register through addInitializer, where
+    // `this.constructor` is the *instance's* class, so constructing one
+    // Tr2LightProfileRes writes CjsResource's methods onto Tr2LightProfileRes.
+    // Which class owns which methods then depends on construction order, and
+    // before any instance exists a class reports no methods at all.
+    //
+    // Declaring metadata as data (CjsSchema.define fields/methods) registers on
+    // the declaring class at module load, so it is deterministic - and it makes
+    // the missing inheritance visible rather than accidentally papered over.
+    //
+    // Left unfixed deliberately: nothing reads .methods off a runtime schema
+    // today (tools-core classTool parses source documents, not these), and the
+    // fix - walking the lineage here as getEffectiveFields does - changes
+    // exported schemas for every decorator-using class in the org.
     for (const method of schema?.methods || [])
     {
         methods.push(exportField(method, namespaces));
@@ -860,27 +907,98 @@ function normalizeClassDefinition(Constructor, definition)
     return result;
 }
 
+/**
+ * Normalize a definition's `fields`/`methods` into internal member records.
+ *
+ * Two spellings are accepted. A name-keyed object is the one to write:
+ * declaration order is key order, which is what drives GetValues() export
+ * order, and the name appears once rather than as a property of its own record.
+ * The array of `{name, ...}` records predates it and still parses, because it
+ * is what the internal schema stores.
+ *
+ * @param {object|Array<object>|null} members Declared members.
+ * @param {string} memberType Either "fields" or "methods", for messages.
+ * @returns {Array<object>} Internal member records.
+ */
 function normalizeManualMembers(members, memberType)
 {
     if (members === undefined || members === null) return [];
-    if (!Array.isArray(members))
+
+    if (Array.isArray(members))
     {
-        throw new TypeError(`CjsSchema.define ${memberType} must be an array.`);
+        return members.map((member, index) =>
+        {
+            if (!isPlainObject(member) || typeof member.name !== "string" || !member.name.trim())
+            {
+                throw new TypeError(`CjsSchema.define ${memberType}[${index}] requires a non-empty name.`);
+            }
+            const { name, ...namespaces } = member;
+            return normalizeManualMember(name.trim(), namespaces, memberType);
+        });
     }
 
-    return members.map((member, index) =>
+    if (!isPlainObject(members))
     {
-        if (!isPlainObject(member) || typeof member.name !== "string" || !member.name.trim())
+        throw new TypeError(
+            `CjsSchema.define ${memberType} must be a name-keyed object or an array of named records.`
+        );
+    }
+
+    return Object.entries(members).map(([ name, definition ]) =>
+    {
+        if (!name.trim())
         {
-            throw new TypeError(`CjsSchema.define ${memberType}[${index}] requires a non-empty name.`);
+            throw new TypeError(`CjsSchema.define ${memberType} requires a non-empty name.`);
         }
-        return {
-            ...member,
-            name: member.name.trim()
-        };
+        return normalizeManualMember(name.trim(), definition, memberType);
     });
 }
 
+/**
+ * Collapse one member's declaration into a namespace map.
+ *
+ * A declaration is a decorator, a namespace object, or an array mixing both.
+ * Decorators are accepted as data so the object form reuses the vocabulary the
+ * decorators already define rather than restating it: `impl.adapted` written
+ * twice in two spellings is two things that can disagree.
+ *
+ * @param {string} name Member name.
+ * @param {*} definition Declared metadata.
+ * @param {string} memberType Either "fields" or "methods", for messages.
+ * @returns {object} Internal member record.
+ */
+function normalizeManualMember(name, definition, memberType)
+{
+    const member = { name };
+
+    for (const entry of Array.isArray(definition) ? definition : [ definition ])
+    {
+        if (entry === undefined || entry === null) continue;
+
+        const decorator = getDecoratorMetadata(entry);
+        if (decorator)
+        {
+            member[decorator.namespace] = mergeNamespace(member[decorator.namespace], decorator.value);
+            continue;
+        }
+
+        if (!isPlainObject(entry))
+        {
+            throw new TypeError(
+                `CjsSchema.define ${memberType} "${name}" accepts schema decorators, ` +
+                "namespace objects, or an array of them."
+            );
+        }
+
+        for (const [ namespace, value ] of Object.entries(entry))
+        {
+            member[namespace] = mergeNamespace(member[namespace], value);
+        }
+    }
+
+    return member;
+}
+
 function registerClassMetadata(Constructor, schema)
 {
     if (!Constructor || !schema?.className) return;

package/src/schema/index.js

@@ -2,12 +2,12 @@ import { CJS_ENUM_NAME, CjsSchema } from "./CjsSchema.js";
 
 // Namespace decorators re-exported as named bindings so consumers can write
 // `import { type, io } from ".../schema"` and `@type.string` instead of `@CjsSchema.type.string`.
-const { type, io, jessica, impl, carbon, components } = CjsSchema;
+const { type, io, jessica, impl, carbon, components } = CjsSchema;
 
 export {
-    carbon,
-    components,
-    CJS_ENUM_NAME,
+    carbon,
+    components,
+    CJS_ENUM_NAME,
     CjsSchema,
     CjsSchema as schema,
     impl,

package/src/shader/index.js

@@ -1 +1 @@
-export * from "./shaderStages.js";
+export * from "./shaderStages.js";

package/src/shader/shaderStages.js

@@ -1,37 +1,37 @@
-/**
- * Canonical shader stage tokens.
- */
-export const ShaderStage = Object.freeze({
-    VERTEX: "vertex",
-    FRAGMENT: "fragment",
-    PIXEL: "pixel",
-    COMPUTE: "compute",
-    GEOMETRY: "geometry",
-    HULL: "hull",
-    DOMAIN: "domain"
-});
-
-/**
- * Canonical shader model/profile tokens.
- */
-export const ShaderModel = Object.freeze({
-    UNKNOWN: "unknown",
-    SM2: "sm2",
-    SM3: "sm3",
-    SM4: "sm4",
-    SM5: "sm5",
-    SM6: "sm6",
-    GLSL_ES_300: "glsl-es-300",
-    WGSL: "wgsl"
-});
-
-/**
- * Normalize a shader stage token.
- *
- * @param {string} stage Shader stage token.
- * @returns {string} Canonical lowercase token.
- */
-export function normalizeShaderStage(stage)
-{
-    return stage ? String(stage).trim().toLowerCase() : "";
-}
+/**
+ * Canonical shader stage tokens.
+ */
+export const ShaderStage = Object.freeze({
+    VERTEX: "vertex",
+    FRAGMENT: "fragment",
+    PIXEL: "pixel",
+    COMPUTE: "compute",
+    GEOMETRY: "geometry",
+    HULL: "hull",
+    DOMAIN: "domain"
+});
+
+/**
+ * Canonical shader model/profile tokens.
+ */
+export const ShaderModel = Object.freeze({
+    UNKNOWN: "unknown",
+    SM2: "sm2",
+    SM3: "sm3",
+    SM4: "sm4",
+    SM5: "sm5",
+    SM6: "sm6",
+    GLSL_ES_300: "glsl-es-300",
+    WGSL: "wgsl"
+});
+
+/**
+ * Normalize a shader stage token.
+ *
+ * @param {string} stage Shader stage token.
+ * @returns {string} Canonical lowercase token.
+ */
+export function normalizeShaderStage(stage)
+{
+    return stage ? String(stage).trim().toLowerCase() : "";
+}