pixifact 0.1.3

package/README.md

@@ -0,0 +1,44 @@
+# Pixifact
+
+Pixifact is a Bun-first framework for AI-editable 2D game UI, HUDs, menus, and lightweight scenes on top of PixiJS v8.
+
+Use `pixifact` for runtime APIs, Scene instantiation, compiler APIs, and generated Scene runtime support.
+
+## Install
+
+```bash
+bun add pixifact pixi.js
+```
+
+## Usage
+
+```ts
+import { Application } from 'pixifact/runtime';
+import { scene, container, text } from 'pixifact/scene';
+```
+
+Compiler Scene projects usually also install the CLI:
+
+```bash
+bun add -d pixifact-cli
+```
+
+Then validate and compile `.scene` files:
+
+```bash
+pixifact scene validate --project-root . --all
+pixifact compile-scenes --project-root .
+```
+
+## Scene Workflow
+
+Pixifact treats project-relative `.scene` files as the source of truth. External agents edit `.scene` source directly, then run validation and compilation.
+
+Generated files such as `.pixifact/generated/**` are build artifacts and should not be edited by hand.
+
+## Requirements
+
+- Bun
+- PixiJS v8
+
+The desktop editor is distributed separately from the npm runtime package.

package/dist/authoring/ActionRegistry.d.ts

@@ -0,0 +1,10 @@
+export interface ActionSpec {
+    key: string;
+    label?: string;
+    description?: string;
+    source?: 'manual' | 'agent' | 'code';
+}
+export declare function actionExists(actions: readonly ActionSpec[] | undefined, key: string): boolean;
+export declare function upsertAction(actions: ActionSpec[], action: ActionSpec): ActionSpec;
+export declare function createRuntimeActions(actions: readonly ActionSpec[] | undefined, handler?: (action: ActionSpec, args: unknown[]) => void): Record<string, (...args: unknown[]) => void>;
+export declare function summarizeActionsForAgent(actions: readonly ActionSpec[] | undefined): string;

package/dist/authoring/ActionRegistry.js

@@ -0,0 +1,26 @@
+export function actionExists(actions, key) {
+    return (actions ?? []).some((action) => action.key === key);
+}
+export function upsertAction(actions, action) {
+    const existing = actions.find((item) => item.key === action.key);
+    if (existing) {
+        Object.assign(existing, action);
+        return existing;
+    }
+    actions.push(action);
+    return action;
+}
+export function createRuntimeActions(actions, handler) {
+    const runtimeActions = {};
+    for (const action of actions ?? []) {
+        runtimeActions[action.key] = (...args) => {
+            handler?.(action, args);
+        };
+    }
+    return runtimeActions;
+}
+export function summarizeActionsForAgent(actions) {
+    return (actions ?? [])
+        .map((action) => `- ${action.key}${action.label ? ` (${action.label})` : ''}${action.description ? `: ${action.description}` : ''}`)
+        .join('\n');
+}

package/dist/authoring/ComponentPalette.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentSchema } from "../runtime/index.js";
+import type { ComponentSpec, SceneSpec } from "../scene/index.js";
+export interface PaletteComponentItem {
+    type: string;
+    displayName: string;
+    category: string;
+    description?: string;
+    disabledReason?: string;
+    schema: ComponentSchema;
+}
+export interface ComponentPaletteOptions {
+    scene?: SceneSpec;
+    node?: string;
+}
+export declare function listPaletteComponents(options?: ComponentPaletteOptions): PaletteComponentItem[];
+export declare function createComponentSpecFromSchema(schemaOrType: ComponentSchema | string, id?: string): ComponentSpec;

package/dist/authoring/ComponentPalette.js

@@ -0,0 +1,50 @@
+import { ComponentRegistry } from "../runtime/index.js";
+import { findNode } from "../commands/utils.js";
+function componentIdFromType(type) {
+    const raw = type.split('.').at(-1) ?? type;
+    return raw.charAt(0).toLowerCase() + raw.slice(1);
+}
+function disabledReason(schema, options) {
+    if (!schema.disallowMultiple || !options.scene || !options.node) {
+        return undefined;
+    }
+    const node = findNode(options.scene, options.node)?.node;
+    if (!node) {
+        return undefined;
+    }
+    return (node.components ?? []).some((component) => component.type === schema.type)
+        ? `${schema.displayName ?? schema.type} already exists on this node.`
+        : undefined;
+}
+export function listPaletteComponents(options = {}) {
+    return ComponentRegistry.list()
+        .filter((schema) => schema.category !== 'UI/Graphic')
+        .map((schema) => ({
+        type: schema.type,
+        displayName: schema.displayName ?? schema.type,
+        category: schema.category ?? 'Other',
+        description: schema.description,
+        disabledReason: disabledReason(schema, options),
+        schema,
+    }))
+        .sort((a, b) => a.category.localeCompare(b.category) || a.displayName.localeCompare(b.displayName));
+}
+export function createComponentSpecFromSchema(schemaOrType, id) {
+    const schema = typeof schemaOrType === 'string'
+        ? ComponentRegistry.get(schemaOrType)
+        : schemaOrType;
+    if (!schema) {
+        throw new Error(`Unknown component type "${schemaOrType}".`);
+    }
+    const props = {};
+    for (const prop of schema.props) {
+        if (prop.default !== undefined && prop.serialize !== false) {
+            props[prop.key] = structuredClone(prop.default);
+        }
+    }
+    return {
+        id: id ?? componentIdFromType(schema.type),
+        type: schema.type,
+        props,
+    };
+}

