@scenoco-three/core 0.1.0

package/dist/core/Engine.js

@@ -0,0 +1,468 @@
+import { PerspectiveCamera, Scene, Vector2, WebGLRenderer } from 'three';
+import { Registry } from './Registry.js';
+import { bundleKind } from '../dsl/bundle-format.js';
+import { deserializeBundle } from '../dsl/deserialize.js';
+import { allSystemDefs } from '../dsl/nodes.js';
+import { instantiateScene } from '../dsl/instantiate.js';
+/**
+ * Core runtime: owns the Three.js scene graph, the render loop, and the
+ * lifecycles of all attached components.
+ *
+ * Without a canvas the engine runs headless — `tick(dt)` advances the
+ * simulation manually, which is how tests and CLI tooling drive it.
+ */
+export class Engine {
+    scene = new Scene();
+    /** The engine's built-in fallback camera, used until a scene supplies one. */
+    camera;
+    renderer;
+    /** Camera the renderer currently draws through (defaults to `camera`). */
+    activeCamera;
+    components = [];
+    byNode = new Map();
+    byId = new Map();
+    systems = [];
+    /** Each running system → the component type its `components` query is kept in sync with. */
+    systemQueries = new Map();
+    rendererSize = new Vector2();
+    /** Seconds per fixed step; accumulator carries leftover frame time. */
+    fixedTimeStep;
+    fixedAccumulator = 0;
+    rafId;
+    lastFrameTime;
+    /** Root object of the currently loaded scene (from loadScene), if any. */
+    sceneRoot;
+    /** Components owned by the loaded scene — the only ones disposeScene removes. */
+    sceneComponents = [];
+    /** Systems auto-run for the loaded scene — removed on unload. */
+    sceneSystems = [];
+    /** Live attachment instances of the loaded scene (retained for findAttachment). */
+    sceneAttachments = [];
+    /** Live spawned subtrees (from instantiate), so dispose() can clean them up. */
+    instances = new Set();
+    constructor(options = {}) {
+        this.fixedTimeStep = options.fixedTimeStep ?? 1 / 60;
+        this.camera = new PerspectiveCamera(60, 1, 0.1, 1000);
+        this.camera.position.set(0, 2, 6);
+        this.camera.lookAt(0, 0, 0);
+        this.activeCamera = this.camera;
+        if (options.canvas) {
+            this.renderer = new WebGLRenderer({ canvas: options.canvas, antialias: true });
+            this.renderer.setPixelRatio(Math.min(globalThis.devicePixelRatio ?? 1, 2));
+            if (options.autoStart !== false)
+                this.start();
+        }
+    }
+    addComponent(node, type, props) {
+        let ctor;
+        if (typeof type === 'string') {
+            const entry = Registry.getComponent(type);
+            if (!entry) {
+                const known = Registry.componentNames().join(', ') || '(none)';
+                throw new Error(`Unknown component "${type}". Registered components: ${known}`);
+            }
+            ctor = entry.ctor;
+        }
+        else {
+            ctor = type;
+        }
+        const instance = new ctor();
+        instance.node = node;
+        if (props)
+            Object.assign(instance, props);
+        this.registerComponent(node, instance);
+        this.initComponent(instance);
+        return instance;
+    }
+    /** Bookkeeping only: track the instance without running any lifecycle hook. */
+    registerComponent(node, instance) {
+        instance.engine = this;
+        this.components.push(instance);
+        let list = this.byNode.get(node);
+        if (!list)
+            this.byNode.set(node, (list = []));
+        list.push(instance);
+        // Index by id for findComponent. First registration wins on a duplicate
+        // (dynamically spawned prefab instances may reuse internal ids).
+        if (instance.id !== undefined && !this.byId.has(instance.id))
+            this.byId.set(instance.id, instance);
+        // Keep each system's live query in sync.
+        for (const [system, type] of this.systemQueries) {
+            if (instance instanceof type)
+                system.components.push(instance);
+        }
+    }
+    /** Run onLoad + onEnable for an already-registered instance. */
+    initComponent(instance) {
+        instance.onLoad?.();
+        instance._loaded = true;
+        if (instance.enabled)
+            instance.onEnable?.();
+    }
+    /** Detach a component, running onDisable (if enabled) and onDestroy. */
+    removeComponent(instance) {
+        const index = this.components.indexOf(instance);
+        if (index === -1)
+            return;
+        this.components.splice(index, 1);
+        const list = this.byNode.get(instance.node);
+        if (list) {
+            const i = list.indexOf(instance);
+            if (i !== -1)
+                list.splice(i, 1);
+            if (list.length === 0)
+                this.byNode.delete(instance.node);
+        }
+        if (instance.id !== undefined && this.byId.get(instance.id) === instance)
+            this.byId.delete(instance.id);
+        // Drop it from any system query it belonged to.
+        for (const [system, type] of this.systemQueries) {
+            if (!(instance instanceof type))
+                continue;
+            const q = system.components;
+            const qi = q.indexOf(instance);
+            if (qi !== -1)
+                q.splice(qi, 1);
+        }
+        if (instance.enabled && instance._loaded)
+            instance.onDisable?.();
+        instance.onDestroy?.();
+    }
+    getComponents(node) {
+        return this.byNode.get(node) ?? [];
+    }
+    /**
+     * Register an engine subsystem instance. Injects `system.engine`, seeds its
+     * `components` query (from its `@system(Type)` registration), and runs
+     * `onAttach`. Usually the engine does this for you (a registered `@system`
+     * auto-runs when its component type appears); call it directly for manual use.
+     */
+    addSystem(system) {
+        system.engine = this;
+        const type = allSystemDefs().find((d) => system instanceof d.ctor)?.componentType;
+        if (type) {
+            this.systemQueries.set(system, type);
+            system.components.push(...this.components.filter((c) => c instanceof type));
+        }
+        this.systems.push(system);
+        system.onAttach?.();
+        return system;
+    }
+    /** The first running system assignable to `type` (Unity GetComponent style). */
+    getSystem(type) {
+        for (const s of this.systems)
+            if (s instanceof type)
+                return s;
+        return undefined;
+    }
+    /** Remove a subsystem, running its `onDetach`. */
+    removeSystem(system) {
+        const i = this.systems.indexOf(system);
+        if (i === -1)
+            return;
+        this.systems.splice(i, 1);
+        this.systemQueries.delete(system);
+        system.onDetach?.();
+    }
+    /**
+     * The live instance of an attachment type in the loaded scene (e.g. a system
+     * reads `engine.findAttachment(Physics)?.gravity`). Singleton config attachments
+     * are the typical use.
+     */
+    findAttachment(type) {
+        for (const a of this.sceneAttachments)
+            if (a instanceof type)
+                return a;
+        return undefined;
+    }
+    /**
+     * Find an Object3D by its scene `id` (e.g. `findObject('Turbine_01')`, or a
+     * scoped prefab-instance internal `findObject('t1/blade')`). Searches the whole
+     * loaded scene and any spawned instances; returns the first match.
+     */
+    findObject(id) {
+        return this.scene.getObjectByName(id);
+    }
+    /**
+     * Find a component by id — mirroring the `#id` references used in XML. Resolves
+     * a component's own id first; failing that, treats `id` as a node id and returns
+     * the (first) component on that node, optionally narrowed to `type`.
+     *
+     * `type` may be a class reference OR a registered component name string (e.g.
+     * `'GameManager'`). The string form avoids the `import type` footgun: a type-only
+     * import is erased at runtime, making the class reference undefined.
+     */
+    findComponent(id, type) {
+        const ctor = typeof type === 'string'
+            ? Registry.getComponent(type)?.ctor
+            : type;
+        const direct = this.byId.get(id);
+        if (direct && (!ctor || direct instanceof ctor))
+            return direct;
+        const node = this.scene.getObjectByName(id);
+        if (node) {
+            for (const c of this.getComponents(node))
+                if (!ctor || c instanceof ctor)
+                    return c;
+        }
+        return undefined;
+    }
+    /** The camera the renderer draws through (a scene camera if one is active). */
+    get renderCamera() {
+        return this.activeCamera;
+    }
+    /**
+     * Render through a specific camera — e.g. one defined in the scene
+     * (`engine.setActiveCamera(engine.findObject('Main')!)`). `loadScene` already
+     * auto-selects the first camera it finds; this is for switching afterwards.
+     * Pass nothing to revert to the engine's built-in camera.
+     */
+    setActiveCamera(camera = this.camera) {
+        this.activeCamera = camera;
+    }
+    /**
+     * Load a scene from a pre-built bundle (or a CompiledScene), replacing any
+     * current one. Bundles are produced at build time by `scenoco/compiler`; the
+     * runtime never parses or validates XML. All components are instantiated and
+     * their references wired before any onLoad runs, so cross-component refs are
+     * valid from the first lifecycle hook.
+     *
+     * If the scene defines a camera, it becomes the active render camera; the
+     * engine's built-in camera is the fallback when it doesn't.
+     */
+    loadScene(source) {
+        if (Array.isArray(source) && bundleKind(source) === 'prefab') {
+            throw new Error('loadScene() received a prefab bundle — use engine.instantiate() to spawn a prefab.');
+        }
+        const compiled = Array.isArray(source) ? deserializeBundle(source) : source;
+        this.disposeScene();
+        // Attachments (geometry/material on nodes, fog/background on the scene) are
+        // applied during instantiation against the live scene/renderer.
+        const live = instantiateScene(compiled, this.instantiateContext());
+        this.sceneRoot = live.root;
+        this.sceneAttachments = live.attachments;
+        this.scene.add(live.root);
+        this.sceneComponents = this.initLive(live);
+        // Auto-run registered systems whose component type the scene contains.
+        this.sceneSystems = this.runSceneSystems();
+        const sceneCamera = findCamera(live.root);
+        if (sceneCamera)
+            this.setActiveCamera(sceneCamera);
+    }
+    /** Instantiate + run each registered @system whose component type is present. */
+    runSceneSystems() {
+        const started = [];
+        for (const def of allSystemDefs()) {
+            const alreadyRunning = this.systems.some((s) => s instanceof def.ctor);
+            const present = this.components.some((c) => c instanceof def.componentType);
+            if (alreadyRunning || !present)
+                continue;
+            started.push(this.addSystem(new def.ctor()));
+        }
+        return started;
+    }
+    /**
+     * Spawn a prefab (or any bundle/CompiledScene) as a subtree under `parent`
+     * (the scene root by default), at runtime — Unity/Cocos `Instantiate`.
+     * Returns a handle whose `destroy()` removes just this subtree; the loaded
+     * scene and other instances are untouched. References inside the prefab are
+     * already wired by index, so spawning the same prefab many times is safe.
+     */
+    instantiate(source, parent = this.scene) {
+        const compiled = Array.isArray(source) ? deserializeBundle(source) : source;
+        const live = instantiateScene(compiled, this.instantiateContext());
+        parent.add(live.root);
+        const components = this.initLive(live);
+        const instance = {
+            root: live.root,
+            destroy: () => {
+                if (!this.instances.delete(instance))
+                    return;
+                for (const c of components)
+                    this.removeComponent(c);
+                live.root.removeFromParent();
+                disposeObject(live.root);
+            },
+        };
+        this.instances.add(instance);
+        return instance;
+    }
+    /**
+     * Context for `instantiateScene`: the live scene/renderer (for attachments)
+     * and how a `prefab` prop spawns — `engine.instantiate`, so spawned subtrees
+     * are tracked and torn down by `dispose()`.
+     */
+    instantiateContext() {
+        return {
+            scene: this.scene,
+            ...(this.renderer ? { renderer: this.renderer } : {}),
+            spawn: (compiled, parent) => this.instantiate(compiled, parent),
+        };
+    }
+    /** Register + run onLoad/onEnable for a freshly instantiated subtree. */
+    initLive(live) {
+        const components = live.components.map(({ instance }) => instance);
+        for (const { instance, node } of live.components)
+            this.registerComponent(node, instance);
+        for (const { instance } of live.components)
+            this.initComponent(instance);
+        return components;
+    }
+    /**
+     * Remove the loaded scene: destroy its components (only those owned by the
+     * scene — manually attached ones and spawned instances survive) and release
+     * its GPU resources.
+     */
+    disposeScene() {
+        if (!this.sceneRoot)
+            return;
+        // Components first (a RigidBody.onDisable removes its body), then the
+        // subsystems they used (PhysicsSystem.onDetach frees the world).
+        for (const c of this.sceneComponents)
+            this.removeComponent(c);
+        this.sceneComponents = [];
+        for (const s of this.sceneSystems)
+            this.removeSystem(s);
+        this.sceneSystems = [];
+        this.sceneAttachments = [];
+        this.scene.remove(this.sceneRoot);
+        disposeObject(this.sceneRoot);
+        this.sceneRoot = undefined;
+        // Reset the built-in scene settings so they don't leak into the next scene.
+        this.scene.fog = null;
+        this.scene.background = null;
+        // The scene's camera is gone; fall back to the built-in one.
+        this.activeCamera = this.camera;
+    }
+    /**
+     * Advance the simulation by dt seconds, then render if a renderer exists.
+     * Phases, in order: fixed steps (`fixedUpdate` + subsystem `fixedStep`,
+     * repeated to drain the accumulator) → `start`/`update` → `lateUpdate` →
+     * subsystem `step` → render. Variable `update` still runs exactly once per
+     * tick, so existing components are unaffected.
+     */
+    tick(dt) {
+        // Fixed-timestep phase (deterministic; physics + fixedUpdate). The substep
+        // cap prevents a "spiral of death" after a long pause.
+        this.fixedAccumulator += dt;
+        let steps = 0;
+        while (this.fixedAccumulator >= this.fixedTimeStep && steps < MAX_FIXED_SUBSTEPS) {
+            this.fixedStep(this.fixedTimeStep);
+            this.fixedAccumulator -= this.fixedTimeStep;
+            steps++;
+        }
+        if (steps === MAX_FIXED_SUBSTEPS)
+            this.fixedAccumulator = 0; // drop the backlog
+        // Variable-rate phase: start (once) then update.
+        for (let i = 0; i < this.components.length; i++) {
+            const c = this.components[i];
+            if (!c.enabled || !c._loaded)
+                continue;
+            if (!c._started) {
+                c._started = true;
+                c.start?.();
+            }
+            c.update?.(dt);
+        }
+        // Late phase: after every update this frame.
+        for (let i = 0; i < this.components.length; i++) {
+            const c = this.components[i];
+            if (c.enabled && c._loaded)
+                c.lateUpdate?.(dt);
+        }
+        for (const s of this.systems)
+            s.step?.(dt);
+        if (this.renderer) {
+            this.resizeToCanvas();
+            this.renderer.render(this.scene, this.activeCamera);
+        }
+    }
+    /** One fixed step: components' fixedUpdate (apply forces/read), then subsystems step. */
+    fixedStep(fixedDt) {
+        for (let i = 0; i < this.components.length; i++) {
+            const c = this.components[i];
+            if (c.enabled && c._loaded)
+                c.fixedUpdate?.(fixedDt);
+        }
+        for (const s of this.systems)
+            s.fixedStep?.(fixedDt);
+    }
+    /** Start the requestAnimationFrame loop (no-op when already running or headless). */
+    start() {
+        if (this.rafId !== undefined || !this.renderer)
+            return;
+        this.lastFrameTime = undefined;
+        const loop = (time) => {
+            this.rafId = requestAnimationFrame(loop);
+            const dt = this.lastFrameTime === undefined ? 0 : (time - this.lastFrameTime) / 1000;
+            this.lastFrameTime = time;
+            // Clamp dt so background-tab pauses don't produce giant simulation steps.
+            this.tick(Math.min(dt, 0.1));
+        };
+        this.rafId = requestAnimationFrame(loop);
+    }
+    stop() {
+        if (this.rafId !== undefined) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = undefined;
+        }
+    }
+    /** Stop the loop, destroy all components/instances/subsystems, free GPU resources. */
+    dispose() {
+        this.stop();
+        for (const instance of [...this.instances])
+            instance.destroy();
+        this.disposeScene();
+        for (const c of [...this.components])
+            this.removeComponent(c);
+        for (const s of [...this.systems])
+            this.removeSystem(s);
+        this.renderer?.dispose();
+    }
+    resizeToCanvas() {
+        const renderer = this.renderer;
+        const canvas = renderer.domElement;
+        const width = canvas.clientWidth;
+        const height = canvas.clientHeight;
+        if (width === 0 || height === 0)
+            return;
+        renderer.getSize(this.rendererSize);
+        if (this.rendererSize.x !== width || this.rendererSize.y !== height) {
+            renderer.setSize(width, height, false);
+            // Keep the built-in camera's aspect current; update the active scene
+            // camera too when it's a perspective camera.
+            const aspect = width / height;
+            this.camera.aspect = aspect;
+            this.camera.updateProjectionMatrix();
+            const active = this.activeCamera;
+            if (active !== this.camera && active instanceof PerspectiveCamera) {
+                active.aspect = aspect;
+                active.updateProjectionMatrix();
+            }
+        }
+    }
+}
+/** Max fixed substeps per frame — caps catch-up work after a long pause. */
+const MAX_FIXED_SUBSTEPS = 5;
+/** Depth-first search for the first camera in a subtree (Object3D.isCamera). */
+function findCamera(root) {
+    let found;
+    root.traverse((o) => {
+        if (!found && o.isCamera)
+            found = o;
+    });
+    return found;
+}
+/** Release geometries and materials of every mesh in a subtree. */
+function disposeObject(root) {
+    root.traverse((object) => {
+        const mesh = object;
+        mesh.geometry?.dispose();
+        const material = mesh.material;
+        if (Array.isArray(material))
+            for (const m of material)
+                m.dispose();
+        else
+            material?.dispose?.();
+    });
+}

