pixifact 0.4.0 → 0.6.0

package/dist/compiler/builtinScenes.d.ts

@@ -1,4 +1,3 @@
-import type { SceneTemplateInterface } from './spec.js';
 export declare const builtinScenePrefix = "pixifact:";
 export declare const builtinSceneNames: readonly [];
 export type BuiltinSceneName = typeof builtinSceneNames[number];
@@ -8,7 +7,3 @@ export declare function builtinSceneAssetId(name: string): string;
 export declare function isBuiltinSceneAssetId(value: string): boolean;
 export declare function builtinSceneNameFromAssetId(assetId: string): never;
 export declare function builtinSceneAssetIds(): string[];
-export declare function builtinSceneInterface(assetId: string, scriptSources: BuiltinSceneScriptSources): SceneTemplateInterface;
-export declare function builtinSceneInterfaces(scriptSources: BuiltinSceneScriptSources): {
-    [k: string]: SceneTemplateInterface;
-};

package/dist/compiler/builtinScenes.js

@@ -1,4 +1,3 @@
-import { extractSceneScriptInterfaces } from './scriptInterfaceExtractor.js';
 export const builtinScenePrefix = 'pixifact:';
 export const builtinSceneNames = [];
 const builtinSceneNameSet = new Set(builtinSceneNames);