package/dist/authoring/DesignToken.d.ts

@@ -0,0 +1,16 @@
+export interface DesignTokenSpec {
+    colors?: Record<string, number>;
+    spacing?: Record<string, number>;
+    radius?: Record<string, number>;
+    typography?: Record<string, {
+        fontFamily: string;
+        fontSize: number;
+        fontWeight?: string;
+    }>;
+}
+export interface DesignTokenWarning {
+    target: string;
+    value: unknown;
+    message: string;
+}
+export declare function validateDesignTokenValue(tokens: DesignTokenSpec | undefined, target: string, prop: string, value: unknown): DesignTokenWarning | undefined;

package/dist/authoring/DesignToken.js

@@ -0,0 +1,33 @@
+function hasNumberValue(record, value) {
+    return typeof value === 'number' && !!record && Object.values(record).includes(value);
+}
+export function validateDesignTokenValue(tokens, target, prop, value) {
+    if (!tokens) {
+        return undefined;
+    }
+    if ((prop === 'color' || prop.toLowerCase().includes('color')) && !hasNumberValue(tokens.colors, value)) {
+        return {
+            target,
+            value,
+            message: `${target} uses color ${String(value)} outside design tokens.`,
+        };
+    }
+    if ((prop === 'radius' || prop.toLowerCase().includes('radius')) && !hasNumberValue(tokens.radius, value)) {
+        return {
+            target,
+            value,
+            message: `${target} uses radius ${String(value)} outside design tokens.`,
+        };
+    }
+    if ((prop === 'x' || prop === 'y' || prop === 'width' || prop === 'height') && typeof value === 'number' && tokens.spacing) {
+        const spacingValues = Object.values(tokens.spacing);
+        if (spacingValues.length > 0 && !spacingValues.some((spacing) => value % spacing === 0)) {
+            return {
+                target,
+                value,
+                message: `${target} uses ${prop}=${value}, which does not align to spacing tokens.`,
+            };
+        }
+    }
+    return undefined;
+}

package/dist/authoring/DiffModel.d.ts

@@ -0,0 +1,10 @@
+import type { SceneCommand } from "../commands/index.js";
+import type { SceneSpec } from "../scene/index.js";
+export interface DiffEntry {
+    target: string;
+    before: unknown;
+    after: unknown;
+    command: SceneCommand;
+}
+export declare function diffCommand(scene: SceneSpec, command: SceneCommand): DiffEntry[];
+export declare function diffCommands(scene: SceneSpec, commands: SceneCommand[]): DiffEntry[];

package/dist/authoring/DiffModel.js

