pixifact 0.1.3

package/dist/authoring/LogicGraph.js

@@ -0,0 +1,184 @@
+import { findNode } from "../commands/utils.js";
+import { actionExists } from "./ActionRegistry.js";
+export function createLogicGraph(flows = []) {
+    return {
+        version: 1,
+        type: 'pixifact.logicGraph',
+        flows,
+    };
+}
+export function createUseInventoryItemFlow() {
+    return {
+        id: 'flow-useInventoryItem',
+        action: 'useInventoryItem',
+        name: 'Use Inventory Item',
+        description: 'Decrease item quantity and remove empty inventory slots.',
+        steps: [
+            {
+                id: 'hasQuantity',
+                type: 'condition',
+                condition: {
+                    left: { kind: 'state', path: 'selectedItem.quantity' },
+                    op: 'gt',
+                    right: { kind: 'const', value: 0 },
+                },
+            },
+            {
+                id: 'decreaseQuantity',
+                type: 'setState',
+                path: 'selectedItem.quantity',
+                value: { kind: 'state', path: 'selectedItem.quantity - 1' },
+            },
+            {
+                id: 'removeEmptySlot',
+                type: 'comment',
+                text: 'When quantity reaches zero, remove or hide the inventory slot in game code.',
+            },
+        ],
+    };
+}
+function validateValue(value, errors, target) {
+    if (value.kind !== 'const' && !value.path) {
+        errors.push(`${target} requires a path.`);
+    }
+}
+function validateStep(step, flow, context, errors) {
+    if (!step.id) {
+        errors.push(`Logic flow "${flow.id}" contains a step without id.`);
+    }
+    switch (step.type) {
+        case 'condition':
+            validateValue(step.condition.left, errors, `${step.id}.condition.left`);
+            if (step.condition.op !== 'truthy' && step.condition.op !== 'falsy' && !step.condition.right) {
+                errors.push(`${step.id}.condition.right is required for ${step.condition.op}.`);
+            }
+            if (step.condition.right) {
+                validateValue(step.condition.right, errors, `${step.id}.condition.right`);
+            }
+            break;
+        case 'setState':
+            if (!step.path) {
+                errors.push(`${step.id}.path is required.`);
+            }
+            validateValue(step.value, errors, `${step.id}.value`);
+            break;
+        case 'setNodeVisible':
+            if (context.scene && !findNode(context.scene, step.node)) {
+                errors.push(`${step.id} references missing node "${step.node}".`);
+            }
+            break;
+        case 'emitAction':
+            if (context.actions && !actionExists(context.actions, step.action)) {
+                errors.push(`${step.id} emits undeclared action "${step.action}".`);
+            }
+            break;
+        case 'comment':
+            if (!step.text) {
+                errors.push(`${step.id}.text is required.`);
+            }
+            break;
+    }
+}
+export function validateLogicGraph(graph, context = {}) {
+    const errors = [];
+    if (graph.type !== 'pixifact.logicGraph') {
+        errors.push('Logic graph type must be "pixifact.logicGraph".');
+    }
+    const flowIds = new Set();
+    for (const flow of graph.flows) {
+        if (!flow.id) {
+            errors.push('Logic flow id is required.');
+        }
+        if (flowIds.has(flow.id)) {
+            errors.push(`Duplicate logic flow id "${flow.id}".`);
+        }
+        flowIds.add(flow.id);
+        if (context.actions && !actionExists(context.actions, flow.action)) {
+            errors.push(`Logic flow "${flow.id}" references undeclared action "${flow.action}".`);
+        }
+        for (const step of flow.steps) {
+            validateStep(step, flow, context, errors);
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+    };
+}
+function accessPath(root, path) {
+    if (path.includes(' - ') || path.includes(' + ')) {
+        const [left, operator, right] = path.split(/\s+/);
+        const numeric = Number(right);
+        if ((operator === '-' || operator === '+') && Number.isFinite(numeric)) {
+            return `(${accessPath(root, left)} ${operator} ${JSON.stringify(numeric)})`;
+        }
+    }
+    return `${root}${path.split('.').map((part) => `[${JSON.stringify(part)}]`).join('')}`;
+}
+function compileValue(value) {
+    switch (value.kind) {
+        case 'const':
+            return JSON.stringify(value.value);
+        case 'state':
+            return accessPath('context.state', value.path);
+        case 'payload':
+            return accessPath('payload', value.path);
+    }
+}
+function compileCondition(condition) {
+    const left = compileValue(condition.left);
+    const right = condition.right ? compileValue(condition.right) : undefined;
+    switch (condition.op) {
+        case 'truthy':
+            return `Boolean(${left})`;
+        case 'falsy':
+            return `!Boolean(${left})`;
+        case 'eq':
+            return `${left} === ${right}`;
+        case 'neq':
+            return `${left} !== ${right}`;
+        case 'lt':
+            return `${left} < ${right}`;
+        case 'lte':
+            return `${left} <= ${right}`;
+        case 'gt':
+            return `${left} > ${right}`;
+        case 'gte':
+            return `${left} >= ${right}`;
+    }
+}
+function compileStep(step) {
+    switch (step.type) {
+        case 'condition':
+            return `        if (!(${compileCondition(step.condition)})) return;`;
+        case 'setState':
+            return `        ${accessPath('context.state', step.path)} = ${compileValue(step.value)};`;
+        case 'setNodeVisible':
+            return `        context.setNodeVisible?.(${JSON.stringify(step.node)}, ${JSON.stringify(step.visible)});`;
+        case 'emitAction':
+            return `        context.emit?.(${JSON.stringify(step.action)});`;
+        case 'comment':
+            return `        // ${step.text.replaceAll('\n', ' ')}`;
+    }
+}
+export function compileLogicGraphToTypescript(graph) {
+    const handlers = graph.flows.map((flow) => {
+        const steps = flow.steps.map(compileStep).join('\n');
+        return `    ${JSON.stringify(flow.action)}(context: LogicRuntimeContext, payload: Record<string, unknown> = {}) {\n${steps}\n    },`;
+    }).join('\n');
+    return `export interface LogicRuntimeContext {
+    state: Record<string, unknown>;
+    emit?: (action: string, payload?: unknown) => void;
+    setNodeVisible?: (node: string, visible: boolean) => void;
+}
+
+export const logicHandlers = {
+${handlers}
+};
+`;
+}
+export function summarizeLogicGraphForAi(graph) {
+    return (graph?.flows ?? [])
+        .map((flow) => `- ${flow.action}: ${flow.steps.map((step) => step.type).join(' -> ')}`)
+        .join('\n');
+}

package/dist/authoring/OverrideJournal.d.ts

@@ -0,0 +1,18 @@
+export interface LockSpec {
+    target: 'transform' | 'component' | 'nodeData';
+    node: string;
+    field?: string;
+    component?: string;
+    prop: string;
+    reason?: string;
+}
+export interface OverrideSpec {
+    source: 'manual' | 'agent';
+    target: string;
+    before: unknown;
+    after: unknown;
+    reason?: string;
+    timestamp: number;
+}
+export declare function lockKey(lock: Omit<LockSpec, 'reason'>): string;
+export declare function isLocked(locks: readonly LockSpec[] | undefined, candidate: Omit<LockSpec, 'reason'>): boolean;

package/dist/authoring/OverrideJournal.js

@@ -0,0 +1,23 @@
+export function lockKey(lock) {
+    if (lock.target === 'transform') {
+        return `${lock.node}.transform.${lock.prop}`;
+    }
+    if (lock.target === 'nodeData') {
+        return `${lock.node}.${lock.field}.${lock.prop}`;
+    }
+    return `${lock.node}.${lock.component}.${lock.prop}`;
+}
+export function isLocked(locks, candidate) {
+    return (locks ?? []).some((lock) => {
+        if (lock.target !== candidate.target || lock.node !== candidate.node || lock.prop !== candidate.prop) {
+            return false;
+        }
+        if (candidate.target === 'component') {
+            return lock.component === candidate.component;
+        }
+        if (candidate.target === 'nodeData') {
+            return lock.field === candidate.field;
+        }
+        return true;
+    });
+}

package/dist/authoring/PreferenceMemory.d.ts

@@ -0,0 +1,21 @@
+import type { OverrideSpec } from "./OverrideJournal.js";
+export interface PreferenceMemory {
+    id: string;
+    context: string;
+    pattern: string;
+    before?: unknown;
+    after: unknown;
+    reason?: string;
+    confidence: number;
+    enabled?: boolean;
+    source?: 'manual' | 'imported' | 'agent';
+}
+export interface MemorySuggestion {
+    id: string;
+    memory: PreferenceMemory;
+    sourceOverride: OverrideSpec;
+}
+export declare function createMemorySuggestion(override: OverrideSpec): MemorySuggestion | undefined;
+export declare function createMemorySuggestions(overrides: readonly OverrideSpec[]): MemorySuggestion[];
+export declare function summarizeMemoryForAgent(memory: readonly PreferenceMemory[]): string;
+export declare function enabledMemory(memory: readonly PreferenceMemory[]): PreferenceMemory[];

package/dist/authoring/PreferenceMemory.js

@@ -0,0 +1,39 @@
+function propFromTarget(target) {
+    const parts = target.split('.');
+    return parts.at(-1) ?? target;
+}
+export function createMemorySuggestion(override) {
+    if (override.source !== 'manual') {
+        return undefined;
+    }
+    const prop = propFromTarget(override.target);
+    return {
+        id: `suggestion-${override.timestamp}-${override.target}`,
+        sourceOverride: override,
+        memory: {
+            id: `memory-${override.timestamp}-${override.target}`,
+            context: override.target,
+            pattern: `When editing ${override.target}, prefer ${prop}=${JSON.stringify(override.after)}.`,
+            before: override.before,
+            after: override.after,
+            reason: override.reason,
+            confidence: 0.5,
+            enabled: true,
+            source: 'manual',
+        },
+    };
+}
+export function createMemorySuggestions(overrides) {
+    return overrides
+        .map(createMemorySuggestion)
+        .filter((suggestion) => !!suggestion);
+}
+export function summarizeMemoryForAgent(memory) {
+    return memory
+        .filter((item) => item.enabled !== false)
+        .map((item) => `- ${item.pattern}`)
+        .join('\n');
+}
+export function enabledMemory(memory) {
+    return memory.filter((item) => item.enabled !== false);
+}

package/dist/authoring/ProjectConfig.d.ts

@@ -0,0 +1,20 @@
+export declare const pixifactProjectConfigFileName = "pixifact.project.json";
+export interface PixifactProjectRunConfig {
+    command: string;
+    args: string[];
+    cwd: string;
+    url?: string;
+}
+export interface PixifactProjectConfig {
+    version: 1;
+    name: string;
+    scenes: Record<string, string>;
+    run?: PixifactProjectRunConfig;
+}
+export interface PixifactProjectSummary {
+    name: string;
+    scenes: Record<string, string>;
+    run?: PixifactProjectRunConfig;
+}
+export declare function parsePixifactProjectConfig(value: unknown): PixifactProjectConfig;
+export declare function summarizePixifactProjectConfig(config: PixifactProjectConfig): PixifactProjectSummary;

package/dist/authoring/ProjectConfig.js

@@ -0,0 +1,78 @@
+export const pixifactProjectConfigFileName = 'pixifact.project.json';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertRecord(value, name) {
+    if (!isRecord(value)) {
+        throw new Error(`${name} must be an object.`);
+    }
+    return value;
+}
+function assertString(value, name) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${name} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function normalizeProjectPath(value, name) {
+    const input = assertString(value, name).replaceAll('\\', '/');
+    if (input.startsWith('/') || /^[A-Za-z]:\//.test(input)) {
+        throw new Error(`${name} must be project-relative.`);
+    }
+    const parts = input.split('/');
+    if (parts.some((part) => part === '..')) {
+        throw new Error(`${name} must stay inside projectRoot.`);
+    }
+    if (parts.some((part) => part === '')) {
+        throw new Error(`${name} must not contain empty path segments.`);
+    }
+    return input;
+}
+function normalizeRunCwd(value) {
+    const input = assertString(value, 'run.cwd').replaceAll('\\', '/');
+    if (input === '.') {
+        return input;
+    }
+    return normalizeProjectPath(input, 'run.cwd');
+}
+function parseScenes(value) {
+    const scenes = assertRecord(value, 'scenes');
+    return Object.fromEntries(Object.entries(scenes).map(([key, scenePath]) => [
+        assertString(key, 'scene key'),
+        normalizeProjectPath(scenePath, `scenes.${key}`),
+    ]));
+}
+function parseRun(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const run = assertRecord(value, 'run');
+    if (!Array.isArray(run.args) || !run.args.every((arg) => typeof arg === 'string')) {
+        throw new Error('run.args must be an array of strings.');
+    }
+    return {
+        command: assertString(run.command, 'run.command'),
+        args: run.args,
+        cwd: normalizeRunCwd(run.cwd),
+        ...(run.url === undefined ? {} : { url: assertString(run.url, 'run.url') }),
+    };
+}
+export function parsePixifactProjectConfig(value) {
+    const config = assertRecord(value, 'pixifact.project.json');
+    if (config.version !== 1) {
+        throw new Error('pixifact.project.json version must be 1.');
+    }
+    return {
+        version: 1,
+        name: assertString(config.name, 'name'),
+        scenes: parseScenes(config.scenes),
+        run: parseRun(config.run),
+    };
+}
+export function summarizePixifactProjectConfig(config) {
+    return {
+        name: config.name,
+        scenes: config.scenes,
+        ...(config.run === undefined ? {} : { run: config.run }),
+    };
+}

package/dist/authoring/RuntimePreview.d.ts

@@ -0,0 +1,11 @@
+import { Group } from "../runtime/index.js";
+import type { Component } from "../runtime/index.js";
+import type { InstantiateContext, SceneSpec } from "../scene/index.js";
+export interface RuntimePreview {
+    root: Group;
+    nodes: Map<string, Group>;
+    components: Map<string, Component>;
+    resolveNode(runtimeNode: Group): string | undefined;
+}
+export declare function createRuntimePreview(scene: SceneSpec, parent?: Group, context?: InstantiateContext): RuntimePreview;
+export declare function destroyRuntimePreview(preview?: RuntimePreview): void;

package/dist/authoring/RuntimePreview.js

@@ -0,0 +1,25 @@
+import { GameObject } from "../runtime/index.js";
+import { instantiate } from "../scene/index.js";
+export function createRuntimePreview(scene, parent, context) {
+    const result = instantiate(scene, parent, context);
+    const nodeIdsByObject = new WeakMap();
+    for (const [id, node] of result.nodes) {
+        if (!nodeIdsByObject.has(node)) {
+            nodeIdsByObject.set(node, id);
+        }
+    }
+    return {
+        root: result.root,
+        nodes: result.nodes,
+        components: result.components,
+        resolveNode(runtimeNode) {
+            return nodeIdsByObject.get(runtimeNode);
+        },
+    };
+}
+export function destroyRuntimePreview(preview) {
+    if (!preview) {
+        return;
+    }
+    GameObject.destroy(preview.root);
+}

package/dist/authoring/SceneDocument.d.ts

@@ -0,0 +1,74 @@
+import EventEmitter from "eventemitter3";
+import type { SceneCommand } from "../commands/Command.js";
+import type { CommandResult } from "../commands/applyCommand.js";
+import type { InstantiateContext, SceneSpec } from "../scene/index.js";
+import type { Group } from "../runtime/index.js";
+import type { SceneSelection } from "./SceneSelection.js";
+import type { InspectorNodeModel } from "./InspectorModel.js";
+import type { RuntimePreview } from "./RuntimePreview.js";
+import type { LockSpec, OverrideSpec } from "./OverrideJournal.js";
+import type { MemorySuggestion, PreferenceMemory } from "./PreferenceMemory.js";
+import type { SceneProjectState } from "./SceneProjectState.js";
+import type { DesignTokenSpec } from "./DesignToken.js";
+import type { ActionSpec } from "./ActionRegistry.js";
+import type { LogicFlowSpec, LogicGraphSpec } from "./LogicGraph.js";
+export interface SceneDocumentEventMap {
+    changed: [result: CommandResult];
+    loaded: [scene: SceneSpec];
+    previewRebuilt: [preview: RuntimePreview];
+    selectionChanged: [selection: SceneSelection];
+}
+export declare class SceneDocument {
+    scene: SceneSpec;
+    selection: SceneSelection;
+    dirty: boolean;
+    emitter: EventEmitter<SceneDocumentEventMap, any>;
+    preview?: RuntimePreview;
+    locks: LockSpec[];
+    overrides: OverrideSpec[];
+    memory: PreferenceMemory[];
+    designTokens?: DesignTokenSpec;
+    actions: ActionSpec[];
+    logicGraph: LogicGraphSpec;
+    private commandStack;
+    private previewContext?;
+    private previewParent?;
+    constructor(scene: SceneSpec);
+    apply(command: SceneCommand, source?: OverrideSpec['source']): CommandResult;
+    addLock(lock: LockSpec): void;
+    removeLock(lock: Omit<LockSpec, 'reason'>): void;
+    getMemorySuggestions(): MemorySuggestion[];
+    acceptMemorySuggestion(suggestion: MemorySuggestion): void;
+    upsertMemory(memory: PreferenceMemory): void;
+    setMemoryEnabled(id: string, enabled: boolean): void;
+    removeMemory(id: string): void;
+    importMemory(memory: readonly PreferenceMemory[], replace?: boolean): void;
+    addAction(action: ActionSpec): void;
+    removeAction(key: string): void;
+    addLogicFlow(flow: LogicFlowSpec): {
+        ok: false;
+        errors: string[];
+        graph?: undefined;
+    } | {
+        ok: true;
+        graph: LogicGraphSpec;
+        errors?: undefined;
+    };
+    removeLogicFlow(id: string): void;
+    private recordOverride;
+    undo(): CommandResult | undefined;
+    redo(): CommandResult | undefined;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    setSelection(selection: SceneSelection): void;
+    private ensureSelectionValid;
+    serialize(): string;
+    serializeState(): string;
+    getState(): SceneProjectState;
+    load(json: string | SceneSpec | SceneProjectState): void;
+    loadState(state: SceneProjectState): void;
+    rebuildPreview(context?: InstantiateContext | undefined, parent?: Group | undefined): RuntimePreview;
+    getInspectorModel(node?: string | undefined): InspectorNodeModel | undefined;
+    clearPreview(): void;
+    destroy(): void;
+}