@scenoco-three/core 0.1.0

package/dist/dsl/deserialize.js

@@ -0,0 +1,125 @@
+import { isScalarType } from '../core/Registry.js';
+import { ComponentFlag, NodeFlag, } from './bundle-format.js';
+import { attachmentAttrEntries, componentPropEntries, nodeAttrEntries, popcount } from './bundle-shared.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 function deserializeBundle(bundle) {
+    const [, strings, asset] = bundle;
+    const [nodeData, attachmentData, componentData, root, prefabData] = asset;
+    const attachments = attachmentData.map((a) => decodeTag(a, strings));
+    const components = componentData.map((c) => decodeComponent(c, strings));
+    const nodes = nodeData.map((n) => decodeNode(n, strings));
+    // Embedded prefabs are self-contained sub-bundles; decode each recursively.
+    const prefabs = prefabData?.map((p) => deserializeBundle(p));
+    // Rebuild parent pointers and component ownership from the forward arrays.
+    nodes.forEach((node, i) => {
+        for (const child of node.children)
+            nodes[child].parent = i;
+        for (const c of node.components)
+            components[c].node = i;
+    });
+    return { root, nodes, attachments, components, ...(prefabs ? { prefabs } : {}) };
+}
+function decodeTag(data, strings) {
+    const tag = strings[data[0]];
+    const mask = data[1];
+    return { tag, attrs: decodeAttrs(attachmentAttrEntries(tag), mask, data.slice(2), strings) };
+}
+function decodeNode(data, strings) {
+    const tag = strings[data[0]];
+    const flags = data[1];
+    const mask = data[2];
+    const entries = nodeAttrEntries(tag);
+    let i = 3;
+    const attrCount = popcount(mask);
+    const attrs = decodeAttrs(entries, mask, data.slice(i, i + attrCount), strings);
+    i += attrCount;
+    const node = {
+        tag,
+        parent: -1,
+        children: [],
+        transform: identityTransform(),
+        attrs,
+        attachments: [],
+        components: [],
+    };
+    if (flags & NodeFlag.Id)
+        node.id = strings[data[i++]];
+    if (flags & NodeFlag.Transform)
+        node.transform = decodeTransform(data[i++]);
+    if (flags & NodeFlag.Attachments)
+        node.attachments = data[i++];
+    if (flags & NodeFlag.Components)
+        node.components = data[i++];
+    if (flags & NodeFlag.Children)
+        node.children = data[i++];
+    return node;
+}
+function decodeComponent(data, strings) {
+    const type = strings[data[0]];
+    const flags = data[1];
+    const mask = data[2];
+    const props = {};
+    let i = 3;
+    let bit = 0;
+    for (const [name, meta] of componentPropEntries(type)) {
+        if (mask & (1 << bit)) {
+            props[name] = decodePropValue(data[i++], meta.type, strings);
+        }
+        bit++;
+    }
+    const component = { type, node: -1, props };
+    if (flags & ComponentFlag.Id)
+        component.id = strings[data[i++]];
+    return component;
+}
+// ---- value helpers --------------------------------------------------------
+function decodeAttrs(entries, mask, values, strings) {
+    const out = {};
+    let vi = 0;
+    let bit = 0;
+    for (const [name, meta] of entries) {
+        if (mask & (1 << bit)) {
+            const raw = values[vi++];
+            out[name] = meta.type === 'string' ? strings[raw] : raw;
+        }
+        else {
+            out[name] = cloneDefault(meta.default);
+        }
+        bit++;
+    }
+    return out;
+}
+function decodePropValue(raw, type, strings) {
+    // A prefab prop stores a plain index into the scene's prefabs[] pool; the
+    // registered type disambiguates it from node/component refs.
+    if (type === 'prefab')
+        return { prefab: raw };
+    if (!isScalarType(type)) {
+        const i = raw;
+        return i < 0 ? { node: ~i } : { component: i };
+    }
+    if (type === 'string')
+        return strings[raw];
+    return raw;
+}
+function decodeTransform(arr) {
+    return {
+        position: arr.slice(0, 3),
+        rotation: arr.slice(3, 6),
+        scale: arr.slice(6, 9),
+        visible: arr[9] === 1,
+    };
+}
+function identityTransform() {
+    return { position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1], visible: true };
+}
+function cloneDefault(value) {
+    if (value === undefined)
+        return 0;
+    return Array.isArray(value) ? [...value] : value;
+}