@@ -0,0 +1,104 @@
+import { findComponent, findNode } from "../commands/utils.js";
+function formatTarget(parts) {
+    return parts.filter(Boolean).join('.');
+}
+export function diffCommand(scene, command) {
+    switch (command.op) {
+        case 'setNodeProp': {
+            const node = findNode(scene, command.node)?.node;
+            return [{
+                    target: formatTarget([command.node, command.prop]),
+                    before: node?.[command.prop],
+                    after: command.value,
+                    command,
+                }];
+        }
+        case 'setTransform': {
+            const node = findNode(scene, command.node)?.node;
+            return Object.entries(command.values).map(([key, value]) => ({
+                target: formatTarget([command.node, 'transform', key]),
+                before: node?.transform?.[key],
+                after: value,
+                command,
+            }));
+        }
+        case 'setNodeData': {
+            const node = findNode(scene, command.node)?.node;
+            const data = node && node.kind === command.field
+                ? node[command.field]
+                : undefined;
+            return [{
+                    target: formatTarget([command.node, command.field, command.prop]),
+                    before: data?.[command.prop],
+                    after: command.value,
+                    command,
+                }];
+        }
+        case 'setComponentProp': {
+            const node = findNode(scene, command.node)?.node;
+            const component = node ? findComponent(node, command.component)?.component : undefined;
+            return [{
+                    target: formatTarget([command.node, command.component, command.prop]),
+                    before: component?.props?.[command.prop],
+                    after: command.value,
+                    command,
+                }];
+        }
+        case 'addComponent':
+            return [{
+                    target: formatTarget([command.node, command.component.id ?? command.component.type]),
+                    before: undefined,
+                    after: command.component,
+                    command,
+                }];
+        case 'removeComponent': {
+            const node = findNode(scene, command.node)?.node;
+            const component = node ? findComponent(node, command.component)?.component : undefined;
+            return [{
+                    target: formatTarget([command.node, command.component]),
+                    before: component,
+                    after: undefined,
+                    command,
+                }];
+        }
+        case 'createNode':
+            return [{
+                    target: formatTarget([command.parent ?? 'root', command.node.id ?? command.node.key ?? command.node.name]),
+                    before: undefined,
+                    after: command.node,
+                    command,
+                }];
+        case 'deleteNode': {
+            const node = findNode(scene, command.node)?.node;
+            return [{
+                    target: command.node,
+                    before: node,
+                    after: undefined,
+                    command,
+                }];
+        }
+        case 'reparentNode': {
+            const node = findNode(scene, command.node);
+            return [{
+                    target: formatTarget([command.node, 'parent']),
+                    before: node?.parent?.key ?? node?.parent?.id ?? node?.parent?.name,
+                    after: command.parent ?? 'root',
+                    command,
+                }];
+        }
+        case 'reorderNode': {
+            const node = findNode(scene, command.node);
+            return [{
+                    target: formatTarget([command.node, 'index']),
+                    before: node?.index,
+                    after: command.index,
+                    command,
+                }];
+        }
+        case 'batch':
+            return diffCommands(scene, command.commands);
+    }
+}
+export function diffCommands(scene, commands) {
+    return commands.flatMap((command) => diffCommand(scene, command));
+}

package/dist/authoring/InspectorModel.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentSchema, PropSchema } from "../runtime/index.js";
+import type { NodeSpec, SceneSpec } from "../scene/index.js";
+export interface InspectorFieldModel {
+    key: string;
+    label: string;
+    type: string;
+    value: unknown;
+    schema?: PropSchema;
+}
+export interface InspectorComponentModel {
+    id?: string;
+    type: string;
+    displayName: string;
+    schema?: ComponentSchema;
+    fields: InspectorFieldModel[];
+}
+export interface InspectorNodeModel {
+    id?: string;
+    key?: string;
+    role?: string;
+    name?: string;
+    kind: NodeSpec['kind'];
+    transform: InspectorFieldModel[];
+    display: InspectorComponentModel[];
+    components: InspectorComponentModel[];
+}
+export declare function buildInspectorModel(scene: SceneSpec, nodeLocator: string): InspectorNodeModel | undefined;

package/dist/authoring/InspectorModel.js

