@scenoco-three/core 0.1.0

package/dist/core/Registry.d.ts

@@ -0,0 +1,55 @@
+import type { Component } from './Component.js';
+export type ComponentCtor = new () => Component;
+/**
+ * Primitive/math property wire types. Each maps to a canonical XML attribute
+ * format (defined in dsl/types.ts) and an XSD encoding:
+ *   float/int/bool/string — native XSD types
+ *   vec2/vec3 — space-separated numbers, A-Frame/X3D style: "0 2.5 -5"
+ *   euler     — degrees, space-separated: "0 90 0"
+ *   color     — "#rrggbb" or a CSS color name
+ *   node      — Object3D reference by scene path: "Turbine_01/Blade"
+ *   prefab    — a `.prefab.xml` file reference, resolved at build time to an
+ *               embedded prefab bundle; the field receives a spawnable PrefabRef
+ *
+ * A property may instead be typed with a Component class (Unity/Cocos-style
+ * typed reference); its XML value is a node path resolved to that node's
+ * component of the declared type.
+ */
+export type PropType = 'float' | 'int' | 'bool' | 'string' | 'vec2' | 'vec3' | 'euler' | 'color' | 'node' | 'prefab';
+export interface PropertyMeta {
+    type: PropType | ComponentCtor;
+    /**
+     * Default in compiled form (number/boolean/string, or number[] for vec/euler/
+     * color-as-array). Used for XSD/docs generation and bundle default-elision.
+     */
+    default?: number | boolean | string | number[];
+    required?: boolean;
+    description?: string;
+}
+/**
+ * Scalar property types parse from text. Reference kinds — `'node'`, `'prefab'`,
+ * and Component classes — are resolved against the scene, not parsed as scalars.
+ */
+export declare function isScalarType(t: PropertyMeta['type']): t is Exclude<PropType, 'node' | 'prefab'>;
+export interface ComponentMeta {
+    /** XML tag name inside <Components>. */
+    name: string;
+    description?: string;
+    /** Attribute name → metadata, in declaration order (subclass first, then inherited). */
+    properties: Map<string, PropertyMeta>;
+}
+export interface RegisteredComponent {
+    meta: ComponentMeta;
+    ctor: ComponentCtor;
+}
+declare class EngineRegistry {
+    private readonly components;
+    registerComponent(meta: ComponentMeta, ctor: ComponentCtor): void;
+    /** Mainly for tests and future hot-reload support. */
+    unregisterComponent(name: string): boolean;
+    getComponent(name: string): RegisteredComponent | undefined;
+    componentNames(): string[];
+}
+/** Global registry indexing all available components (and, later, node tags). */
+export declare const Registry: EngineRegistry;
+export {};

package/dist/core/Registry.js

@@ -0,0 +1,28 @@
+/**
+ * Scalar property types parse from text. Reference kinds — `'node'`, `'prefab'`,
+ * and Component classes — are resolved against the scene, not parsed as scalars.
+ */
+export function isScalarType(t) {
+    return typeof t === 'string' && t !== 'node' && t !== 'prefab';
+}
+class EngineRegistry {
+    components = new Map();
+    registerComponent(meta, ctor) {
+        if (this.components.has(meta.name)) {
+            throw new Error(`Component "${meta.name}" is already registered`);
+        }
+        this.components.set(meta.name, { meta, ctor });
+    }
+    /** Mainly for tests and future hot-reload support. */
+    unregisterComponent(name) {
+        return this.components.delete(name);
+    }
+    getComponent(name) {
+        return this.components.get(name);
+    }
+    componentNames() {
+        return [...this.components.keys()];
+    }
+}
+/** Global registry indexing all available components (and, later, node tags). */
+export const Registry = new EngineRegistry();

package/dist/core/System.d.ts

