@scenoco-three/compiler 0.1.0

package/dist/dsl/compile.js

@@ -0,0 +1,308 @@
+import { isScalarType, isSpatial, Registry, getNodeDef, getAttachmentDef, TRANSFORM_ATTRS, } from '@scenoco-three/core/internal';
+import { parseScene } from './SceneParser.js';
+import { validatePrefab, validateScene } from './Validator.js';
+import { expandPrefabs } from './prefab.js';
+import { codecs } from './types.js';
+/** Full pipeline: parse → expand prefabs → validate → compile. */
+export function compileSceneXml(xml, options = {}) {
+    const parsed = parseScene(xml);
+    if (!parsed.ok)
+        return { ok: false, diagnostics: parsed.diagnostics };
+    // Expand <PrefabInstance src> elements inline before validation, so the
+    // validator and compiler see ordinary nodes (the bundle format is prefab-agnostic).
+    const expansion = [];
+    expandPrefabs(parsed.root, options.path ?? '', options, expansion);
+    if (expansion.length > 0)
+        return { ok: false, diagnostics: sortDiagnostics(expansion) };
+    const diagnostics = validateScene(parsed.root);
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    const result = compileTree(parsed.root, options);
+    if (result.diagnostics.length > 0)
+        return { ok: false, diagnostics: result.diagnostics };
+    return { ok: true, scene: result.scene };
+}
+/**
+ * Compile a `.prefab.xml` file into a standalone bundle for **dynamic
+ * instantiation** at runtime (`engine.instantiate`). The compiled root is the
+ * prefab's single node; ids stay local (each runtime instance is its own
+ * subtree, and internal references are already resolved to indices).
+ */
+export function compilePrefabXml(xml, options = {}) {
+    const parsed = parseScene(xml);
+    if (!parsed.ok)
+        return { ok: false, diagnostics: parsed.diagnostics };
+    const expansion = [];
+    expandPrefabs(parsed.root, options.path ?? '', options, expansion);
+    if (expansion.length > 0)
+        return { ok: false, diagnostics: sortDiagnostics(expansion) };
+    const diagnostics = validatePrefab(parsed.root);
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    const prefabRoot = parsed.root.children.find((c) => isSpatial(c.tag));
+    const result = compileTree(prefabRoot, options);
+    if (result.diagnostics.length > 0)
+        return { ok: false, diagnostics: result.diagnostics };
+    return { ok: true, scene: result.scene };
+}
+function sortDiagnostics(diagnostics) {
+    return [...diagnostics].sort((a, b) => (a.file ?? '').localeCompare(b.file ?? '') || a.line - b.line || a.column - b.column);
+}
+/** Compile an already-validated tree, resolving referenced resource files. */
+function compileTree(root, options) {
+    const scene = { root: 0, nodes: [], attachments: [], components: [] };
+    const diagnostics = [];
+    const nodeIdToIndex = new Map();
+    const componentIdToIndex = new Map();
+    const componentsOnNode = new Map();
+    const pending = [];
+    // One content-addressed pool so identical attachments (geometry/material/…) are shared.
+    const attachmentPool = new Map();
+    // Prefab files referenced by `prefab` props, deduped by source path.
+    const prefabPool = new Map();
+    const internAttachment = (asset) => {
+        const key = `${asset.tag}|${JSON.stringify(asset.attrs)}`;
+        const existing = attachmentPool.get(key);
+        if (existing !== undefined)
+            return existing;
+        const index = scene.attachments.length;
+        scene.attachments.push(asset);
+        attachmentPool.set(key, index);
+        return index;
+    };
+    /**
+     * Resolve a `prefab="…"` file, compile it to a standalone prefab CompiledScene,
+     * and intern it into the scene's prefabs[] pool. Returns its index, or
+     * undefined (with a diagnostic) if it can't be resolved/compiled.
+     */
+    const internPrefab = (src, el) => {
+        const cached = prefabPool.get(src);
+        if (cached !== undefined)
+            return cached;
+        const push = (code, message, file) => diagnostics.push({ line: el.line, column: el.column, code, message, ...(file ? { file } : {}) });
+        if (!options.resolve) {
+            push('no-resolver', `<${el.tag}> uses prefab="${src}" but no resource resolver is configured`);
+            return undefined;
+        }
+        const file = options.resolve(src, options.path ?? '');
+        if (!file) {
+            push('resource-not-found', `Cannot resolve prefab="${src}"`);
+            return undefined;
+        }
+        const result = compilePrefabXml(file.contents, { path: file.path, resolve: options.resolve });
+        if (!result.ok) {
+            for (const d of result.diagnostics)
+                diagnostics.push({ ...d, file: d.file ?? file.path });
+            return undefined;
+        }
+        const prefabs = (scene.prefabs ??= []);
+        const index = prefabs.length;
+        prefabs.push(result.scene);
+        prefabPool.set(src, index);
+        return index;
+    };
+    const buildNode = (el, parent) => {
+        const def = getNodeDef(el.tag);
+        const index = scene.nodes.length;
+        const id = el.attributes.get('id');
+        const node = {
+            tag: el.tag,
+            ...(id !== undefined ? { id } : {}),
+            parent,
+            children: [],
+            transform: compileTransform(el),
+            attrs: compileAttrs(el, def.attrs),
+            attachments: [],
+            components: [],
+        };
+        scene.nodes.push(node);
+        if (id !== undefined)
+            nodeIdToIndex.set(id, index);
+        for (const child of el.children) {
+            const attDef = getAttachmentDef(child.tag);
+            if (attDef) {
+                const attrs = resolveAttachmentAttrs(child, attDef.attrs, options, diagnostics);
+                node.attachments.push(internAttachment({ tag: child.tag, attrs }));
+            }
+            else if (child.tag === 'Components') {
+                buildComponents(child, index, node);
+            }
+            else if (getNodeDef(child.tag)) {
+                node.children.push(buildNode(child, index));
+            }
+        }
+        return index;
+    };
+    const buildComponents = (block, nodeIndex, node) => {
+        const targets = componentsOnNode.get(nodeIndex) ?? [];
+        componentsOnNode.set(nodeIndex, targets);
+        for (const el of block.children) {
+            const entry = Registry.getComponent(el.tag);
+            if (!entry)
+                continue; // validated; unreachable
+            const componentIndex = scene.components.length;
+            const id = el.attributes.get('id');
+            const compiled = {
+                type: el.tag,
+                ...(id !== undefined ? { id } : {}),
+                node: nodeIndex,
+                props: {},
+            };
+            scene.components.push(compiled);
+            node.components.push(componentIndex);
+            targets.push({ ctor: entry.ctor, componentIndex });
+            if (id !== undefined)
+                componentIdToIndex.set(id, componentIndex);
+            collectComponentProps(el, entry.meta.properties, componentIndex, compiled, pending, internPrefab);
+        }
+    };
+    buildNode(root, -1);
+    // Second pass: resolve references now that every node and component is indexed.
+    for (const ref of pending) {
+        const resolved = resolveRef(ref, nodeIdToIndex, componentIdToIndex, componentsOnNode);
+        if (resolved)
+            scene.components[ref.componentIndex].props[ref.attr] = resolved;
+    }
+    return { scene, diagnostics };
+}
+/**
+ * Compute an attachment's attributes, pulling defaults from a `src=` resource
+ * file when present (inline attributes override the file) — e.g. a shared
+ * `.material.xml`. Diagnostics for a missing/invalid file point at that file.
+ */
+function resolveAttachmentAttrs(el, attrs, options, diagnostics) {
+    const src = el.attributes.get('src');
+    if (src === undefined)
+        return compileAttrs(el, attrs);
+    const push = (d) => diagnostics.push({ line: el.line, column: el.column, ...d });
+    if (!options.resolve) {
+        push({ code: 'no-resolver', message: `<${el.tag}> uses src="${src}" but no resource resolver is configured` });
+        return compileAttrs(el, attrs);
+    }
+    const file = options.resolve(src, options.path ?? '');
+    if (!file) {
+        push({ code: 'resource-not-found', message: `Cannot resolve src="${src}"` });
+        return compileAttrs(el, attrs);
+    }
+    const parsed = parseScene(file.contents);
+    if (!parsed.ok) {
+        for (const d of parsed.diagnostics)
+            diagnostics.push({ ...d, file: file.path });
+        return compileAttrs(el, attrs);
+    }
+    const fileRoot = parsed.root;
+    if (fileRoot.tag !== el.tag) {
+        push({ code: 'resource-tag-mismatch', message: `src="${src}" defines a <${fileRoot.tag}>, but it is used as a <${el.tag}>` });
+        return compileAttrs(el, attrs);
+    }
+    // File attributes are the base; inline attributes (except src) override them.
+    const merged = new Map();
+    for (const [k, v] of fileRoot.attributes)
+        if (k in attrs)
+            merged.set(k, v);
+    for (const [k, v] of el.attributes)
+        if (k !== 'src' && k in attrs)
+            merged.set(k, v);
+    // Validate the file's own values so a bad resource reports against its file.
+    for (const [k, v] of fileRoot.attributes) {
+        const meta = attrs[k];
+        if (!meta) {
+            diagnostics.push({ line: fileRoot.line, column: fileRoot.column, file: file.path, code: 'unknown-attr', message: `<${fileRoot.tag}> has no attribute "${k}"` });
+        }
+        else if (!codecs[meta.type].parse(v).ok) {
+            diagnostics.push({ line: fileRoot.line, column: fileRoot.column, file: file.path, code: 'bad-value', message: `<${fileRoot.tag}> attribute "${k}": ${codecs[meta.type].parse(v).message}` });
+        }
+    }
+    const out = {};
+    for (const [key, meta] of Object.entries(attrs)) {
+        out[key] = scalarValue(meta.type, merged.get(key), meta.default);
+    }
+    return out;
+}
+function compileTransform(el) {
+    const t = (key) => {
+        const meta = TRANSFORM_ATTRS[key];
+        return scalarValue(meta.type, el.attributes.get(key), meta.default);
+    };
+    return {
+        position: t('position'),
+        rotation: t('rotation'),
+        scale: t('scale'),
+        visible: t('visible'),
+    };
+}
+function compileAttrs(el, attrs) {
+    const out = {};
+    for (const [key, meta] of Object.entries(attrs)) {
+        out[key] = scalarValue(meta.type, el.attributes.get(key), meta.default);
+    }
+    return out;
+}
+function collectComponentProps(el, props, componentIndex, compiled, pending, internPrefab) {
+    for (const [attr, raw] of el.attributes) {
+        if (attr === 'id')
+            continue;
+        const meta = props.get(attr);
+        if (!meta)
+            continue; // validated
+        if (isScalarType(meta.type)) {
+            compiled.props[attr] = codecParse(meta.type, raw);
+        }
+        else if (meta.type === 'prefab') {
+            // A prefab prop value is a file path (like src=), not a `#id`. Resolve and
+            // embed it at build time; the runtime hands the component a PrefabRef.
+            const src = raw.trim();
+            if (src !== '') {
+                const index = internPrefab(src, el);
+                if (index !== undefined)
+                    compiled.props[attr] = { prefab: index };
+            }
+        }
+        else {
+            // Reference value is `#id`; store the bare id (validated upstream).
+            const value = raw.trim().replace(/^#/, '');
+            if (value !== '')
+                pending.push({ componentIndex, attr, value, declared: meta.type });
+        }
+    }
+}
+function resolveRef(ref, nodeIdToIndex, componentIdToIndex, componentsOnNode) {
+    if (ref.declared === 'node') {
+        const idx = nodeIdToIndex.get(ref.value);
+        return idx === undefined ? undefined : { node: idx };
+    }
+    const byId = componentIdToIndex.get(ref.value);
+    if (byId !== undefined)
+        return { component: byId };
+    const nodeIndex = nodeIdToIndex.get(ref.value);
+    if (nodeIndex === undefined)
+        return undefined;
+    const declared = ref.declared;
+    const match = (componentsOnNode.get(nodeIndex) ?? []).find((c) => c.ctor === declared || c.ctor.prototype instanceof declared);
+    return match ? { component: match.componentIndex } : undefined;
+}
+const codecParse = (type, raw) => {
+    const r = codecs[type].parse(raw);
+    return r.ok ? r.value : zeroFor(type);
+};
+function scalarValue(type, raw, fallback) {
+    if (raw === undefined)
+        return fallback ?? zeroFor(type);
+    const r = codecs[type].parse(raw);
+    return r.ok ? r.value : (fallback ?? zeroFor(type));
+}
+function zeroFor(type) {
+    switch (type) {
+        case 'bool':
+            return false;
+        case 'string':
+            return '';
+        case 'vec2':
+            return [0, 0];
+        case 'vec3':
+        case 'euler':
+            return [0, 0, 0];
+        default:
+            return 0;
+    }
+}

package/dist/dsl/diagnostics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A single problem found while parsing, validating, or compiling a scene.
+ * Diagnostics carry a source position so agents driving the engine with plain
+ * file tools (grep, line edits) can jump straight to the offending line.
+ */
+export interface SceDiagnostic {
+    /** 1-based line in the source XML. */
+    line: number;
+    /** 1-based column in the source XML. */
+    column: number;
+    /** Stable machine-readable category, e.g. "unknown-tag". */
+    code: string;
+    /** Human- and LLM-actionable description: what's wrong and how to fix it. */
+    message: string;
+    /** Set when the problem is in a referenced file (a resource or prefab), not the scene. */
+    file?: string;
+}
+/** tsc-style `file:line:col` rendering, e.g. `scene.xml:12:6  unknown-tag  ...`. */
+export declare function formatDiagnostic(d: SceDiagnostic, file?: string): string;
+/** Levenshtein-nearest candidate within a small edit distance, for "did you mean" hints. */
+export declare function nearestName(input: string, candidates: readonly string[]): string | undefined;

package/dist/dsl/diagnostics.js

@@ -0,0 +1,38 @@
+/** tsc-style `file:line:col` rendering, e.g. `scene.xml:12:6  unknown-tag  ...`. */
+export function formatDiagnostic(d, file = '<scene>') {
+    return `${d.file ?? file}:${d.line}:${d.column}  ${d.code}  ${d.message}`;
+}
+/** Levenshtein-nearest candidate within a small edit distance, for "did you mean" hints. */
+export function nearestName(input, candidates) {
+    let best;
+    let bestDist = Infinity;
+    for (const c of candidates) {
+        const d = editDistance(input, c);
+        if (d < bestDist) {
+            bestDist = d;
+            best = c;
+        }
+    }
+    // Only suggest when the typo is plausibly a typo, not an unrelated word.
+    const threshold = Math.max(2, Math.floor(input.length / 3));
+    return best !== undefined && bestDist <= threshold ? best : undefined;
+}
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}