@@ -0,0 +1,139 @@
+import { ComponentRegistry } from "../runtime/index.js";
+import { findNode } from "../commands/utils.js";
+const transformFields = [
+    'x',
+    'y',
+    'width',
+    'height',
+    'anchorX',
+    'anchorY',
+    'scaleX',
+    'scaleY',
+    'rotation',
+];
+function buildTransformFields(node) {
+    const transform = node.transform ?? {};
+    return transformFields.map((key) => ({
+        key,
+        label: key,
+        type: 'number',
+        value: transform[key],
+    }));
+}
+function field(key, type, value, schema) {
+    return {
+        key,
+        label: key,
+        type,
+        value,
+        schema,
+    };
+}
+function enumSchema(key, options) {
+    return {
+        key,
+        type: 'enum',
+        options,
+    };
+}
+function buildDisplayModel(node) {
+    switch (node.kind) {
+        case 'image':
+            return [{
+                    type: 'node.image',
+                    displayName: 'Image',
+                    fields: [
+                        field('mode', 'enum', node.image?.mode, enumSchema('mode', ['sprite', 'nineSlice'])),
+                        field('src', 'string', node.image?.src),
+                        field('tint', 'color', node.image?.tint),
+                        field('leftWidth', 'number', node.image?.leftWidth),
+                        field('rightWidth', 'number', node.image?.rightWidth),
+                        field('topHeight', 'number', node.image?.topHeight),
+                        field('bottomHeight', 'number', node.image?.bottomHeight),
+                    ],
+                }];
+        case 'text':
+            return [{
+                    type: 'node.text',
+                    displayName: 'Text',
+                    fields: [
+                        field('value', 'string', node.text?.value),
+                        field('color', 'color', node.text?.color),
+                        field('fontSize', 'number', node.text?.fontSize),
+                        field('fontFamily', 'string', Array.isArray(node.text?.fontFamily) ? node.text.fontFamily.join(',') : node.text?.fontFamily),
+                        field('fontWeight', 'enum', node.text?.fontWeight, enumSchema('fontWeight', ['normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'])),
+                        field('center', 'boolean', node.text?.center),
+                    ],
+                }];
+        case 'input':
+            return [{
+                    type: 'node.input',
+                    displayName: 'Input',
+                    fields: [
+                        field('value', 'string', node.input?.value),
+                        field('backgroundColor', 'color', node.input?.backgroundColor),
+                        field('borderColor', 'color', node.input?.borderColor),
+                        field('borderSize', 'number', node.input?.borderSize),
+                        field('textColor', 'string', node.input?.textColor),
+                        field('fontSize', 'number', node.input?.fontSize),
+                        field('fontFamily', 'string', Array.isArray(node.input?.fontFamily) ? node.input.fontFamily.join(',') : node.input?.fontFamily),
+                        field('paddingLeft', 'number', node.input?.paddingLeft),
+                        field('paddingRight', 'number', node.input?.paddingRight),
+                        field('paddingTop', 'number', node.input?.paddingTop),
+                        field('paddingBottom', 'number', node.input?.paddingBottom),
+                    ],
+                }];
+        case 'shape':
+            return [{
+                    type: 'node.shape',
+                    displayName: 'Shape',
+                    fields: [
+                        field('type', 'enum', node.shape?.type, enumSchema('type', ['rect', 'roundedRect'])),
+                        field('color', 'color', node.shape?.color),
+                        field('fillAlpha', 'number', node.shape?.fillAlpha),
+                        field('radius', 'number', node.shape?.radius),
+                        field('strokeColor', 'color', node.shape?.strokeColor),
+                        field('strokeWidth', 'number', node.shape?.strokeWidth),
+                        field('strokeAlpha', 'number', node.shape?.strokeAlpha),
+                    ],
+                }];
+        case 'container':
+            return [];
+    }
+}
+function buildComponentFields(component, schema) {
+    return (schema?.props ?? []).filter((prop) => !prop.hidden).map((prop) => ({
+        key: prop.key,
+        label: prop.key,
+        type: prop.type,
+        value: component.props?.[prop.key] ?? prop.default,
+        schema: prop,
+    }));
+}
+function buildComponentModel(component) {
+    const schema = ComponentRegistry.get(component.type);
+    return {
+        id: component.id,
+        type: component.type,
+        displayName: schema?.displayName ?? component.type,
+        schema,
+        fields: buildComponentFields(component, schema),
+    };
+}
+export function buildInspectorModel(scene, nodeLocator) {
+    const located = findNode(scene, nodeLocator);
+    if (!located) {
+        return undefined;
+    }
+    const node = located.node;
+    return {
+        id: node.id,
+        key: node.key,
+        role: node.role,
+        name: node.name,
+        kind: node.kind,
+        transform: buildTransformFields(node),
+        display: buildDisplayModel(node),
+        components: (node.components ?? []).map(buildComponentModel),
+    };
+}

package/dist/authoring/LogicGraph.d.ts

@@ -0,0 +1,66 @@
+import type { SceneSpec } from "../scene/index.js";
+import type { ActionSpec } from "./ActionRegistry.js";
+export type LogicValue = {
+    kind: 'const';
+    value: unknown;
+} | {
+    kind: 'state';
+    path: string;
+} | {
+    kind: 'payload';
+    path: string;
+};
+export type LogicConditionOperator = 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'truthy' | 'falsy';
+export interface LogicConditionSpec {
+    left: LogicValue;
+    op: LogicConditionOperator;
+    right?: LogicValue;
+}
+export type LogicStepSpec = {
+    id: string;
+    type: 'condition';
+    condition: LogicConditionSpec;
+} | {
+    id: string;
+    type: 'setState';
+    path: string;
+    value: LogicValue;
+} | {
+    id: string;
+    type: 'setNodeVisible';
+    node: string;
+    visible: boolean;
+} | {
+    id: string;
+    type: 'emitAction';
+    action: string;
+} | {
+    id: string;
+    type: 'comment';
+    text: string;
+};
+export interface LogicFlowSpec {
+    id: string;
+    action: string;
+    name?: string;
+    description?: string;
+    steps: LogicStepSpec[];
+}
+export interface LogicGraphSpec {
+    version: 1;
+    type: 'pixifact.logicGraph';
+    flows: LogicFlowSpec[];
+}
+export interface LogicValidationContext {
+    actions?: readonly ActionSpec[];
+    scene?: SceneSpec;
+}
+export interface LogicValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+export declare function createLogicGraph(flows?: LogicFlowSpec[]): LogicGraphSpec;
+export declare function createUseInventoryItemFlow(): LogicFlowSpec;
+export declare function validateLogicGraph(graph: LogicGraphSpec, context?: LogicValidationContext): LogicValidationResult;
+export declare function compileLogicGraphToTypescript(graph: LogicGraphSpec): string;
+export declare function summarizeLogicGraphForAi(graph: LogicGraphSpec | undefined): string;