@scenoco-three/compiler 0.1.0

package/dist/dsl/SceneParser.js

@@ -0,0 +1,59 @@
+import { SaxesParser } from 'saxes';
+/**
+ * Parse a scene XML string into a position-aware element tree. Returns XML
+ * syntax errors (malformed markup) as diagnostics; semantic validation against
+ * the schema is a separate pass (see Validator).
+ */
+export function parseScene(xml) {
+    const parser = new SaxesParser({ fileName: 'scene' });
+    const diagnostics = [];
+    let root = null;
+    const stack = [];
+    parser.on('opentagstart', (tag) => {
+        const el = {
+            tag: tag.name,
+            attributes: new Map(),
+            children: [],
+            parent: stack[stack.length - 1] ?? null,
+            // saxes columns are 0-based; present 1-based to match editor gutters.
+            line: parser.line,
+            column: parser.column + 1,
+        };
+        if (el.parent)
+            el.parent.children.push(el);
+        else
+            root ??= el;
+        stack.push(el);
+    });
+    parser.on('attribute', (attr) => {
+        const top = stack[stack.length - 1];
+        if (top)
+            top.attributes.set(attr.name, attr.value);
+    });
+    parser.on('closetag', () => {
+        stack.pop();
+    });
+    parser.on('error', (e) => {
+        diagnostics.push({
+            line: parser.line,
+            column: parser.column + 1,
+            code: 'xml-syntax',
+            message: e.message,
+        });
+    });
+    try {
+        parser.write(xml).close();
+    }
+    catch {
+        // saxes throws after emitting the 'error' event; the diagnostic is already recorded.
+    }
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    if (!root) {
+        return {
+            ok: false,
+            diagnostics: [{ line: 1, column: 1, code: 'empty-document', message: 'No root element found' }],
+        };
+    }
+    return { ok: true, root };
+}

package/dist/dsl/Validator.d.ts

@@ -0,0 +1,15 @@
+import { type SceDiagnostic } from './diagnostics.js';
+import type { SceElement } from './SceneParser.js';
+/**
+ * Validates a parsed scene tree against the node and component registries,
+ * collecting *every* problem (never fail-fast) with a source position and an
+ * LLM-actionable message. This is the heart of the edit→check→fix loop: the
+ * `scenoco validate` CLI is a thin wrapper over this.
+ */
+export declare function validateScene(root: SceElement): SceDiagnostic[];
+/**
+ * Validates a prefab file: a `<Prefab>` root wrapping exactly one spatial node.
+ * Prefabs must be **self-contained** — every `#ref` resolves within the file —
+ * which is what makes them instantiable at runtime without a surrounding scene.
+ */
+export declare function validatePrefab(root: SceElement): SceDiagnostic[];

package/dist/dsl/Validator.js

