pixifact 0.1.3

package/dist/compiler/scriptInterfaceExtractor.js

@@ -0,0 +1,258 @@
+import ts from 'typescript';
+export function extractSceneScriptInterface(source, fileName = 'scene-script.ts', options) {
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const structClasses = collectStructClasses(sourceFile);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isClassDeclaration(statement)) {
+            continue;
+        }
+        if (!hasSceneDecorator(statement)) {
+            continue;
+        }
+        const className = statement.name?.text;
+        if (!className) {
+            throw new Error('Scene script class is missing a name.');
+        }
+        const props = {};
+        const events = {};
+        const slots = {};
+        const parts = {};
+        for (const member of statement.members) {
+            const name = memberName(member.name);
+            if (!name) {
+                continue;
+            }
+            const prop = memberDecoratorOptions(member, 'prop');
+            if (prop) {
+                props[name] = propContract(prop, structClasses);
+            }
+            const event = memberDecoratorOptions(member, 'event');
+            if (event) {
+                events[typeof event.name === 'string' ? event.name : name] = { type: 'action' };
+            }
+            const slot = memberDecoratorOptions(member, 'slot');
+            if (slot) {
+                slots[typeof slot.name === 'string' ? slot.name : name] = {};
+            }
+            const part = memberDecoratorOptions(member, 'part');
+            if (part) {
+                parts[name] = typeof part.id === 'string' ? part.id : name;
+            }
+        }
+        return {
+            scene: options.scene,
+            className,
+            interface: {
+                props,
+                events,
+                slots,
+            },
+            parts,
+        };
+    }
+    throw new Error('No @scene decorator found.');
+}
+export function emitSceneScriptInterfaceDescriptor(source, fileName = 'scene-script.ts', options) {
+    return `${JSON.stringify(extractSceneScriptInterface(source, fileName, options), null, 2)}\n`;
+}
+function hasSceneDecorator(node) {
+    const decorator = decorators(node).find((item) => decoratorName(item) === 'scene');
+    if (!decorator) {
+        return false;
+    }
+    const args = decoratorArguments(decorator);
+    if (args.length !== 0) {
+        throw new Error('@scene does not accept arguments. Pair scripts by colocating a same-basename .ts file next to the .scene file.');
+    }
+    return true;
+}
+function memberDecoratorOptions(member, name) {
+    const decorator = decorators(member).find((item) => decoratorName(item) === name);
+    if (!decorator) {
+        return undefined;
+    }
+    const args = decoratorArguments(decorator);
+    if (args.length === 0) {
+        return {};
+    }
+    if (args.length !== 1) {
+        throw new Error(`@${name} accepts at most one argument.`);
+    }
+    return objectLiteralValue(args[0], `@${name} argument`);
+}
+function decorators(node) {
+    return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : [];
+}
+function decoratorName(decorator) {
+    const expression = decorator.expression;
+    if (ts.isIdentifier(expression)) {
+        return expression.text;
+    }
+    if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+        return expression.expression.text;
+    }
+    return undefined;
+}
+function decoratorArguments(decorator) {
+    const expression = decorator.expression;
+    return ts.isCallExpression(expression) ? [...expression.arguments] : [];
+}
+function memberName(name) {
+    if (!name) {
+        return undefined;
+    }
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}
+function collectStructClasses(sourceFile) {
+    const classes = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isClassDeclaration(statement) || !statement.name) {
+            continue;
+        }
+        classes.set(statement.name.text, {
+            exported: statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false,
+            node: statement,
+        });
+    }
+    return classes;
+}
+function structFields(node) {
+    const fields = {};
+    for (const member of node.members) {
+        if (!ts.isPropertyDeclaration(member)) {
+            continue;
+        }
+        const name = memberName(member.name);
+        if (!name) {
+            throw new Error(`Struct prop type ${node.name?.text ?? 'anonymous'} only supports literal field names.`);
+        }
+        if (!member.initializer) {
+            throw new Error(`Struct prop type ${node.name?.text ?? 'anonymous'} field ${name} requires a primitive initializer.`);
+        }
+        const value = literalValue(member.initializer, `struct ${node.name?.text ?? 'anonymous'}.${name}`);
+        if (!isSceneTemplateScalarValue(value)) {
+            throw new Error(`Struct prop type ${node.name?.text ?? 'anonymous'} field ${name} requires a primitive initializer.`);
+        }
+        fields[name] = {
+            type: sceneTemplateScalarType(value),
+            default: value,
+        };
+    }
+    return fields;
+}
+function propContract(prop, structClasses) {
+    const type = prop.type;
+    const defaultValue = prop.default;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        throw new Error('@prop type must be String, Number, Boolean, or a struct class.');
+    }
+    if (!isIdentifierValue(type)) {
+        throw new Error('@prop type must be String, Number, Boolean, or a struct class.');
+    }
+    const primitiveType = primitiveConstructorType(type.text);
+    if (primitiveType) {
+        if (defaultValue !== undefined && (!isSceneTemplateScalarValue(defaultValue) || sceneTemplateScalarType(defaultValue) !== primitiveType)) {
+            throw new Error(`@prop default for ${type.text} must be a ${primitiveType} literal.`);
+        }
+        return {
+            type: primitiveType,
+            ...(defaultValue !== undefined ? { default: defaultValue } : {}),
+        };
+    }
+    const structClass = structClasses.get(type.text);
+    if (!structClass) {
+        throw new Error(`Struct prop type ${type.text} was not found.`);
+    }
+    if (!structClass.exported) {
+        throw new Error(`Struct prop type ${type.text} must be exported.`);
+    }
+    if (defaultValue !== undefined) {
+        throw new Error('@prop default is only supported for primitive props.');
+    }
+    const struct = structContractInfo(structClass.node);
+    if (struct.hasRequiredConstructorParameters) {
+        throw new Error(`Struct prop type ${type.text} must be constructable with no required parameters.`);
+    }
+    return {
+        type: 'struct',
+        struct: type.text,
+        fields: struct.fields,
+    };
+}
+function structContractInfo(node) {
+    return {
+        fields: structFields(node),
+        hasRequiredConstructorParameters: node.members.some((member) => ts.isConstructorDeclaration(member) && member.parameters.some((parameter) => !parameter.questionToken && !parameter.initializer)),
+    };
+}
+function primitiveConstructorType(name) {
+    if (name === 'String') {
+        return 'string';
+    }
+    if (name === 'Number') {
+        return 'number';
+    }
+    if (name === 'Boolean') {
+        return 'boolean';
+    }
+    return undefined;
+}
+function isIdentifierValue(value) {
+    return ts.isIdentifier(value);
+}
+function isSceneTemplateScalarValue(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+function sceneTemplateScalarType(value) {
+    if (typeof value === 'string') {
+        return 'string';
+    }
+    if (typeof value === 'number') {
+        return 'number';
+    }
+    return 'boolean';
+}
+function objectLiteralValue(expression, label) {
+    if (!ts.isObjectLiteralExpression(expression)) {
+        throw new Error(`${label} must be an object literal.`);
+    }
+    const result = {};
+    for (const property of expression.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            throw new Error(`${label} only supports property assignments.`);
+        }
+        const name = memberName(property.name);
+        if (!name) {
+            throw new Error(`${label} only supports literal property names.`);
+        }
+        result[name] = decoratorValue(property.initializer, `${label}.${name}`);
+    }
+    return result;
+}
+function decoratorValue(expression, label) {
+    if (ts.isIdentifier(expression)) {
+        return expression;
+    }
+    return literalValue(expression, label);
+}
+function literalValue(expression, label) {
+    if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
+        return expression.text;
+    }
+    if (expression.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (expression.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    if (ts.isNumericLiteral(expression)) {
+        return Number(expression.text);
+    }
+    if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(expression.operand)) {
+        return -Number(expression.operand.text);
+    }
+    throw new Error(`${label} must be a string, number, or boolean literal.`);
+}

