@scenoco-three/compiler 0.1.0

package/dist/exporters/xsd.js

@@ -0,0 +1,199 @@
+import { Registry, allNodeDefs, allAttachmentDefs, attachmentsForNode, TRANSFORM_ATTRS, } from '@scenoco-three/core/internal';
+import { codecs } from '../dsl/types.js';
+/**
+ * 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 function generateXsd() {
+    const defs = allNodeDefs();
+    const byKind = (k) => defs.filter((d) => d.kind === k);
+    const out = [];
+    out.push(`<?xml version="1.0" encoding="UTF-8"?>`);
+    out.push(`<!-- Generated by scenoco. Do not edit by hand; run \`scenoco export\`. -->`);
+    out.push(`<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">`);
+    out.push('');
+    // --- Reusable simple types for math/reference attribute values -----------
+    out.push(`  <!-- Value formats -->`);
+    for (const t of ['vec2', 'vec3', 'euler', 'color']) {
+        out.push(simpleType(t, codecs[t].xsd.pattern));
+    }
+    out.push(simpleType('ref', '#\\S+')); // a "#id" reference
+    out.push('');
+    // --- Shared transform attributes (every spatial node) --------------------
+    out.push(`  <!-- Transform attributes shared by all spatial nodes -->`);
+    out.push(`  <xs:attributeGroup name="transform">`);
+    out.push(`    <xs:attribute name="id" type="xs:string"/>`);
+    for (const [name, meta] of Object.entries(TRANSFORM_ATTRS)) {
+        out.push(`    ${nodeAttr(name, meta)}`);
+    }
+    out.push(`  </xs:attributeGroup>`);
+    out.push('');
+    // --- Attachment elements (geometry/material/fog/…) -----------------------
+    out.push(`  <!-- Attachments: leaves that configure a node (per-node allowed set below) -->`);
+    for (const def of allAttachmentDefs())
+        out.push(attachmentElement(def));
+    out.push('');
+    // --- Components -----------------------------------------------------------
+    out.push(`  <!-- Components (children of <Components>) -->`);
+    for (const name of Registry.componentNames())
+        out.push(componentElement(name));
+    out.push('');
+    out.push(`  <xs:element name="Components">`);
+    out.push(`    <xs:complexType>`);
+    out.push(`      <xs:choice minOccurs="0" maxOccurs="unbounded">`);
+    for (const name of Registry.componentNames())
+        out.push(`        <xs:element ref="${name}"/>`);
+    out.push(`      </xs:choice>`);
+    out.push(`    </xs:complexType>`);
+    out.push(`  </xs:element>`);
+    out.push('');
+    // --- Prefab instance + Override (DSL elements, not registered node tags) --
+    out.push(`  <!-- Prefab instance: expands a .prefab.xml file in place -->`);
+    out.push(prefabElement());
+    out.push(overrideElement());
+    out.push('');
+    // --- Spatial nodes (Object3D family) -------------------------------------
+    const object3d = defs.filter((d) => d.kind === 'object3d');
+    out.push(choiceGroup('object3dNodes', [...object3d.map((d) => d.tag), 'PrefabInstance']));
+    out.push('');
+    out.push(`  <!-- Spatial nodes -->`);
+    for (const def of [...byKind('scene'), ...object3d])
+        out.push(spatialElement(def));
+    out.push(`</xs:schema>`);
+    out.push('');
+    return out.join('\n');
+}
+function prefabElement() {
+    return [
+        `  <xs:element name="PrefabInstance"> <!-- &lt;PrefabInstance src="x.prefab.xml" id="t1" …/&gt; -->`,
+        `    <xs:complexType>`,
+        `      <xs:choice minOccurs="0" maxOccurs="unbounded">`,
+        `        <xs:element ref="Override"/>`,
+        `        <xs:element ref="Components"/>`,
+        `      </xs:choice>`,
+        `      <xs:attribute name="src" type="xs:string" use="required"/> <!-- the .prefab.xml file -->`,
+        `      <xs:attributeGroup ref="transform"/> <!-- incl. id (required by the validator) -->`,
+        `    </xs:complexType>`,
+        `  </xs:element>`,
+    ].join('\n');
+}
+function overrideElement() {
+    return [
+        `  <xs:element name="Override"> <!-- patch a prefab-internal node/component by id -->`,
+        `    <xs:complexType>`,
+        `      <xs:attribute name="target" type="ref" use="required"/> <!-- #&lt;prefab-local id&gt; -->`,
+        `      <xs:anyAttribute processContents="skip"/>`,
+        `    </xs:complexType>`,
+        `  </xs:element>`,
+    ].join('\n');
+}
+// ---- element builders -----------------------------------------------------
+function spatialElement(def) {
+    const lines = [];
+    lines.push(`  <xs:element name="${def.tag}">${comment(def.description)}`);
+    lines.push(`    <xs:complexType>`);
+    const childRefs = [];
+    // Attachments this node accepts (geometry/material/fog/…).
+    for (const att of attachmentsForNode(def))
+        childRefs.push(`<xs:element ref="${att.tag}"/>`);
+    if (def.children.object3d)
+        childRefs.push(`<xs:group ref="object3dNodes"/>`);
+    if (def.children.components)
+        childRefs.push(`<xs:element ref="Components"/>`);
+    if (childRefs.length > 0) {
+        lines.push(`      <xs:choice minOccurs="0" maxOccurs="unbounded">`);
+        for (const ref of childRefs)
+            lines.push(`        ${ref}`);
+        lines.push(`      </xs:choice>`);
+    }
+    lines.push(`      <xs:attributeGroup ref="transform"/>`);
+    for (const [name, meta] of Object.entries(def.attrs))
+        lines.push(`      ${nodeAttr(name, meta)}`);
+    lines.push(`    </xs:complexType>`);
+    lines.push(`  </xs:element>`);
+    return lines.join('\n');
+}
+function attachmentElement(def) {
+    const attrs = Object.entries(def.attrs).map(([name, meta]) => `    ${nodeAttr(name, meta)}`);
+    // Any attachment may pull defaults from a resource file via src= (e.g. .material.xml).
+    attrs.unshift(`    <xs:attribute name="src" type="xs:string"/> <!-- load defaults from a resource file -->`);
+    return [
+        `  <xs:element name="${def.tag}">${comment(def.description)}`,
+        `    <xs:complexType>`,
+        ...attrs,
+        `    </xs:complexType>`,
+        `  </xs:element>`,
+    ].join('\n');
+}
+function componentElement(name) {
+    const meta = Registry.getComponent(name).meta;
+    const attrs = [`    <xs:attribute name="id" type="xs:string"/>`];
+    for (const [attr, prop] of meta.properties)
+        attrs.push(`    ${propertyAttr(attr, prop)}`);
+    return [
+        `  <xs:element name="${name}">${comment(meta.description)}`,
+        `    <xs:complexType>`,
+        ...attrs,
+        `    </xs:complexType>`,
+        `  </xs:element>`,
+    ].join('\n');
+}
+// ---- attribute / type helpers ---------------------------------------------
+function nodeAttr(name, meta) {
+    const use = meta.required ? ` use="required"` : '';
+    return `<xs:attribute name="${name}" type="${xsdType(meta.type)}"${use}/>${comment(meta.description)}`;
+}
+function propertyAttr(name, meta) {
+    const use = meta.required ? ` use="required"` : '';
+    return `<xs:attribute name="${name}" type="${propertyXsdType(meta.type)}"${use}/>${comment(meta.description)}`;
+}
+/** XSD attribute type for a component property. */
+function propertyXsdType(type) {
+    // A prefab prop is a file path; 'node' and Component-class refs are written "#id".
+    if (type === 'prefab')
+        return 'xs:string';
+    if (typeof type === 'string' && type !== 'node')
+        return xsdType(type);
+    return 'ref';
+}
+/** Map a scalar type to its XSD type name (named simpleType or xs: builtin). */
+function xsdType(type) {
+    switch (type) {
+        case 'vec2':
+        case 'vec3':
+        case 'euler':
+        case 'color':
+            return type;
+        default:
+            return codecs[type].xsd.base;
+    }
+}
+function simpleType(name, pattern) {
+    return [
+        `  <xs:simpleType name="${name}">`,
+        `    <xs:restriction base="xs:string">`,
+        `      <xs:pattern value="${escapeXml(pattern)}"/>`,
+        `    </xs:restriction>`,
+        `  </xs:simpleType>`,
+    ].join('\n');
+}
+function choiceGroup(name, tags) {
+    const refs = tags.map((t) => `      <xs:element ref="${t}"/>`);
+    return [`  <xs:group name="${name}">`, `    <xs:choice>`, ...refs, `    </xs:choice>`, `  </xs:group>`].join('\n');
+}
+const comment = (text) => (text ? ` <!-- ${escapeXml(text)} -->` : '');
+function escapeXml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import '@scenoco-three/core/nodes';
+export { parseScene, type SceElement, type ParseResult } from './dsl/SceneParser.js';
+export { validateScene } from './dsl/Validator.js';
+export { compileSceneXml, compilePrefabXml, type CompileResult, type CompileOptions, type ResourceResolver, type ResolvedFile, } from './dsl/compile.js';
+export { bundleScene, bundlePrefab } from './dsl/bundle.js';
+export { serializeScene } from './dsl/serialize.js';
+export { watchSceneFiles, type WatchOptions, type WatchHandle, type WatchEvent, } from './watch.js';
+export { scanComponents, loadComponents, type ComponentScan, type LoadOptions } from './components.js';
+export { scaffoldFiles } from './cli/templates.js';
+export { builtinNodeModules, builtinNodeModule } from '@scenoco-three/core/internal';
+export { generateXsd } from './exporters/xsd.js';
+export { generateDocs, type DocsOptions } from './exporters/docs.js';
+export { formatDiagnostic, type SceDiagnostic } from './dsl/diagnostics.js';
+export { codecs, type ScalarType, type TypeCodec } from './dsl/types.js';
+export type { CompiledScene, CompiledNode, CompiledComponent, CompiledAsset, CompiledRef, CompiledValue, Bundle, } from '@scenoco-three/core/internal';