@@ -0,0 +1,33 @@
+import type { Component } from './Component.js';
+import type { Engine } from './Engine.js';
+/**
+ * An ECS-hybrid system: registered with `@system(SomeComponent)`, the engine
+ * auto-runs it while the loaded scene contains at least one component of that
+ * type and keeps `this.components` populated with the live set. The system owns
+ * the behaviour; the components are plain data (they keep their own lifecycle —
+ * this is additive, à la Unity DOTS hybrid).
+ *
+ *   @system(RigidBody)
+ *   class PhysicsSystem extends System<RigidBody> {
+ *     override fixedStep(dt) { for (const rb of this.components) { … } }
+ *   }
+ *
+ * The engine drives it alongside component lifecycles: `fixedStep` runs inside
+ * the fixed-timestep loop (after components' `fixedUpdate`), `step` once per
+ * frame (after `update`). Config comes from a singleton attachment, reachable
+ * via `this.engine.findAttachment(SomeAttachment)`.
+ */
+export declare abstract class System<T extends Component = Component> {
+    /** Owning engine. Assigned before onAttach. */
+    engine: Engine;
+    /** The live set of components of this system's type — maintained by the engine. */
+    readonly components: readonly T[];
+    /** Once, when the engine starts running the system (its component type appeared). */
+    onAttach?(): void;
+    /** Fixed-rate step, for deterministic simulation (physics world step, …). */
+    fixedStep?(fixedDt: number): void;
+    /** Variable-rate step, once per frame. */
+    step?(dt: number): void;
+    /** Once, when the system stops (scene unload / dispose). */
+    onDetach?(): void;
+}

package/dist/core/System.js

@@ -0,0 +1,23 @@
+/**
+ * An ECS-hybrid system: registered with `@system(SomeComponent)`, the engine
+ * auto-runs it while the loaded scene contains at least one component of that
+ * type and keeps `this.components` populated with the live set. The system owns
+ * the behaviour; the components are plain data (they keep their own lifecycle —
+ * this is additive, à la Unity DOTS hybrid).
+ *
+ *   @system(RigidBody)
+ *   class PhysicsSystem extends System<RigidBody> {
+ *     override fixedStep(dt) { for (const rb of this.components) { … } }
+ *   }
+ *
+ * The engine drives it alongside component lifecycles: `fixedStep` runs inside
+ * the fixed-timestep loop (after components' `fixedUpdate`), `step` once per
+ * frame (after `update`). Config comes from a singleton attachment, reachable
+ * via `this.engine.findAttachment(SomeAttachment)`.
+ */
+export class System {
+    /** Owning engine. Assigned before onAttach. */
+    engine;
+    /** The live set of components of this system's type — maintained by the engine. */
+    components = [];
+}

package/dist/core/decorators.d.ts

@@ -0,0 +1,50 @@
+import type { Object3D } from 'three';
+import { type PropertyMeta } from './Registry.js';
+import type { ComponentCtor } from './Registry.js';
+import { type AttachContext, type AttachTarget, type ChildRules } from './NodeRegistry.js';
+export interface ComponentOptions {
+    /** XML tag name inside <Components>. */
+    name: string;
+    description?: string;
+}
+/**
+ * Declares an XML-exposed property on a field (Cocos `@property` style). Used by
+ * components, nodes, and attachments. Two forms:
+ *   @property({ type: 'float', default: 1 })  — primitive/math property
+ *   @property(SomeComponent)                  — typed reference (components only)
+ */
+export declare function property(meta: PropertyMeta | ComponentCtor): (proto: object, key: string | symbol) => void;
+/** Registers a Component subclass under its XML tag name (Cocos `@ccclass` style). */
+export declare function component(options: ComponentOptions): <T extends ComponentCtor>(target: T) => void;
+export interface NodeOptions {
+    /** XML element name (mirrors the Three.js class). */
+    name: string;
+    description?: string;
+    /** Override the default child rules (object3d children + <Components>). */
+    children?: Partial<ChildRules>;
+    /** `'scene'` only for the root; everything else (the default) is `'object3d'`. */
+    kind?: 'scene' | 'object3d';
+}
+/** Registers an Object3D-family node tag (lights, cameras, meshes, groups, …). */
+export declare function node(options: NodeOptions): (target: new () => {
+    build(): Object3D;
+}) => void;
+export interface AttachmentOptions {
+    /** XML element name. */
+    name: string;
+    description?: string;
+    /** Node(s) this attaches to: an Object3D class (subclass-aware) or a node tag. */
+    target: AttachTarget;
+    /** Cardinality bucket on the target (e.g. 'geometry', 'material', 'fog'). */
+    group: string;
+    /** The target needs at least one attachment of this group. Default false. */
+    required?: boolean;
+    /** At most one attachment of this group per target. Default true. */
+    unique?: boolean;
+}
+/** Registers an attachment tag — a leaf that configures its target node. */
+export declare function attachment(options: AttachmentOptions): (target: new () => {
+    attach(ctx: AttachContext): void;
+}) => void;
+/** Registers an ECS-hybrid system that processes all components of `componentType`. */
+export declare function system(componentType: abstract new (...args: never[]) => object): (target: new () => unknown) => void;