package/dist/dsl/prefab.d.ts

@@ -0,0 +1,30 @@
+import type { CompileOptions } from './compile.js';
+import type { SceDiagnostic } from './diagnostics.js';
+import { type SceElement } from './SceneParser.js';
+/**
+ * Prefab expansion — a pre-pass on the parsed element tree.
+ *
+ * A prefab *file* has a `<Prefab>` root wrapping one node; a *scene* places an
+ * instance of it with `<PrefabInstance src="x.prefab.xml" id="t1" …/>` (the two
+ * tags are distinct so neither is ambiguous). Each `<PrefabInstance>` is
+ * replaced, at compile time, by the prefab file's node subtree:
+ *
+ *  - the prefab file is parsed, recursively expanded, and validated standalone
+ *    (prefabs are self-contained — that's what makes them dynamically loadable);
+ *  - internal ids are namespaced into the instance scope (`osc` → `t1/osc`,
+ *    composing for nested prefabs: `t1/inner/osc`) and internal `#refs` are
+ *    rewritten to match; the prefab root's own id becomes the instance id;
+ *  - instance transform attributes override the prefab root's (file = defaults,
+ *    inline overrides — same rule as material `src=`);
+ *  - `<Override target="#osc" amplitude="2"/>` children patch any internal
+ *    node/component by its prefab-local id;
+ *  - a `<Components>` child adds extra components to the instance root.
+ *
+ * Nesting: a prefab file may itself contain `<PrefabInstance>` children, which
+ * are expanded depth-first (and scoped: `t1/inner/osc`), so prefabs compose.
+ *
+ * Because expansion happens before validation, the validator and compiler see
+ * ordinary nodes — the bundle format is untouched, and the scene can address
+ * instance internals (`target="#t1/osc"`) like any other id.
+ */
+export declare function expandPrefabs(root: SceElement, referrer: string, options: CompileOptions, diagnostics: SceDiagnostic[], stack?: string[]): void;