package/dist/index.js

@@ -0,0 +1,23 @@
+// `@scenoco-three/compiler` — the BUILD-TIME entry point: XML → validated → CompiledScene
+// → optimized Bundle, plus the XSD/docs exporters. This is where the XML parser
+// (saxes), validator, and compiler live; it never ships to the browser runtime.
+//
+// Build-time tooling needs the full built-in node set registered so validation,
+// compilation and exporters see every tag. The runtime entry no longer pulls in
+// node modules (for tree-shaking), so the compiler imports the barrel explicitly.
+// This is the Node process only; it never reaches the browser bundle.
+import '@scenoco-three/core/nodes';
+export { parseScene } from './dsl/SceneParser.js';
+export { validateScene } from './dsl/Validator.js';
+export { compileSceneXml, compilePrefabXml, } from './dsl/compile.js';
+export { bundleScene, bundlePrefab } from './dsl/bundle.js';
+export { serializeScene } from './dsl/serialize.js';
+export { watchSceneFiles, } from './watch.js';
+export { scanComponents, loadComponents } from './components.js';
+export { scaffoldFiles } from './cli/templates.js';
+// Built-in node tag → package subpath that registers it, for usage-based shipping.
+export { builtinNodeModules, builtinNodeModule } from '@scenoco-three/core/internal';
+export { generateXsd } from './exporters/xsd.js';
+export { generateDocs } from './exporters/docs.js';
+export { formatDiagnostic } from './dsl/diagnostics.js';
+export { codecs } from './dsl/types.js';