package/dist/core/decorators.js

@@ -0,0 +1,142 @@
+import { Registry } from './Registry.js';
+import { registerAttachment, registerNode, registerSystem, spatialChildren, } from './NodeRegistry.js';
+// SceNoCo uses legacy (experimentalDecorators) decorators, like Cocos Creator.
+// Rationale: as of 2026 the TC39 standard decorators are still not lowered by
+// oxc (Vite 8 / Rolldown), so a library shipping them breaks consumers' builds.
+//
+// One authoring idiom for every registered, schema-bearing thing — a class with
+// `@property` fields plus a class decorator declaring its role:
+//   @component — behaviour on a node (lifecycle, MonoBehaviour-style)
+//   @node      — a scene-graph Object3D tag
+//   @attachment(target) — a leaf that configures a node (geometry/material/setting)
+//   @system(Component)  — an ECS-hybrid batch processor for a component type
+/** Key under which @property accumulates metadata on the constructor. */
+const PROPS = Symbol.for('scenoco:properties');
+/**
+ * Declares an XML-exposed property on a field (Cocos `@property` style). Used by
+ * components, nodes, and attachments. Two forms:
+ *   @property({ type: 'float', default: 1 })  — primitive/math property
+ *   @property(SomeComponent)                  — typed reference (components only)
+ */
+export function property(meta) {
+    const normalized = typeof meta === 'function' ? { type: meta } : meta;
+    return function (proto, key) {
+        if (typeof proto === 'function') {
+            throw new Error(`@property cannot decorate static field "${String(key)}"`);
+        }
+        if (typeof key !== 'string') {
+            throw new Error('@property fields must have string (non-symbol) names');
+        }
+        const ctor = proto.constructor;
+        let bag = ctor[PROPS];
+        if (!Object.hasOwn(ctor, PROPS)) {
+            bag = Object.create(bag ?? null);
+            Object.defineProperty(ctor, PROPS, { value: bag, configurable: true });
+        }
+        bag[key] = normalized;
+    };
+}
+/** Collect every @property (own + inherited) declared on a class, in order. */
+function collectProperties(target) {
+    const bag = target[PROPS];
+    const properties = new Map();
+    for (const key in bag)
+        properties.set(key, bag[key]);
+    return properties;
+}
+/** Registers a Component subclass under its XML tag name (Cocos `@ccclass` style). */
+export function component(options) {
+    return function (target) {
+        assertTagName(options.name);
+        Registry.registerComponent({ name: options.name, description: options.description, properties: collectProperties(target) }, target);
+    };
+}
+/** Registers an Object3D-family node tag (lights, cameras, meshes, groups, …). */
+export function node(options) {
+    return function (target) {
+        const { attrs, names } = readAttrs(target, options.name);
+        const build = (a) => {
+            const inst = new target();
+            assign(inst, names, a);
+            return inst.build();
+        };
+        // Probe the produced Three.js class (for attachment target matching). Build
+        // with no attrs so fields keep their initializers.
+        let produces;
+        try {
+            produces = build({}).constructor;
+        }
+        catch {
+            produces = undefined;
+        }
+        registerNode({
+            tag: options.name,
+            kind: options.kind ?? 'object3d',
+            ...(options.description !== undefined ? { description: options.description } : {}),
+            attrs,
+            children: spatialChildren(options.children),
+            build,
+            ...(produces ? { produces } : {}),
+        });
+    };
+}
+/** Registers an attachment tag — a leaf that configures its target node. */
+export function attachment(options) {
+    return function (target) {
+        const { attrs, names } = readAttrs(target, options.name);
+        registerAttachment({
+            tag: options.name,
+            ...(options.description !== undefined ? { description: options.description } : {}),
+            attrs,
+            target: options.target,
+            group: options.group,
+            required: options.required ?? false,
+            unique: options.unique ?? true,
+            make: (a) => {
+                const inst = new target();
+                assign(inst, names, a);
+                return inst;
+            },
+        });
+    };
+}
+// ---- systems ----------------------------------------------------------------
+/** Registers an ECS-hybrid system that processes all components of `componentType`. */
+export function system(componentType) {
+    return function (target) {
+        registerSystem({ ctor: target, componentType });
+    };
+}
+// ---- shared internals -------------------------------------------------------
+/** Read a tag's `@property` fields into the registry's NodeAttr shape. */
+function readAttrs(target, tag) {
+    assertTagName(tag);
+    const props = collectProperties(target);
+    const attrs = {};
+    for (const [name, meta] of props) {
+        if (typeof meta.type !== 'string' || meta.type === 'node') {
+            throw new Error(`<${tag}> @property "${name}" must use a scalar type (float/int/bool/string/vec2/vec3/euler/color); references are for components only`);
+        }
+        attrs[name] = {
+            type: meta.type,
+            ...(meta.default !== undefined ? { default: meta.default } : {}),
+            ...(meta.required ? { required: true } : {}),
+            ...(meta.description !== undefined ? { description: meta.description } : {}),
+        };
+    }
+    return { attrs, names: [...props.keys()] };
+}
+/** Assign compiled attr values onto a fresh instance, skipping undefined (keeps initializers). */
+function assign(inst, names, attrs) {
+    const target = inst;
+    for (const name of names) {
+        const v = attrs[name];
+        if (v !== undefined)
+            target[name] = v;
+    }
+}
+function assertTagName(name) {
+    if (name.includes('/')) {
+        throw new Error(`Tag/component name "${name}" may not contain "/" (reserved for prefab scope paths)`);
+    }
+}

