pixifact 0.1.3 → 0.1.4

package/dist/compiler/compileScenes.js

@@ -1,8 +1,10 @@
 import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { builtinSceneAssetIds, builtinSceneNameFromAssetId, isBuiltinSceneAssetId, } from './builtinScenes.js';
 import { defaultSceneSourceRoots, generatedSceneModuleImport, generatedSceneModulePath, isIgnoredSceneSourceDirectory, normalizeSceneAssetId, pairedSceneScriptPath, resolveSceneReference, sceneClassAlias, sceneLocalName, toPosixPath, } from './sceneAssetPair.js';
-import { extractSceneScriptInterface } from './scriptInterfaceExtractor.js';
+import { builtinSceneScriptPath, readBuiltinSceneScriptSources, readBuiltinSceneSource, } from '../compiler-node/builtinSceneAssets.js';
+import { extractSceneScriptInterfaces } from './scriptInterfaceExtractor.js';
 import { findMissingScenePartReferences } from './scenePartValidation.js';
 import { parseSceneTemplate } from './templateParser.js';
 import { compileSceneTemplateToTs } from './typescriptCompiler.js';
@@ -21,24 +23,48 @@ export async function compileScenes(options) {
         ? options.projectRoot
         : fileURLToPath(options.projectRoot);
     const generatedDir = path.resolve(projectRoot, options.generatedDir ?? '.pixifact/generated');
-    const scenePaths = await collectSceneAssetIds(projectRoot, options.sourceRoots);
+    const projectScenePaths = await collectSceneAssetIds(projectRoot, options.sourceRoots);
+    const sceneRecords = [
+        ...projectScenePaths.map((scenePath) => ({ scenePath, kind: 'project' })),
+        ...builtinSceneAssetIds().map((scenePath) => ({ scenePath, kind: 'builtin' })),
+    ];
+    const builtinScriptSources = await readBuiltinSceneScriptSources();
     await mkdir(generatedDir, { recursive: true });
+    const sceneSources = new Map();
     const templates = new Map();
-    for (const scenePath of scenePaths) {
-        const source = await readFile(path.resolve(projectRoot, scenePath), 'utf8');
+    for (const record of sceneRecords) {
+        const { scenePath } = record;
+        const source = record.kind === 'builtin'
+            ? await readBuiltinSceneSource(scenePath)
+            : await readFile(path.resolve(projectRoot, scenePath), 'utf8');
+        sceneSources.set(scenePath, source);
         try {
             const template = parseSceneTemplate(source);
             assertSceneLocalName(scenePath, template);
-            const descriptor = await readPairedSceneScript(projectRoot, scenePath, template);
-            template.interface = descriptor.interface;
             templates.set(scenePath, normalizeSceneReferences(scenePath, template));
         }
         catch (error) {
             throw new CompileSceneError(error instanceof Error ? error.message : String(error), scenePath, source);
         }
     }
-    const registryImports = [];
-    for (const scenePath of scenePaths) {
+    const sceneScriptDescriptors = await readSceneScriptDescriptors(projectRoot, projectScenePaths, builtinScriptSources, sceneSources);
+    for (const record of sceneRecords) {
+        const { scenePath } = record;
+        const template = templates.get(scenePath);
+        if (!template) {
+            throw new Error(`Missing parsed template for ${scenePath}.`);
+        }
+        try {
+            template.interface = bindSceneScriptInterface(scenePath, template, sceneScriptDescriptors[scenePath]).interface;
+        }
+        catch (error) {
+            throw new CompileSceneError(error instanceof Error ? error.message : String(error), scenePath, sceneSources.get(scenePath));
+        }
+    }
+    const projectRegistryImports = [];
+    const builtinRegistryImports = [];
+    for (const record of sceneRecords) {
+        const { scenePath } = record;
         const template = templates.get(scenePath);
         if (!template) {
             throw new Error(`Missing parsed template for ${scenePath}.`);
@@ -51,7 +77,7 @@ export async function compileScenes(options) {
             scriptImport: {
                 exportName: template.name,
                 localName: sceneClassAlias(scenePath),
-                source: importSourceFor(path.resolve(projectRoot, pairedSceneScriptPath(scenePath)), generatedFileDir),
+                source: importSourceFor(sceneScriptAbsolutePath(projectRoot, scenePath), generatedFileDir),
             },
             sceneImports: sceneImportsFor(template, templates, projectRoot, generatedFileDir),
             sceneClassAliases: sceneClassAliasesFor(template),
@@ -60,9 +86,43 @@ export async function compileScenes(options) {
         });
         await mkdir(path.dirname(generatedFile), { recursive: true });
         await writeFile(generatedFile, code);
-        registryImports.push(`import ${JSON.stringify(generatedSceneModuleImport(scenePath))};`);
+        if (record.kind === 'project') {
+            projectRegistryImports.push(`import ${JSON.stringify(generatedSceneModuleImport(scenePath))};`);
+        }
+        else if (sceneIsReferencedByProjectScenes(scenePath, projectScenePaths, templates)) {
+            builtinRegistryImports.push(`import ${JSON.stringify(generatedSceneModuleImport(scenePath))};`);
+        }
     }
-    await writeFile(path.join(generatedDir, 'scenes.generated.ts'), `${registryImports.join('\n')}\n`);
+    await writeFile(path.join(generatedDir, 'scenes.generated.ts'), `${[
+        ...builtinRegistryImports,
+        ...projectRegistryImports,
+    ].join('\n')}\n`);
+}
+function sceneIsReferencedByProjectScenes(scenePath, projectScenePaths, templates) {
+    if (!isBuiltinSceneAssetId(scenePath)) {
+        return false;
+    }
+    const visited = new Set();
+    const stack = [...projectScenePaths];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (visited.has(current)) {
+            continue;
+        }
+        visited.add(current);
+        for (const referencedScenePath of collectSceneInstancePaths(templates.get(current)?.children ?? [])) {
+            if (referencedScenePath === scenePath) {
+                return true;
+            }
+            stack.push(referencedScenePath);
+        }
+    }
+    return false;
+}
+function sceneScriptAbsolutePath(projectRoot, scenePath) {
+    return isBuiltinSceneAssetId(scenePath)
+        ? builtinSceneScriptPath(scenePath)
+        : path.resolve(projectRoot, pairedSceneScriptPath(scenePath));
 }
 async function collectSceneAssetIds(projectRoot, sourceRoots = defaultSceneSourceRoots) {
     const scenes = [];
@@ -97,19 +157,39 @@ async function exists(filePath) {
         return false;
     }
 }
+async function readSceneScriptDescriptors(projectRoot, projectScenePaths, builtinScriptSources, sceneSources) {
+    const sources = builtinSceneAssetIds().map((scene) => {
+        const name = builtinSceneNameFromAssetId(scene);
+        return {
+            scene,
+            fileName: builtinSceneScriptPath(scene),
+            source: builtinScriptSources[name],
+        };
+    });
+    for (const scenePath of projectScenePaths) {
+        const scriptPath = pairedSceneScriptPath(scenePath);
+        const absoluteScriptPath = path.resolve(projectRoot, scriptPath);
+        if (!await exists(absoluteScriptPath)) {
+            throw new CompileSceneError(`Scene "${scenePath}" requires paired script "${scriptPath}".`, scenePath, sceneSources.get(scenePath));
+        }
+        sources.push({
+            scene: scenePath,
+            fileName: absoluteScriptPath,
+            source: await readFile(absoluteScriptPath, 'utf8'),
+        });
+    }
+    return extractSceneScriptInterfaces(sources);
+}
 function assertSceneLocalName(scenePath, template) {
     const expected = sceneLocalName(scenePath);
     if (template.name !== expected) {
         throw new Error(`Scene "${scenePath}" name "${template.name}" must match file basename "${expected}".`);
     }
 }
-async function readPairedSceneScript(projectRoot, scenePath, template) {
-    const scriptPath = pairedSceneScriptPath(scenePath);
-    const absoluteScriptPath = path.resolve(projectRoot, scriptPath);
-    if (!await exists(absoluteScriptPath)) {
-        throw new Error(`Scene "${scenePath}" requires paired script "${scriptPath}".`);
+function bindSceneScriptInterface(scenePath, template, descriptor) {
+    if (!descriptor) {
+        throw new Error(`Scene "${scenePath}" requires a @scene script class.`);
     }
-    const descriptor = extractSceneScriptInterface(await readFile(absoluteScriptPath, 'utf8'), absoluteScriptPath, { scene: scenePath });
     if (descriptor.className !== template.name) {
         throw new Error(`Scene "${scenePath}" name "${template.name}" must match @scene class "${descriptor.className}".`);
     }
@@ -141,7 +221,7 @@ function normalizeSceneReferences(scenePath, template) {
     return next;
 }
 function sceneImportsFor(template, templates, projectRoot, generatedFileDir) {
-    return [...collectSceneInstancePaths(template.children)]
+    return [...collectSceneImportPaths(template, templates)]
         .sort()
         .map((scenePath) => {
         const sceneTemplate = templates.get(scenePath);
@@ -149,12 +229,39 @@ function sceneImportsFor(template, templates, projectRoot, generatedFileDir) {
             throw new Error(`Scene "${template.name}" references unknown Scene "${scenePath}".`);
         }
         return {
+            scene: scenePath,
             exportName: sceneTemplate.name,
             localName: sceneClassAlias(scenePath),
-            source: importSourceFor(path.resolve(projectRoot, pairedSceneScriptPath(scenePath)), generatedFileDir),
+            source: importSourceFor(sceneScriptAbsolutePath(projectRoot, scenePath), generatedFileDir),
         };
     });
 }
+function collectSceneImportPaths(template, templates) {
+    const scenePaths = collectSceneInstancePaths(template.children);
+    collectSceneStructSourcePaths(template.children, templates, scenePaths);
+    return scenePaths;
+}
+function collectSceneStructSourcePaths(nodes, templates, scenePaths) {
+    for (const node of nodes) {
+        if (node.kind === 'slotOutlet') {
+            continue;
+        }
+        if (node.kind === 'pixi') {
+            collectSceneStructSourcePaths(node.children, templates, scenePaths);
+            continue;
+        }
+        const sceneInterface = templates.get(node.scene)?.interface;
+        for (const [key, value] of Object.entries(node.props)) {
+            const contract = value && typeof value === 'object' ? sceneInterface?.props[key] : undefined;
+            if (contract?.type === 'struct' && contract.sourceScene) {
+                scenePaths.add(contract.sourceScene);
+            }
+        }
+        for (const children of Object.values(node.slots)) {
+            collectSceneStructSourcePaths(children, templates, scenePaths);
+        }
+    }
+}
 function sceneClassAliasesFor(template) {
     return Object.fromEntries([...collectSceneInstancePaths(template.children)].map((scenePath) => [scenePath, sceneClassAlias(scenePath)]));
 }

package/dist/compiler/decorators.js

@@ -5,6 +5,9 @@ export function scene() {
         const SceneClass = class extends constructor {
             constructor(...args) {
                 super(...args);
+                if (new.target !== SceneClass) {
+                    return;
+                }
                 const result = mountSceneClass(this, SceneClass);
                 const metadata = sceneMetadata(constructor);
                 for (const [property, id] of metadata.parts) {

package/dist/compiler/index.d.ts

@@ -1,4 +1,5 @@
 export * from './commands/index.js';
+export * from './builtinScenes.js';
 export * from './decorators.js';
 export * from './eventRuntime.js';
 export * from './pixiNodeSchema.js';

package/dist/compiler/index.js

@@ -1,4 +1,5 @@
 export * from './commands/index.js';
+export * from './builtinScenes.js';
 export * from './decorators.js';
 export * from './eventRuntime.js';
 export * from './pixiNodeSchema.js';

package/dist/compiler/sceneAssetPair.js

@@ -1,3 +1,4 @@
+import { builtinSceneAssetId, builtinSceneNameFromAssetId, isBuiltinSceneAssetId } from './builtinScenes.js';
 export const defaultSceneSourceRoots = ['src'];
 export const ignoredSceneSourceDirectories = new Set([
     'node_modules',
@@ -45,6 +46,9 @@ function posixJoin(...parts) {
     return normalizePosixPath(parts.filter(Boolean).join('/'));
 }
 export function normalizeSceneAssetId(value) {
+    if (isBuiltinSceneAssetId(value)) {
+        return builtinSceneAssetId(builtinSceneNameFromAssetId(value));
+    }
     const normalized = toPosixPath(value).replace(/^\.\/+/, '').replace(/^\/+/, '');
     const parts = normalized.split('/').filter(Boolean);
     if (parts.includes('..')) {
@@ -59,19 +63,31 @@ export function isIgnoredSceneSourceDirectory(name) {
     return ignoredSceneSourceDirectories.has(name);
 }
 export function sceneLocalName(scenePath) {
+    if (isBuiltinSceneAssetId(scenePath)) {
+        return builtinSceneNameFromAssetId(scenePath);
+    }
     return posixBasename(normalizeSceneAssetId(scenePath), '.scene');
 }
 export function pairedSceneScriptPath(scenePath) {
+    if (isBuiltinSceneAssetId(scenePath)) {
+        return `${builtinSceneNameFromAssetId(scenePath)}.ts`;
+    }
     const assetId = normalizeSceneAssetId(scenePath);
     return `${assetId.slice(0, -'.scene'.length)}.ts`;
 }
 export function generatedSceneModulePath(scenePath) {
+    if (isBuiltinSceneAssetId(scenePath)) {
+        return `pixifact-builtin/${builtinSceneNameFromAssetId(scenePath)}.scene.generated.ts`;
+    }
     return `${normalizeSceneAssetId(scenePath).slice(0, -'.scene'.length)}.scene.generated.ts`;
 }
 export function generatedSceneModuleImport(scenePath) {
     return `./${generatedSceneModulePath(scenePath).replace(/\.ts$/, '')}`;
 }
 export function sceneClassAlias(scenePath) {
+    if (isBuiltinSceneAssetId(scenePath)) {
+        return `BuiltinSceneClass_${builtinSceneNameFromAssetId(scenePath)}`;
+    }
     const base = normalizeSceneAssetId(scenePath)
         .slice(0, -'.scene'.length)
         .split('/')
@@ -81,6 +97,9 @@ export function sceneClassAlias(scenePath) {
 }
 export function resolveSceneReference(fromScenePath, reference) {
     const value = toPosixPath(reference.trim());
+    if (isBuiltinSceneAssetId(value)) {
+        return normalizeSceneAssetId(value);
+    }
     if (!value.endsWith('.scene')) {
         throw new Error('Scene references must use .scene paths.');
     }

package/dist/compiler/sceneRuntime.d.ts

@@ -1,13 +1,14 @@
 import type { Container } from 'pixi.js';
+import type { Group } from '../runtime/index.js';
 export interface SceneMountResult {
-    root: Container;
+    root: Group;
     parts: Record<string, Container>;
     slots: Record<string, Container>;
 }
 export interface SceneDefinition {
-    mount(root: Container): SceneMountResult;
+    mount(root: Group): SceneMountResult;
 }
 export declare function registerScene(path: string, definition: SceneDefinition): void;
 export declare function registerSceneClass(constructor: object, path: string): void;
-export declare function mountScene(root: Container, path: string): SceneMountResult;
-export declare function mountSceneClass(root: Container, constructor: object): SceneMountResult;
+export declare function mountScene(root: Group, path: string): SceneMountResult;
+export declare function mountSceneClass(root: Group, constructor: object): SceneMountResult;

package/dist/compiler/scriptInterfaceExtractor.d.ts

@@ -2,5 +2,10 @@ import type { SceneScriptInterface } from './spec.js';
 export interface ExtractSceneScriptInterfaceOptions {
     scene: string;
 }
+export interface ExtractSceneScriptInterfaceSource extends ExtractSceneScriptInterfaceOptions {
+    source: string;
+    fileName?: string;
+}
 export declare function extractSceneScriptInterface(source: string, fileName: string | undefined, options: ExtractSceneScriptInterfaceOptions): SceneScriptInterface;
+export declare function extractSceneScriptInterfaces(sources: readonly ExtractSceneScriptInterfaceSource[]): Record<string, SceneScriptInterface>;
 export declare function emitSceneScriptInterfaceDescriptor(source: string, fileName: string | undefined, options: ExtractSceneScriptInterfaceOptions): string;

package/dist/compiler/scriptInterfaceExtractor.js

@@ -1,17 +1,32 @@
 import ts from 'typescript';
 export function extractSceneScriptInterface(source, fileName = 'scene-script.ts', options) {
+    const descriptors = composeSceneScriptClasses(extractSceneScriptClasses(source, fileName, options));
+    const descriptor = descriptors[options.scene];
+    if (!descriptor) {
+        throw new Error('No @scene decorator found.');
+    }
+    return descriptor;
+}
+export function extractSceneScriptInterfaces(sources) {
+    return composeSceneScriptClasses(sources.flatMap((source) => extractSceneScriptClasses(source.source, source.fileName ?? 'scene-script.ts', { scene: source.scene })));
+}
+function extractSceneScriptClasses(source, fileName, options) {
     const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const sourceId = normalizeScriptSourceId(fileName);
+    const imports = collectNamedImports(sourceFile, sourceId);
     const structClasses = collectStructClasses(sourceFile);
+    const classes = [];
     for (const statement of sourceFile.statements) {
         if (!ts.isClassDeclaration(statement)) {
             continue;
         }
-        if (!hasSceneDecorator(statement)) {
-            continue;
-        }
+        const isSceneClass = hasSceneDecorator(statement);
         const className = statement.name?.text;
         if (!className) {
-            throw new Error('Scene script class is missing a name.');
+            if (isSceneClass) {
+                throw new Error('Scene script class is missing a name.');
+            }
+            continue;
         }
         const props = {};
         const events = {};
@@ -39,22 +54,199 @@ export function extractSceneScriptInterface(source, fileName = 'scene-script.ts'
                 parts[name] = typeof part.id === 'string' ? part.id : name;
             }
         }
-        return {
-            scene: options.scene,
+        const parentClassName = parentClassNameOf(statement);
+        if (!isSceneClass && !parentClassName && !hasPublicContract(props, events, slots, parts)) {
+            continue;
+        }
+        classes.push({
+            sourceId,
+            scriptScene: options.scene,
+            ...(isSceneClass ? { scene: options.scene } : {}),
             className,
+            ...(parentClassName ? { parentClassName } : {}),
+            imports,
             interface: {
                 props,
                 events,
                 slots,
             },
             parts,
-        };
+        });
     }
-    throw new Error('No @scene decorator found.');
+    return classes;
 }
 export function emitSceneScriptInterfaceDescriptor(source, fileName = 'scene-script.ts', options) {
     return `${JSON.stringify(extractSceneScriptInterface(source, fileName, options), null, 2)}\n`;
 }
+function composeSceneScriptClasses(classes) {
+    const classesByName = new Map();
+    const classesBySourceAndName = new Map();
+    for (const item of classes) {
+        const bucket = classesByName.get(item.className) ?? [];
+        bucket.push(item);
+        classesByName.set(item.className, bucket);
+        classesBySourceAndName.set(sourceClassKey(item.sourceId, item.className), item);
+    }
+    const composed = new Map();
+    const visiting = new Set();
+    function compose(item) {
+        const cached = composed.get(item);
+        if (cached) {
+            return cached;
+        }
+        if (visiting.has(item)) {
+            throw new Error(`Scene script class "${item.className}" has a circular inheritance chain.`);
+        }
+        visiting.add(item);
+        const parent = item.parentClassName ? resolveParentClass(item, classesByName, classesBySourceAndName) : undefined;
+        const parentInterface = parent ? inheritedSceneInterface(compose(parent), parent.scriptScene, item.scriptScene) : emptySceneInterface();
+        const sceneInterface = mergeSceneInterfaces(parentInterface, item.interface);
+        visiting.delete(item);
+        composed.set(item, sceneInterface);
+        return sceneInterface;
+    }
+    const result = {};
+    for (const item of classes) {
+        if (!item.scene) {
+            continue;
+        }
+        if (result[item.scene]) {
+            throw new Error(`Scene script "${item.scene}" has multiple @scene classes.`);
+        }
+        result[item.scene] = {
+            scene: item.scene,
+            className: item.className,
+            interface: compose(item),
+            parts: item.parts,
+        };
+    }
+    return result;
+}
+function resolveParentClass(item, classesByName, classesBySourceAndName) {
+    const parentClassName = item.parentClassName ?? '';
+    const sameSourceParent = classesBySourceAndName.get(sourceClassKey(item.sourceId, parentClassName));
+    if (sameSourceParent) {
+        return sameSourceParent;
+    }
+    const importedSource = item.imports.get(parentClassName);
+    if (importedSource) {
+        return classesBySourceAndName.get(sourceClassKey(importedSource, parentClassName));
+    }
+    const candidates = classesByName.get(parentClassName) ?? [];
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    if (candidates.length > 1) {
+        throw new Error(`Scene script parent class "${item.parentClassName}" is ambiguous for "${item.className}".`);
+    }
+    return candidates[0];
+}
+function sourceClassKey(sourceId, className) {
+    return `${sourceId}:${className}`;
+}
+function emptySceneInterface() {
+    return {
+        props: {},
+        events: {},
+        slots: {},
+    };
+}
+function mergeSceneInterfaces(parent, own) {
+    return {
+        props: {
+            ...parent.props,
+            ...own.props,
+        },
+        events: {
+            ...parent.events,
+            ...own.events,
+        },
+        slots: {
+            ...parent.slots,
+            ...own.slots,
+        },
+    };
+}
+function inheritedSceneInterface(parent, parentSourceScene, childSourceScene) {
+    return {
+        props: Object.fromEntries(Object.entries(parent.props).map(([name, contract]) => {
+            if (contract.type !== 'struct') {
+                return [name, contract];
+            }
+            const sourceScene = contract.sourceScene ?? parentSourceScene;
+            return [
+                name,
+                sourceScene === childSourceScene
+                    ? contract
+                    : { ...contract, sourceScene },
+            ];
+        })),
+        events: parent.events,
+        slots: parent.slots,
+    };
+}
+function hasPublicContract(props, events, slots, parts) {
+    return Object.keys(props).length > 0
+        || Object.keys(events).length > 0
+        || Object.keys(slots).length > 0
+        || Object.keys(parts).length > 0;
+}
+function collectNamedImports(sourceFile, sourceId) {
+    const imports = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+            continue;
+        }
+        const moduleSpecifier = statement.moduleSpecifier.text;
+        if (!moduleSpecifier.startsWith('.')) {
+            continue;
+        }
+        const namedBindings = statement.importClause?.namedBindings;
+        if (!namedBindings || !ts.isNamedImports(namedBindings)) {
+            continue;
+        }
+        const targetSource = resolveScriptSourceId(sourceId, moduleSpecifier);
+        for (const element of namedBindings.elements) {
+            imports.set(element.name.text, targetSource);
+        }
+    }
+    return imports;
+}
+function normalizeScriptSourceId(value) {
+    const normalized = normalizePosixPath(value);
+    return hasScriptExtension(normalized) ? normalized : `${normalized}.ts`;
+}
+function resolveScriptSourceId(fromSourceId, moduleSpecifier) {
+    const dirname = posixDirname(fromSourceId);
+    return normalizeScriptSourceId(normalizePosixPath(`${dirname}/${moduleSpecifier}`));
+}
+function hasScriptExtension(value) {
+    return /\.[cm]?[tj]sx?$/.test(value);
+}
+function posixDirname(value) {
+    const normalized = normalizePosixPath(value);
+    const index = normalized.lastIndexOf('/');
+    return index >= 0 ? normalized.slice(0, index) : '';
+}
+function normalizePosixPath(value) {
+    const segments = [];
+    for (const segment of value.replaceAll('\\', '/').split('/')) {
+        if (!segment || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            if (segments.length && segments[segments.length - 1] !== '..') {
+                segments.pop();
+            }
+            else {
+                segments.push(segment);
+            }
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.join('/');
+}
 function hasSceneDecorator(node) {
     const decorator = decorators(node).find((item) => decoratorName(item) === 'scene');
     if (!decorator) {
@@ -66,6 +258,20 @@ function hasSceneDecorator(node) {
     }
     return true;
 }
+function parentClassNameOf(node) {
+    const heritage = node.heritageClauses?.find((item) => item.token === ts.SyntaxKind.ExtendsKeyword);
+    const parent = heritage?.types[0]?.expression;
+    if (!parent) {
+        return undefined;
+    }
+    if (ts.isIdentifier(parent)) {
+        return parent.text;
+    }
+    if (ts.isPropertyAccessExpression(parent)) {
+        return parent.name.text;
+    }
+    return undefined;
+}
 function memberDecoratorOptions(member, name) {
     const decorator = decorators(member).find((item) => decoratorName(item) === name);
     if (!decorator) {

package/dist/compiler/spec.d.ts

@@ -14,6 +14,7 @@ export interface SceneTemplateStructFieldContract {
 export interface SceneTemplateStructPropContract {
     type: 'struct';
     struct: string;
+    sourceScene?: string;
     fields: Record<string, SceneTemplateStructFieldContract>;
 }
 export type SceneTemplatePropContract = SceneTemplatePrimitivePropContract | SceneTemplateStructPropContract;
@@ -56,6 +57,7 @@ export interface SlotOutletTemplateNode {
     name: string;
 }
 export interface SceneTemplateScriptImport {
+    scene?: string;
     exportName: string;
     localName: string;
     source: string;

package/dist/compiler/templateParser.js

@@ -1,4 +1,5 @@
 import { pixiSceneFieldSchema } from './pixiNodeSchema.js';
+import { builtinSceneAssetId, isBuiltinSceneName } from './builtinScenes.js';
 const pixiTypes = new Set([
     'Container',
     'Sprite',
@@ -61,7 +62,7 @@ function parseTemplateNode(element) {
         };
         return node;
     }
-    if (element.attributes.scene) {
+    if (element.attributes.scene !== undefined || isBuiltinSceneName(element.name)) {
         const slots = {};
         for (const child of element.children) {
             const slot = child.attributes.slot || 'default';
@@ -71,7 +72,7 @@ function parseTemplateNode(element) {
         const node = {
             kind: 'sceneInstance',
             type: element.name,
-            scene: element.attributes.scene,
+            scene: element.attributes.scene !== undefined ? element.attributes.scene : builtinSceneAssetId(element.name),
             props: parseProps(element, ['id', 'scene', 'slot'], isEventAttribute),
             events: parseEvents(element),
             slots,
@@ -79,7 +80,7 @@ function parseTemplateNode(element) {
         };
         return node;
     }
-    throw new Error(`Unsupported template tag <${element.name}>.`);
+    throw new Error(`Unsupported template tag <${element.name}>. Add scene="..." or use a built-in Scene name.`);
 }
 function parseProps(element, omitted, shouldOmit = () => false) {
     const props = {};

package/dist/compiler/templateSerializer.js

@@ -1,3 +1,4 @@
+import { isBuiltinSceneAssetId } from './builtinScenes.js';
 const colorPropNames = new Set([
     'backgroundColor',
     'borderColor',
@@ -40,7 +41,7 @@ function serializeTemplateNode(node, depth, extraAttributes = []) {
     }
     const attributes = [
         ...(node.id ? [['id', node.id]] : []),
-        ['scene', node.scene],
+        ...(isBuiltinSceneAssetId(node.scene) ? [] : [['scene', node.scene]]),
         ...extraAttributes,
         ...Object.entries(node.props),
         ...Object.entries(node.events).map(([name, value]) => [`@${name}`, value]),