package/dist/compiler/slotRuntime.d.ts

@@ -0,0 +1,3 @@
+import type { Container } from 'pixi.js';
+export declare function registerSlot(target: Container, name: string, host: Container): void;
+export declare function mount<T extends Container>(target: Container, child: T, slot?: string): T;

package/dist/compiler/slotRuntime.js

@@ -0,0 +1,17 @@
+const sceneSlots = new WeakMap();
+export function registerSlot(target, name, host) {
+    let slots = sceneSlots.get(target);
+    if (!slots) {
+        slots = new Map();
+        sceneSlots.set(target, slots);
+    }
+    slots.set(name, host);
+}
+export function mount(target, child, slot = 'default') {
+    const host = sceneSlots.get(target)?.get(slot);
+    if (!host) {
+        throw new Error(`Unknown slot "${slot}".`);
+    }
+    host.addChild(child);
+    return child;
+}

package/dist/compiler/spec.d.ts

@@ -0,0 +1,95 @@
+export type SceneTemplatePrimitiveType = 'Container' | 'Sprite' | 'Text' | 'Graphics' | 'BitmapText' | 'HTMLText' | 'Mesh' | 'NineSliceSprite' | 'TilingSprite' | 'DOMContainer';
+export type SceneTemplateScalarValue = string | number | boolean;
+export type SceneTemplateStructValue = Record<string, SceneTemplateScalarValue>;
+export type SceneTemplateValue = SceneTemplateScalarValue | SceneTemplateStructValue;
+export type SceneTemplatePrimitivePropType = 'string' | 'number' | 'boolean';
+export interface SceneTemplatePrimitivePropContract {
+    type: SceneTemplatePrimitivePropType;
+    default?: SceneTemplateScalarValue;
+}
+export interface SceneTemplateStructFieldContract {
+    type: SceneTemplatePrimitivePropType;
+    default: SceneTemplateScalarValue;
+}
+export interface SceneTemplateStructPropContract {
+    type: 'struct';
+    struct: string;
+    fields: Record<string, SceneTemplateStructFieldContract>;
+}
+export type SceneTemplatePropContract = SceneTemplatePrimitivePropContract | SceneTemplateStructPropContract;
+export interface SceneTemplateEventContract {
+    type: 'action';
+}
+export interface SceneTemplateSlotContract {
+}
+export interface SceneTemplateInterface {
+    props: Record<string, SceneTemplatePropContract>;
+    events: Record<string, SceneTemplateEventContract>;
+    slots: Record<string, SceneTemplateSlotContract>;
+}
+export interface SceneTemplate {
+    version: 2;
+    name: string;
+    props: Record<string, SceneTemplateValue>;
+    interface: SceneTemplateInterface;
+    children: SceneTemplateNode[];
+}
+export type SceneTemplateNode = PixiTemplateNode | SceneInstanceTemplateNode | SlotOutletTemplateNode;
+export interface PixiTemplateNode {
+    kind: 'pixi';
+    type: SceneTemplatePrimitiveType;
+    id?: string;
+    props: Record<string, SceneTemplateValue>;
+    children: SceneTemplateNode[];
+}
+export interface SceneInstanceTemplateNode {
+    kind: 'sceneInstance';
+    type: string;
+    id?: string;
+    scene: string;
+    props: Record<string, SceneTemplateValue>;
+    events: Record<string, string>;
+    slots: Record<string, SceneTemplateNode[]>;
+}
+export interface SlotOutletTemplateNode {
+    kind: 'slotOutlet';
+    name: string;
+}
+export interface SceneTemplateScriptImport {
+    exportName: string;
+    localName: string;
+    source: string;
+}
+export interface CompileSceneTemplateOptions {
+    functionName?: string;
+    actionsParameter?: string;
+    registrationPath?: string;
+    scriptImport?: SceneTemplateScriptImport;
+    sceneImports?: SceneTemplateScriptImport[];
+    sceneClassAliases?: Record<string, string>;
+    sceneInterfaces?: Record<string, SceneTemplateInterface>;
+    textureImports?: Record<string, string>;
+}
+export interface SceneScriptInterface {
+    scene: string;
+    className: string;
+    interface: SceneTemplateInterface;
+    parts: Record<string, string>;
+}
+export type SceneClassDecorator = ClassDecorator;
+export type SceneMemberDecorator = PropertyDecorator & MethodDecorator;
+export type SceneStructConstructor = new () => object;
+export type ScenePropType = StringConstructor | NumberConstructor | BooleanConstructor | SceneStructConstructor;
+export interface ScenePropDecoratorOptions {
+    type: ScenePropType;
+    default?: SceneTemplateValue;
+}
+export interface SceneEventDecoratorOptions {
+    name?: string;
+}
+export interface SceneSlotDecoratorOptions {
+    name?: string;
+}
+export interface ScenePartDecoratorOptions {
+    id?: string;
+}