package/dist/dsl/PrefabRef.d.ts

@@ -0,0 +1,36 @@
+import type { Object3D } from 'three';
+import type { SceneInstance } from '../core/Engine.js';
+import type { CompiledScene } from './compiled.js';
+/** How a prefab is instantiated — the Engine supplies this when wiring props. */
+export type SpawnFn = (compiled: CompiledScene, parent?: Object3D) => SceneInstance;
+export interface SpawnOptions {
+    /** Parent for the spawned subtree. Defaults to the owning component's node. */
+    parent?: Object3D;
+    /** Local position to apply to the spawned root after spawning. */
+    position?: [number, number, number];
+}
+/**
+ * The value a `@property({ type: 'prefab' })` field receives: a handle that
+ * spawns the build-time-embedded prefab at runtime — Unity/Cocos `Instantiate`,
+ * without the component touching the bundle/instantiate machinery.
+ *
+ *   @property({ type: 'prefab' }) brick: PrefabRef | null = null;
+ *   // …
+ *   const instance = this.brick!.spawn({ position: [x, y, 0] });
+ *   // later: instance.destroy();
+ *
+ * Spawned instances are owned by the engine; destroy them yourself (or let the
+ * owning component destroy them in onDestroy) — they are *not* torn down by the
+ * scene unload that removes the spawning component's subtree.
+ */
+export declare class PrefabRef {
+    private readonly compiled;
+    private readonly spawnFn;
+    /** Default parent — the node of the component that holds this reference. */
+    private readonly defaultParent?;
+    constructor(compiled: CompiledScene, spawnFn: SpawnFn, 
+    /** Default parent — the node of the component that holds this reference. */
+    defaultParent?: Object3D | undefined);
+    /** Spawn one instance of the prefab. Returns its handle (call `.destroy()` to remove). */
+    spawn(options?: SpawnOptions): SceneInstance;
+}

package/dist/dsl/PrefabRef.js