@@ -27,28 +26,3 @@ export function builtinSceneNameFromAssetId(assetId) {
 export function builtinSceneAssetIds() {
     return builtinSceneNames.map(builtinSceneAssetId);
 }
-export function builtinSceneInterface(assetId, scriptSources) {
-    return builtinSceneInterfaceDescriptors(scriptSources)[assetId].interface;
-}
-export function builtinSceneInterfaces(scriptSources) {
-    const descriptors = builtinSceneInterfaceDescriptors(scriptSources);
-    return Object.fromEntries(builtinSceneAssetIds().map((assetId) => [assetId, descriptors[assetId].interface]));
-}
-function builtinSceneInterfaceDescriptors(scriptSources) {
-    const descriptors = extractSceneScriptInterfaces(builtinSceneNames.map((name) => ({
-        scene: builtinSceneAssetId(name),
-        fileName: `${name}.ts`,
-        source: scriptSources[name],
-    })));
-    for (const assetId of builtinSceneAssetIds()) {
-        const name = builtinSceneNameFromAssetId(assetId);
-        const descriptor = descriptors[assetId];
-        if (!descriptor) {
-            throw new Error(`Built-in Scene "${assetId}" is missing a @scene script.`);
-        }
-        if (descriptor.className !== name) {
-            throw new Error(`Built-in Scene "${assetId}" name must match @scene class "${descriptor.className}".`);
-        }
-    }
-    return descriptors;
-}

package/dist/compiler/commands/index.js

@@ -1,4 +1,5 @@
 import { pixiSceneNodeAcceptsChildren } from '../pixiNodeSchema.js';
+import { isSceneTemplateBindingValue } from '../spec.js';
 function cloneNode(node) {
     return structuredClone(node);
 }
@@ -217,7 +218,7 @@ function getPropPathValue(props, prop) {
         return props[prop];
     }
     const value = props[root];
-    return value && typeof value === 'object' ? value[field] : undefined;
+    return value && typeof value === 'object' && !isSceneTemplateBindingValue(value) ? value[field] : undefined;
 }
 function setPropPathValue(props, prop, value) {
     const [root, field, ...rest] = prop.split('.');
@@ -231,7 +232,7 @@ function setPropPathValue(props, prop, value) {
         return;
     }
     const current = props[root];
-    const objectValue = current && typeof current === 'object'
+    const objectValue = current && typeof current === 'object' && !isSceneTemplateBindingValue(current)
         ? { ...current }
         : {};
     if (value === undefined) {
@@ -338,11 +339,13 @@ function moveNode(template, command, context) {
     if (!source || !target || !canInsertNodeIntoParent(command.parent, source.node, target.acceptsSlotOutlet)) {
         return { ok: false, command, error: 'Target cannot contain this node.' };
     }
+    const sameChildList = source.nodes === target.nodes;
     const [node] = source.nodes.splice(source.index, 1);
-    let index = Math.max(0, Math.min(command.index, target.nodes.length));
-    if (source.nodes === target.nodes && source.index < index) {
+    let index = command.index;
+    if (sameChildList && source.index < index) {
         index -= 1;
     }
+    index = Math.max(0, Math.min(index, target.nodes.length));
     target.nodes.splice(index, 0, node);
     const locator = findCompilerSceneNodeLocator(template.children, node);
     if (!locator) {
@@ -355,7 +358,7 @@ function moveNode(template, command, context) {
             op: 'moveNode',
             node: locator,
             parent: source.parentLocator,
-            index: source.index,
+            index: sameChildList && index < source.index ? source.index + 1 : source.index,
         },
         selection: { type: 'node', node: locator },
     };

package/dist/compiler/compileScenes.d.ts

@@ -1,3 +1,4 @@
+import { type SceneValidationDiagnostic } from './sceneValidation.js';
 export interface CompileScenesOptions {
     projectRoot: string | URL;
     sourceRoots?: string[];
@@ -7,6 +8,7 @@ export declare const generatedSceneAssetsFileName = "scene-assets.generated.json
 export declare class CompileSceneError extends Error {
     readonly scene: string;
     readonly source?: string | undefined;
-    constructor(message: string, scene: string, source?: string | undefined);
+    readonly diagnostics?: SceneValidationDiagnostic[] | undefined;
+    constructor(message: string, scene: string, source?: string | undefined, diagnostics?: SceneValidationDiagnostic[] | undefined);
 }
 export declare function compileScenes(options: CompileScenesOptions): Promise<void>;

package/dist/compiler/compileScenes.js

@@ -4,8 +4,9 @@ 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 { builtinSceneScriptPath, readBuiltinSceneScriptSources, readBuiltinSceneSource, } from '../compiler-node/builtinSceneAssets.js';
-import { extractSceneScriptInterfaces } from './scriptInterfaceExtractor.js';
+import { extractSceneScriptInterfaces } from '../compiler-node/scriptInterfaceExtractor.js';
 import { findMissingScenePartReferences } from './scenePartValidation.js';
+import { validateSceneContent } from './sceneValidation.js';
 import { parseSceneTemplate } from './templateParser.js';
 import { compileSceneTemplateToTs } from './typescriptCompiler.js';
 import { parsePixifactProjectConfig, pixifactProjectConfigFileName, } from '../project/index.js';
@@ -13,10 +14,12 @@ export const generatedSceneAssetsFileName = 'scene-assets.generated.json';
 export class CompileSceneError extends Error {
     scene;
     source;
-    constructor(message, scene, source) {
+    diagnostics;
+    constructor(message, scene, source, diagnostics) {
         super(message);
         this.scene = scene;
         this.source = source;
+        this.diagnostics = diagnostics;
         this.name = 'CompileSceneError';
     }
 }
@@ -64,6 +67,33 @@ export async function compileScenes(options) {
             throw new CompileSceneError(error instanceof Error ? error.message : String(error), scenePath, sceneSources.get(scenePath));
         }
     }
+    for (const record of sceneRecords) {
+        const { scenePath } = record;
+        const template = templates.get(scenePath);
+        const source = sceneSources.get(scenePath);
+        if (!template || source === undefined) {
+            throw new Error(`Missing bound template for ${scenePath}.`);
+        }
+        try {
+            const result = validateSceneContent({
+                scene: scenePath,
+                bindingsOnly: true,
+                content: source,
+                sceneInterface: template.interface,
+                sceneInterfaces: sceneInterfacesFor(template, templates),
+                normalizeSceneReference: (scene) => resolveSceneReference(scenePath, scene),
+            });
+            if (!result.ok) {
+                throw new CompileSceneError(result.error, scenePath, source, result.diagnostics);
+            }
+        }
+        catch (error) {
+            if (error instanceof CompileSceneError) {
+                throw error;
+            }
+            throw new CompileSceneError(error instanceof Error ? error.message : String(error), scenePath, source);
+        }
+    }
     const projectRegistryImports = [];
     const builtinRegistryImports = [];
     const projectAssets = new Set();

package/dist/compiler/index.d.ts

@@ -2,7 +2,6 @@ export * from './commands/index.js';
 export * from './builtinScenes.js';
 export * from './pixiNodeSchema.js';
 export * from './spec.js';
-export * from './scriptInterfaceExtractor.js';
 export * from './sceneAssetPair.js';
 export * from './scenePartValidation.js';
 export * from './sceneValidation.js';

package/dist/compiler/index.js

@@ -2,7 +2,6 @@ export * from './commands/index.js';
 export * from './builtinScenes.js';
 export * from './pixiNodeSchema.js';
 export * from './spec.js';
-export * from './scriptInterfaceExtractor.js';
 export * from './sceneAssetPair.js';
 export * from './scenePartValidation.js';
 export * from './sceneValidation.js';

package/dist/compiler/pixiNodeSchema.d.ts

@@ -1,9 +1,10 @@
 import type { SceneTemplatePrimitiveType, SceneTemplateValue } from './spec.js';
-export type PixiSceneNodeType = Extract<SceneTemplatePrimitiveType, 'Group' | 'Container' | 'Sprite' | 'NineSliceSprite' | 'TilingSprite' | 'Text' | 'BitmapText' | 'HTMLText' | 'Graphics' | 'Rect' | 'Image' | 'NineImage' | 'TileImage' | 'GridContainer' | 'HBoxContainer' | 'ScrollContainer' | 'VBoxContainer'>;
+export type PixiSceneNodeType = Extract<SceneTemplatePrimitiveType, 'Group' | 'Container' | 'Sprite' | 'NineSliceSprite' | 'TilingSprite' | 'Text' | 'Label' | 'BitmapLabel' | 'BitmapText' | 'HTMLText' | 'Graphics' | 'Rect' | 'Image' | 'NineImage' | 'TileImage' | 'GridContainer' | 'HBoxContainer' | 'ScrollContainer' | 'VBoxContainer'>;
 export type PixiSceneFieldType = 'string' | 'number' | 'boolean' | 'color' | 'enum';
 export type PixiScenePropGroup = 'transform' | 'display' | 'sprite' | 'nineSlice' | 'tiling' | 'text' | 'graphics' | 'stack' | 'props';
 export interface PixiSceneFieldSchema {
     key: string;
+    resource?: 'image';
     type: PixiSceneFieldType;
     options?: readonly (string | number)[];
 }
@@ -23,6 +24,7 @@ export declare const pixiSceneTileImageProps: readonly ["texture", "tilePosition
 export declare const pixiSceneNineSliceProps: readonly ["leftWidth", "rightWidth", "topHeight", "bottomHeight"];
 export declare const pixiSceneTilingProps: readonly ["tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation"];
 export declare const pixiSceneTextProps: readonly ["text", "fontSize", "fontFamily", "fontWeight", "fill"];
+export declare const pixiSceneLabelProps: readonly ["text", "fontSize", "fontFamily", "fontWeight", "fill", "lineHeight", "letterSpacing", "wordWrap", "alignX", "alignY", "overflow"];
 export declare const pixiSceneGraphicsProps: readonly ["shape", "radius", "fill", "fillAlpha", "strokeColor", "strokeWidth", "strokeAlpha"];
 export declare const pixiSceneRectProps: readonly ["fillColor", "fillAlpha", "strokeColor", "strokeAlpha", "strokeWidth", "radius"];
 export declare const pixiSceneStackHBoxProps: readonly ["gap", "alignY", "justify"];
@@ -32,8 +34,8 @@ export declare const pixiSceneStackProps: readonly ["columns", "gap", "gapX", "g
 export declare const pixiSceneScrollProps: readonly ["direction", "scrollX", "scrollY"];
 export declare const pixiSceneTextStyleProps: readonly ["fontSize", "fontFamily", "fontWeight", "fill"];
 export declare const pixiSceneSpriteLikeProps: readonly ["texture", "anchorX", "anchorY", "tint", "texture", "fit", "anchorX", "anchorY", "tint", "texture", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "anchorX", "anchorY", "tint", "texture", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation", "anchorX", "anchorY", "tint", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation"];
-export declare const pixiSceneKnownProps: readonly ["x", "y", "width", "height", "scaleX", "scaleY", "rotation", "pivotX", "pivotY", "skewX", "skewY", "left", "right", "top", "bottom", "horizontal", "vertical", "alpha", "visible", "zIndex", "eventMode", "cursor", "label", "texture", "anchorX", "anchorY", "tint", "texture", "fit", "anchorX", "anchorY", "tint", "texture", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "anchorX", "anchorY", "tint", "texture", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation", "anchorX", "anchorY", "tint", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation", "text", "fontSize", "fontFamily", "fontWeight", "fill", "shape", "radius", "fill", "fillAlpha", "strokeColor", "strokeWidth", "strokeAlpha", "fillColor", "fillAlpha", "strokeColor", "strokeAlpha", "strokeWidth", "radius", "columns", "gap", "gapX", "gapY", "alignX", "alignY", "justify", "direction", "scrollX", "scrollY"];
-export declare const pixiSceneAddableNodeTypes: readonly ["Group", "GridContainer", "HBoxContainer", "ScrollContainer", "VBoxContainer", "Container", "Sprite", "NineSliceSprite", "TilingSprite", "Text", "BitmapText", "HTMLText", "Graphics", "Rect", "Image", "NineImage", "TileImage"];
+export declare const pixiSceneKnownProps: readonly ["x", "y", "width", "height", "scaleX", "scaleY", "rotation", "pivotX", "pivotY", "skewX", "skewY", "left", "right", "top", "bottom", "horizontal", "vertical", "alpha", "visible", "zIndex", "eventMode", "cursor", "label", "texture", "anchorX", "anchorY", "tint", "texture", "fit", "anchorX", "anchorY", "tint", "texture", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "anchorX", "anchorY", "tint", "texture", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation", "anchorX", "anchorY", "tint", "leftWidth", "rightWidth", "topHeight", "bottomHeight", "tilePositionX", "tilePositionY", "tileScaleX", "tileScaleY", "tileRotation", "text", "fontSize", "fontFamily", "fontWeight", "fill", "text", "fontSize", "fontFamily", "fontWeight", "fill", "lineHeight", "letterSpacing", "wordWrap", "alignX", "alignY", "overflow", "shape", "radius", "fill", "fillAlpha", "strokeColor", "strokeWidth", "strokeAlpha", "fillColor", "fillAlpha", "strokeColor", "strokeAlpha", "strokeWidth", "radius", "columns", "gap", "gapX", "gapY", "alignX", "alignY", "justify", "direction", "scrollX", "scrollY"];
+export declare const pixiSceneAddableNodeTypes: readonly ["Group", "GridContainer", "HBoxContainer", "ScrollContainer", "VBoxContainer", "Container", "Sprite", "NineSliceSprite", "TilingSprite", "Label", "BitmapLabel", "Text", "BitmapText", "HTMLText", "Graphics", "Rect", "Image", "NineImage", "TileImage"];
 export declare const pixiSceneNodePropGroupOrder: readonly ["stack", "sprite", "nineSlice", "tiling", "text", "graphics", "props"];
 export declare function pixiSceneNodeSchema(type: PixiSceneNodeType): PixiSceneNodeSchema;
 export declare function isPixiSceneNodeType(type: SceneTemplatePrimitiveType): type is PixiSceneNodeType;

package/dist/compiler/pixiNodeSchema.js

@@ -81,6 +81,15 @@ export const pixiSceneTextProps = [
     'fontWeight',
     'fill',
 ];
+export const pixiSceneLabelProps = [
+    ...pixiSceneTextProps,
+    'lineHeight',
+    'letterSpacing',
+    'wordWrap',
+    'alignX',
+    'alignY',
+    'overflow',
+];
 export const pixiSceneGraphicsProps = [
     'shape',
     'radius',
@@ -149,6 +158,7 @@ export const pixiSceneKnownProps = [
     ...pixiSceneDisplayProps,
     ...pixiSceneSpriteLikeProps,
     ...pixiSceneTextProps,
+    ...pixiSceneLabelProps,
     ...pixiSceneGraphicsProps,
     ...pixiSceneRectProps,
     ...pixiSceneStackProps,
@@ -164,6 +174,8 @@ export const pixiSceneAddableNodeTypes = [
     'Sprite',
     'NineSliceSprite',
     'TilingSprite',
+    'Label',
+    'BitmapLabel',
     'Text',
     'BitmapText',
     'HTMLText',
@@ -206,7 +218,7 @@ const pixiSceneFieldSchemas = {
     eventMode: { key: 'eventMode', type: 'enum', options: ['none', 'passive', 'auto', 'static', 'dynamic'] },
     cursor: { key: 'cursor', type: 'enum', options: ['default', 'pointer', 'text', 'grab', 'grabbing'] },
     label: { key: 'label', type: 'string' },
-    texture: { key: 'texture', type: 'string' },
+    texture: { key: 'texture', type: 'string', resource: 'image' },
     fit: { key: 'fit', type: 'enum', options: ['stretch', 'contain', 'cover', 'none'] },
     anchorX: { key: 'anchorX', type: 'number' },
     anchorY: { key: 'anchorY', type: 'number' },
@@ -223,8 +235,12 @@ const pixiSceneFieldSchemas = {
     text: { key: 'text', type: 'string' },
     fontSize: { key: 'fontSize', type: 'number' },
     fontFamily: { key: 'fontFamily', type: 'string' },
-    fontWeight: { key: 'fontWeight', type: 'enum', options: [400, 500, 600, 700, '400', '500', '600', '700', 'bold'] },
+    fontWeight: { key: 'fontWeight', type: 'enum', options: [400, 500, 600, 700, 'bold'] },
     fill: { key: 'fill', type: 'color' },
+    lineHeight: { key: 'lineHeight', type: 'number' },
+    letterSpacing: { key: 'letterSpacing', type: 'number' },
+    wordWrap: { key: 'wordWrap', type: 'boolean' },
+    overflow: { key: 'overflow', type: 'enum', options: ['visible', 'clip'] },
     fillColor: { key: 'fillColor', type: 'color' },
     shape: { key: 'shape', type: 'enum', options: ['roundRect', 'rect'] },
     radius: { key: 'radius', type: 'number' },
@@ -306,24 +322,64 @@ const pixiSceneNodeSchemas = {
     Text: {
         type: 'Text',
         acceptsChildren: false,
+        defaults: {
+            text: 'Text',
+            fontSize: 16,
+            fill: 0x111827,
+        },
+        groups: {
+            text: pixiSceneTextProps,
+        },
+    },
+    Label: {
+        type: 'Label',
+        acceptsChildren: false,
         defaults: {
             text: 'Text',
             width: 120,
             height: 28,
+            fontFamily: 'Arial',
             fontSize: 16,
+            fontWeight: 400,
             fill: 0x111827,
+            lineHeight: 0,
+            letterSpacing: 0,
+            wordWrap: false,
+            alignX: 'start',
+            alignY: 'start',
+            overflow: 'visible',
         },
         groups: {
-            text: pixiSceneTextProps,
+            text: pixiSceneLabelProps,
         },
     },
-    BitmapText: {
-        type: 'BitmapText',
+    BitmapLabel: {
+        type: 'BitmapLabel',
         acceptsChildren: false,
         defaults: {
             text: 'Text',
             width: 120,
             height: 28,
+            fontFamily: 'Arial',
+            fontSize: 16,
+            fontWeight: 400,
+            fill: 0x111827,
+            lineHeight: 0,
+            letterSpacing: 0,
+            wordWrap: false,
+            alignX: 'start',
+            alignY: 'start',
+            overflow: 'visible',
+        },
+        groups: {
+            text: pixiSceneLabelProps,
+        },
+    },
+    BitmapText: {
+        type: 'BitmapText',
+        acceptsChildren: false,
+        defaults: {
+            text: 'Text',
             fontSize: 16,
             fill: 0x111827,
         },
@@ -336,8 +392,6 @@ const pixiSceneNodeSchemas = {
         acceptsChildren: false,
         defaults: {
             text: 'Text',
-            width: 120,
-            height: 28,
             fontSize: 16,
             fill: 0x111827,
         },

package/dist/compiler/sceneValidation.d.ts

@@ -1,4 +1,4 @@
-import type { SceneTemplate, SceneTemplateInterface, SceneTemplateNode, SceneTemplateValue } from './spec.js';
+import { type SceneTemplate, type SceneTemplateInterface, type SceneTemplateNode, type SceneTemplateValue } from './spec.js';
 export interface SceneTemplateNodeSummary {
     id?: string;
     kind: SceneTemplateNode['kind'];
@@ -29,6 +29,8 @@ export interface ValidateSceneContentOptions {
     content: string;
     existingAssets?: ReadonlySet<string>;
     sceneInterfaces?: Record<string, SceneTemplateInterface>;
+    sceneInterface?: SceneTemplateInterface;
+    bindingsOnly?: boolean;
     normalizeSceneReference?: (scene: string) => string;
 }
 export type SceneContentValidationResult = {

package/dist/compiler/sceneValidation.js

@@ -1,3 +1,4 @@
+import { isSceneTemplateBindingValue, } from './spec.js';
 import { isPixiSceneNodeType, pixiSceneFieldSchema, pixiSceneLayoutProps, pixiSceneNodeAcceptsChildren, pixiSceneNodePropKeys, pixiSceneTransformProps, pixiSceneDisplayProps, } from './pixiNodeSchema.js';
 import { parseSceneTemplate } from './templateParser.js';
 import { serializeSceneTemplate } from './templateSerializer.js';
@@ -57,6 +58,9 @@ export function inspectSceneTemplate(template) {
 export function validateSceneContent(options) {
     try {
         const template = parseSceneTemplate(options.content);
+        if (options.sceneInterface) {
+            template.interface = options.sceneInterface;
+        }
         const diagnostics = validateSceneTemplate(template, options);
         const revision = createSceneRevision(options.content);
         if (diagnostics.length > 0) {
@@ -123,7 +127,7 @@ function validateSceneNode(node, path, context) {
     }
     if (node.kind === 'pixi') {
         return [
-            ...validatePixiNode(node, path, context.existingAssets),
+            ...validatePixiNode(node, path, context),
             ...node.children.flatMap((child, index) => validateSceneNode(child, `${path}/${nodePathSegment(index, child)}`, context)),
         ];
     }
@@ -132,14 +136,14 @@ function validateSceneNode(node, path, context) {
         ...Object.entries(node.slots).flatMap(([slot, children]) => children.flatMap((child, index) => validateSceneNode(child, `${path}/slot:${slot}/${nodePathSegment(index, child)}`, context))),
     ];
 }
-function validatePixiNode(node, path, existingAssets) {
+function validatePixiNode(node, path, context) {
     if (!isPixiSceneNodeType(node.type)) {
         return [{
                 path,
                 prop: 'type',
                 expected: 'supported compiler Pixi node type',
                 actual: node.type,
-                hint: 'Use GridContainer, HBoxContainer, ScrollContainer, VBoxContainer, Container, Sprite, NineSliceSprite, TilingSprite, Text, BitmapText, HTMLText, Graphics, Rect, Image, NineImage, or TileImage.',
+                hint: 'Use GridContainer, HBoxContainer, ScrollContainer, VBoxContainer, Container, Sprite, NineSliceSprite, TilingSprite, Label, BitmapLabel, Text, BitmapText, HTMLText, Graphics, Rect, Image, NineImage, or TileImage.',
             }];
     }
     const diagnostics = [];
@@ -159,6 +163,9 @@ function validatePixiNode(node, path, existingAssets) {
         ...pixiSceneNodePropKeys(node.type),
     ]);
     for (const [prop, value] of Object.entries(node.props)) {
+        if (context.bindingsOnly && !isSceneTemplateBindingValue(value)) {
+            continue;
+        }
         if (!knownProps.has(prop)) {
             diagnostics.push({
                 path,
@@ -170,6 +177,10 @@ function validatePixiNode(node, path, existingAssets) {
             continue;
         }
         const schema = pixiSceneFieldSchema(prop);
+        if (isSceneTemplateBindingValue(value)) {
+            diagnostics.push(...validateSceneBinding(path, prop, value, context.sceneInterface, schema?.type, schema?.options));
+            continue;
+        }
         if (schema && !sceneValueMatchesFieldType(value, schema.type, schema.options)) {
             diagnostics.push({
                 path,
@@ -182,7 +193,7 @@ function validatePixiNode(node, path, existingAssets) {
     }
     const texture = node.props.texture;
     if (typeof texture === 'string') {
-        const assetDiagnostic = validateTextureReference(path, texture, existingAssets);
+        const assetDiagnostic = validateTextureReference(path, texture, context.existingAssets);
         if (assetDiagnostic) {
             diagnostics.push(assetDiagnostic);
         }
@@ -224,6 +235,9 @@ function validateSceneInstanceNode(node, path, context) {
         ...Object.keys(sceneInterface.props),
     ]);
     for (const [prop, value] of Object.entries(node.props)) {
+        if (context.bindingsOnly && !isSceneTemplateBindingValue(value)) {
+            continue;
+        }
         if (!allowedProps.has(prop)) {
             diagnostics.push({
                 path,
@@ -236,11 +250,26 @@ function validateSceneInstanceNode(node, path, context) {
         }
         const schema = pixiSceneFieldSchema(prop);
         const contract = sceneInterface.props[prop];
+        if (isSceneTemplateBindingValue(value)) {
+            const expectedType = contract?.type === 'variant' ? 'string' : contract?.type ?? schema?.type;
+            diagnostics.push(...validateSceneBinding(path, prop, value, context.sceneInterface, expectedType, schema?.options));
+            continue;
+        }
         if (contract?.type === 'struct') {
             diagnostics.push(...validateSceneInstanceStructProp(node, path, prop, value, contract));
             continue;
         }
         const expectedType = contract?.type ?? schema?.type;
+        if (contract?.type === 'variant' && typeof value === 'string' && !contract.variants[value]) {
+            diagnostics.push({
+                path,
+                prop,
+                expected: `one of ${Object.keys(contract.variants).map((name) => JSON.stringify(name)).join(', ')}`,
+                actual: JSON.stringify(value),
+                hint: `Set ${node.type}.${prop} to a declared Variant case.`,
+            });
+            continue;
+        }
         if (expectedType && !sceneValueMatchesContractType(value, expectedType, schema?.options)) {
             diagnostics.push({
                 path,
@@ -251,7 +280,7 @@ function validateSceneInstanceNode(node, path, context) {
             });
         }
     }
-    for (const eventName of Object.keys(node.events)) {
+    for (const eventName of context.bindingsOnly ? [] : Object.keys(node.events)) {
         if (!sceneInterface.events[eventName]) {
             diagnostics.push({
                 path,
@@ -262,7 +291,7 @@ function validateSceneInstanceNode(node, path, context) {
             });
         }
     }
-    for (const slot of Object.keys(node.slots)) {
+    for (const slot of context.bindingsOnly ? [] : Object.keys(node.slots)) {
         if (!sceneInterface.slots[slot]) {
             diagnostics.push({
                 path: `${path}/slot:${slot}`,
@@ -275,6 +304,76 @@ function validateSceneInstanceNode(node, path, context) {
     }
     return diagnostics;
 }
+function validateSceneBinding(path, targetProp, binding, sceneInterface, expectedType, options) {
+    const [prop, field] = binding.path;
+    const contract = sceneInterface?.props[prop];
+    if (!contract) {
+        return [{
+                path,
+                prop: targetProp,
+                expected: `Scene Prop declared by ${sceneInterface ? 'the paired script' : 'the owner Scene'}`,
+                actual: 'unknown binding prop',
+                hint: `Declare @prop "${prop}" in the paired Scene script.`,
+            }];
+    }
+    let sourceType;
+    let sourceValues;
+    if (field) {
+        if (contract.type !== 'variant') {
+            return [{
+                    path,
+                    prop: targetProp,
+                    expected: `Variant Prop for binding field "${field}"`,
+                    actual: `${contract.type} binding`,
+                    hint: `Use {${prop}} or declare ${prop} with defineVariants().`,
+                }];
+        }
+        sourceValues = Object.values(contract.variants).map((variant) => variant[field]).filter((value) => value !== undefined);
+        if (sourceValues.length !== Object.keys(contract.variants).length) {
+            return [{
+                    path,
+                    prop: targetProp,
+                    expected: `Variant field declared by ${prop}`,
+                    actual: 'unknown binding field',
+                    hint: `Use one of ${Object.keys(Object.values(contract.variants)[0] ?? {}).map((name) => JSON.stringify(name)).join(', ')}.`,
+                }];
+        }
+        sourceType = typeof sourceValues[0];
+    }
+    else if (contract.type === 'struct') {
+        sourceType = 'object';
+    }
+    else if (contract.type === 'variant') {
+        sourceType = 'string';
+        sourceValues = Object.keys(contract.variants);
+    }
+    else {
+        sourceType = contract.type;
+        if (contract.default !== undefined) {
+            sourceValues = [contract.default];
+        }
+    }
+    const textAcceptsScalar = targetProp === 'text' && ['string', 'number', 'boolean'].includes(sourceType);
+    if (expectedType && !textAcceptsScalar && !bindingSourceMatchesTarget(sourceType, sourceValues, expectedType, options)) {
+        return [{
+                path,
+                prop: targetProp,
+                expected: expectedType,
+                actual: `${sourceType} binding`,
+                hint: `Bind ${targetProp} to a Scene Prop with a compatible value type.`,
+            }];
+    }
+    return [];
+}
+function bindingSourceMatchesTarget(sourceType, values, expectedType, options) {
+    if (expectedType === 'color') {
+        return sourceType === 'number' || (sourceType === 'string' && values?.every((value) => (typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value))) === true);
+    }
+    if (expectedType === 'enum') {
+        return !!values && values.every((value) => options?.includes(value));
+    }
+    return sourceType === expectedType;
+}
 function validateSceneInstanceStructProp(node, path, prop, value, contract) {
     if (!value || typeof value !== 'object') {
         return [{

package/dist/compiler/spec.d.ts

@@ -1,7 +1,12 @@
-export type SceneTemplatePrimitiveType = 'Group' | 'Container' | 'Sprite' | 'Text' | 'Graphics' | 'Rect' | 'Image' | 'NineImage' | 'TileImage' | 'BitmapText' | 'HTMLText' | 'Mesh' | 'NineSliceSprite' | 'TilingSprite' | 'DOMContainer' | 'GridContainer' | 'HBoxContainer' | 'ScrollContainer' | 'VBoxContainer';
+export type SceneTemplatePrimitiveType = 'Group' | 'Container' | 'Sprite' | 'Text' | 'Label' | 'BitmapLabel' | 'Graphics' | 'Rect' | 'Image' | 'NineImage' | 'TileImage' | 'BitmapText' | 'HTMLText' | 'Mesh' | 'NineSliceSprite' | 'TilingSprite' | 'DOMContainer' | 'GridContainer' | 'HBoxContainer' | 'ScrollContainer' | 'VBoxContainer';
 export type SceneTemplateScalarValue = string | number | boolean;
 export type SceneTemplateStructValue = Record<string, SceneTemplateScalarValue>;
-export type SceneTemplateValue = SceneTemplateScalarValue | SceneTemplateStructValue;
+export interface SceneTemplateBindingValue {
+    kind: 'binding';
+    path: [string] | [string, string];
+}
+export type SceneTemplateValue = SceneTemplateScalarValue | SceneTemplateStructValue | SceneTemplateBindingValue;
+export declare function isSceneTemplateBindingValue(value: SceneTemplateValue | undefined): value is SceneTemplateBindingValue;
 export type SceneTemplatePrimitivePropType = 'string' | 'number' | 'boolean';
 export interface SceneTemplatePrimitivePropContract {
     type: SceneTemplatePrimitivePropType;
@@ -17,7 +22,14 @@ export interface SceneTemplateStructPropContract {
     sourceScene?: string;
     fields: Record<string, SceneTemplateStructFieldContract>;
 }
-export type SceneTemplatePropContract = SceneTemplatePrimitivePropContract | SceneTemplateStructPropContract;
+export type SceneTemplateVariantFields = Record<string, SceneTemplateScalarValue>;
+export type SceneTemplateVariants = Record<string, SceneTemplateVariantFields>;
+export interface SceneTemplateVariantPropContract {
+    type: 'variant';
+    default: string;
+    variants: SceneTemplateVariants;
+}
+export type SceneTemplatePropContract = SceneTemplatePrimitivePropContract | SceneTemplateStructPropContract | SceneTemplateVariantPropContract;
 export interface SceneTemplateEventContract {
     type: 'action';
 }
@@ -84,11 +96,10 @@ export interface SceneScriptInterface {
 }
 export type SceneClassDecorator = ClassDecorator;
 export type SceneMemberDecorator = PropertyDecorator & MethodDecorator;
-export type SceneStructConstructor = new () => object;
-export type ScenePropType = StringConstructor | NumberConstructor | BooleanConstructor | SceneStructConstructor;
+export type SceneVariants = Record<string, Record<string, SceneTemplateScalarValue>>;
 export interface ScenePropDecoratorOptions {
-    type: ScenePropType;
-    default?: SceneTemplateValue;
+    default?: SceneTemplateScalarValue;
+    variants?: SceneVariants;
 }
 export interface SceneEventDecoratorOptions {
     name?: string;

package/dist/compiler/spec.js

@@ -1 +1,3 @@
-export {};
+export function isSceneTemplateBindingValue(value) {
+    return !!value && typeof value === 'object' && value.kind === 'binding';
+}