@scenoco-three/compiler 0.1.0

package/dist/dsl/serialize.js

@@ -0,0 +1,157 @@
+import { getNodeDef, getAttachmentDef, isScalarType, Registry, TRANSFORM_ATTRS, valueEquals, } from '@scenoco-three/core/internal';
+import { codecs } from './types.js';
+/**
+ * Serialize a CompiledScene back to canonical, re-compilable XML — the inverse
+ * of the compiler (minus validation). Used to write programmatic/agent edits
+ * back to file form.
+ *
+ * The output is the **flat** form: prefab instances and material `src=` files
+ * have already been expanded/inlined by the compiler, so they appear as ordinary
+ * nodes and inline materials. Only non-default attributes are emitted. A
+ * reference (`{ node|component: index }`) is written as `#id`; if its target had
+ * no id, a stable unique one is synthesized so the reference survives the round
+ * trip.
+ */
+export function serializeScene(scene) {
+    const ids = assignIds(scene);
+    const lines = [];
+    emitNode(scene, scene.root, 0, ids, lines);
+    return lines.join('\n') + '\n';
+}
+/** Resolve every node/component to an id, synthesizing unique ones for referenced-but-unnamed targets. */
+function assignIds(scene) {
+    const refNodes = new Set();
+    const refComponents = new Set();
+    for (const c of scene.components) {
+        for (const v of Object.values(c.props)) {
+            if (!isRef(v))
+                continue;
+            if ('node' in v)
+                refNodes.add(v.node);
+            else if ('component' in v)
+                refComponents.add(v.component);
+        }
+    }
+    const taken = new Set();
+    for (const n of scene.nodes)
+        if (n.id !== undefined)
+            taken.add(n.id);
+    for (const c of scene.components)
+        if (c.id !== undefined)
+            taken.add(c.id);
+    const synth = (base) => {
+        let id = base;
+        let i = 1;
+        while (taken.has(id))
+            id = `${base}_${i++}`;
+        taken.add(id);
+        return id;
+    };
+    const nodeIds = new Map();
+    scene.nodes.forEach((n, i) => {
+        if (n.id !== undefined)
+            nodeIds.set(i, n.id);
+        else if (refNodes.has(i))
+            nodeIds.set(i, synth(n.tag.toLowerCase()));
+    });
+    const componentIds = new Map();
+    scene.components.forEach((c, i) => {
+        if (c.id !== undefined)
+            componentIds.set(i, c.id);
+        else if (refComponents.has(i))
+            componentIds.set(i, synth(c.type.toLowerCase()));
+    });
+    return {
+        node: (i) => nodeIds.get(i),
+        component: (i) => componentIds.get(i),
+        nodeHas: (i) => nodeIds.has(i),
+        componentHas: (i) => componentIds.has(i),
+    };
+}
+function emitNode(scene, index, depth, ids, out) {
+    const node = scene.nodes[index];
+    const pad = '  '.repeat(depth);
+    const attrs = nodeAttrs(node, index, ids);
+    const hasAttachments = node.attachments.length > 0;
+    const hasComponents = node.components.length > 0;
+    const hasChildren = node.children.length > 0;
+    if (!hasAttachments && !hasComponents && !hasChildren) {
+        out.push(`${pad}<${node.tag}${attrs} />`);
+        return;
+    }
+    out.push(`${pad}<${node.tag}${attrs}>`);
+    const inner = '  '.repeat(depth + 1);
+    for (const ai of node.attachments)
+        out.push(`${inner}${attachmentTag(scene.attachments[ai])}`);
+    if (hasComponents) {
+        out.push(`${inner}<Components>`);
+        for (const ci of node.components)
+            out.push(`${inner}  ${componentTag(scene.components[ci], ci, ids)}`);
+        out.push(`${inner}</Components>`);
+    }
+    for (const child of node.children)
+        emitNode(scene, child, depth + 1, ids, out);
+    out.push(`${pad}</${node.tag}>`);
+}
+// ---- attribute builders -----------------------------------------------------
+function nodeAttrs(node, index, ids) {
+    const parts = [];
+    if (ids.nodeHas(index))
+        parts.push(attr('id', ids.node(index)));
+    const t = node.transform;
+    if (!isZero(t.position))
+        parts.push(attr('position', codecs.vec3.serialize(t.position)));
+    if (!isZero(t.rotation))
+        parts.push(attr('rotation', codecs.euler.serialize(t.rotation)));
+    if (!isOne(t.scale))
+        parts.push(attr('scale', codecs.vec3.serialize(t.scale)));
+    if (!t.visible)
+        parts.push(attr('visible', 'false'));
+    appendDefaultedAttrs(parts, getNodeDef(node.tag)?.attrs ?? {}, node.attrs);
+    return parts.length > 0 ? ' ' + parts.join(' ') : '';
+}
+function attachmentTag(asset) {
+    const parts = [];
+    appendDefaultedAttrs(parts, getAttachmentDef(asset.tag)?.attrs ?? {}, asset.attrs);
+    return `<${asset.tag}${parts.length > 0 ? ' ' + parts.join(' ') : ''} />`;
+}
+function componentTag(component, index, ids) {
+    const meta = Registry.getComponent(component.type).meta;
+    const parts = [];
+    if (ids.componentHas(index))
+        parts.push(attr('id', ids.component(index)));
+    for (const [name, value] of Object.entries(component.props)) {
+        const propMeta = meta.properties.get(name);
+        if (!propMeta)
+            continue;
+        if (isRef(value)) {
+            // A prefab prop embeds the compiled prefab; its original file path is not
+            // retained, so it cannot be reconstructed as a `prefab="…"` attribute here.
+            if ('prefab' in value)
+                continue;
+            const target = 'node' in value ? ids.node(value.node) : ids.component(value.component);
+            parts.push(attr(name, `#${target}`));
+        }
+        else if (isScalarType(propMeta.type)) {
+            parts.push(attr(name, codecs[propMeta.type].serialize(value)));
+        }
+    }
+    return `<${component.type}${parts.length > 0 ? ' ' + parts.join(' ') : ''} />`;
+}
+/** Emit each attr whose value differs from the registry default. */
+function appendDefaultedAttrs(parts, defs, values) {
+    for (const [name, meta] of Object.entries(defs)) {
+        const value = values[name];
+        if (value === undefined || valueEquals(value, meta.default))
+            continue;
+        parts.push(attr(name, codecs[meta.type].serialize(value)));
+    }
+}
+// ---- small helpers ----------------------------------------------------------
+const attr = (name, value) => `${name}="${escapeXml(value)}"`;
+const isRef = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isZero = (v) => v.every((x) => x === 0);
+const isOne = (v) => v.every((x) => x === 1);
+function escapeXml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

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/exporters/docs.d.ts