@@ -0,0 +1,33 @@
+/**
+ * The value a `@property({ type: 'prefab' })` field receives: a handle that
+ * spawns the build-time-embedded prefab at runtime — Unity/Cocos `Instantiate`,
+ * without the component touching the bundle/instantiate machinery.
+ *
+ *   @property({ type: 'prefab' }) brick: PrefabRef | null = null;
+ *   // …
+ *   const instance = this.brick!.spawn({ position: [x, y, 0] });
+ *   // later: instance.destroy();
+ *
+ * Spawned instances are owned by the engine; destroy them yourself (or let the
+ * owning component destroy them in onDestroy) — they are *not* torn down by the
+ * scene unload that removes the spawning component's subtree.
+ */
+export class PrefabRef {
+    compiled;
+    spawnFn;
+    defaultParent;
+    constructor(compiled, spawnFn, 
+    /** Default parent — the node of the component that holds this reference. */
+    defaultParent) {
+        this.compiled = compiled;
+        this.spawnFn = spawnFn;
+        this.defaultParent = defaultParent;
+    }
+    /** Spawn one instance of the prefab. Returns its handle (call `.destroy()` to remove). */
+    spawn(options = {}) {
+        const instance = this.spawnFn(this.compiled, options.parent ?? this.defaultParent);
+        if (options.position)
+            instance.root.position.fromArray(options.position);
+        return instance;
+    }
+}

package/dist/dsl/bundle-format.d.ts

@@ -0,0 +1,74 @@
+/**
+ * SceNoCo scene bundle — the optimized, XML-free format the runtime loads.
+ *
+ * Design follows the Cocos Creator compiled-bundle principles, adapted to the
+ * fact that SceNoCo's type system is *known to the runtime* (the registry), so
+ * we never ship class/schema definitions — only a string pool and per-instance
+ * data. Optimizations applied:
+ *
+ *  - **Fixed-index arrays**, not keyed objects (no key strings on the wire).
+ *  - **Frequency-sorted string pool**: tags, ids, and string values are interned
+ *    once; instances reference them by integer (small ints in any varint codec).
+ *  - **Default-value elision via bitmask**: only attributes that differ from the
+ *    registry default are stored; a per-tag mask says which. A node at defaults
+ *    carries almost no data.
+ *  - **TRS special-case**: an identity transform is omitted entirely.
+ *  - **Bitwise-NOT reference encoding**: a reference prop stores `i` for
+ *    component[i] or `~i` for node[i] — one integer, no wrapper (unambiguous
+ *    because the registry knows which props are references).
+ *
+ * v1 is JSON; the array-positional shape makes a later msgpack/binary wrapper a
+ * drop-in. The decoder lives in the runtime; the encoder in the compiler.
+ */
+import type { CompiledScalar } from './types.js';
+/** A JSON-native wire value used positionally inside bundle records. */
+export type BundleValue = CompiledScalar;
+/**
+ * What a bundle is for: a `scene` is loaded as the whole scene
+ * (`engine.loadScene`); a `prefab` is a reusable subtree spawned at runtime
+ * (`engine.instantiate`). Absent (older 3-element bundles) means `scene`.
+ */
+export type BundleKind = 'scene' | 'prefab';
+export type Bundle = [version: number, strings: string[], scene: BundleAsset, kind?: BundleKind];
+/** The bundle's kind, defaulting to `scene` for bundles that predate the marker. */
+export declare function bundleKind(bundle: Bundle): BundleKind;
+export type BundleAsset = [
+    nodes: BundleNode[],
+    /** Content-addressed attachment pool (geometry/material/fog/…). */
+    attachments: BundleTag[],
+    components: BundleComponent[],
+    root: number,
+    /**
+     * Embedded prefab sub-bundles, referenced by `prefab` props (one index each).
+     * Appended only when the scene uses a prefab prop, so prefab-free bundles keep
+     * their 4-element asset shape unchanged.
+     */
+    prefabs?: Bundle[]
+];
+/** Attachment: `[tagStringIndex, attrMask, ...nonDefaultValues]`. */
+export type BundleTag = [number, number, ...BundleValue[]];
+/**
+ * Node: `[tagStringIndex, flags, attrMask, ...nonDefaultAttrValues, ...extras]`.
+ * `extras` appear in flag-bit order: id, transform, attachments, components,
+ * children (only those whose flag bit is set).
+ */
+export type BundleNode = BundleValue[];
+/**
+ * Component: `[typeStringIndex, flags, propMask, ...propValues, id?]`.
+ * Only the `id` flag bit is used in `flags`; `propMask` selects which of the
+ * component's registered properties are present.
+ */
+export type BundleComponent = BundleValue[];
+export declare const BUNDLE_VERSION = 3;
+/** Node flag bits (presence of optional sections). */
+export declare const NodeFlag: {
+    readonly Id: number;
+    readonly Transform: number;
+    readonly Attachments: number;
+    readonly Components: number;
+    readonly Children: number;
+};
+/** Component flag bits. */
+export declare const ComponentFlag: {
+    readonly Id: number;
+};