package/dist/core/NodeRegistry.d.ts

@@ -0,0 +1,99 @@
+import type { Object3D, Scene, WebGLRenderer } from 'three';
+import type { CompiledScalar, ScalarType } from '../dsl/types.js';
+/**
+ * The tag registry — the extensible counterpart to the component `Registry`.
+ *
+ * Two kinds of tag live here:
+ *  - **Nodes** (`@node`): scene-graph `Object3D` tags (`<Mesh>`, `<SpotLight>`, …).
+ *  - **Attachments** (`@attachment`): leaf config that attaches to and configures a
+ *    node — geometry/material on a mesh, fog/background on the scene. One concept
+ *    replaces the old geometry/material/setting kinds.
+ *
+ * Built-ins live one-per-file under `src/nodes/**` and self-register on import via
+ * the class decorators (see core/decorators.ts); projects register their own the
+ * same way (the compiler discovers those decorators like it discovers `@component`).
+ */
+export type NodeKind = 'scene' | 'object3d';
+export interface NodeAttr {
+    type: ScalarType;
+    /** Default in compiled form (number, boolean, number[], 0xRRGGBB). */
+    default?: CompiledScalar;
+    required?: boolean;
+    description?: string;
+}
+/** What a node may contain (attachments are governed separately, by target). */
+export interface ChildRules {
+    /** May contain child Object3D node tags. */
+    object3d: boolean;
+    /** May contain a single <Components> block. */
+    components: boolean;
+}
+export interface NodeDef {
+    tag: string;
+    kind: NodeKind;
+    description?: string;
+    /** Type-specific attributes (transform attrs are shared, see TRANSFORM_ATTRS). */
+    attrs: Record<string, NodeAttr>;
+    children: ChildRules;
+    /** Build the bare Three.js object (transforms are applied separately). */
+    build(attrs: Record<string, CompiledScalar>): Object3D;
+    /** The Object3D subclass this node builds — used to match attachment targets. */
+    produces?: AttachClass;
+}
+/** A node's runtime Object3D constructor (for attachment target matching). */
+export type AttachClass = abstract new (...args: never[]) => Object3D;
+/** Where an attachment may attach: an Object3D class (subclass-aware) or a node tag. */
+export type AttachTarget = AttachClass | AttachClass[] | string;
+/** What an attachment is given when the scene loads. `node` is the host. */
+export interface AttachContext<TNode extends Object3D = Object3D> {
+    node: TNode;
+    scene: Scene;
+    renderer?: WebGLRenderer;
+}
+/** A live attachment instance (created by the def, holds @property fields). */
+export interface AttachmentInstance {
+    attach(ctx: AttachContext): void;
+}
+export interface AttachmentDef {
+    tag: string;
+    description?: string;
+    attrs: Record<string, NodeAttr>;
+    /** The node(s) this attaches to. */
+    target: AttachTarget;
+    /** Cardinality bucket on the target (e.g. 'geometry', 'material', 'fog'). */
+    group: string;
+    /** The target needs at least one attachment of this group. */
+    required: boolean;
+    /** At most one attachment of this group per target (default true). */
+    unique: boolean;
+    /** Make a fresh instance and assign its attrs. */
+    make(attrs: Record<string, CompiledScalar>): AttachmentInstance;
+}
+export interface SystemDef {
+    ctor: new () => unknown;
+    /** The component type the engine feeds this system (single-type query, v1). */
+    componentType: abstract new (...args: never[]) => object;
+}
+/** Transform attributes shared by every Object3D-family node (degrees for rotation). */
+export declare const TRANSFORM_ATTRS: Record<string, NodeAttr>;
+export declare function registerNode(def: NodeDef): void;
+export declare function unregisterNode(tag: string): boolean;
+export declare function getNodeDef(tag: string): NodeDef | undefined;
+export declare function nodeTags(): string[];
+export declare function allNodeDefs(): NodeDef[];
+/** True for tags that carry a transform (Scene + Object3D family). All nodes do. */
+export declare function isSpatial(tag: string): boolean;
+export declare function registerAttachment(def: AttachmentDef): void;
+export declare function unregisterAttachment(tag: string): boolean;
+export declare function getAttachmentDef(tag: string): AttachmentDef | undefined;
+export declare function attachmentTags(): string[];
+export declare function allAttachmentDefs(): AttachmentDef[];
+/** Does an attachment's target accept this node? (class-assignable or tag match) */
+export declare function attachmentAcceptsNode(def: AttachmentDef, node: NodeDef): boolean;
+/** Attachment tags a node may contain (for the XSD/docs and validator). */
+export declare function attachmentsForNode(node: NodeDef): AttachmentDef[];
+export declare function registerSystem(def: SystemDef): void;
+export declare function unregisterSystem(ctor: new () => unknown): boolean;
+export declare function allSystemDefs(): readonly SystemDef[];
+/** Default child rules for a node: holds child nodes + a <Components> block. */
+export declare const spatialChildren: (overrides?: Partial<ChildRules>) => ChildRules;