package/dist/dsl/instantiate.d.ts

@@ -0,0 +1,40 @@
+import { type Object3D, Scene, type WebGLRenderer } from 'three';
+import type { Component } from '../core/Component.js';
+import type { CompiledScene } from './compiled.js';
+import { type AttachmentInstance } from './nodes.js';
+import { type SpawnFn } from './PrefabRef.js';
+/**
+ * The live result of instantiating a CompiledScene: a Three.js subtree, bare
+ * component instances (lifecycle not yet started — the Engine owns that), and
+ * the live attachment instances (which the engine retains for `findAttachment`).
+ * Arrays are index-aligned with the CompiledScene so references resolve by index.
+ */
+export interface InstantiatedScene {
+    /** Object for the root <Scene> node; its children are the scene contents. */
+    root: Object3D;
+    /** Index-aligned with CompiledScene.components. */
+    components: {
+        instance: Component;
+        node: Object3D;
+    }[];
+    /** One per pooled attachment (caching → shared geometry/material). */
+    attachments: AttachmentInstance[];
+}
+/** Live scene/renderer context an attachment may configure (settings need it). */
+export interface InstantiateContext {
+    scene?: Scene;
+    renderer?: WebGLRenderer;
+    /**
+     * How a `prefab` prop spawns its subtree (the Engine passes `engine.instantiate`).
+     * Absent when instantiating standalone (pure tests) — a PrefabRef.spawn() then
+     * throws a clear error rather than silently no-op.
+     */
+    spawn?: SpawnFn;
+}
+/**
+ * Build live Three.js objects, attachments, and component instances from a
+ * compiled scene. Attachments are pooled (one instance per entry → shared
+ * resources); component references are wired by index in a second pass, so they
+ * are valid before any component lifecycle runs.
+ */
+export declare function instantiateScene(compiled: CompiledScene, ctx?: InstantiateContext): InstantiatedScene;

package/dist/dsl/instantiate.js