package/dist/dsl/bundle-format.js

@@ -0,0 +1,41 @@
+/**
+ * SceNoCo scene bundle — the optimized, XML-free format the runtime loads.
+ *
+ * Design follows the Cocos Creator compiled-bundle principles, adapted to the
+ * fact that SceNoCo's type system is *known to the runtime* (the registry), so
+ * we never ship class/schema definitions — only a string pool and per-instance
+ * data. Optimizations applied:
+ *
+ *  - **Fixed-index arrays**, not keyed objects (no key strings on the wire).
+ *  - **Frequency-sorted string pool**: tags, ids, and string values are interned
+ *    once; instances reference them by integer (small ints in any varint codec).
+ *  - **Default-value elision via bitmask**: only attributes that differ from the
+ *    registry default are stored; a per-tag mask says which. A node at defaults
+ *    carries almost no data.
+ *  - **TRS special-case**: an identity transform is omitted entirely.
+ *  - **Bitwise-NOT reference encoding**: a reference prop stores `i` for
+ *    component[i] or `~i` for node[i] — one integer, no wrapper (unambiguous
+ *    because the registry knows which props are references).
+ *
+ * v1 is JSON; the array-positional shape makes a later msgpack/binary wrapper a
+ * drop-in. The decoder lives in the runtime; the encoder in the compiler.
+ */
+/** The bundle's kind, defaulting to `scene` for bundles that predate the marker. */
+export function bundleKind(bundle) {
+    return bundle[3] ?? 'scene';
+}
+// v3 unifies the old geometries/materials/settings pools into one `attachments`
+// pool, and a node references its attachments by an index list.
+export const BUNDLE_VERSION = 3;
+/** Node flag bits (presence of optional sections). */
+export const NodeFlag = {
+    Id: 1 << 0,
+    Transform: 1 << 1,
+    Attachments: 1 << 2,
+    Components: 1 << 3,
+    Children: 1 << 4,
+};
+/** Component flag bits. */
+export const ComponentFlag = {
+    Id: 1 << 0,
+};

package/dist/dsl/bundle-shared.d.ts

@@ -0,0 +1,18 @@
+import { type PropertyMeta } from '../core/Registry.js';
+import { type NodeAttr } from './nodes.js';
+import type { CompiledScalar } from './types.js';
+/**
+ * Schema helpers shared by the bundle encoder and decoder, so both agree on the
+ * attribute/property *order* (which the bitmasks index into) and on which
+ * values are interned strings. Both derive the schema from the same registries.
+ */
+/** Ordered [name, meta] of a node tag's type-specific attributes. */
+export declare function nodeAttrEntries(tag: string): [string, NodeAttr][];
+/** Ordered [name, meta] of an attachment tag's attributes. */
+export declare function attachmentAttrEntries(tag: string): [string, NodeAttr][];
+/** Ordered [name, meta] of a component type's properties. */
+export declare function componentPropEntries(type: string): [string, PropertyMeta][];
+/** Number of set bits — how many values a mask selects. */
+export declare function popcount(n: number): number;
+/** Structural equality for compiled scalar values (numbers, bools, vec arrays). */
+export declare function valueEquals(a: CompiledScalar | undefined, b: CompiledScalar | undefined): boolean;

package/dist/dsl/bundle-shared.js

