pixifact 0.1.3

package/dist/compiler/sceneAssetPair.d.ts

@@ -0,0 +1,11 @@
+export declare const defaultSceneSourceRoots: readonly ["src"];
+export declare const ignoredSceneSourceDirectories: Set<string>;
+export declare function toPosixPath(value: string): string;
+export declare function normalizeSceneAssetId(value: string): string;
+export declare function isIgnoredSceneSourceDirectory(name: string): boolean;
+export declare function sceneLocalName(scenePath: string): string;
+export declare function pairedSceneScriptPath(scenePath: string): string;
+export declare function generatedSceneModulePath(scenePath: string): string;
+export declare function generatedSceneModuleImport(scenePath: string): string;
+export declare function sceneClassAlias(scenePath: string): string;
+export declare function resolveSceneReference(fromScenePath: string, reference: string): string;

package/dist/compiler/sceneAssetPair.js

@@ -0,0 +1,92 @@
+export const defaultSceneSourceRoots = ['src'];
+export const ignoredSceneSourceDirectories = new Set([
+    'node_modules',
+    'build',
+    'dist',
+    'generated',
+    '.pixifact',
+    'coverage',
+    'test-results',
+]);
+export function toPosixPath(value) {
+    return value.replaceAll('\\', '/');
+}
+function posixBasename(value, suffix = '') {
+    const basename = value.split('/').filter(Boolean).at(-1) ?? '';
+    return suffix && basename.endsWith(suffix)
+        ? basename.slice(0, -suffix.length)
+        : basename;
+}
+function posixDirname(value) {
+    const normalized = toPosixPath(value).replace(/\/+$/, '');
+    const index = normalized.lastIndexOf('/');
+    return index >= 0 ? normalized.slice(0, index) : '';
+}
+function normalizePosixPath(value) {
+    const segments = [];
+    for (const segment of toPosixPath(value).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 posixJoin(...parts) {
+    return normalizePosixPath(parts.filter(Boolean).join('/'));
+}
+export function normalizeSceneAssetId(value) {
+    const normalized = toPosixPath(value).replace(/^\.\/+/, '').replace(/^\/+/, '');
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.includes('..')) {
+        throw new Error(`Scene path "${value}" must stay inside projectRoot.`);
+    }
+    if (!normalized.endsWith('.scene')) {
+        throw new Error(`Scene path "${value}" must end with .scene.`);
+    }
+    return parts.join('/');
+}
+export function isIgnoredSceneSourceDirectory(name) {
+    return ignoredSceneSourceDirectories.has(name);
+}
+export function sceneLocalName(scenePath) {
+    return posixBasename(normalizeSceneAssetId(scenePath), '.scene');
+}
+export function pairedSceneScriptPath(scenePath) {
+    const assetId = normalizeSceneAssetId(scenePath);
+    return `${assetId.slice(0, -'.scene'.length)}.ts`;
+}
+export function generatedSceneModulePath(scenePath) {
+    return `${normalizeSceneAssetId(scenePath).slice(0, -'.scene'.length)}.scene.generated.ts`;
+}
+export function generatedSceneModuleImport(scenePath) {
+    return `./${generatedSceneModulePath(scenePath).replace(/\.ts$/, '')}`;
+}
+export function sceneClassAlias(scenePath) {
+    const base = normalizeSceneAssetId(scenePath)
+        .slice(0, -'.scene'.length)
+        .split('/')
+        .map((segment) => segment.replace(/[^A-Za-z0-9]/g, (character) => `_x${character.charCodeAt(0).toString(16)}_`))
+        .join('_');
+    return `SceneClass_${base}`;
+}
+export function resolveSceneReference(fromScenePath, reference) {
+    const value = toPosixPath(reference.trim());
+    if (!value.endsWith('.scene')) {
+        throw new Error('Scene references must use .scene paths.');
+    }
+    if (value.startsWith('./') || value.startsWith('../')) {
+        const baseDir = posixDirname(normalizeSceneAssetId(fromScenePath));
+        return normalizeSceneAssetId(posixJoin(baseDir, value));
+    }
+    return normalizeSceneAssetId(value);
+}

package/dist/compiler/scenePartValidation.d.ts

@@ -0,0 +1,6 @@
+import type { SceneTemplate } from './spec.js';
+export interface MissingScenePartReference {
+    property: string;
+    id: string;
+}
+export declare function findMissingScenePartReferences(template: SceneTemplate, parts: Readonly<Record<string, string>>): MissingScenePartReference[];

package/dist/compiler/scenePartValidation.js

@@ -0,0 +1,24 @@
+export function findMissingScenePartReferences(template, parts) {
+    const nodeIds = collectSceneNodeIds(template.children);
+    return Object.entries(parts)
+        .filter(([, id]) => !nodeIds.has(id))
+        .map(([property, id]) => ({ property, id }));
+}
+function collectSceneNodeIds(nodes, ids = new Set()) {
+    for (const node of nodes) {
+        if (node.kind === 'slotOutlet') {
+            continue;
+        }
+        if (node.id) {
+            ids.add(node.id);
+        }
+        if (node.kind === 'pixi') {
+            collectSceneNodeIds(node.children, ids);
+            continue;
+        }
+        for (const children of Object.values(node.slots)) {
+            collectSceneNodeIds(children, ids);
+        }
+    }
+    return ids;
+}

package/dist/compiler/sceneRuntime.d.ts

@@ -0,0 +1,13 @@
+import type { Container } from 'pixi.js';
+export interface SceneMountResult {
+    root: Container;
+    parts: Record<string, Container>;
+    slots: Record<string, Container>;
+}
+export interface SceneDefinition {
+    mount(root: Container): 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;

package/dist/compiler/sceneRuntime.js

@@ -0,0 +1,22 @@
+const sceneDefinitions = new Map();
+const scenePathsByConstructor = new WeakMap();
+export function registerScene(path, definition) {
+    sceneDefinitions.set(path, definition);
+}
+export function registerSceneClass(constructor, path) {
+    scenePathsByConstructor.set(constructor, path);
+}
+export function mountScene(root, path) {
+    const definition = sceneDefinitions.get(path);
+    if (!definition) {
+        throw new Error(`Scene "${path}" has not been registered.`);
+    }
+    return definition.mount(root);
+}
+export function mountSceneClass(root, constructor) {
+    const path = scenePathsByConstructor.get(constructor);
+    if (!path) {
+        throw new Error(`Scene class "${constructor instanceof Function ? constructor.name : 'unknown'}" has not been bound to a .scene file.`);
+    }
+    return mountScene(root, path);
+}

package/dist/compiler/sceneValidation.d.ts

@@ -0,0 +1,48 @@
+import type { SceneTemplate, SceneTemplateInterface, SceneTemplateNode, SceneTemplateValue } from './spec.js';
+export interface SceneTemplateNodeSummary {
+    id?: string;
+    kind: SceneTemplateNode['kind'];
+    type: string;
+    path: string;
+    propKeys: string[];
+    childCount: number;
+}
+export interface SceneTemplateInspection {
+    name: string;
+    props: Record<string, SceneTemplateValue>;
+    nodeCount: number;
+    nodes: SceneTemplateNodeSummary[];
+}
+export interface SceneValidationDiagnostic {
+    path: string;
+    prop: string;
+    expected: string;
+    actual: string;
+    hint?: string;
+    line?: number;
+    column?: number;
+}
+export declare function createSceneRevision(source: string): string;
+export declare function inspectSceneTemplate(template: SceneTemplate): SceneTemplateInspection;
+export interface ValidateSceneContentOptions {
+    scene: string;
+    content: string;
+    existingAssets?: ReadonlySet<string>;
+    sceneInterfaces?: Record<string, SceneTemplateInterface>;
+    normalizeSceneReference?: (scene: string) => string;
+}
+export type SceneContentValidationResult = {
+    ok: true;
+    scene: string;
+    revision: string;
+    canonicalContent: string;
+    summary: SceneTemplateInspection;
+} | {
+    ok: false;
+    scene: string;
+    revision?: string;
+    error: string;
+    diagnostics?: SceneValidationDiagnostic[];
+    hint?: string;
+};
+export declare function validateSceneContent(options: ValidateSceneContentOptions): SceneContentValidationResult;

package/dist/compiler/sceneValidation.js

@@ -0,0 +1,383 @@
+import { isPixiSceneNodeType, pixiSceneFieldSchema, pixiSceneNodePropKeys, pixiSceneTransformProps, pixiSceneDisplayProps, } from './pixiNodeSchema.js';
+import { parseSceneTemplate } from './templateParser.js';
+import { serializeSceneTemplate } from './templateSerializer.js';
+export function createSceneRevision(source) {
+    const canonical = serializeSceneTemplate(parseSceneTemplate(source));
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < canonical.length; index += 1) {
+        hash = Math.imul(hash ^ canonical.charCodeAt(index), 0x01000193);
+    }
+    return `scene:${canonical.length}:${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+export function inspectSceneTemplate(template) {
+    const nodes = [];
+    function visit(node, path) {
+        if (node.kind === 'slotOutlet') {
+            nodes.push({
+                kind: 'slotOutlet',
+                type: 'slot',
+                path,
+                propKeys: ['name'],
+                childCount: 0,
+            });
+            return;
+        }
+        if (node.kind === 'pixi') {
+            nodes.push({
+                id: node.id,
+                kind: node.kind,
+                type: node.type,
+                path,
+                propKeys: Object.keys(node.props).sort(),
+                childCount: node.children.length,
+            });
+            node.children.forEach((child, index) => visit(child, `${path}/${nodePathSegment(index, child)}`));
+            return;
+        }
+        nodes.push({
+            id: node.id,
+            kind: node.kind,
+            type: node.type,
+            path,
+            propKeys: Object.keys(node.props).sort(),
+            childCount: Object.values(node.slots).reduce((sum, children) => sum + children.length, 0),
+        });
+        for (const [slot, children] of Object.entries(node.slots)) {
+            children.forEach((child, index) => visit(child, `${path}/slot:${slot}/${nodePathSegment(index, child)}`));
+        }
+    }
+    template.children.forEach((child, index) => visit(child, nodePathSegment(index, child)));
+    return {
+        name: template.name,
+        props: template.props,
+        nodeCount: nodes.length,
+        nodes,
+    };
+}
+export function validateSceneContent(options) {
+    try {
+        const template = parseSceneTemplate(options.content);
+        const diagnostics = validateSceneTemplate(template, options);
+        const revision = createSceneRevision(options.content);
+        if (diagnostics.length > 0) {
+            return {
+                ok: false,
+                scene: options.scene,
+                revision,
+                error: 'Scene validation failed.',
+                diagnostics,
+                hint: 'Fix the listed diagnostics, then run scene validate again.',
+            };
+        }
+        return {
+            ok: true,
+            scene: options.scene,
+            revision,
+            canonicalContent: serializeSceneTemplate(template),
+            summary: inspectSceneTemplate(template),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            scene: options.scene,
+            error: 'Scene parse failed.',
+            diagnostics: [sceneSourceDiagnostic(options.content, message)],
+            hint: 'Fix the listed diagnostics, then run scene validate again.',
+        };
+    }
+}
+function sceneSourceDiagnostic(source, message) {
+    return {
+        path: '__scene__',
+        prop: 'source',
+        expected: 'valid Pixifact .scene source',
+        actual: message,
+        hint: 'Fix the .scene source syntax near the reported location.',
+        ...sourcePositionFromMessage(source, message),
+    };
+}
+function sourcePositionFromMessage(source, message) {
+    const match = message.match(/\boffset (\d+)\b/);
+    if (!match) {
+        return {};
+    }
+    const offset = Number(match[1]);
+    if (!Number.isInteger(offset) || offset < 0) {
+        return {};
+    }
+    const before = source.slice(0, offset);
+    const lines = before.split('\n');
+    return {
+        line: lines.length,
+        column: lines.at(-1).length + 1,
+    };
+}
+function validateSceneTemplate(template, context) {
+    return template.children.flatMap((child, index) => validateSceneNode(child, nodePathSegment(index, child), context));
+}
+function validateSceneNode(node, path, context) {
+    if (node.kind === 'slotOutlet') {
+        return [];
+    }
+    if (node.kind === 'pixi') {
+        return [
+            ...validatePixiNode(node, path, context.existingAssets),
+            ...node.children.flatMap((child, index) => validateSceneNode(child, `${path}/${nodePathSegment(index, child)}`, context)),
+        ];
+    }
+    return [
+        ...validateSceneInstanceNode(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) {
+    if (!isPixiSceneNodeType(node.type)) {
+        return [{
+                path,
+                prop: 'type',
+                expected: 'supported compiler Pixi node type',
+                actual: node.type,
+                hint: 'Use Container, Sprite, NineSliceSprite, TilingSprite, Text, BitmapText, HTMLText, or Graphics.',
+            }];
+    }
+    const diagnostics = [];
+    const knownProps = new Set([
+        ...pixiSceneTransformProps,
+        ...pixiSceneDisplayProps,
+        ...pixiSceneNodePropKeys(node.type),
+    ]);
+    for (const [prop, value] of Object.entries(node.props)) {
+        if (!knownProps.has(prop)) {
+            diagnostics.push({
+                path,
+                prop,
+                expected: `known ${node.type} prop`,
+                actual: 'unknown prop',
+                hint: unknownPixiPropHint(prop),
+            });
+            continue;
+        }
+        const schema = pixiSceneFieldSchema(prop);
+        if (schema && !sceneValueMatchesFieldType(value, schema.type, schema.options)) {
+            diagnostics.push({
+                path,
+                prop,
+                expected: schema.type === 'enum' ? `one of ${schema.options?.map((option) => JSON.stringify(option)).join(', ')}` : schema.type,
+                actual: sceneValueType(value),
+                hint: `Set ${node.type}.${prop} to ${fieldTypeDescription(schema.type)}.`,
+            });
+        }
+    }
+    const texture = node.props.texture;
+    if (typeof texture === 'string') {
+        const assetDiagnostic = validateTextureReference(path, texture, existingAssets);
+        if (assetDiagnostic) {
+            diagnostics.push(assetDiagnostic);
+        }
+    }
+    return diagnostics;
+}
+function validateSceneInstanceNode(node, path, context) {
+    let scene = node.scene;
+    try {
+        scene = context.normalizeSceneReference ? context.normalizeSceneReference(node.scene) : node.scene;
+    }
+    catch (error) {
+        return [{
+                path,
+                prop: 'scene',
+                expected: 'project-relative or relative .scene path',
+                actual: node.scene,
+                hint: error instanceof Error ? error.message : 'Use a .scene path.',
+            }];
+    }
+    const sceneInterface = context.sceneInterfaces?.[scene];
+    if (!sceneInterface) {
+        if (context.sceneInterfaces) {
+            return [{
+                    path,
+                    prop: 'scene',
+                    expected: 'known compiler Scene contract',
+                    actual: node.scene,
+                    hint: 'Ensure the referenced .scene file exists and has a readable paired script.',
+                }];
+        }
+        return [];
+    }
+    const diagnostics = [];
+    const allowedProps = new Set([
+        ...pixiSceneTransformProps,
+        ...pixiSceneDisplayProps,
+        ...Object.keys(sceneInterface.props),
+    ]);
+    for (const [prop, value] of Object.entries(node.props)) {
+        if (!allowedProps.has(prop)) {
+            diagnostics.push({
+                path,
+                prop,
+                expected: `public prop declared by ${scene}`,
+                actual: 'unknown prop',
+                hint: 'Expose the property with @prop on the child Scene script before setting it from a parent Scene.',
+            });
+            continue;
+        }
+        const schema = pixiSceneFieldSchema(prop);
+        const contract = sceneInterface.props[prop];
+        if (contract?.type === 'struct') {
+            diagnostics.push(...validateSceneInstanceStructProp(node, path, prop, value, contract));
+            continue;
+        }
+        const expectedType = contract?.type ?? schema?.type;
+        if (expectedType && !sceneValueMatchesContractType(value, expectedType, schema?.options)) {
+            diagnostics.push({
+                path,
+                prop,
+                expected: expectedType,
+                actual: sceneValueType(value),
+                hint: `Set ${node.type}.${prop} to ${fieldTypeDescription(expectedType)}.`,
+            });
+        }
+    }
+    for (const eventName of Object.keys(node.events)) {
+        if (!sceneInterface.events[eventName]) {
+            diagnostics.push({
+                path,
+                prop: `@${eventName}`,
+                expected: `public event declared by ${scene}`,
+                actual: 'unknown event',
+                hint: 'Expose the event with @event on the child Scene script before binding it from a parent Scene.',
+            });
+        }
+    }
+    for (const slot of Object.keys(node.slots)) {
+        if (!sceneInterface.slots[slot]) {
+            diagnostics.push({
+                path: `${path}/slot:${slot}`,
+                prop: 'slot',
+                expected: `public slot declared by ${scene}`,
+                actual: 'unknown slot',
+                hint: 'Expose the slot with @slot on the child Scene script before placing children into it.',
+            });
+        }
+    }
+    return diagnostics;
+}
+function validateSceneInstanceStructProp(node, path, prop, value, contract) {
+    if (!value || typeof value !== 'object') {
+        return [{
+                path,
+                prop,
+                expected: contract.struct,
+                actual: sceneValueType(value),
+                hint: `Set ${node.type}.${prop} fields using dot-path attributes such as ${prop}.x="0".`,
+            }];
+    }
+    const diagnostics = [];
+    for (const [field, fieldValue] of Object.entries(value)) {
+        const fieldContract = contract.fields[field];
+        if (!fieldContract) {
+            diagnostics.push({
+                path,
+                prop: `${prop}.${field}`,
+                expected: `field declared by ${contract.struct}`,
+                actual: 'unknown field',
+                hint: `Use one of ${Object.keys(contract.fields).map((name) => JSON.stringify(name)).join(', ')}.`,
+            });
+            continue;
+        }
+        if (!sceneValueMatchesContractType(fieldValue, fieldContract.type)) {
+            diagnostics.push({
+                path,
+                prop: `${prop}.${field}`,
+                expected: fieldContract.type,
+                actual: sceneValueType(fieldValue),
+                hint: `Set ${node.type}.${prop}.${field} to ${fieldTypeDescription(fieldContract.type)}.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+function validateTextureReference(path, texture, existingAssets) {
+    if (!isProjectRelativeAssetPath(texture)) {
+        return {
+            path,
+            prop: 'texture',
+            expected: 'project-relative asset path inside project root',
+            actual: texture,
+            hint: 'Use a project-relative path such as "assets/play.png".',
+        };
+    }
+    if (existingAssets && !existingAssets.has(normalizeAssetPath(texture))) {
+        return {
+            path,
+            prop: 'texture',
+            expected: 'existing project asset',
+            actual: texture,
+            hint: 'Use an asset path that exists in the project before validating the scene.',
+        };
+    }
+    return undefined;
+}
+function isProjectRelativeAssetPath(value) {
+    if (value.trim() === ''
+        || value.startsWith('/')
+        || value.startsWith('./')
+        || value.includes('\\')
+        || /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value)) {
+        return false;
+    }
+    return !value.split('/').includes('..');
+}
+function normalizeAssetPath(value) {
+    return value.split('/').filter((part) => part !== '' && part !== '.').join('/');
+}
+function sceneValueMatchesFieldType(value, type, options) {
+    if (type === 'enum') {
+        return options?.includes(value) ?? false;
+    }
+    return sceneValueMatchesContractType(value, type);
+}
+function sceneValueMatchesContractType(value, type, options) {
+    if (type === 'enum') {
+        return options?.includes(value) ?? false;
+    }
+    if (type === 'number' || type === 'color') {
+        return typeof value === 'number';
+    }
+    if (type === 'boolean') {
+        return typeof value === 'boolean';
+    }
+    return typeof value === 'string';
+}
+function sceneValueType(value) {
+    if (value && typeof value === 'object') {
+        return 'object';
+    }
+    return typeof value;
+}
+function fieldTypeDescription(type) {
+    if (type === 'number') {
+        return 'a numeric value';
+    }
+    if (type === 'color') {
+        return 'a color value such as "#ffffff"';
+    }
+    if (type === 'enum') {
+        return 'one of the allowed values';
+    }
+    return `a ${type} value`;
+}
+function unknownPixiPropHint(prop) {
+    if (prop === 'textrue') {
+        return 'Use "texture" for Sprite image assets.';
+    }
+    return 'Use the editor inspector or scene inspect command to list supported props for this node type.';
+}
+function nodePathSegment(index, node) {
+    if (node.kind === 'slotOutlet') {
+        return `${index}:slot:${node.name}`;
+    }
+    return `${index}:${node.id ?? node.kind}`;
+}

package/dist/compiler/scriptInterfaceExtractor.d.ts

@@ -0,0 +1,6 @@
+import type { SceneScriptInterface } from './spec.js';
+export interface ExtractSceneScriptInterfaceOptions {
+    scene: string;
+}
+export declare function extractSceneScriptInterface(source: string, fileName: string | undefined, options: ExtractSceneScriptInterfaceOptions): SceneScriptInterface;
+export declare function emitSceneScriptInterfaceDescriptor(source: string, fileName: string | undefined, options: ExtractSceneScriptInterfaceOptions): string;