package/dist/dsl/prefab.js

@@ -0,0 +1,255 @@
+import { isScalarType, isSpatial, getNodeDef, Registry, TRANSFORM_ATTRS, } from '@scenoco-three/core/internal';
+import { parseScene } from './SceneParser.js';
+import { codecs } from './types.js';
+import { validatePrefab } from './Validator.js';
+/**
+ * Prefab expansion — a pre-pass on the parsed element tree.
+ *
+ * A prefab *file* has a `<Prefab>` root wrapping one node; a *scene* places an
+ * instance of it with `<PrefabInstance src="x.prefab.xml" id="t1" …/>` (the two
+ * tags are distinct so neither is ambiguous). Each `<PrefabInstance>` is
+ * replaced, at compile time, by the prefab file's node subtree:
+ *
+ *  - the prefab file is parsed, recursively expanded, and validated standalone
+ *    (prefabs are self-contained — that's what makes them dynamically loadable);
+ *  - internal ids are namespaced into the instance scope (`osc` → `t1/osc`,
+ *    composing for nested prefabs: `t1/inner/osc`) and internal `#refs` are
+ *    rewritten to match; the prefab root's own id becomes the instance id;
+ *  - instance transform attributes override the prefab root's (file = defaults,
+ *    inline overrides — same rule as material `src=`);
+ *  - `<Override target="#osc" amplitude="2"/>` children patch any internal
+ *    node/component by its prefab-local id;
+ *  - a `<Components>` child adds extra components to the instance root.
+ *
+ * Nesting: a prefab file may itself contain `<PrefabInstance>` children, which
+ * are expanded depth-first (and scoped: `t1/inner/osc`), so prefabs compose.
+ *
+ * Because expansion happens before validation, the validator and compiler see
+ * ordinary nodes — the bundle format is untouched, and the scene can address
+ * instance internals (`target="#t1/osc"`) like any other id.
+ */
+export function expandPrefabs(root, referrer, options, diagnostics, stack = []) {
+    for (let i = 0; i < root.children.length; i++) {
+        const child = root.children[i];
+        if (child.tag === 'PrefabInstance') {
+            if (!child.attributes.has('src')) {
+                diagnostics.push({ line: child.line, column: child.column, code: 'prefab-missing-src', message: `<PrefabInstance> requires a src="…prefab.xml" attribute`, ...(child.file ? { file: child.file } : {}) });
+                continue;
+            }
+            const expanded = expandInstance(child, referrer, options, diagnostics, stack);
+            if (expanded) {
+                expanded.parent = root;
+                root.children[i] = expanded;
+            }
+            continue;
+        }
+        expandPrefabs(child, referrer, options, diagnostics, stack);
+    }
+}
+function expandInstance(instance, referrer, options, diagnostics, stack) {
+    const fail = (code, message, el = instance) => void diagnostics.push({ line: el.line, column: el.column, code, message, ...(el.file ? { file: el.file } : {}) });
+    const src = instance.attributes.get('src');
+    const instanceId = instance.attributes.get('id');
+    if (instanceId === undefined || instanceId === '') {
+        fail('prefab-missing-id', `<PrefabInstance src="${src}"> requires an id — instance internals are addressed as "#<id>/<inner>"`);
+        return null;
+    }
+    if (!options.resolve) {
+        fail('no-resolver', `<PrefabInstance> uses src="${src}" but no resource resolver is configured`);
+        return null;
+    }
+    const file = options.resolve(src, referrer);
+    if (!file) {
+        fail('prefab-not-found', `Cannot resolve src="${src}"`);
+        return null;
+    }
+    if (stack.includes(file.path)) {
+        fail('prefab-cycle', `Prefab cycle: ${[...stack, file.path].join(' → ')}`);
+        return null;
+    }
+    const parsed = parseScene(file.contents);
+    if (!parsed.ok) {
+        diagnostics.push(...parsed.diagnostics.map((d) => ({ ...d, file: d.file ?? file.path })));
+        return null;
+    }
+    // Depth-first: expand the prefab's own instances, then validate it standalone.
+    expandPrefabs(parsed.root, file.path, options, diagnostics, [...stack, file.path]);
+    const prefabDiags = validatePrefab(parsed.root);
+    if (prefabDiags.length > 0) {
+        diagnostics.push(...prefabDiags.map((d) => ({ ...d, file: d.file ?? file.path })));
+        return null;
+    }
+    const prefabRoot = parsed.root.children.find((c) => isSpatial(c.tag));
+    const clone = cloneSubtree(prefabRoot, file.path, null);
+    // Scope ids into the instance: root id → instance id, inner `x` → `id/x`.
+    const rename = buildRenameMap(clone, instanceId);
+    applyRenames(clone, rename);
+    // Instance transform attributes override the prefab root's.
+    for (const key of Object.keys(TRANSFORM_ATTRS)) {
+        const value = instance.attributes.get(key);
+        if (value === undefined)
+            continue;
+        const meta = TRANSFORM_ATTRS[key];
+        if (!codecs[meta.type].parse(value).ok) {
+            fail('bad-value', `<PrefabInstance> attribute "${key}": ${codecs[meta.type].parse(value).message}`);
+        }
+        clone.attributes.set(key, value);
+    }
+    for (const attr of instance.attributes.keys()) {
+        if (attr === 'src' || attr === 'id' || attr in TRANSFORM_ATTRS || isNamespaceAttr(attr))
+            continue;
+        fail('unknown-attr', `<PrefabInstance> has no attribute "${attr}" (allowed: src, id, ${Object.keys(TRANSFORM_ATTRS).join(', ')})`);
+    }
+    // Instance children: <Override target="#inner" …/> patches and an optional
+    // <Components> block appended to the instance root.
+    for (const child of instance.children) {
+        if (child.tag === 'Override') {
+            applyOverride(child, clone, rename, instanceId, fail);
+        }
+        else if (child.tag === 'Components') {
+            let block = clone.children.find((c) => c.tag === 'Components');
+            if (!block) {
+                block = { tag: 'Components', attributes: new Map(), children: [], parent: clone, line: child.line, column: child.column };
+                clone.children.push(block);
+            }
+            for (const comp of child.children) {
+                comp.parent = block;
+                block.children.push(comp);
+            }
+        }
+        else {
+            fail('unexpected-child', `<PrefabInstance> may only contain <Override> and <Components> (found <${child.tag}>)`, child);
+        }
+    }
+    return clone;
+}
+// ---- subtree mechanics ------------------------------------------------------
+function cloneSubtree(el, file, parent) {
+    const clone = {
+        tag: el.tag,
+        attributes: new Map(el.attributes),
+        children: [],
+        parent,
+        line: el.line,
+        column: el.column,
+        file: el.file ?? file,
+    };
+    clone.children = el.children.map((c) => cloneSubtree(c, file, clone));
+    return clone;
+}
+/** old prefab-local id → scoped id. The root's own id maps to the instance id. */
+function buildRenameMap(clonedRoot, instanceId) {
+    const rename = new Map();
+    const rootId = clonedRoot.attributes.get('id');
+    if (rootId !== undefined)
+        rename.set(rootId, instanceId);
+    const walk = (el) => {
+        if (el !== clonedRoot) {
+            const id = el.attributes.get('id');
+            if (id !== undefined && idCarrier(el))
+                rename.set(id, `${instanceId}/${id}`);
+        }
+        for (const c of el.children)
+            walk(c);
+    };
+    walk(clonedRoot);
+    // The root always carries the instance id, even if it had none in the file.
+    clonedRoot.attributes.set('id', instanceId);
+    return rename;
+}
+function applyRenames(root, rename) {
+    const walk = (el) => {
+        if (el !== root && idCarrier(el)) {
+            const id = el.attributes.get('id');
+            const renamed = id !== undefined ? rename.get(id) : undefined;
+            if (renamed !== undefined)
+                el.attributes.set('id', renamed);
+        }
+        // Rewrite reference values on component elements (`#old` → `#scoped`).
+        if (el.parent?.tag === 'Components') {
+            const entry = Registry.getComponent(el.tag);
+            if (entry) {
+                for (const [attr, value] of el.attributes) {
+                    const meta = entry.meta.properties.get(attr);
+                    if (!meta || isScalarType(meta.type) || !value.startsWith('#'))
+                        continue;
+                    const renamed = rename.get(value.slice(1).trim());
+                    if (renamed !== undefined)
+                        el.attributes.set(attr, `#${renamed}`);
+                }
+            }
+        }
+        for (const c of el.children)
+            walk(c);
+    };
+    walk(root);
+}
+/** Elements whose `id` participates in the scene namespace (nodes + components). */
+function idCarrier(el) {
+    return isSpatial(el.tag) || el.parent?.tag === 'Components';
+}
+// ---- <Override> -------------------------------------------------------------
+function applyOverride(override, clonedRoot, rename, instanceId, fail) {
+    const target = override.attributes.get('target');
+    if (target === undefined || !target.startsWith('#')) {
+        fail('ref-missing-hash', `<Override> needs target="#<prefab-local id>" (e.g. target="#osc")`, override);
+        return;
+    }
+    const localId = target.slice(1).trim();
+    const scopedId = rename.get(localId) ?? (localId === instanceId ? instanceId : undefined);
+    const found = scopedId !== undefined ? findById(clonedRoot, scopedId) : undefined;
+    if (!found) {
+        const known = [...rename.keys()].join(', ') || '(none)';
+        fail('override-unknown-target', `<Override> target "#${localId}" does not exist in the prefab. Ids declared there: ${known}`, override);
+        return;
+    }
+    // Validate override values against the target's schema *here*, so errors
+    // point at the <Override> the author wrote, not into the prefab file.
+    const schema = attrSchema(found);
+    for (const [attr, value] of override.attributes) {
+        if (attr === 'target')
+            continue;
+        const type = schema.get(attr);
+        if (type === undefined) {
+            fail('unknown-attr', `<Override>: <${found.tag}> has no attribute "${attr}"`, override);
+            continue;
+        }
+        if (type !== null && !codecs[type].parse(value).ok) {
+            fail('bad-value', `<Override> "${attr}": ${codecs[type].parse(value).message}`, override);
+            continue;
+        }
+        found.attributes.set(attr, value);
+    }
+}
+function findById(root, id) {
+    if (root.attributes.get('id') === id)
+        return root;
+    for (const c of root.children) {
+        const found = findById(c, id);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** attr → scalar type for value checking; `null` marks reference props (any #id). */
+function attrSchema(el) {
+    const out = new Map();
+    if (el.parent?.tag === 'Components') {
+        const entry = Registry.getComponent(el.tag);
+        if (entry) {
+            for (const [name, meta] of entry.meta.properties) {
+                out.set(name, isScalarType(meta.type) ? meta.type : null);
+            }
+        }
+        return out;
+    }
+    const def = getNodeDef(el.tag);
+    if (def) {
+        for (const [name, meta] of Object.entries({ ...TRANSFORM_ATTRS, ...def.attrs }))
+            out.set(name, meta.type);
+    }
+    return out;
+}
+function isNamespaceAttr(name) {
+    return name === 'xmlns' || name.startsWith('xmlns:') || name.startsWith('xsi:');
+}

package/dist/dsl/serialize.d.ts

@@ -0,0 +1,14 @@
+import { type CompiledScene } from '@scenoco-three/core/internal';
+/**
+ * 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 declare function serializeScene(scene: CompiledScene): string;