@@ -0,0 +1,33 @@
+import { Registry } from '../core/Registry.js';
+import { getAttachmentDef, getNodeDef } from './nodes.js';
+/**
+ * Schema helpers shared by the bundle encoder and decoder, so both agree on the
+ * attribute/property *order* (which the bitmasks index into) and on which
+ * values are interned strings. Both derive the schema from the same registries.
+ */
+/** Ordered [name, meta] of a node tag's type-specific attributes. */
+export function nodeAttrEntries(tag) {
+    return Object.entries(getNodeDef(tag).attrs);
+}
+/** Ordered [name, meta] of an attachment tag's attributes. */
+export function attachmentAttrEntries(tag) {
+    return Object.entries(getAttachmentDef(tag).attrs);
+}
+/** Ordered [name, meta] of a component type's properties. */
+export function componentPropEntries(type) {
+    return [...Registry.getComponent(type).meta.properties];
+}
+/** Number of set bits — how many values a mask selects. */
+export function popcount(n) {
+    let count = 0;
+    for (let v = n >>> 0; v !== 0; v >>= 1)
+        count += v & 1;
+    return count;
+}
+/** Structural equality for compiled scalar values (numbers, bools, vec arrays). */
+export function valueEquals(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => x === b[i]);
+    }
+    return a === b;
+}

package/dist/dsl/compiled.d.ts

@@ -0,0 +1,64 @@
+import type { CompiledScalar } from './types.js';
+/**
+ * Compiled scene: a flat, indexed structure (Cocos Creator scene-format style).
+ * All cross-references are integer indices, so the runtime instantiates with no
+ * name lookups or string parsing. This is the ergonomic intermediate the
+ * compiler emits and the bundle decoder reconstructs.
+ *
+ * These are **pure types with no runtime imports**, so the runtime can use them
+ * without pulling in the XML parser/validator (which live in compile.ts).
+ */
+export interface CompiledScene {
+    /** Index of the root <Scene> node (always 0). */
+    root: number;
+    nodes: CompiledNode[];
+    /** Content-addressed pool of attachments (geometry/material/fog/…), shared by index. */
+    attachments: CompiledAsset[];
+    components: CompiledComponent[];
+    /**
+     * Embedded prefab subtrees referenced by `@property({ type: 'prefab' })`
+     * props, one self-contained CompiledScene each (resolved + compiled at build
+     * time). A prefab prop stores `{ prefab: i }`; the runtime hands the component
+     * a PrefabRef bound to `prefabs[i]`. Present only when the scene uses one.
+     */
+    prefabs?: CompiledScene[];
+}
+/** A resolved reference: an index into nodes[], components[], or prefabs[]. */
+export type CompiledRef = {
+    node: number;
+} | {
+    component: number;
+} | {
+    prefab: number;
+};
+export type CompiledValue = CompiledScalar | CompiledRef;
+export interface CompiledTransform {
+    position: number[];
+    rotation: number[];
+    scale: number[];
+    visible: boolean;
+}
+export interface CompiledNode {
+    tag: string;
+    /** Author-assigned id (maps to Object3D.name at runtime). */
+    id?: string;
+    parent: number;
+    children: number[];
+    transform: CompiledTransform;
+    /** Type-specific scalar attrs (e.g. light color/intensity, camera fov). */
+    attrs: Record<string, CompiledScalar>;
+    /** Indices into the scene's attachments[] pool (geometry/material/settings/…). */
+    attachments: number[];
+    components: number[];
+}
+export interface CompiledAsset {
+    tag: string;
+    attrs: Record<string, CompiledScalar>;
+}
+export interface CompiledComponent {
+    type: string;
+    id?: string;
+    node: number;
+    /** Only explicitly-set props; omitted props keep the component's field defaults. */
+    props: Record<string, CompiledValue>;
+}

package/dist/dsl/compiled.js

@@ -0,0 +1 @@
+export {};

package/dist/dsl/deserialize.d.ts

@@ -0,0 +1,9 @@
+import { type Bundle } from './bundle-format.js';
+import type { CompiledScene } from './compiled.js';
+/**
+ * Decode a bundle into a CompiledScene. This is the runtime's only "loader" —
+ * it contains no XML and no parser, just array indexing against the registry
+ * schema. The redundant back-pointers (`node.parent`, `component.node`) are
+ * reconstructed from the children/components arrays rather than stored.
+ */
+export declare function deserializeBundle(bundle: Bundle): CompiledScene;