package/dist/compiler/spec.js

@@ -0,0 +1 @@
+export {};

package/dist/compiler/templateParser.d.ts

@@ -0,0 +1,2 @@
+import type { SceneTemplate } from './spec.js';
+export declare function parseSceneTemplate(source: string): SceneTemplate;

package/dist/compiler/templateParser.js

@@ -0,0 +1,302 @@
+import { pixiSceneFieldSchema } from './pixiNodeSchema.js';
+const pixiTypes = new Set([
+    'Container',
+    'Sprite',
+    'Text',
+    'Graphics',
+    'BitmapText',
+    'HTMLText',
+    'Mesh',
+    'NineSliceSprite',
+    'TilingSprite',
+    'DOMContainer',
+]);
+export function parseSceneTemplate(source) {
+    const root = new TemplateXmlParser(source).parse();
+    if (root.name !== 'Scene') {
+        throw new Error(`Expected <Scene> root, received <${root.name}>.`);
+    }
+    const name = root.attributes.name;
+    if (!name) {
+        throw new Error('Scene template is missing name.');
+    }
+    if (root.attributes.class !== undefined) {
+        throw new Error('Scene class is inferred from the paired script @scene class; remove the class attribute.');
+    }
+    if (root.attributes.script !== undefined) {
+        throw new Error('Scene script binding is inferred from the colocated TypeScript file.');
+    }
+    const children = root.children.map(parseTemplateNode);
+    assertUniqueIds(name, children);
+    return {
+        version: 2,
+        name,
+        props: parseProps(root, ['name']),
+        interface: emptyInterface(),
+        children,
+    };
+}
+function emptyInterface() {
+    return {
+        props: {},
+        events: {},
+        slots: {},
+    };
+}
+function parseTemplateNode(element) {
+    if (element.name === 'slot') {
+        const node = {
+            kind: 'slotOutlet',
+            name: element.attributes.name || 'default',
+        };
+        return node;
+    }
+    if (pixiTypes.has(element.name)) {
+        const node = {
+            kind: 'pixi',
+            type: element.name,
+            props: parseProps(element, ['id', 'slot']),
+            children: element.children.map(parseTemplateNode),
+            ...(element.attributes.id ? { id: element.attributes.id } : {}),
+        };
+        return node;
+    }
+    if (element.attributes.scene) {
+        const slots = {};
+        for (const child of element.children) {
+            const slot = child.attributes.slot || 'default';
+            slots[slot] = slots[slot] ?? [];
+            slots[slot].push(parseTemplateNode(removeAttribute(child, 'slot')));
+        }
+        const node = {
+            kind: 'sceneInstance',
+            type: element.name,
+            scene: element.attributes.scene,
+            props: parseProps(element, ['id', 'scene', 'slot'], isEventAttribute),
+            events: parseEvents(element),
+            slots,
+            ...(element.attributes.id ? { id: element.attributes.id } : {}),
+        };
+        return node;
+    }
+    throw new Error(`Unsupported template tag <${element.name}>.`);
+}
+function parseProps(element, omitted, shouldOmit = () => 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 path = name.split('.');
+        if (path.length === 1) {
+            if (props[name] && typeof props[name] === 'object') {
+                throw new Error(`Prop "${name}" cannot be both scalar and structured.`);
+            }
+            props[name] = parsed;
+            continue;
+        }
+        const [root, field, ...rest] = path;
+        if (!root || !field || rest.length > 0) {
+            throw new Error(`Unsupported structured prop path "${name}".`);
+        }
+        if (props[root] !== undefined && typeof props[root] !== 'object') {
+            throw new Error(`Prop "${root}" cannot be both scalar and structured.`);
+        }
+        if (typeof parsed === 'object') {
+            throw new Error(`Structured prop field "${name}" cannot contain an object value.`);
+        }
+        const objectValue = (props[root] ?? {});
+        objectValue[field] = parsed;
+        props[root] = objectValue;
+    }
+    return props;
+}
+function parseEvents(element) {
+    const events = {};
+    for (const [name, value] of Object.entries(element.attributes)) {
+        const event = eventName(name);
+        if (event) {
+            events[event] = value;
+        }
+    }
+    return events;
+}
+function eventName(name) {
+    if (name.startsWith('@')) {
+        return name.slice(1);
+    }
+    if (name.startsWith('on-')) {
+        return name.slice(3);
+    }
+    if (name.startsWith('on:')) {
+        return name.slice(3);
+    }
+    return undefined;
+}
+function isEventAttribute(name) {
+    return eventName(name) !== undefined;
+}
+function parseAttributeValue(name, value) {
+    if (pixiSceneFieldSchema(name)?.type === 'string') {
+        return value;
+    }
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    if (/^#[0-9a-fA-F]{6}$/.test(value))
+        return Number.parseInt(value.slice(1), 16);
+    return value;
+}
+function removeAttribute(element, name) {
+    const attributes = { ...element.attributes };
+    delete attributes[name];
+    return {
+        ...element,
+        attributes,
+    };
+}
+function assertUniqueIds(sceneName, children) {
+    const seen = new Set();
+    function visit(node) {
+        if (node.kind === 'slotOutlet') {
+            return;
+        }
+        if (node.id) {
+            if (seen.has(node.id)) {
+                throw new Error(`Scene "${sceneName}" has duplicate id "${node.id}".`);
+            }
+            seen.add(node.id);
+        }
+        if (node.kind === 'pixi') {
+            for (const child of node.children) {
+                visit(child);
+            }
+            return;
+        }
+        for (const slottedChildren of Object.values(node.slots)) {
+            for (const child of slottedChildren) {
+                visit(child);
+            }
+        }
+    }
+    for (const child of children) {
+        visit(child);
+    }
+}
+class TemplateXmlParser {
+    source;
+    #index = 0;
+    constructor(source) {
+        this.source = source;
+    }
+    parse() {
+        this.#skipWhitespace();
+        const element = this.#parseElement();
+        this.#skipWhitespace();
+        if (this.#index !== this.source.length) {
+            throw new Error(`Unexpected content after <${element.name}>.`);
+        }
+        return element;
+    }
+    #parseElement() {
+        this.#consume('<');
+        if (this.#peek('/')) {
+            throw new Error('Unexpected closing tag.');
+        }
+        const name = this.#readName();
+        const attributes = {};
+        while (true) {
+            this.#skipWhitespace();
+            if (this.#consumeIf('/>')) {
+                return { name, attributes, children: [] };
+            }
+            if (this.#consumeIf('>')) {
+                break;
+            }
+            const attributeName = this.#readName();
+            this.#skipWhitespace();
+            this.#consume('=');
+            this.#skipWhitespace();
+            attributes[attributeName] = this.#readQuotedValue();
+        }
+        const children = [];
+        while (true) {
+            this.#skipWhitespace();
+            if (this.#consumeIf(`</${name}>`)) {
+                return { name, attributes, children };
+            }
+            if (this.#peek('<!--')) {
+                this.#skipComment();
+                continue;
+            }
+            if (this.#peek('<')) {
+                children.push(this.#parseElement());
+                continue;
+            }
+            throw new Error(`Unexpected text inside <${name}>.`);
+        }
+    }
+    #readName() {
+        const start = this.#index;
+        while (this.#index < this.source.length && /[A-Za-z0-9_:@.-]/.test(this.source[this.#index])) {
+            this.#index += 1;
+        }
+        if (start === this.#index) {
+            throw new Error(`Expected name at offset ${this.#index}.`);
+        }
+        return this.source.slice(start, this.#index);
+    }
+    #readQuotedValue() {
+        const quote = this.source[this.#index];
+        if (quote !== '"' && quote !== "'") {
+            throw new Error(`Expected quoted value at offset ${this.#index}.`);
+        }
+        this.#index += 1;
+        const start = this.#index;
+        while (this.#index < this.source.length && this.source[this.#index] !== quote) {
+            this.#index += 1;
+        }
+        const value = this.source.slice(start, this.#index);
+        this.#consume(quote);
+        return decodeEntities(value);
+    }
+    #skipWhitespace() {
+        while (this.#index < this.source.length && /\s/.test(this.source[this.#index])) {
+            this.#index += 1;
+        }
+    }
+    #skipComment() {
+        const end = this.source.indexOf('-->', this.#index + 4);
+        if (end === -1) {
+            throw new Error('Unterminated comment.');
+        }
+        this.#index = end + 3;
+    }
+    #consume(value) {
+        if (!this.#consumeIf(value)) {
+            throw new Error(`Expected "${value}" at offset ${this.#index}.`);
+        }
+    }
+    #consumeIf(value) {
+        if (!this.source.startsWith(value, this.#index)) {
+            return false;
+        }
+        this.#index += value.length;
+        return true;
+    }
+    #peek(value) {
+        return this.source.startsWith(value, this.#index);
+    }
+}
+function decodeEntities(value) {
+    return value
+        .replaceAll('&quot;', '"')
+        .replaceAll('&apos;', "'")
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&amp;', '&');
+}

package/dist/compiler/templateSerializer.d.ts

@@ -0,0 +1,2 @@
+import type { SceneTemplate } from './spec.js';
+export declare function serializeSceneTemplate(template: SceneTemplate): string;