@@ -0,0 +1,331 @@
+import { isScalarType, Registry, getNodeDef, getAttachmentDef, allAttachmentDefs, attachmentAcceptsNode, attachmentTags, isSpatial, nodeTags, TRANSFORM_ATTRS, } from '@scenoco-three/core/internal';
+import { nearestName } from './diagnostics.js';
+import { codecs } from './types.js';
+/**
+ * Validates a parsed scene tree against the node and component registries,
+ * collecting *every* problem (never fail-fast) with a source position and an
+ * LLM-actionable message. This is the heart of the edit→check→fix loop: the
+ * `scenoco validate` CLI is a thin wrapper over this.
+ */
+export function validateScene(root) {
+    const ctx = new ValidationContext();
+    if (root.tag !== 'Scene') {
+        ctx.error(root, 'bad-root', `Root element must be <Scene>, got <${root.tag}>`);
+        // Still walk it as best we can, so attribute/child errors surface too.
+    }
+    ctx.walk(root);
+    ctx.resolveReferences();
+    ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
+    return ctx.diagnostics;
+}
+/**
+ * Validates a prefab file: a `<Prefab>` root wrapping exactly one spatial node.
+ * Prefabs must be **self-contained** — every `#ref` resolves within the file —
+ * which is what makes them instantiable at runtime without a surrounding scene.
+ */
+export function validatePrefab(root) {
+    const ctx = new ValidationContext();
+    if (root.tag !== 'Prefab') {
+        ctx.error(root, 'bad-root', `A prefab file's root element must be <Prefab>, got <${root.tag}>`);
+    }
+    for (const attr of root.attributes.keys()) {
+        ctx.error(root, 'unexpected-attr', `A prefab file's <Prefab> root takes no attributes (found "${attr}")`);
+    }
+    const spatial = root.children.filter((c) => isSpatial(c.tag));
+    if (root.children.length !== 1 || spatial.length !== 1) {
+        ctx.error(root, 'bad-prefab-root', `<Prefab> must contain exactly one node (e.g. a <Mesh> or <Group>); found ${root.children.length}`);
+    }
+    for (const child of root.children)
+        ctx.walk(child);
+    ctx.resolveReferences();
+    ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
+    return ctx.diagnostics;
+}
+class ValidationContext {
+    diagnostics = [];
+    // One scene-wide id namespace shared by nodes and components, so a `#id`
+    // reference resolves unambiguously to exactly one element.
+    ids = new Map();
+    componentsByNode = new Map();
+    pendingRefs = [];
+    error(el, code, message) {
+        // Elements spliced in from another file (prefab expansion) carry their
+        // origin so the fix-it loop points at the right file.
+        this.diagnostics.push({ line: el.line, column: el.column, code, message, ...(el.file ? { file: el.file } : {}) });
+    }
+    walk(el) {
+        const def = getNodeDef(el.tag);
+        if (!def) {
+            // Unknown at this position. Components are handled by their parent; if we
+            // reach an unregistered, non-Components tag here it's a genuine unknown.
+            if (el.tag !== 'Components') {
+                const suggestion = nearestName(el.tag, [...nodeTags(), ...attachmentTags(), 'Components']);
+                this.error(el, 'unknown-tag', `Unknown element <${el.tag}>${suggestion ? `. Did you mean <${suggestion}>?` : ''}`);
+            }
+            return;
+        }
+        if (def.kind === 'scene' && el.parent !== null) {
+            this.error(el, 'nested-scene', '<Scene> may only be the root element');
+        }
+        this.validateNodeAttributes(el, def);
+        this.validateChildren(el, def);
+    }
+    validateChildren(el, def) {
+        let componentsCount = 0;
+        // group → first attachment tag seen on this node (for uniqueness diagnostics).
+        const groupFirst = new Map();
+        for (const child of el.children) {
+            const attDef = getAttachmentDef(child.tag);
+            if (attDef) {
+                this.validateAttachment(el, def, child, attDef, groupFirst);
+                continue;
+            }
+            if (child.tag === 'Components') {
+                if (!def.children.components) {
+                    this.error(child, 'misplaced-components', `<Components> is not allowed inside <${el.tag}>`);
+                }
+                else if (++componentsCount > 1) {
+                    this.error(child, 'duplicate-components', `<${el.tag}> may have only one <Components> block`);
+                }
+                this.validateComponentsBlock(el, child);
+                continue;
+            }
+            const childDef = getNodeDef(child.tag);
+            if (childDef) {
+                if (!def.children.object3d) {
+                    this.error(child, 'misplaced-node', `<${child.tag}> is not allowed inside <${el.tag}>`);
+                }
+                this.walk(child);
+                continue;
+            }
+            if (Registry.getComponent(child.tag)) {
+                this.error(child, 'component-outside-block', `<${child.tag}> is a component and must be placed inside a <Components> block`);
+                continue;
+            }
+            // Truly unknown tag.
+            this.walk(child);
+        }
+        // Required attachment groups (e.g. a <Mesh> needs a geometry).
+        for (const [group, tags] of requiredGroupsFor(def)) {
+            if (!groupFirst.has(group)) {
+                this.error(el, 'missing-required-attachment', `<${el.tag}> requires a ${group} (e.g. <${tags[0]} />)`);
+            }
+        }
+    }
+    /** One attachment rule: target-compatible? group cardinality ok? attrs valid? */
+    validateAttachment(host, hostDef, child, attDef, groupFirst) {
+        if (!attachmentAcceptsNode(attDef, hostDef)) {
+            this.error(child, 'attachment-wrong-target', `<${child.tag}> cannot attach to <${host.tag}>${targetHint(attDef)}`);
+        }
+        else {
+            const prev = groupFirst.get(attDef.group);
+            if (prev !== undefined && attDef.unique) {
+                this.error(child, 'duplicate-attachment', `<${host.tag}> may have only one ${attDef.group} (already has <${prev}>)`);
+            }
+            else if (prev === undefined) {
+                groupFirst.set(attDef.group, child.tag);
+            }
+        }
+        this.validateAttachmentAttributes(child, attDef);
+        this.rejectChildElements(child);
+    }
+    validateComponentsBlock(host, block) {
+        if (block.attributes.size > 0) {
+            this.error(block, 'unexpected-attr', `<Components> takes no attributes`);
+        }
+        const hostComponents = this.componentsByNode.get(host) ?? [];
+        this.componentsByNode.set(host, hostComponents);
+        for (const child of block.children) {
+            const entry = Registry.getComponent(child.tag);
+            if (!entry) {
+                if (getNodeDef(child.tag)) {
+                    this.error(child, 'not-a-component', `<${child.tag}> is not a component; <Components> may only contain components`);
+                }
+                else {
+                    const suggestion = nearestName(child.tag, Registry.componentNames());
+                    this.error(child, 'unknown-component', `Unknown component <${child.tag}>${suggestion ? `. Did you mean <${suggestion}>?` : ''}`);
+                }
+                continue;
+            }
+            this.validateComponentAttributes(child, entry.meta.properties);
+            hostComponents.push(entry.ctor);
+            this.rejectChildElements(child);
+        }
+    }
+    /** Validate a node element's transform + type-specific attributes. */
+    validateNodeAttributes(el, def) {
+        const allowed = { ...TRANSFORM_ATTRS, ...def.attrs };
+        for (const [attr, raw] of el.attributes) {
+            if (isNamespaceAttr(attr))
+                continue; // xmlns / xsi schema hints for IDEs
+            if (attr === 'id') {
+                this.registerId(el, raw, 'node');
+                continue;
+            }
+            const meta = allowed[attr];
+            if (!meta) {
+                const suggestion = nearestName(attr, [...Object.keys(allowed), 'id']);
+                this.error(el, 'unknown-attr', `<${el.tag}> has no attribute "${attr}"${suggestion ? `. Did you mean "${suggestion}"?` : ''}`);
+                continue;
+            }
+            this.parseScalarAttr(el, attr, raw, meta.type);
+        }
+        for (const [attr, meta] of Object.entries(allowed)) {
+            if (meta.required && !el.attributes.has(attr)) {
+                this.error(el, 'missing-attr', `<${el.tag}> is missing required attribute "${attr}"`);
+            }
+        }
+    }
+    /** Validate an attachment element's attributes (no transform/id; `src` allowed). */
+    validateAttachmentAttributes(el, def) {
+        for (const [attr, raw] of el.attributes) {
+            if (isNamespaceAttr(attr))
+                continue;
+            // An attachment may pull its defaults from a resource file (e.g. a shared
+            // .material.xml); the file itself is resolved and checked at compile time.
+            if (attr === 'src')
+                continue;
+            const meta = def.attrs[attr];
+            if (!meta) {
+                const suggestion = nearestName(attr, [...Object.keys(def.attrs), 'src']);
+                this.error(el, 'unknown-attr', `<${el.tag}> has no attribute "${attr}"${suggestion ? `. Did you mean "${suggestion}"?` : ''}`);
+                continue;
+            }
+            this.parseScalarAttr(el, attr, raw, meta.type);
+        }
+        for (const [attr, meta] of Object.entries(def.attrs)) {
+            if (meta.required && !el.attributes.has(attr)) {
+                this.error(el, 'missing-attr', `<${el.tag}> is missing required attribute "${attr}"`);
+            }
+        }
+    }
+    /** Validate a component element. */
+    validateComponentAttributes(el, props) {
+        for (const [attr, raw] of el.attributes) {
+            if (isNamespaceAttr(attr))
+                continue;
+            if (attr === 'id') {
+                this.registerId(el, raw, 'component');
+                continue;
+            }
+            const meta = props.get(attr);
+            if (!meta) {
+                const suggestion = nearestName(attr, [...props.keys(), 'id']);
+                this.error(el, 'unknown-attr', `<${el.tag}> has no property "${attr}"${suggestion ? `. Did you mean "${suggestion}"?` : ''}`);
+                continue;
+            }
+            if (isScalarType(meta.type)) {
+                this.parseScalarAttr(el, attr, raw, meta.type);
+            }
+            else if (meta.type === 'prefab') {
+                // A prefab prop is a `.prefab.xml` file path (no `#`); the file itself is
+                // resolved, compiled, and checked at compile time (with its own diagnostics).
+                this.validatePrefabAttr(el, attr, raw);
+            }
+            else {
+                this.recordReference(el, attr, raw, meta.type);
+            }
+        }
+        for (const [attr, meta] of props) {
+            if (meta.required && !el.attributes.has(attr)) {
+                this.error(el, 'missing-attr', `<${el.tag}> is missing required property "${attr}"`);
+            }
+        }
+    }
+    /** Record a `#id` reference for resolution once the whole tree is known. */
+    recordReference(el, attr, raw, declared) {
+        const value = raw.trim();
+        if (value === '')
+            return; // optional, left unset
+        if (!value.startsWith('#')) {
+            this.error(el, 'ref-missing-hash', `<${el.tag}> "${attr}" must reference an id with a leading "#" (e.g. "#turbine")`);
+            return;
+        }
+        this.pendingRefs.push({ element: el, attr, value: value.slice(1), declared });
+    }
+    /** A `prefab` prop must name a file; `#id` here is almost always a mistake. */
+    validatePrefabAttr(el, attr, raw) {
+        const value = raw.trim();
+        if (value === '')
+            return; // optional, left unset
+        if (value.startsWith('#')) {
+            this.error(el, 'bad-value', `<${el.tag}> "${attr}" is a prefab file path (e.g. "enemy.prefab.xml"), not an id reference — drop the leading "#"`);
+        }
+    }
+    parseScalarAttr(el, attr, raw, type) {
+        const result = codecs[type].parse(raw);
+        if (!result.ok) {
+            this.error(el, 'bad-value', `<${el.tag}> attribute "${attr}": ${result.message}`);
+        }
+    }
+    rejectChildElements(el) {
+        for (const child of el.children) {
+            this.error(child, 'unexpected-child', `<${el.tag}> may not contain child elements (found <${child.tag}>)`);
+        }
+    }
+    registerId(el, raw, kind) {
+        // `/` is allowed in ids — references are literal `#id` lookups, so a scoped
+        // id like `t1/osc` (from prefab expansion, or authored) is unambiguous.
+        const existing = this.ids.get(raw);
+        if (existing) {
+            this.error(el, 'duplicate-id', `Duplicate id "${raw}" (first used at line ${existing.el.line})`);
+            return;
+        }
+        this.ids.set(raw, { el, kind });
+    }
+    resolveReferences() {
+        for (const ref of this.pendingRefs) {
+            const entry = this.ids.get(ref.value);
+            if (!entry) {
+                this.error(ref.element, 'unresolved-ref', `<${ref.element.tag}> "${ref.attr}" references "#${ref.value}", which has no matching id`);
+                continue;
+            }
+            if (ref.declared === 'node') {
+                if (entry.kind !== 'node') {
+                    this.error(ref.element, 'ref-type-mismatch', `<${ref.element.tag}> "${ref.attr}" expects a node, but "#${ref.value}" is a component`);
+                }
+                continue;
+            }
+            this.resolveComponentRef(ref, ref.declared, entry);
+        }
+    }
+    resolveComponentRef(ref, declared, entry) {
+        if (entry.kind === 'component') {
+            const compEntry = Registry.getComponent(entry.el.tag);
+            if (compEntry && !isAssignable(compEntry.ctor, declared)) {
+                this.error(ref.element, 'ref-type-mismatch', `<${ref.element.tag}> "${ref.attr}" expects a ${declared.name}, but "#${ref.value}" is a ${entry.el.tag}`);
+            }
+            return;
+        }
+        // The id names a node: resolve to a component of the declared type on it.
+        const matches = (this.componentsByNode.get(entry.el) ?? []).filter((c) => isAssignable(c, declared));
+        if (matches.length === 0) {
+            this.error(ref.element, 'unresolved-ref', `<${ref.element.tag}> "${ref.attr}" expects a ${declared.name} on node "#${ref.value}", but that node has none`);
+        }
+        else if (matches.length > 1) {
+            this.error(ref.element, 'ambiguous-ref', `<${ref.element.tag}> "${ref.attr}": node "#${ref.value}" has multiple ${declared.name} components — give the target component its own id and reference that`);
+        }
+    }
+}
+function isAssignable(actual, declared) {
+    return actual === declared || actual.prototype instanceof declared;
+}
+/** Required attachment groups for a node (e.g. a <Mesh> requires a 'geometry'). */
+function requiredGroupsFor(node) {
+    const groups = new Map();
+    for (const d of allAttachmentDefs()) {
+        if (!d.required || !attachmentAcceptsNode(d, node))
+            continue;
+        (groups.get(d.group) ?? groups.set(d.group, []).get(d.group)).push(d.tag);
+    }
+    return groups;
+}
+/** A fix-it hint listing the node tags an attachment can attach to. */
+function targetHint(attDef) {
+    const tags = nodeTags().filter((t) => attachmentAcceptsNode(attDef, getNodeDef(t)));
+    return tags.length > 0 ? ` (it attaches to ${tags.map((t) => `<${t}>`).join(', ')})` : '';
+}
+/** XML namespace bookkeeping (xmlns, xsi:*) — used to wire an XSD, ignored by us. */
+function isNamespaceAttr(name) {
+    return name === 'xmlns' || name.startsWith('xmlns:') || name.startsWith('xsi:');
+}