@@ -0,0 +1,16 @@
+export interface DocsOptions {
+    /**
+     * Compact mode for small-context local models: drops prose descriptions,
+     * the prefab section, and the value-format table in favour of one-liners.
+     * Roughly halves the token count while keeping every tag, attribute, type,
+     * default and a worked example. Same registries, so it never drifts.
+     */
+    compact?: boolean;
+}
+/**
+ * Generates `component-api.md` — the compact reference an agent loads into
+ * context (CLAUDE.md / .cursorrules / AGENTS.md). Built from the same registries
+ * as the runtime and the XSD, so it never drifts. Kept deliberately terse:
+ * tags, attributes, types, defaults, one example each.
+ */
+export declare function generateDocs(options?: DocsOptions): string;

package/dist/exporters/docs.js

@@ -0,0 +1,190 @@
+import { Registry, allNodeDefs, allAttachmentDefs, TRANSFORM_ATTRS, } from '@scenoco-three/core/internal';
+import { codecs } from '../dsl/types.js';
+/**
+ * Generates `component-api.md` — the compact reference an agent loads into
+ * context (CLAUDE.md / .cursorrules / AGENTS.md). Built from the same registries
+ * as the runtime and the XSD, so it never drifts. Kept deliberately terse:
+ * tags, attributes, types, defaults, one example each.
+ */
+export function generateDocs(options = {}) {
+    const compact = options.compact ?? false;
+    const defs = allNodeDefs();
+    const byKind = (k) => defs.filter((d) => d.kind === k);
+    const md = [];
+    md.push('# SceNoCo Scene API');
+    md.push('');
+    md.push('Scenes are XML files. The root element is `<Scene>`. Rules:');
+    md.push('');
+    md.push('- An object is a `<Mesh>` with exactly one geometry child and an optional material child.');
+    md.push('- Behaviour goes in a single `<Components>` block per node; each child is a component.');
+    md.push('- `id` (optional, unique) labels any node or component; reference one elsewhere as `"#id"`.');
+    md.push('- Angles are **degrees**; positions/vectors are space-separated; colors are hex or CSS names.');
+    md.push('');
+    md.push('## Value formats');
+    md.push('');
+    if (compact) {
+        const types = ['float', 'int', 'bool', 'string', 'vec2', 'vec3', 'euler', 'color']
+            .map((t) => `${t} \`${codecs[t].example}\``)
+            .join(' · ');
+        md.push(`${types} · reference \`"#someId"\``);
+    }
+    else {
+        md.push('| Type | Example |');
+        md.push('| --- | --- |');
+        for (const t of ['float', 'int', 'bool', 'string', 'vec2', 'vec3', 'euler', 'color']) {
+            md.push(`| ${t} | \`${codecs[t].example}\` |`);
+        }
+        md.push('| reference | `"#someId"` |');
+    }
+    md.push('');
+    md.push('## Nodes');
+    md.push('');
+    md.push('All spatial nodes also accept: ' + transformLine() + '.');
+    md.push('');
+    for (const def of [...byKind('scene'), ...byKind('object3d')]) {
+        md.push(`### \`<${def.tag}>\`${def.description && !compact ? ` — ${def.description}` : ''}`);
+        const attrs = nodeAttrLines(def.attrs, compact);
+        if (attrs.length > 0)
+            md.push(...attrs);
+        md.push('');
+    }
+    // Attachments — leaves that configure a node (geometry/material on a mesh,
+    // fog/background on the scene), grouped by their cardinality group.
+    for (const [group, group_defs] of attachmentsByGroup()) {
+        md.push(`## ${capitalize(group)} (attaches to ${targetSummary(group_defs)})`);
+        md.push('');
+        if (!compact && group === 'material') {
+            md.push('Any attachment may set `src="file.material.xml"` to inherit attributes from a');
+            md.push('resource file; inline attributes override it, and identical attachments are shared.');
+            md.push('');
+        }
+        for (const def of group_defs) {
+            md.push(`### \`<${def.tag}>\`${def.description && !compact ? ` — ${def.description}` : ''}`);
+            md.push(...nodeAttrLines(def.attrs, compact));
+            md.push('');
+        }
+    }
+    md.push('## Components (inside `<Components>`)');
+    md.push('');
+    for (const name of Registry.componentNames()) {
+        const meta = Registry.getComponent(name).meta;
+        md.push(`### \`<${name}>\`${meta.description && !compact ? ` — ${meta.description}` : ''}`);
+        for (const [attr, prop] of meta.properties)
+            md.push(`- \`${attr}\` ${propertyLine(prop, compact)}`);
+        md.push('');
+    }
+    if (!compact) {
+        md.push('## Prefabs');
+        md.push('');
+        md.push('A `.prefab.xml` file has a `<Prefab>` root wrapping exactly one node; it must be');
+        md.push('self-contained (every `#ref` resolves inside the file). Place one in a scene with a');
+        md.push('`<PrefabInstance>` (a prefab file may also contain `<PrefabInstance>` children, so');
+        md.push('prefabs nest):');
+        md.push('');
+        md.push('### `<PrefabInstance>` — instance of a prefab file');
+        md.push('- `src` (string) *(required)* — the `.prefab.xml` file to expand');
+        md.push('- `id` (string) *(required)* — instance id; internals are addressed as `"#<id>/<inner>"`');
+        md.push('- plus the transform attributes (override the prefab root): ' + transformLine());
+        md.push('');
+        md.push('Children: `<Override target="#<inner-id>" …/>` patches an internal node/component;');
+        md.push('a `<Components>` block adds components to the instance root. Example:');
+        md.push('');
+        md.push('```xml');
+        md.push(prefabExample());
+        md.push('```');
+        md.push('');
+    }
+    md.push('## Example');
+    md.push('');
+    md.push('```xml');
+    md.push(example());
+    md.push('```');
+    md.push('');
+    return md.join('\n');
+}
+/** Group attachment defs by their cardinality group (geometry/material/fog/…). */
+function attachmentsByGroup() {
+    const groups = new Map();
+    for (const d of allAttachmentDefs()) {
+        (groups.get(d.group) ?? groups.set(d.group, []).get(d.group)).push(d);
+    }
+    return groups;
+}
+/** A short description of the node(s) a group of attachments attaches to. */
+function targetSummary(defs) {
+    const t = defs[0].target;
+    if (typeof t === 'string')
+        return `\`<${t}>\``;
+    const classes = Array.isArray(t) ? t : [t];
+    return classes.map((c) => `\`<${c.name}>\``).join('/');
+}
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+function transformLine() {
+    return Object.entries(TRANSFORM_ATTRS)
+        .map(([name, meta]) => `\`${name}\` (${typeLabel(meta.type)})`)
+        .join(', ');
+}
+function nodeAttrLines(attrs, compact = false) {
+    return Object.entries(attrs).map(([name, meta]) => {
+        const dflt = meta.default !== undefined ? ` = \`${codecs[meta.type].serialize(meta.default)}\`` : '';
+        const desc = meta.description && !compact ? ` — ${meta.description}` : '';
+        const req = meta.required ? ' *(required)*' : '';
+        return `- \`${name}\` (${typeLabel(meta.type)})${dflt}${req}${desc}`;
+    });
+}
+function propertyLine(meta, compact = false) {
+    const desc = meta.description && !compact ? ` — ${meta.description}` : '';
+    const req = meta.required ? ' *(required)*' : '';
+    if (typeof meta.type !== 'string')
+        return `(reference → \`<${meta.type.name}>\`, as \`"#id"\`)${req}${desc}`;
+    if (meta.type === 'node')
+        return `(reference → node, as \`"#id"\`)${req}${desc}`;
+    if (meta.type === 'prefab')
+        return `(prefab file → \`"name.prefab.xml"\`, spawnable at runtime)${req}${desc}`;
+    const dflt = meta.default !== undefined ? ` = \`${meta.default}\`` : '';
+    return `(${typeLabel(meta.type)})${dflt}${req}${desc}`;
+}
+const typeLabel = (type) => (type === 'euler' ? 'degrees' : type);
+function example() {
+    return [
+        '<Scene>',
+        '  <AmbientLight intensity="0.3" />',
+        '  <DirectionalLight intensity="2" position="3 5 2" />',
+        '',
+        '  <Mesh id="Hero" position="0 1 0" rotation="0 45 0">',
+        '    <BoxGeometry width="1.5" />',
+        '    <MeshStandardMaterial color="#4f8ef7" metalness="0.6" />',
+        '    <Components>',
+        '      <Rotator speed="2" />',
+        '      <Oscillator id="bob" amplitude="0.5" />',
+        '    </Components>',
+        '  </Mesh>',
+        '',
+        '  <Mesh id="Chaser" position="3 1 0">',
+        '    <SphereGeometry radius="0.3" />',
+        '    <Components>',
+        '      <Follow source="#bob" scale="2" />',
+        '      <LookAt target="#Hero" />',
+        '    </Components>',
+        '  </Mesh>',
+        '</Scene>',
+    ].join('\n');
+}
+function prefabExample() {
+    return [
+        '<!-- turbine.prefab.xml -->',
+        '<Prefab>',
+        '  <Mesh id="body" position="0 1 0">',
+        '    <CylinderGeometry height="2" />',
+        '    <Components><Oscillator id="osc" amplitude="0.5" /></Components>',
+        '  </Mesh>',
+        '</Prefab>',
+        '',
+        '<!-- in a scene: two instances, one overridden -->',
+        '<PrefabInstance src="turbine.prefab.xml" id="t1" position="0 0 0" />',
+        '<PrefabInstance src="turbine.prefab.xml" id="t2" position="5 0 0">',
+        '  <Override target="#osc" amplitude="1.5" />',
+        '</PrefabInstance>',
+        '<!-- reach an instance internal from elsewhere: target="#t2/osc" -->',
+    ].join('\n');
+}

package/dist/exporters/xsd.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generates a no-namespace XSD 1.0 from the live registries (node tags +
+ * components). Point an editor's XML language server at it (via
+ * `xsi:noNamespaceSchemaLocation="scene.xsd"`) to get attribute autocomplete and
+ * inline validation for free — the same data the runtime Validator checks, in a
+ * form stock IDE tooling understands.
+ *
+ * The structure favors editor assistance over strict validation (e.g. it does
+ * not enforce "exactly one geometry per Mesh" — that's the Validator's job and
+ * would fight XSD 1.0's Unique Particle Attribution rule). Every element still
+ * carries a precise, typed attribute list.
+ */
+export declare function generateXsd(): string;