pixifact 0.14.0 → 0.15.0

package/dist/compiler/commands/index.d.ts

@@ -12,6 +12,14 @@ export type CompilerSceneCommand = {
     op: 'setSceneProp';
     prop: string;
     value?: SceneTemplateValue;
+} | {
+    op: 'setSceneDefaultProp';
+    prop: string;
+    value?: SceneTemplateValue;
+} | {
+    op: 'setSceneEvent';
+    event: string;
+    value?: string;
 } | {
     op: 'setNodeId';
     node: string;

package/dist/compiler/commands/index.js

@@ -174,6 +174,21 @@ function setSceneProp(template, command) {
         selection: { type: 'scene' },
     };
 }
+function setSceneDefaultProp(template, command) {
+    const defaults = template.propDefaults ??= {};
+    const previous = getPropPathValue(defaults, command.prop);
+    setPropPathValue(defaults, command.prop, command.value);
+    return { ok: true, command, inverse: { op: 'setSceneDefaultProp', prop: command.prop, value: previous }, selection: { type: 'scene' } };
+}
+function setSceneEvent(template, command) {
+    const events = template.events ??= {};
+    const previous = events[command.event];
+    if (command.value === undefined)
+        delete events[command.event];
+    else
+        events[command.event] = command.value;
+    return { ok: true, command, inverse: { op: 'setSceneEvent', event: command.event, value: previous }, selection: { type: 'scene' } };
+}
 function setNodeId(template, command, context) {
     const located = findCompilerSceneNodeLocation(template.children, command.node, context);
     if (!located || located.node.kind === 'slotOutlet') {
@@ -275,15 +290,16 @@ function setPropPathValue(props, prop, value) {
 }
 function setNodeEvent(template, command, context) {
     const located = findCompilerSceneNodeLocation(template.children, command.node, context);
-    if (!located || located.node.kind !== 'sceneInstance') {
+    if (!located || located.node.kind === 'slotOutlet') {
         return { ok: false, command, error: 'Node event target was not found.' };
     }
-    const previous = located.node.events[command.event];
+    const events = located.node.events ??= {};
+    const previous = events[command.event];
     if (command.value === undefined) {
-        delete located.node.events[command.event];
+        delete events[command.event];
     }
     else {
-        located.node.events[command.event] = command.value;
+        events[command.event] = command.value;
     }
     return {
         ok: true,
@@ -422,6 +438,10 @@ export function applyCompilerSceneCommand(template, command, context = {}) {
             return setSceneName(template, command);
         case 'setSceneProp':
             return setSceneProp(template, command);
+        case 'setSceneDefaultProp':
+            return setSceneDefaultProp(template, command);
+        case 'setSceneEvent':
+            return setSceneEvent(template, command);
         case 'setNodeId':
             return setNodeId(template, command, context);
         case 'setNodeProp':

package/dist/compiler/compileScenes.js

@@ -282,7 +282,7 @@ function normalizeSceneReferences(scenePath, template) {
     return next;
 }
 function sceneImportsFor(template, templates, projectRoot, generatedFileDir) {
-    return [...collectSceneImportPaths(template, templates)]
+    return [...collectSceneImportPaths(template)]
         .sort()
         .map((scenePath) => {
         const sceneTemplate = templates.get(scenePath);
@@ -297,31 +297,13 @@ function sceneImportsFor(template, templates, projectRoot, generatedFileDir) {
         };
     });
 }
-function collectSceneImportPaths(template, templates) {
+function collectSceneImportPaths(template) {
     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);
-        }
+    for (const contract of Object.values(template.interface.props)) {
+        if (contract.type === 'struct' && contract.sourceScene)
+            scenePaths.add(contract.sourceScene);
     }
+    return scenePaths;
 }
 function sceneClassAliasesFor(template) {
     return Object.fromEntries([...collectSceneInstancePaths(template.children)].map((scenePath) => [scenePath, sceneClassAlias(scenePath)]));

package/dist/compiler/sceneValidation.js

@@ -1,4 +1,4 @@
-import { isSceneTemplateBindingValue, } from './spec.js';
+import { isSceneTemplateBindingValue, sceneNativeEventNames, } from './spec.js';
 import { isPixiSceneNodeType, pixiSceneFieldSchema, pixiSceneLayoutProps, pixiSceneNodeAcceptsChildren, pixiSceneNodePropKeys, pixiSceneTransformProps, pixiSceneDisplayProps, } from './pixiNodeSchema.js';
 import { parseSceneTemplate } from './templateParser.js';
 import { serializeSceneTemplate } from './templateSerializer.js';
@@ -119,7 +119,40 @@ function sourcePositionFromMessage(source, message) {
     };
 }
 function validateSceneTemplate(template, context) {
-    return template.children.flatMap((child, index) => validateSceneNode(child, nodePathSegment(index, child), context));
+    return [
+        ...validateSceneDefaults(template, context),
+        ...validateNativeEvents(template.events, '__scene__'),
+        ...template.children.flatMap((child, index) => validateSceneNode(child, nodePathSegment(index, child), { ...context, sceneDefaults: template.propDefaults })),
+    ];
+}
+function validateSceneDefaults(template, context) {
+    if (context.bindingsOnly || !context.sceneInterface)
+        return [];
+    const diagnostics = [];
+    for (const [name, value] of Object.entries(template.propDefaults ?? {})) {
+        const contract = context.sceneInterface?.props[name];
+        if (!contract) {
+            diagnostics.push({ path: '__scene__', prop: `default.${name}`, expected: 'Prop declared by the paired script', actual: 'unknown Prop' });
+            continue;
+        }
+        if (contract.type === 'struct') {
+            diagnostics.push(...validateStructFields('__scene__', `default.${name}`, value, contract, template.name));
+            continue;
+        }
+        const expectedType = contract.type === 'variant' ? 'string' : contract.type;
+        if (!sceneValueMatchesContractType(value, expectedType) || (contract.type === 'variant' && !contract.variants[String(value)])) {
+            diagnostics.push({ path: '__scene__', prop: `default.${name}`, expected: contract.type === 'variant' ? `one of ${Object.keys(contract.variants).join(', ')}` : expectedType, actual: sceneValueType(value) });
+        }
+    }
+    return diagnostics;
+}
+function validateNativeEvents(events, path) {
+    return Object.entries(events ?? {}).flatMap(([name, action]) => {
+        if (!sceneNativeEventNames.includes(name)) {
+            return [{ path, prop: `on:${name}`, expected: `one of ${sceneNativeEventNames.join(', ')}`, actual: name }];
+        }
+        return action.trim() ? [] : [{ path, prop: `on:${name}`, expected: 'nonempty action name', actual: action }];
+    });
 }
 function validateSceneNode(node, path, context) {
     if (node.kind === 'slotOutlet') {
@@ -147,6 +180,7 @@ function validatePixiNode(node, path, context) {
             }];
     }
     const diagnostics = [];
+    diagnostics.push(...validateNativeEvents(node.events, path));
     if (!pixiSceneNodeAcceptsChildren(node.type) && node.children.length > 0) {
         diagnostics.push({
             path,
@@ -178,7 +212,7 @@ function validatePixiNode(node, path, context) {
         }
         const schema = pixiSceneFieldSchema(prop);
         if (isSceneTemplateBindingValue(value)) {
-            diagnostics.push(...validateSceneBinding(path, prop, value, context.sceneInterface, schema?.type, schema?.options));
+            diagnostics.push(...validateSceneBinding(path, prop, value, context.sceneInterface, schema?.type, schema?.options, context.sceneDefaults));
             continue;
         }
         if (schema && !sceneValueMatchesFieldType(value, schema.type, schema.options)) {
@@ -252,7 +286,7 @@ function validateSceneInstanceNode(node, path, context) {
         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));
+            diagnostics.push(...validateSceneBinding(path, prop, value, context.sceneInterface, expectedType, schema?.options, context.sceneDefaults));
             continue;
         }
         if (contract?.type === 'struct') {
@@ -304,7 +338,7 @@ function validateSceneInstanceNode(node, path, context) {
     }
     return diagnostics;
 }
-function validateSceneBinding(path, targetProp, binding, sceneInterface, expectedType, options) {
+function validateSceneBinding(path, targetProp, binding, sceneInterface, expectedType, options, sceneDefaults) {
     const [prop, field] = binding.path;
     const contract = sceneInterface?.props[prop];
     if (!contract) {
@@ -349,8 +383,9 @@ function validateSceneBinding(path, targetProp, binding, sceneInterface, expecte
     }
     else {
         sourceType = contract.type;
-        if (contract.default !== undefined) {
-            sourceValues = [contract.default];
+        const sourceValue = sceneDefaults?.[prop] ?? contract.default;
+        if (sourceValue !== undefined && typeof sourceValue !== 'object') {
+            sourceValues = [sourceValue];
         }
     }
     const textAcceptsScalar = targetProp === 'text' && ['string', 'number', 'boolean'].includes(sourceType);
@@ -375,13 +410,16 @@ function bindingSourceMatchesTarget(sourceType, values, expectedType, options) {
     return sourceType === expectedType;
 }
 function validateSceneInstanceStructProp(node, path, prop, value, contract) {
-    if (!value || typeof value !== 'object') {
+    return validateStructFields(path, prop, value, contract, node.type);
+}
+function validateStructFields(path, prop, value, contract, ownerType) {
+    if (!value || typeof value !== 'object' || isSceneTemplateBindingValue(value)) {
         return [{
                 path,
                 prop,
                 expected: contract.struct,
                 actual: sceneValueType(value),
-                hint: `Set ${node.type}.${prop} fields using dot-path attributes such as ${prop}.x="0".`,
+                hint: `Set ${ownerType}.${prop} fields using dot-path attributes such as ${prop}.x="0".`,
             }];
     }
     const diagnostics = [];
@@ -403,7 +441,7 @@ function validateSceneInstanceStructProp(node, path, prop, value, contract) {
                 prop: `${prop}.${field}`,
                 expected: fieldContract.type,
                 actual: sceneValueType(fieldValue),
-                hint: `Set ${node.type}.${prop}.${field} to ${fieldTypeDescription(fieldContract.type)}.`,
+                hint: `Set ${ownerType}.${prop}.${field} to ${fieldTypeDescription(fieldContract.type)}.`,
             });
         }
     }

package/dist/compiler/spec.d.ts

@@ -6,6 +6,7 @@ export interface SceneTemplateBindingValue {
     path: [string] | [string, string];
 }
 export type SceneTemplateValue = SceneTemplateScalarValue | SceneTemplateStructValue | SceneTemplateBindingValue;
+export declare const sceneNativeEventNames: readonly ["pointertap", "pointerdown", "pointerup", "pointerupoutside", "pointerover", "pointerout", "click"];
 export declare function isSceneTemplateBindingValue(value: SceneTemplateValue | undefined): value is SceneTemplateBindingValue;
 export type SceneTemplatePrimitivePropType = 'string' | 'number' | 'boolean';
 export interface SceneTemplatePrimitivePropContract {
@@ -44,6 +45,8 @@ export interface SceneTemplate {
     version: 2;
     name: string;
     props: Record<string, SceneTemplateValue>;
+    propDefaults?: Record<string, SceneTemplateValue>;
+    events?: Record<string, string>;
     interface: SceneTemplateInterface;
     children: SceneTemplateNode[];
 }
@@ -53,6 +56,7 @@ export interface PixiTemplateNode {
     type: SceneTemplatePrimitiveType;
     id?: string;
     props: Record<string, SceneTemplateValue>;
+    events?: Record<string, string>;
     children: SceneTemplateNode[];
 }
 export interface SceneInstanceTemplateNode {

package/dist/compiler/spec.js

@@ -1,3 +1,4 @@
+export const sceneNativeEventNames = ['pointertap', 'pointerdown', 'pointerup', 'pointerupoutside', 'pointerover', 'pointerout', 'click'];
 export function isSceneTemplateBindingValue(value) {
     return !!value && typeof value === 'object' && value.kind === 'binding';
 }

package/dist/compiler/templateParser.js

@@ -43,7 +43,11 @@ export function parseSceneTemplate(source) {
     return {
         version: 2,
         name,
-        props: parseProps(root, ['name']),
+        props: parseProps(root, ['name'], (attribute) => attribute.startsWith('default.') || attribute.startsWith('on:')),
+        propDefaults: parseProps({ ...root, attributes: Object.fromEntries(Object.entries(root.attributes)
+                .filter(([attribute]) => attribute.startsWith('default.'))
+                .map(([attribute, value]) => [attribute.slice('default.'.length), value])) }, [], undefined, true),
+        events: parseNativeEvents(root),
         interface: emptyInterface(),
         children,
     };
@@ -85,7 +89,8 @@ function parseTemplateNode(element) {
         const node = {
             kind: 'pixi',
             type: element.name,
-            props: parseProps(element, ['id', 'slot']),
+            props: parseProps(element, ['id', 'slot'], (attribute) => attribute.startsWith('on:')),
+            events: parseNativeEvents(element),
             children: element.children.map(parseTemplateNode),
             ...(element.attributes.id ? { id: element.attributes.id } : {}),
         };
@@ -93,13 +98,13 @@ function parseTemplateNode(element) {
     }
     throw new Error(`Unsupported template tag <${element.name}>. Add scene="..." or use a built-in Scene name.`);
 }
-function parseProps(element, omitted, shouldOmit = () => false) {
+function parseProps(element, omitted, shouldOmit = () => false, allowQuotedStrings = false) {
     const props = {};
     for (const [name, value] of Object.entries(element.attributes)) {
         if (omitted.includes(name) || shouldOmit(name)) {
             continue;
         }
-        const parsed = parseAttributeValue(name, value);
+        const parsed = parseAttributeValue(name, value, allowQuotedStrings);
         const path = name.split('.');
         if (path.length === 1) {
             if (props[name] && typeof props[name] === 'object') {
@@ -134,6 +139,11 @@ function parseEvents(element) {
     }
     return events;
 }
+function parseNativeEvents(element) {
+    return Object.fromEntries(Object.entries(element.attributes)
+        .filter(([name]) => name.startsWith('on:'))
+        .map(([name, value]) => [name.slice(3), value]));
+}
 function eventName(name) {
     if (name.startsWith('@')) {
         return name.slice(1);
@@ -149,7 +159,9 @@ function eventName(name) {
 function isEventAttribute(name) {
     return eventName(name) !== undefined;
 }
-function parseAttributeValue(name, value) {
+function parseAttributeValue(name, value, allowQuotedStrings = false) {
+    if (allowQuotedStrings && value.startsWith('"') && value.endsWith('"'))
+        return JSON.parse(value);
     const binding = parseBindingValue(value);
     if (binding) {
         return binding;

package/dist/compiler/templateSerializer.js

@@ -16,6 +16,8 @@ export function serializeSceneTemplate(template) {
     const rootAttributes = [
         ['name', template.name],
         ...Object.entries(template.props),
+        ...Object.entries(template.propDefaults ?? {}).map(([name, value]) => [`default.${name}`, value]),
+        ...Object.entries(template.events ?? {}).map(([name, value]) => [`on:${name}`, value]),
     ];
     const lines = [`<Scene${serializeAttributes(rootAttributes)}>`];
     for (const child of template.children) {
@@ -37,6 +39,7 @@ function serializeTemplateNode(node, depth, extraAttributes = []) {
             ...(node.id ? [['id', node.id]] : []),
             ...extraAttributes,
             ...Object.entries(node.props),
+            ...Object.entries(node.events ?? {}).map(([name, value]) => [`on:${name}`, value]),
         ];
         return serializeElement(node.type, attributes, node.children, depth);
     }
@@ -89,6 +92,12 @@ function formatAttributeValue(name, value) {
     if (isBindingValue(value)) {
         return `{${value.path.join('.')}}`;
     }
+    if (name.startsWith('default.') && typeof value === 'string'
+        && (/^(?:true|false|-?\d+(?:\.\d+)?|#[0-9a-fA-F]{6})$/.test(value)
+            || value.startsWith('{') || value.endsWith('}')
+            || (value.startsWith('"') && value.endsWith('"')))) {
+        return JSON.stringify(value);
+    }
     if (typeof value === 'number' && colorPropNames.has(name)) {
         return `#${value.toString(16).padStart(6, '0').slice(-6)}`;
     }

package/dist/compiler/typescriptCompiler.js

@@ -70,6 +70,7 @@ class CompileContext {
             this.#lines.push(`registerScene(${JSON.stringify(this.options.registrationPath)}, {`);
             this.#lines.push(`  assets: ${JSON.stringify([...this.#textures.keys()])},`);
             this.#lines.push(`  dependencies: ${JSON.stringify(this.options.sceneDependencies ?? [])},`);
+            this.#lines.push(`  propDefaults: () => (${this.#sceneDefaultProps()}),`);
             this.#lines.push(`  mount: ${functionName},`);
             this.#lines.push(`  prepare: ${this.#prepareFunctionName()},`);
             this.#lines.push('});');
@@ -106,7 +107,10 @@ class CompileContext {
             }
         }
         if (this.options.scriptImport) {
-            lines.push(`import { ${this.options.scriptImport.exportName} as ${this.options.scriptImport.localName} } from ${JSON.stringify(this.options.scriptImport.source)};`);
+            const localStructs = Object.values(this.template.interface.props)
+                .filter((contract) => contract.type === 'struct' && !contract.sourceScene)
+                .map((contract) => contract.struct);
+            lines.push(`import { ${[`${this.options.scriptImport.exportName} as ${this.options.scriptImport.localName}`, ...new Set(localStructs)].join(', ')} } from ${JSON.stringify(this.options.scriptImport.source)};`);
         }
         if (this.#runtimeImports.size > 0) {
             lines.push(`import { ${[...this.#runtimeImports].sort().join(', ')} } from 'pixifact/scene';`);
@@ -226,6 +230,13 @@ class CompileContext {
         this.#recordSource(variable, locator);
         this.#applyNodeId(variable, node.id);
         this.#applyPixiProps(variable, node.props, false, undefined, node.type);
+        if (Object.keys(node.events ?? {}).length > 0 && node.props.eventMode === undefined) {
+            this.#lines.push(`  ${variable}.eventMode = 'static';`);
+        }
+        for (const [eventName, actionName] of Object.entries(node.events ?? {})) {
+            this.#runtimeImports.add('connectSceneNodeEvent');
+            this.#lines.push(`  connectSceneNodeEvent(${variable}, ${JSON.stringify(eventName)}, ${JSON.stringify(actionName)}, root, ${actionsParameter});`);
+        }
         this.#applyParentSorting(parent, node.props);
         this.#lines.push(`  ${parent}.addChild(${variable});`);
         this.#lines.push(`  __pixifactNodes[${JSON.stringify(locator)}] = ${variable};`);
@@ -237,7 +248,7 @@ class CompileContext {
         const variable = node.id || this.#anonymousName(node.type);
         const locator = compilerSceneNodeLocator(node, path);
         const constructorName = this.#sceneConstructorName(node);
-        const constructorArgs = this.#sceneInstanceConstructorArgs(variable, node);
+        const constructorArgs = this.#sceneInstanceConstructorArgs(node);
         this.#lines.push(`  const ${variable} = new ${constructorName}(${constructorArgs});`);
         this.#recordSource(variable, locator, true);
         this.#applyPixiProps(variable, node.props, true, node);
@@ -264,7 +275,7 @@ class CompileContext {
             const variable = node.id || this.#anonymousName(node.type);
             const locator = compilerSceneNodeLocator(node, path);
             const constructorName = this.#sceneConstructorName(node);
-            const constructorArgs = this.#sceneInstanceConstructorArgs(variable, node);
+            const constructorArgs = this.#sceneInstanceConstructorArgs(node);
             this.#lines.push(`  const ${variable} = new ${constructorName}(${constructorArgs});`);
             this.#recordSource(variable, locator, true);
             this.#applyPixiProps(variable, node.props, true, node);
@@ -322,7 +333,7 @@ class CompileContext {
     #sceneConstructorName(node) {
         return this.options.sceneClassAliases?.[node.scene] ?? node.type;
     }
-    #sceneInstanceConstructorArgs(variable, node) {
+    #sceneInstanceConstructorArgs(node) {
         const sceneInterface = this.options.sceneInterfaces?.[node.scene];
         if (!sceneInterface) {
             return '';
@@ -339,8 +350,7 @@ class CompileContext {
                 continue;
             }
             if (contract.type === 'struct' && value && typeof value === 'object') {
-                const structVariable = this.#createStructValue(variable, key, value, contract);
-                entries.push(`${key}: ${structVariable}`);
+                entries.push(`${key}: ${this.#value(value)}`);
                 continue;
             }
             entries.push(`${key}: ${this.#value(value)}`);
@@ -353,29 +363,11 @@ class CompileContext {
             return [];
         }
         const structs = new Set();
-        this.#collectSceneStructImports(this.template.children, scene, structs);
-        return [...structs].sort();
-    }
-    #collectSceneStructImports(nodes, sourceScene, structs) {
-        for (const node of nodes) {
-            if (node.kind === 'slotOutlet') {
-                continue;
-            }
-            if (node.kind === 'pixi') {
-                this.#collectSceneStructImports(node.children, sourceScene, structs);
-                continue;
-            }
-            const sceneInterface = this.options.sceneInterfaces?.[node.scene];
-            for (const [key, value] of Object.entries(node.props)) {
-                const contract = value && typeof value === 'object' ? sceneInterface?.props[key] : undefined;
-                if (contract?.type === 'struct' && this.#structContractSourceScene(node.scene, contract) === sourceScene) {
-                    structs.add(contract.struct);
-                }
-            }
-            for (const children of Object.values(node.slots)) {
-                this.#collectSceneStructImports(children, sourceScene, structs);
-            }
+        for (const contract of Object.values(this.template.interface.props)) {
+            if (contract.type === 'struct' && contract.sourceScene === scene)
+                structs.add(contract.struct);
         }
+        return [...structs].sort();
     }
     #usesSceneClassImport(sceneImport) {
         const scene = this.#sceneImportScene(sceneImport);
@@ -413,9 +405,6 @@ class CompileContext {
         return sceneImport.scene
             ?? Object.entries(this.options.sceneClassAliases ?? {}).find(([, alias]) => alias === sceneImport.localName)?.[0];
     }
-    #structContractSourceScene(instanceScene, contract) {
-        return contract.sourceScene ?? instanceScene;
-    }
     #applyPixiProps(variable, props, instance = false, sceneInstance, pixiType) {
         const publicProps = new Set(Object.keys(sceneInstance ? this.options.sceneInterfaces?.[sceneInstance.scene]?.props ?? {} : {}));
         const bindingEntries = Object.entries(props).filter((entry) => (isSceneBindingValue(entry[1]) && !publicProps.has(entry[0])));
@@ -515,6 +504,25 @@ class CompileContext {
             this.#lines.push(`  root.setSize(${this.#value(width ?? 0)}, ${this.#value(height ?? 0)});`);
         }
         this.#applyPixiProps('root', props);
+        if (Object.keys(this.template.events ?? {}).length > 0 && props.eventMode === undefined) {
+            this.#lines.push("  root.eventMode = 'static';");
+        }
+        for (const [eventName, actionName] of Object.entries(this.template.events ?? {})) {
+            this.#runtimeImports.add('connectSceneNodeEvent');
+            this.#lines.push(`  connectSceneNodeEvent(root, ${JSON.stringify(eventName)}, ${JSON.stringify(actionName)}, root, ${this.options.actionsParameter || 'actions'});`);
+        }
+    }
+    #sceneDefaultProps() {
+        const editorDefaults = this.template.propDefaults ?? {};
+        const entries = Object.entries(this.template.interface.props).flatMap(([name, contract]) => {
+            const explicit = editorDefaults[name];
+            if (contract.type === 'struct') {
+                const overrides = explicit && typeof explicit === 'object' ? explicit : {};
+                return [`${JSON.stringify(name)}: Object.assign(new ${contract.struct}(), ${this.#value(overrides)})`];
+            }
+            return explicit === undefined ? [] : [`${JSON.stringify(name)}: ${this.#value(explicit)}`];
+        });
+        return `{ ${entries.join(', ')} }`;
     }
     #applyLayoutProps(variable, props) {
         const entries = pixiSceneLayoutProps.flatMap((key) => {
@@ -631,6 +639,8 @@ class CompileContext {
             : `{ texture: ${this.#textureValue(props.texture)} }`;
     }
     #hasEvents() {
+        if (Object.keys(this.template.events ?? {}).length > 0)
+            return true;
         for (const child of this.template.children) {
             if (this.#nodeHasEvents(child)) {
                 return true;
@@ -648,7 +658,7 @@ class CompileContext {
             }
             return Object.values(node.slots).some((children) => children.some((child) => this.#nodeHasEvents(child)));
         }
-        return node.children.some((child) => this.#nodeHasEvents(child));
+        return Object.keys(node.events ?? {}).length > 0 || node.children.some((child) => this.#nodeHasEvents(child));
     }
     #isTextStyleProp(key) {
         return textStyleProps.has(key);

package/dist/scene/decorators.js

@@ -1,5 +1,5 @@
 import { activateRuntimeTree } from '../runtime/runtimeBehavior.js';
-import { mountSceneClass } from './sceneRuntime.js';
+import { mountSceneClass, scenePropDefaultsForClass } from './sceneRuntime.js';
 import { initializeSceneProps } from './sceneBindingRuntime.js';
 const metadataByConstructor = new WeakMap();
 export function scene() {
@@ -14,7 +14,7 @@ export function scene() {
                 const initialProps = args[0] && typeof args[0] === 'object'
                     ? args[0]
                     : {};
-                initializeSceneProps(this, metadata.props, initialProps);
+                initializeSceneProps(this, metadata.props, initialProps, scenePropDefaultsForClass(SceneClass));
                 const result = mountSceneClass(this, SceneClass);
                 for (const [property, id] of metadata.parts) {
                     Object.defineProperty(this, property, {

package/dist/scene/eventRuntime.d.ts

@@ -1,3 +1,4 @@
+import type { Container } from 'pixi.js';
 export type SceneEventListener<TPayload = void> = TPayload extends void ? () => void : (payload: TPayload) => void;
 export interface SceneEvent<TPayload = void> {
     connect(listener: SceneEventListener<TPayload>): () => void;
@@ -6,3 +7,4 @@ export interface SceneEvent<TPayload = void> {
 export type SceneActions = Record<string, (() => void) | undefined>;
 export declare function createEvent<TPayload = void>(): SceneEvent<TPayload>;
 export declare function connectSceneEvent(event: SceneEvent, actionName: string, owner: object, actions?: SceneActions): () => void;
+export declare function connectSceneNodeEvent(target: Container, eventName: string, actionName: string, owner: object, actions?: SceneActions): void;

package/dist/scene/eventRuntime.js

@@ -27,3 +27,16 @@ export function connectSceneEvent(event, actionName, owner, actions = {}) {
     }
     throw new Error(`Scene action "${actionName}" was not found.`);
 }
+export function connectSceneNodeEvent(target, eventName, actionName, owner, actions = {}) {
+    const action = actions[actionName];
+    if (action) {
+        target.on(eventName, action);
+        return;
+    }
+    const ownerAction = owner[actionName];
+    if (typeof ownerAction === 'function') {
+        target.on(eventName, () => ownerAction.call(owner));
+        return;
+    }
+    throw new Error(`Scene action "${actionName}" was not found.`);
+}

package/dist/scene/sceneBindingRuntime.d.ts

@@ -1,7 +1,7 @@
 import type { Container } from 'pixi.js';
 import type { ScenePropDecoratorOptions, SceneTemplateBindingValue, SceneTemplateInterface, SceneTemplateScalarValue } from '../compiler/spec.js';
-export declare function initializeSceneProps(target: object, definitions: ReadonlyMap<string, ScenePropDecoratorOptions>, initialProps?: Record<string, unknown>): void;
-export declare function initializeScenePropsFromInterface(target: object, sceneInterface: SceneTemplateInterface, initialProps?: Record<string, unknown>): void;
+export declare function initializeSceneProps(target: object, definitions: ReadonlyMap<string, ScenePropDecoratorOptions>, initialProps?: Record<string, unknown>, sceneDefaults?: Record<string, unknown>): void;
+export declare function initializeScenePropsFromInterface(target: object, sceneInterface: SceneTemplateInterface, initialProps?: Record<string, unknown>, sceneDefaults?: Record<string, unknown>): void;
 export declare function setSceneProp(target: object, name: string, value: unknown): void;
 export declare function getSceneProp<T = unknown>(target: object, name: string): T;
 export declare function readSceneBindingValue<T = unknown>(target: object, binding: SceneTemplateBindingValue): T;

package/dist/scene/sceneBindingRuntime.js

@@ -3,7 +3,7 @@ const states = new WeakMap();
 const layoutProps = new Set(['left', 'right', 'top', 'bottom', 'horizontal', 'vertical']);
 const textStyleProps = new Set(['fontSize', 'fontFamily', 'fontWeight', 'fill']);
 const colorProps = new Set(['fill', 'fillColor', 'strokeColor', 'tint']);
-export function initializeSceneProps(target, definitions, initialProps = {}) {
+export function initializeSceneProps(target, definitions, initialProps = {}, sceneDefaults = {}) {
     const state = {
         definitions: Object.fromEntries(definitions),
         subscribers: new Map(),
@@ -11,9 +11,13 @@ export function initializeSceneProps(target, definitions, initialProps = {}) {
     };
     states.set(target, state);
     for (const [name, definition] of Object.entries(state.definitions)) {
+        const fallback = Object.hasOwn(sceneDefaults, name) ? sceneDefaults[name] : definition.default;
+        const initial = initialProps[name];
         state.values[name] = Object.hasOwn(initialProps, name)
-            ? initialProps[name]
-            : definition.default;
+            ? initial && fallback && typeof initial === 'object' && typeof fallback === 'object'
+                ? Object.assign(fallback, initial)
+                : initial
+            : fallback;
         Object.defineProperty(target, name, {
             configurable: true,
             enumerable: true,
@@ -22,14 +26,14 @@ export function initializeSceneProps(target, definitions, initialProps = {}) {
         });
     }
 }
-export function initializeScenePropsFromInterface(target, sceneInterface, initialProps = {}) {
+export function initializeScenePropsFromInterface(target, sceneInterface, initialProps = {}, sceneDefaults = {}) {
     initializeSceneProps(target, new Map(Object.entries(sceneInterface.props).map(([name, contract]) => [
         name,
         {
             ...('default' in contract ? { default: contract.default } : {}),
             ...(contract.type === 'variant' ? { variants: contract.variants } : {}),
         },
-    ])), initialProps);
+    ])), initialProps, sceneDefaults);
 }
 export function setSceneProp(target, name, value) {
     const state = sceneBindingState(target);

package/dist/scene/sceneRuntime.d.ts

@@ -9,11 +9,13 @@ export interface SceneMountResult {
 export interface SceneDefinition {
     assets: string[];
     dependencies: string[];
+    propDefaults?: () => Record<string, unknown>;
     mount(root: Group): SceneMountResult;
     prepare(): Promise<void>;
 }
 export declare function registerScene(path: string, definition: SceneDefinition): void;
 export declare function registerSceneClass(constructor: object, path: string): void;
+export declare function scenePropDefaultsForClass(constructor: object): Record<string, unknown>;
 export declare function mountScene(root: Group, path: string): SceneMountResult;
 export declare function mountSceneClass(root: Group, constructor: object): SceneMountResult;
 export declare function prepareScene(path: string): Promise<void>;

package/dist/scene/sceneRuntime.js

@@ -11,6 +11,10 @@ export function registerScene(path, definition) {
 export function registerSceneClass(constructor, path) {
     scenePathsByConstructor.set(constructor, path);
 }
+export function scenePropDefaultsForClass(constructor) {
+    const path = scenePathsByConstructor.get(constructor);
+    return path ? sceneDefinitions.get(path)?.propDefaults?.() ?? {} : {};
+}
 export function mountScene(root, path) {
     const definition = sceneDefinitions.get(path);
     if (!definition) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Pixifact 2D UI 和轻量游戏 Scene 语义框架。",
   "packageManager": "bun@1.3.13",
   "main": "./dist/index.js",