package/dist/dsl/bundle.d.ts

@@ -0,0 +1,9 @@
+import { type Bundle, type BundleKind, type CompiledScene } from '@scenoco-three/core/internal';
+/**
+ * Encode a CompiledScene into the optimized bundle (string pool + default
+ * elision + TRS special-case + bitwise-NOT refs). Build-time only; the runtime
+ * decoder reverses it. See bundle-format.ts for the wire layout.
+ */
+export declare function bundleScene(compiled: CompiledScene, kind?: BundleKind): Bundle;
+/** Encode a prefab CompiledScene for runtime `engine.instantiate`. */
+export declare function bundlePrefab(compiled: CompiledScene): Bundle;

package/dist/dsl/bundle.js

@@ -0,0 +1,151 @@
+import { isScalarType, BUNDLE_VERSION, ComponentFlag, NodeFlag, componentPropEntries, nodeAttrEntries, attachmentAttrEntries, valueEquals, } from '@scenoco-three/core/internal';
+/**
+ * Encode a CompiledScene into the optimized bundle (string pool + default
+ * elision + TRS special-case + bitwise-NOT refs). Build-time only; the runtime
+ * decoder reverses it. See bundle-format.ts for the wire layout.
+ */
+export function bundleScene(compiled, kind = 'scene') {
+    const pool = buildStringPool(compiled);
+    const intern = (s) => pool.index.get(s);
+    const attachments = compiled.attachments.map((a) => encodeTag(a, intern));
+    const components = compiled.components.map((c) => encodeComponent(c, intern));
+    const nodes = compiled.nodes.map((n) => encodeNode(n, intern));
+    // Embedded prefabs are self-contained sub-bundles (their own string pool), so
+    // they nest cleanly; the slot is appended only when the scene uses one.
+    const asset = compiled.prefabs?.length
+        ? [nodes, attachments, components, compiled.root, compiled.prefabs.map((p) => bundlePrefab(p))]
+        : [nodes, attachments, components, compiled.root];
+    // The `kind` slot is appended only for prefabs, so scene bundles stay at 3 elements.
+    return kind === 'prefab' ? [BUNDLE_VERSION, pool.strings, asset, 'prefab'] : [BUNDLE_VERSION, pool.strings, asset];
+}
+/** Encode a prefab CompiledScene for runtime `engine.instantiate`. */
+export function bundlePrefab(compiled) {
+    return bundleScene(compiled, 'prefab');
+}
+// ---- string pool ----------------------------------------------------------
+function buildStringPool(compiled) {
+    const counts = new Map();
+    const add = (s) => {
+        if (s !== undefined)
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+    };
+    const addStringAttrs = (entries, attrs) => {
+        for (const [name, meta] of entries) {
+            if (meta.type === 'string')
+                add(attrs[name]);
+        }
+    };
+    for (const n of compiled.nodes) {
+        add(n.tag);
+        add(n.id);
+        addStringAttrs(nodeAttrEntries(n.tag), n.attrs);
+    }
+    for (const a of compiled.attachments) {
+        add(a.tag);
+        addStringAttrs(attachmentAttrEntries(a.tag), a.attrs);
+    }
+    for (const c of compiled.components) {
+        add(c.type);
+        add(c.id);
+        for (const [name, meta] of componentPropEntries(c.type)) {
+            if (meta.type === 'string' && name in c.props)
+                add(c.props[name]);
+        }
+    }
+    // Most-used strings first → smallest indices (cheapest in any varint codec).
+    // Tie-break alphabetically so the bundle is deterministic.
+    const strings = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+        .map(([s]) => s);
+    return { strings, index: new Map(strings.map((s, i) => [s, i])) };
+}
+// ---- records --------------------------------------------------------------
+function encodeTag(asset, intern) {
+    const { mask, values } = encodeAttrs(attachmentAttrEntries(asset.tag), asset.attrs, intern);
+    return [intern(asset.tag), mask, ...values];
+}
+function encodeNode(n, intern) {
+    const { mask, values } = encodeAttrs(nodeAttrEntries(n.tag), n.attrs, intern);
+    let flags = 0;
+    const extras = [];
+    if (n.id !== undefined) {
+        flags |= NodeFlag.Id;
+        extras.push(intern(n.id));
+    }
+    const trs = encodeTransform(n.transform);
+    if (trs) {
+        flags |= NodeFlag.Transform;
+        extras.push(trs);
+    }
+    if (n.attachments.length > 0) {
+        flags |= NodeFlag.Attachments;
+        extras.push(n.attachments);
+    }
+    if (n.components.length > 0) {
+        flags |= NodeFlag.Components;
+        extras.push(n.components);
+    }
+    if (n.children.length > 0) {
+        flags |= NodeFlag.Children;
+        extras.push(n.children);
+    }
+    return [intern(n.tag), flags, mask, ...values, ...extras];
+}
+function encodeComponent(c, intern) {
+    let mask = 0;
+    const values = [];
+    let bit = 0;
+    for (const [name, meta] of componentPropEntries(c.type)) {
+        if (name in c.props) {
+            mask |= 1 << bit;
+            values.push(encodePropValue(c.props[name], meta.type, intern));
+        }
+        bit++;
+    }
+    let flags = 0;
+    const out = [intern(c.type), 0, mask, ...values];
+    if (c.id !== undefined) {
+        flags |= ComponentFlag.Id;
+        out.push(intern(c.id));
+    }
+    out[1] = flags;
+    return out;
+}
+// ---- value helpers --------------------------------------------------------
+function encodeAttrs(entries, attrs, intern) {
+    let mask = 0;
+    const values = [];
+    let bit = 0;
+    for (const [name, meta] of entries) {
+        const value = attrs[name];
+        if (value !== undefined && !valueEquals(value, meta.default)) {
+            mask |= 1 << bit;
+            values.push(meta.type === 'string' ? intern(value) : value);
+        }
+        bit++;
+    }
+    return { mask, values };
+}
+/** Reference props use bitwise-NOT: component → `i`, node → `~i`. */
+function encodePropValue(value, type, intern) {
+    // A prefab prop stores a plain prefabs[] index (the registered type, not the
+    // sign, tells the decoder it is a prefab — no collision with node/component).
+    if (type === 'prefab')
+        return value.prefab;
+    if (!isScalarType(type)) {
+        const ref = value;
+        return 'component' in ref ? ref.component : ~ref.node;
+    }
+    if (type === 'string')
+        return intern(value);
+    return value;
+}
+function encodeTransform(t) {
+    const isIdentity = t.position.every((v) => v === 0) &&
+        t.rotation.every((v) => v === 0) &&
+        t.scale.every((v) => v === 1) &&
+        t.visible;
+    if (isIdentity)
+        return null;
+    return [...t.position, ...t.rotation, ...t.scale, t.visible ? 1 : 0];
+}