package/dist/core/NodeRegistry.js

@@ -0,0 +1,87 @@
+/** Transform attributes shared by every Object3D-family node (degrees for rotation). */
+export const TRANSFORM_ATTRS = {
+    position: { type: 'vec3', default: [0, 0, 0], description: 'Local position x y z' },
+    rotation: { type: 'euler', default: [0, 0, 0], description: 'Local rotation in degrees x y z' },
+    scale: { type: 'vec3', default: [1, 1, 1], description: 'Local scale x y z' },
+    visible: { type: 'bool', default: true, description: 'Whether the object renders' },
+};
+// ---- node registry ----------------------------------------------------------
+const nodeDefs = new Map();
+export function registerNode(def) {
+    if (nodeDefs.has(def.tag))
+        throw new Error(`Node tag <${def.tag}> is already registered`);
+    nodeDefs.set(def.tag, def);
+}
+export function unregisterNode(tag) {
+    return nodeDefs.delete(tag);
+}
+export function getNodeDef(tag) {
+    return nodeDefs.get(tag);
+}
+export function nodeTags() {
+    return [...nodeDefs.keys()];
+}
+export function allNodeDefs() {
+    return [...nodeDefs.values()];
+}
+/** True for tags that carry a transform (Scene + Object3D family). All nodes do. */
+export function isSpatial(tag) {
+    return nodeDefs.has(tag);
+}
+// ---- attachment registry ----------------------------------------------------
+const attachmentDefs = new Map();
+export function registerAttachment(def) {
+    if (attachmentDefs.has(def.tag))
+        throw new Error(`Attachment tag <${def.tag}> is already registered`);
+    attachmentDefs.set(def.tag, def);
+}
+export function unregisterAttachment(tag) {
+    return attachmentDefs.delete(tag);
+}
+export function getAttachmentDef(tag) {
+    return attachmentDefs.get(tag);
+}
+export function attachmentTags() {
+    return [...attachmentDefs.keys()];
+}
+export function allAttachmentDefs() {
+    return [...attachmentDefs.values()];
+}
+/** Does an attachment's target accept this node? (class-assignable or tag match) */
+export function attachmentAcceptsNode(def, node) {
+    const t = def.target;
+    if (typeof t === 'string')
+        return node.tag === t;
+    const classes = Array.isArray(t) ? t : [t];
+    return node.produces !== undefined && classes.some((c) => isProducedBy(node.produces, c));
+}
+/** `produces` is `target` or a subclass of it. */
+function isProducedBy(produces, target) {
+    return produces === target || produces.prototype instanceof target;
+}
+/** Attachment tags a node may contain (for the XSD/docs and validator). */
+export function attachmentsForNode(node) {
+    return allAttachmentDefs().filter((d) => attachmentAcceptsNode(d, node));
+}
+// ---- system registry --------------------------------------------------------
+const systemDefs = [];
+export function registerSystem(def) {
+    systemDefs.push(def);
+}
+export function unregisterSystem(ctor) {
+    const i = systemDefs.findIndex((d) => d.ctor === ctor);
+    if (i === -1)
+        return false;
+    systemDefs.splice(i, 1);
+    return true;
+}
+export function allSystemDefs() {
+    return systemDefs;
+}
+// ---- shared helper ----------------------------------------------------------
+/** Default child rules for a node: holds child nodes + a <Components> block. */
+export const spatialChildren = (overrides = {}) => ({
+    object3d: true,
+    components: true,
+    ...overrides,
+});