@@ -0,0 +1,111 @@
+import { Color, Euler, Scene, Vector2, Vector3 } from 'three';
+import { Registry } from '../core/Registry.js';
+import { getAttachmentDef, getNodeDef } from './nodes.js';
+import { PrefabRef } from './PrefabRef.js';
+/**
+ * Build live Three.js objects, attachments, and component instances from a
+ * compiled scene. Attachments are pooled (one instance per entry → shared
+ * resources); component references are wired by index in a second pass, so they
+ * are valid before any component lifecycle runs.
+ */
+export function instantiateScene(compiled, ctx = {}) {
+    // A scene is needed by scene-targeted attachments (fog/background); default to
+    // a throwaway when instantiating standalone (prefabs/tests use node attachments).
+    const scene = ctx.scene ?? new Scene();
+    const renderer = ctx.renderer;
+    // One instance per pooled attachment entry, so caching shares the resource.
+    const attachments = compiled.attachments.map((a) => getAttachmentDef(a.tag).make(a.attrs));
+    const objects = compiled.nodes.map((node) => buildObject(node));
+    // Link the scene graph.
+    compiled.nodes.forEach((node, i) => {
+        for (const childIndex of node.children)
+            objects[i].add(objects[childIndex]);
+    });
+    // Apply attachments (geometry/material on the node, fog/background on the scene).
+    compiled.nodes.forEach((node, i) => {
+        for (const ai of node.attachments)
+            attachments[ai].attach({ node: objects[i], scene, ...(renderer ? { renderer } : {}) });
+    });
+    // Create component instances and set their scalar props (refs come next).
+    const instances = compiled.components.map((c) => {
+        const entry = Registry.getComponent(c.type);
+        const instance = new entry.ctor();
+        instance.node = objects[c.node];
+        if (c.id !== undefined)
+            instance.id = c.id;
+        setScalarProps(instance, c, entry.meta.properties);
+        return instance;
+    });
+    // Wire references now that every object and instance exists.
+    const spawn = ctx.spawn ?? unboundSpawn;
+    compiled.components.forEach((c, i) => {
+        const props = Registry.getComponent(c.type).meta.properties;
+        for (const [attr, value] of Object.entries(c.props)) {
+            if (!isRef(value))
+                continue;
+            const meta = props.get(attr);
+            if (!meta)
+                continue;
+            const target = instances[i];
+            if ('prefab' in value) {
+                target[attr] = new PrefabRef(compiled.prefabs[value.prefab], spawn, instances[i].node);
+            }
+            else {
+                target[attr] = 'node' in value ? objects[value.node] : instances[value.component];
+            }
+        }
+    });
+    return {
+        root: objects[compiled.root],
+        components: instances.map((instance, i) => ({ instance, node: objects[compiled.components[i].node] })),
+        attachments,
+    };
+}
+function buildObject(node) {
+    const object = getNodeDef(node.tag).build(node.attrs);
+    // The DSL `id` maps to Three.js's Object3D.name (Object3D.id is a reserved
+    // numeric auto-id), so name-based lookups keep working.
+    if (node.id !== undefined)
+        object.name = node.id;
+    const { position, rotation, scale, visible } = node.transform;
+    object.position.fromArray(position);
+    object.rotation.set(rotation[0], rotation[1], rotation[2]);
+    object.scale.fromArray(scale);
+    object.visible = visible;
+    return object;
+}
+function setScalarProps(instance, compiled, props) {
+    const target = instance;
+    for (const [attr, value] of Object.entries(compiled.props)) {
+        if (isRef(value))
+            continue;
+        const meta = props.get(attr);
+        if (!meta)
+            continue;
+        target[attr] = toRuntimeValue(meta.type, value);
+    }
+}
+/** Convert a compiled scalar into the Three.js-typed value a component field expects. */
+function toRuntimeValue(type, value) {
+    switch (type) {
+        case 'vec2':
+            return new Vector2().fromArray(value);
+        case 'vec3':
+            return new Vector3().fromArray(value);
+        case 'euler': {
+            const e = value;
+            return new Euler(e[0], e[1], e[2]);
+        }
+        case 'color':
+            return new Color(value);
+        default:
+            return value; // float/int/bool/string
+    }
+}
+function isRef(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Fallback for a prefab prop instantiated without an engine (pure/standalone use). */
+const unboundSpawn = () => {
+    throw new Error('PrefabRef.spawn() needs an engine — instantiate the scene via Engine.loadScene/instantiate.');
+};

package/dist/dsl/nodes.d.ts

@@ -0,0 +1 @@
+export * from '../core/NodeRegistry.js';

package/dist/dsl/nodes.js

@@ -0,0 +1,10 @@
+// Compatibility shim. The node system moved to an extensible registry in
+// `core/NodeRegistry.ts`, with built-ins split one-per-file under `nodes/**`.
+// This module re-exports the registry surface (so existing `from './nodes.js'`
+// import sites keep working).
+//
+// It deliberately does NOT import the built-in barrel: keeping the runtime entry
+// node-module-free is what lets bundlers tree-shake unused node tags. Built-ins
+// register on demand — the Vite plugin emits a usage-based import per used tag
+// (see nodes/manifest.ts), or import `@scenoco-three/core/nodes` to register all.
+export * from '../core/NodeRegistry.js';

package/dist/dsl/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical wire formats for SceNoCo attribute values — the single place that
+ * defines how each scalar/math property is written in XML, parsed into a
+ * JSON-serializable compiled value, serialized back, and described in XSD.
+ *
+ * Compiled representation (what flows through compile → instantiate, and what
+ * ships as JSON in production builds) is deliberately plain and fast:
+ *   float/int  → number
+ *   bool       → boolean
+ *   string     → string
+ *   vec2/vec3  → number[]              (length 2 / 3)
+ *   euler      → number[] in RADIANS   (XML is degrees; converted at parse time)
+ *   color      → number (0xRRGGBB)
+ *
+ * Reference types (`node` and typed component references) are not scalar codecs;
+ * they need the scene-wide name/id tables and are resolved by the compiler.
+ */
+export type ScalarType = 'float' | 'int' | 'bool' | 'string' | 'vec2' | 'vec3' | 'euler' | 'color';
+export type CompiledScalar = number | boolean | string | number[];
+export interface ParseOk<T> {
+    ok: true;
+    value: T;
+}
+export interface ParseErr {
+    ok: false;
+    /** LLM-actionable: says what was expected and shows a valid example. */
+    message: string;
+}
+export type ParseResult<T> = ParseOk<T> | ParseErr;
+export interface XsdType {
+    /** Underlying XSD simple type. */
+    base: string;
+    /** Optional restriction pattern for string-encoded math types. */
+    pattern?: string;
+}
+export interface TypeCodec<T extends CompiledScalar = CompiledScalar> {
+    /** Human label used in error messages, e.g. "a vec3". */
+    label: string;
+    /** A valid example value, shown in errors and docs. */
+    example: string;
+    parse(raw: string): ParseResult<T>;
+    serialize(value: T): string;
+    xsd: XsdType;
+}
+export declare const codecs: Record<ScalarType, TypeCodec>;

package/dist/dsl/types.js

@@ -0,0 +1,120 @@
+import { Color } from 'three';
+const ok = (value) => ({ ok: true, value });
+const err = (message) => ({ ok: false, message });
+// A single finite number: 1, -2.5, .5, 3e2, +4. Used for runtime parsing (JS regex).
+const NUM_SRC = '[-+]?(?:\\d+\\.?\\d*|\\.\\d+)(?:[eE][-+]?\\d+)?';
+const NUM_RE = new RegExp(`^${NUM_SRC}$`);
+// XML-Schema-flavored equivalents for the generated XSD: patterns are implicitly
+// anchored and forbid the `(?:…)` non-capturing group, so we use plain groups.
+const XSD_NUM = '[+-]?(\\d+(\\.\\d*)?|\\.\\d+)([eE][+-]?\\d+)?';
+const xsdVecPattern = (n) => `\\s*${XSD_NUM}(\\s+${XSD_NUM}){${n - 1}}\\s*`;
+function parseFiniteNumber(raw) {
+    const t = raw.trim();
+    if (!NUM_RE.test(t))
+        return err(`expected a number (e.g. "1.5"), got "${raw}"`);
+    const n = Number(t);
+    return Number.isFinite(n) ? ok(n) : err(`expected a finite number, got "${raw}"`);
+}
+function parseVec(raw, n, label) {
+    const parts = raw.trim().split(/\s+/);
+    if (parts.length !== n) {
+        return err(`expected ${label} — ${n} space-separated numbers (e.g. "${vecExample(n)}"), got "${raw}"`);
+    }
+    const out = [];
+    for (const p of parts) {
+        if (!NUM_RE.test(p)) {
+            return err(`expected ${label} — ${n} space-separated numbers (e.g. "${vecExample(n)}"), got "${raw}"`);
+        }
+        out.push(Number(p));
+    }
+    return ok(out);
+}
+const vecExample = (n) => (n === 2 ? '0 1' : '0 1.5 -3');
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+export const codecs = {
+    float: {
+        label: 'a number',
+        example: '1.5',
+        parse: parseFiniteNumber,
+        serialize: (v) => String(v),
+        xsd: { base: 'xs:float' },
+    },
+    int: {
+        label: 'an integer',
+        example: '32',
+        parse: (raw) => {
+            const r = parseFiniteNumber(raw);
+            if (!r.ok)
+                return r;
+            return Number.isInteger(r.value) ? r : err(`expected an integer (e.g. "32"), got "${raw}"`);
+        },
+        serialize: (v) => String(v),
+        xsd: { base: 'xs:int' },
+    },
+    bool: {
+        label: 'a boolean',
+        example: 'true',
+        parse: (raw) => {
+            const t = raw.trim();
+            if (t === 'true')
+                return ok(true);
+            if (t === 'false')
+                return ok(false);
+            return err(`expected "true" or "false", got "${raw}"`);
+        },
+        serialize: (v) => String(v),
+        xsd: { base: 'xs:boolean' },
+    },
+    string: {
+        label: 'a string',
+        example: 'hello',
+        parse: (raw) => ok(raw),
+        serialize: (v) => String(v),
+        xsd: { base: 'xs:string' },
+    },
+    vec2: {
+        label: 'a vec2',
+        example: '0 1',
+        parse: (raw) => parseVec(raw, 2, 'a vec2'),
+        serialize: (v) => v.join(' '),
+        xsd: { base: 'xs:string', pattern: xsdVecPattern(2) },
+    },
+    vec3: {
+        label: 'a vec3',
+        example: '0 1.5 -3',
+        parse: (raw) => parseVec(raw, 3, 'a vec3'),
+        serialize: (v) => v.join(' '),
+        xsd: { base: 'xs:string', pattern: xsdVecPattern(3) },
+    },
+    euler: {
+        // XML carries degrees (Unity/Blender/A-Frame convention); compiled is radians.
+        label: 'an euler (degrees)',
+        example: '0 90 0',
+        parse: (raw) => {
+            const r = parseVec(raw, 3, 'an euler (degrees)');
+            return r.ok ? ok(r.value.map((d) => d * DEG2RAD)) : r;
+        },
+        serialize: (v) => v.map((rad) => round(rad * RAD2DEG)).join(' '),
+        xsd: { base: 'xs:string', pattern: xsdVecPattern(3) },
+    },
+    color: {
+        label: 'a color',
+        example: '#ffcc00',
+        parse: (raw) => {
+            const t = raw.trim();
+            if (HEX_RE.test(t))
+                return ok(new Color(t).getHex());
+            if (t.toLowerCase() in Color.NAMES)
+                return ok(new Color(t.toLowerCase()).getHex());
+            return err(`expected a hex color (e.g. "#ffcc00") or a CSS color name (e.g. "tomato"), got "${raw}"`);
+        },
+        serialize: (v) => `#${v.toString(16).padStart(6, '0')}`,
+        xsd: { base: 'xs:string', pattern: `#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})|[a-zA-Z]+` },
+    },
+};
+// Trim floating-point dust when serializing degrees back from radians.
+function round(n) {
+    return Math.round(n * 1e6) / 1e6;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { Engine, type EngineOptions } from './core/Engine.js';
+export { Component } from './core/Component.js';
+export { System } from './core/System.js';
+export { Registry, isScalarType, type PropType, type PropertyMeta, type ComponentMeta, type ComponentCtor, type RegisteredComponent, } from './core/Registry.js';
+export { component, property, node, attachment, system, type ComponentOptions, type NodeOptions, type AttachmentOptions, } from './core/decorators.js';
+export { Object3DNode, Attachment } from './nodes/base.js';
+export { getNodeDef, nodeTags, allNodeDefs, registerNode, unregisterNode, getAttachmentDef, attachmentTags, allAttachmentDefs, registerAttachment, unregisterAttachment, type NodeDef, type NodeAttr, type NodeKind, type ChildRules, type AttachmentDef, type AttachTarget, type AttachContext, } from './dsl/nodes.js';
+export { deserializeBundle } from './dsl/deserialize.js';
+export { BUNDLE_VERSION, bundleKind, type Bundle, type BundleAsset, type BundleKind, } from './dsl/bundle-format.js';
+export { instantiateScene, type InstantiatedScene } from './dsl/instantiate.js';
+export { PrefabRef, type SpawnOptions, type SpawnFn } from './dsl/PrefabRef.js';
+export type { SceneInstance } from './core/Engine.js';
+export type { CompiledScene, CompiledNode, CompiledComponent, CompiledAsset, CompiledRef, CompiledValue, CompiledTransform, } from './dsl/compiled.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+// `@scenoco-three/core` — the runtime entry point. Contains no XML parser,
+// validator, or compiler: it loads pre-built bundles only.
+export { Engine } from './core/Engine.js';
+export { Component } from './core/Component.js';
+export { System } from './core/System.js';
+export { Registry, isScalarType, } from './core/Registry.js';
+// One authoring idiom: @property fields + a class decorator per role.
+export { component, property, node, attachment, system, } from './core/decorators.js';
+export { Object3DNode, Attachment } from './nodes/base.js';
+// Tag registry — built-in tags self-register on import; projects add their own
+// the same way (the extensible counterpart to @component).
+export { getNodeDef, nodeTags, allNodeDefs, registerNode, unregisterNode, getAttachmentDef, attachmentTags, allAttachmentDefs, registerAttachment, unregisterAttachment, } from './dsl/nodes.js';
+// Bundle: the optimized format the runtime loads.
+export { deserializeBundle } from './dsl/deserialize.js';
+export { BUNDLE_VERSION, bundleKind, } from './dsl/bundle-format.js';
+export { instantiateScene } from './dsl/instantiate.js';
+export { PrefabRef } from './dsl/PrefabRef.js';

package/dist/internal.d.ts

@@ -0,0 +1,7 @@
+export { Registry, isScalarType, type ComponentCtor, type PropertyMeta, type PropType } from './core/Registry.js';
+export { getNodeDef, nodeTags, allNodeDefs, isSpatial, unregisterNode, getAttachmentDef, attachmentTags, allAttachmentDefs, attachmentsForNode, attachmentAcceptsNode, unregisterAttachment, allSystemDefs, TRANSFORM_ATTRS, type NodeDef, type NodeAttr, type NodeKind, type ChildRules, type AttachmentDef, type AttachTarget, type AttachClass, type AttachContext, type SystemDef, } from './dsl/nodes.js';
+export { builtinNodeModules, builtinNodeModule } from './nodes/manifest.js';
+export { BUNDLE_VERSION, ComponentFlag, NodeFlag, type Bundle, type BundleAsset, type BundleComponent, type BundleKind, type BundleNode, type BundleTag, type BundleValue, } from './dsl/bundle-format.js';
+export { componentPropEntries, nodeAttrEntries, attachmentAttrEntries, popcount, valueEquals, } from './dsl/bundle-shared.js';
+export type { CompiledScene, CompiledNode, CompiledComponent, CompiledAsset, CompiledRef, CompiledValue, CompiledTransform, } from './dsl/compiled.js';
+export type { CompiledScalar, ScalarType } from './dsl/types.js';

package/dist/internal.js

@@ -0,0 +1,7 @@
+// Internal bridge exports for build-time tooling packages.
+// Not intended as the primary runtime API surface.
+export { Registry, isScalarType } from './core/Registry.js';
+export { getNodeDef, nodeTags, allNodeDefs, isSpatial, unregisterNode, getAttachmentDef, attachmentTags, allAttachmentDefs, attachmentsForNode, attachmentAcceptsNode, unregisterAttachment, allSystemDefs, TRANSFORM_ATTRS, } from './dsl/nodes.js';
+export { builtinNodeModules, builtinNodeModule } from './nodes/manifest.js';
+export { BUNDLE_VERSION, ComponentFlag, NodeFlag, } from './dsl/bundle-format.js';
+export { componentPropEntries, nodeAttrEntries, attachmentAttrEntries, popcount, valueEquals, } from './dsl/bundle-shared.js';

package/dist/nodes/base.d.ts

@@ -0,0 +1,31 @@
+import type { Object3D } from 'three';
+import type { AttachContext } from '../core/NodeRegistry.js';
+/**
+ * Base classes for the two tag kinds that live in the scene tree — the factory
+ * counterpart to `Component`. A tag is a class: its XML attributes are
+ * `@property` fields, a class decorator (`@node`/`@attachment`) declares its kind
+ * and registers it, and the body reads the fields with full typing.
+ *
+ *   @node({ name: 'Mesh', children: { … } })
+ *   class MeshNode extends Object3DNode { build() { return new Mesh(); } }
+ *
+ *   @attachment({ target: Mesh, group: 'geometry', required: true })
+ *   class BoxGeometry extends Attachment<Mesh> {
+ *     @property({ type: 'float', default: 1 }) width = 1;
+ *     attach(ctx) { ctx.node.geometry = new BoxGeometry(this.width); }
+ *   }
+ */
+/** A scene-graph node (Object3D family + the Scene root). Builds the bare object. */
+export declare abstract class Object3DNode {
+    abstract build(): Object3D;
+}
+/**
+ * A leaf that attaches to and configures a node — geometry/material on a mesh,
+ * fog/background on the scene. `TNode` types the host: `Attachment<Mesh>` gives
+ * `ctx.node` typed as `Mesh`. An attachment may cache the resource it builds on
+ * `this`, so the compiler's content-dedup (one def instance shared across nodes)
+ * yields one shared geometry/material.
+ */
+export declare abstract class Attachment<TNode extends Object3D = Object3D> {
+    abstract attach(ctx: AttachContext<TNode>): void;
+}

package/dist/nodes/base.js

@@ -0,0 +1,27 @@
+/**
+ * Base classes for the two tag kinds that live in the scene tree — the factory
+ * counterpart to `Component`. A tag is a class: its XML attributes are
+ * `@property` fields, a class decorator (`@node`/`@attachment`) declares its kind
+ * and registers it, and the body reads the fields with full typing.
+ *
+ *   @node({ name: 'Mesh', children: { … } })
+ *   class MeshNode extends Object3DNode { build() { return new Mesh(); } }
+ *
+ *   @attachment({ target: Mesh, group: 'geometry', required: true })
+ *   class BoxGeometry extends Attachment<Mesh> {
+ *     @property({ type: 'float', default: 1 }) width = 1;
+ *     attach(ctx) { ctx.node.geometry = new BoxGeometry(this.width); }
+ *   }
+ */
+/** A scene-graph node (Object3D family + the Scene root). Builds the bare object. */
+export class Object3DNode {
+}
+/**
+ * A leaf that attaches to and configures a node — geometry/material on a mesh,
+ * fog/background on the scene. `TNode` types the host: `Attachment<Mesh>` gives
+ * `ctx.node` typed as `Mesh`. An attachment may cache the resource it builds on
+ * `this`, so the compiler's content-dedup (one def instance shared across nodes)
+ * yields one shared geometry/material.
+ */
+export class Attachment {
+}

package/dist/nodes/geometry/BoxGeometry.d.ts

@@ -0,0 +1,13 @@
+import { type Mesh } from 'three';
+import { Attachment } from '../base.js';
+import type { AttachContext } from '../../core/NodeRegistry.js';
+export declare class BoxGeometryNode extends Attachment<Mesh> {
+    width: number;
+    height: number;
+    depth: number;
+    widthSegments: number;
+    heightSegments: number;
+    depthSegments: number;
+    private cached?;
+    attach(ctx: AttachContext<Mesh>): void;
+}

package/dist/nodes/geometry/BoxGeometry.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BoxGeometry } from 'three';
+import { Attachment } from '../base.js';
+import { attachment, property } from '../../core/decorators.js';
+import { GEOMETRY_TARGETS } from '../targets.js';
+let BoxGeometryNode = class BoxGeometryNode extends Attachment {
+    width = 1;
+    height = 1;
+    depth = 1;
+    widthSegments = 1;
+    heightSegments = 1;
+    depthSegments = 1;
+    cached;
+    attach(ctx) {
+        ctx.node.geometry = (this.cached ??= new BoxGeometry(this.width, this.height, this.depth, this.widthSegments, this.heightSegments, this.depthSegments));
+    }
+};
+__decorate([
+    property({ type: 'float', default: 1 })
+], BoxGeometryNode.prototype, "width", void 0);
+__decorate([
+    property({ type: 'float', default: 1 })
+], BoxGeometryNode.prototype, "height", void 0);
+__decorate([
+    property({ type: 'float', default: 1 })
+], BoxGeometryNode.prototype, "depth", void 0);
+__decorate([
+    property({ type: 'int', default: 1 })
+], BoxGeometryNode.prototype, "widthSegments", void 0);
+__decorate([
+    property({ type: 'int', default: 1 })
+], BoxGeometryNode.prototype, "heightSegments", void 0);
+__decorate([
+    property({ type: 'int', default: 1 })
+], BoxGeometryNode.prototype, "depthSegments", void 0);
+BoxGeometryNode = __decorate([
+    attachment({ name: 'BoxGeometry', target: GEOMETRY_TARGETS, group: 'geometry', required: true })
+], BoxGeometryNode);
+export { BoxGeometryNode };

package/dist/nodes/geometry/CylinderGeometry.d.ts

@@ -0,0 +1,11 @@
+import { type Mesh } from 'three';
+import { Attachment } from '../base.js';
+import type { AttachContext } from '../../core/NodeRegistry.js';
+export declare class CylinderGeometryNode extends Attachment<Mesh> {
+    radiusTop: number;
+    radiusBottom: number;
+    height: number;
+    radialSegments: number;
+    private cached?;
+    attach(ctx: AttachContext<Mesh>): void;
+}