package/dist/watch.d.ts

@@ -0,0 +1,33 @@
+import { type ResourceResolver } from './dsl/compile.js';
+import type { SceDiagnostic } from './dsl/diagnostics.js';
+export type WatchEvent = {
+    type: 'start';
+    file: string;
+} | {
+    type: 'success';
+    file: string;
+    outputPath: string;
+    durationMs: number;
+} | {
+    type: 'diagnostics';
+    file: string;
+    diagnostics: SceDiagnostic[];
+} | {
+    type: 'error';
+    file: string;
+    message: string;
+};
+export interface WatchOptions {
+    outDir?: string;
+    mode?: 'bundle' | 'compiled';
+    resolve?: ResourceResolver;
+    onEvent?: (event: WatchEvent) => void;
+}
+export interface WatchHandle {
+    close(): Promise<void>;
+}
+/**
+ * Watches scene XML files and writes updated outputs on every change.
+ * Also follows `src=` dependencies discovered during compilation.
+ */
+export declare function watchSceneFiles(entries: string[], options?: WatchOptions): Promise<WatchHandle>;

package/dist/watch.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import chokidar, {} from 'chokidar';
+import { bundlePrefab, bundleScene } from './dsl/bundle.js';
+import { compilePrefabXml, compileSceneXml } from './dsl/compile.js';
+/**
+ * Watches scene XML files and writes updated outputs on every change.
+ * Also follows `src=` dependencies discovered during compilation.
+ */
+export async function watchSceneFiles(entries, options = {}) {
+    const roots = entries.map((f) => resolve(f));
+    const outDir = options.outDir ? resolve(options.outDir) : undefined;
+    const mode = options.mode ?? 'bundle';
+    const onEvent = options.onEvent ?? (() => { });
+    const depToRoots = new Map();
+    const rootToDeps = new Map();
+    let watcher;
+    const updateDeps = (rootFile, deps) => {
+        const prev = rootToDeps.get(rootFile);
+        if (prev) {
+            for (const dep of prev) {
+                const owners = depToRoots.get(dep);
+                if (!owners)
+                    continue;
+                owners.delete(rootFile);
+                if (owners.size === 0)
+                    depToRoots.delete(dep);
+            }
+        }
+        rootToDeps.set(rootFile, deps);
+        for (const dep of deps) {
+            const owners = depToRoots.get(dep) ?? new Set();
+            owners.add(rootFile);
+            depToRoots.set(dep, owners);
+        }
+    };
+    const compileOne = (file) => {
+        const start = Date.now();
+        onEvent({ type: 'start', file });
+        const deps = new Set();
+        const resolver = createTrackingResolver(file, deps, options.resolve);
+        const isPrefab = file.endsWith('.prefab.xml');
+        const compile = isPrefab ? compilePrefabXml : compileSceneXml;
+        const result = compile(readFileSync(file, 'utf8'), {
+            path: file,
+            resolve: resolver,
+        });
+        updateDeps(file, deps);
+        watcher.add([...deps]);
+        if (!result.ok) {
+            onEvent({ type: 'diagnostics', file, diagnostics: result.diagnostics });
+            return;
+        }
+        const outputPath = outputFileFor(file, mode, outDir);
+        const payload = mode === 'bundle'
+            ? isPrefab
+                ? bundlePrefab(result.scene)
+                : bundleScene(result.scene)
+            : result.scene;
+        try {
+            mkdirSync(dirname(outputPath), { recursive: true });
+            writeFileSync(outputPath, JSON.stringify(payload));
+        }
+        catch (e) {
+            onEvent({ type: 'error', file, message: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        onEvent({ type: 'success', file, outputPath, durationMs: Date.now() - start });
+    };
+    watcher = chokidar.watch(roots, { ignoreInitial: false, awaitWriteFinish: true });
+    const onChange = (changedPath) => {
+        const abs = resolve(changedPath);
+        if (roots.includes(abs)) {
+            compileOne(abs);
+            return;
+        }
+        const dependents = depToRoots.get(abs);
+        if (!dependents)
+            return;
+        for (const rootFile of dependents)
+            compileOne(rootFile);
+    };
+    watcher.on('add', onChange);
+    watcher.on('change', onChange);
+    return {
+        async close() {
+            await watcher.close();
+        },
+    };
+}
+function outputFileFor(file, mode, outDir) {
+    const baseName = `${file}${mode === 'bundle' ? '.bundle.json' : '.json'}`;
+    if (!outDir)
+        return baseName;
+    const leaf = baseName.split('/').pop() ?? baseName;
+    return resolve(outDir, leaf);
+}
+function createTrackingResolver(rootFile, deps, fallback) {
+    return (request, referrer) => {
+        if (fallback) {
+            const resolved = fallback(request, referrer);
+            if (resolved)
+                deps.add(resolve(resolved.path));
+            return resolved;
+        }
+        const target = resolve(referrer ? dirname(referrer) : dirname(rootFile), request);
+        if (!existsSync(target))
+            return null;
+        deps.add(target);
+        return { path: target, contents: readFileSync(target, 'utf8') };
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@scenoco-three/compiler",
+  "version": "0.1.0",
+  "description": "SceNoCo build-time compiler, CLI and watcher",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "scenoco": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": ["three", "threejs", "scene", "components", "ecs", "xml", "dsl", "compiler", "gamedev"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "npm --prefix ../core run build && tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@scenoco-three/core": "^0.1.0",
+    "chokidar": "^4.0.3",
+    "esbuild": "^0.25.12",
+    "saxes": "^6.0.0"
+  }
+}