package/dist/dsl/compile.d.ts

@@ -0,0 +1,36 @@
+import { type CompiledScene } from '@scenoco-three/core/internal';
+import type { SceDiagnostic } from './diagnostics.js';
+export type { CompiledScene, CompiledNode, CompiledAsset, CompiledComponent, CompiledTransform, CompiledRef, CompiledValue, } from '@scenoco-three/core/internal';
+export type CompileResult = {
+    ok: true;
+    scene: CompiledScene;
+} | {
+    ok: false;
+    diagnostics: SceDiagnostic[];
+};
+/** A referenced file loaded by a resolver: its canonical path and contents. */
+export interface ResolvedFile {
+    path: string;
+    contents: string;
+}
+/**
+ * Loads a file referenced by `src=` (a material/prefab resource), resolving
+ * `request` relative to `referrer`. Returns null if it can't be found. The CLI
+ * supplies a filesystem resolver; a browser host can read from a bundled map.
+ */
+export type ResourceResolver = (request: string, referrer: string) => ResolvedFile | null;
+export interface CompileOptions {
+    /** Path of the scene being compiled — the referrer for relative `src=` paths. */
+    path?: string;
+    /** Required for scenes that use `src=` to pull in resource files. */
+    resolve?: ResourceResolver;
+}
+/** Full pipeline: parse → expand prefabs → validate → compile. */
+export declare function compileSceneXml(xml: string, options?: CompileOptions): CompileResult;
+/**
+ * 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 declare function compilePrefabXml(xml: string, options?: CompileOptions): CompileResult;