@aotui/mobile-ai-native 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/core/action/createActionRuntime.d.ts

@@ -1,13 +1,13 @@
-import type { ActionDefinition } from "./defineAction";
-import type { ActionResult, Store, ToolDefinition } from "../types";
+import type { ActionDefinition } from "./defineAction.js";
+import type { EffectMap } from "../effect/types.js";
+import type { ActionResult, Store, ToolDefinition, TraceStore } from "../types.js";
 export declare function createActionRuntime<State, Event>(config: {
     store: Store<State, Event>;
     actions: Array<ActionDefinition<State, Event, any>>;
-    effects?: Record<string, (ctx: {
-        getState(): State;
-        emit(event: Event): void;
-    }, input: any) => Promise<void> | void>;
+    traceStore?: TraceStore;
+    effects?: EffectMap<State, Event>;
+    getRelevantViewTypes?: () => readonly string[];
 }): {
     executeAction: (name: string, input: Record<string, unknown>) => Promise<ActionResult>;
-    listVisibleTools: () => ToolDefinition[];
+    listVisibleTools: (relevantViewTypes?: readonly string[]) => ToolDefinition[];
 };

package/dist/core/action/createActionRuntime.js

@@ -1,11 +1,22 @@
+import { createTraceStore } from "../trace/createTraceStore.js";
 export function createActionRuntime(config) {
     const actionsByName = new Map(config.actions.map((action) => [action.name, action]));
-    const trace = {
-        start(_summary) { },
-        update(_summary) { },
-        success(_summary) { },
-        fail(_summary) { },
-    };
+    const traceStore = config.traceStore ?? createTraceStore();
+    function isActionRelevant(action) {
+        const scopedAction = action;
+        const relevantViewTypes = config.getRelevantViewTypes?.() ?? [];
+        if (!scopedAction.viewType) {
+            return true;
+        }
+        return relevantViewTypes.includes(scopedAction.viewType);
+    }
+    function recordTrace(actionName, status, summary) {
+        traceStore.record({
+            actionName,
+            status,
+            summary,
+        });
+    }
     async function executeAction(name, input) {
         const action = actionsByName.get(name);
         if (!action) {
@@ -17,7 +28,8 @@ export function createActionRuntime(config) {
                 },
             };
         }
-        if (!action.visibility(config.store.getState())) {
+        if (!isActionRelevant(action) ||
+            !action.visibility(config.store.getState())) {
             return {
                 success: false,
                 error: {
@@ -36,31 +48,72 @@ export function createActionRuntime(config) {
                 },
             };
         }
+        let latestSummary = `Started action ${name}`;
+        recordTrace(name, "started", latestSummary);
+        const trace = {
+            update(summary) {
+                latestSummary = summary;
+                recordTrace(name, "updated", summary);
+            },
+        };
         const ctx = {
             getState: () => config.store.getState(),
             emit: (event) => config.store.emit(event),
-            runEffect: async (name, input) => {
+            runEffect: (name, input) => {
                 const effect = config.effects?.[name];
                 if (!effect) {
-                    return;
+                    return Promise.resolve(undefined);
                 }
-                await effect({
+                return Promise.resolve(effect({
                     getState: () => config.store.getState(),
                     emit: (event) => config.store.emit(event),
-                }, input);
+                    trace,
+                }, input));
             },
             trace,
         };
-        return await action.handler(ctx, parsed.data);
+        try {
+            const result = await action.handler(ctx, parsed.data);
+            if (result.success) {
+                latestSummary = result.message ?? latestSummary;
+                recordTrace(name, "succeeded", latestSummary);
+            }
+            else {
+                latestSummary =
+                    result.error?.message ?? result.message ?? `Action ${name} failed`;
+                recordTrace(name, "failed", latestSummary);
+            }
+            return result;
+        }
+        catch (error) {
+            latestSummary =
+                error instanceof Error ? error.message : `Action ${name} failed`;
+            recordTrace(name, "failed", latestSummary);
+            throw error;
+        }
     }
-    function listVisibleTools() {
+    function listVisibleTools(relevantViewTypes = config.getRelevantViewTypes?.() ?? []) {
         const state = config.store.getState();
+        const relevantViewTypeSet = new Set(relevantViewTypes);
         return config.actions
-            .filter((action) => action.visibility(state))
-            .map((action) => ({
-            name: action.name,
-            description: action.description,
-        }));
+            .filter((action) => {
+            const scopedAction = action;
+            const isViewTypeRelevant = !scopedAction.viewType ||
+                relevantViewTypeSet.has(scopedAction.viewType);
+            return isViewTypeRelevant && action.visibility(state);
+        })
+            .map((action) => {
+            const scopedAction = action;
+            return {
+                name: action.name,
+                description: action.description,
+                inputSchema: action.schema,
+                meta: action.meta ?? {},
+                ...(scopedAction.viewType
+                    ? { viewType: scopedAction.viewType }
+                    : {}),
+            };
+        });
     }
     return {
         executeAction,

package/dist/core/action/defineAction.d.ts

@@ -1,20 +1,19 @@
 import type { ZodType } from "zod";
-import type { ActionResult } from "../types";
+import type { EffectResult } from "../effect/types.js";
+import type { ActionResult, ToolMetadata } from "../types.js";
 export type ActionContext<State, Event> = {
     getState(): State;
     emit(event: Event): void;
-    runEffect(name: string, input: unknown): Promise<void>;
+    runEffect(name: string, input: unknown): Promise<EffectResult>;
     trace: {
-        start(summary: string): void;
         update(summary: string): void;
-        success(summary?: string): void;
-        fail(summary: string): void;
     };
 };
 export type ActionDefinition<State, Event, Input> = {
     name: string;
     description: string;
     schema: ZodType<Input>;
+    meta?: ToolMetadata;
     visibility(state: State): boolean;
     handler(ctx: ActionContext<State, Event>, input: Input): Promise<ActionResult> | ActionResult;
 };

package/dist/core/action/defineViewTypeTool.d.ts

@@ -0,0 +1,5 @@
+import type { ActionDefinition } from "./defineAction.js";
+export type ViewTypeToolActionDefinition<State, Event, Input> = ActionDefinition<State, Event, Input> & {
+    readonly viewType: string;
+};
+export declare function defineViewTypeTool<State, Event, Input>(tool: ViewTypeToolActionDefinition<State, Event, Input>): ViewTypeToolActionDefinition<State, Event, Input>;

package/dist/core/action/defineViewTypeTool.js

@@ -0,0 +1,3 @@
+export function defineViewTypeTool(tool) {
+    return tool;
+}

package/dist/core/effect/types.d.ts

@@ -1 +1,21 @@
-export type EffectMap = Record<string, (input: unknown) => Promise<void> | void>;
+export type EffectTrace = {
+    update(summary: string): void;
+};
+export type EffectFailure = {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type EffectSuccess = {
+    success: true;
+};
+export type EffectResult = EffectSuccess | EffectFailure | void;
+export type EffectContext<State, Event> = {
+    getState(): State;
+    emit(event: Event): void;
+    trace: EffectTrace;
+};
+export type EffectHandler<State, Event, Input> = (ctx: EffectContext<State, Event>, input: Input) => Promise<EffectResult> | EffectResult;
+export type EffectMap<State, Event> = Record<string, EffectHandler<State, Event, any>>;

package/dist/core/ref/ref-index.d.ts

@@ -1,4 +1,4 @@
-import type { RefIndexEntry } from "../types";
+import type { RefIndexEntry } from "../types.js";
 export declare function createRefCollector(): {
     register(refId: string, entry: RefIndexEntry): void;
     snapshot(): Record<string, RefIndexEntry>;

package/dist/core/snapshot/createSnapshotBundle.d.ts

@@ -1,6 +1,9 @@
-import type { SnapshotBundle, ToolDefinition, RefIndexEntry } from "../types";
+import type { SnapshotBundle, ToolDefinition, RefIndexEntry, ViewFragment } from "../types.js";
+export declare function hardenSnapshotBundle(snapshot: SnapshotBundle): SnapshotBundle;
 export declare function createSnapshotBundle(input: {
-    tui: string;
-    refIndex: Record<string, RefIndexEntry>;
-    visibleTools: ToolDefinition[];
+    markup?: string;
+    views?: readonly ViewFragment[];
+    tui?: string;
+    refIndex: Readonly<Record<string, RefIndexEntry>>;
+    visibleTools: readonly ToolDefinition[];
 }): SnapshotBundle;

package/dist/core/snapshot/createSnapshotBundle.js

@@ -1,12 +1,119 @@
 let snapshotCounter = 0;
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function cloneReadonlyValue(value, seen = new WeakMap()) {
+    if (value === null) {
+        return null;
+    }
+    const valueType = typeof value;
+    if (valueType === "string" ||
+        valueType === "boolean") {
+        return value;
+    }
+    if (valueType === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Snapshot values must be plain JSON-like data; received a non-finite number.");
+        }
+        return value;
+    }
+    if (valueType === "undefined" ||
+        valueType === "function" ||
+        valueType === "symbol" ||
+        valueType === "bigint") {
+        throw new Error("Snapshot values must be plain JSON-like data; received an unsupported primitive value.");
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const clone = [];
+        seen.set(value, clone);
+        for (const item of value) {
+            clone.push(cloneReadonlyValue(item, seen));
+        }
+        return Object.freeze(clone);
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const clone = Object.create(null);
+        seen.set(value, clone);
+        for (const [key, nestedValue] of Object.entries(value)) {
+            clone[key] = cloneReadonlyValue(nestedValue, seen);
+        }
+        return Object.freeze(clone);
+    }
+    if (typeof value === "object" && value !== null) {
+        throw new Error("Snapshot values must be plain JSON-like data; received a non-plain object.");
+    }
+    return value;
+}
+function hardenRefIndex(refIndex) {
+    const clonedEntries = Object.create(null);
+    for (const [refId, entry] of Object.entries(refIndex)) {
+        clonedEntries[refId] = Object.freeze({
+            type: entry.type,
+            value: cloneReadonlyValue(entry.value),
+        });
+    }
+    return Object.freeze(clonedEntries);
+}
+function hardenVisibleTools(visibleTools) {
+    const clonedTools = visibleTools.map((tool) => Object.freeze({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        meta: cloneReadonlyValue(tool.meta),
+        ...(tool.viewType ? { viewType: tool.viewType } : {}),
+    }));
+    return Object.freeze(clonedTools);
+}
+function validateSnapshotCoherence(snapshot) {
+    if (snapshot.views.length === 0) {
+        return;
+    }
+    const derivedMarkup = snapshot.views.map((view) => view.markup).join("");
+    if (snapshot.markup !== derivedMarkup) {
+        throw new Error("Snapshot markup must match the provided view fragments from the same render tick.");
+    }
+}
+export function hardenSnapshotBundle(snapshot) {
+    validateSnapshotCoherence(snapshot);
+    return Object.freeze({
+        snapshotId: snapshot.snapshotId,
+        generatedAt: snapshot.generatedAt,
+        markup: snapshot.markup,
+        views: Object.freeze(snapshot.views.map((view) => Object.freeze({
+            id: view.id,
+            type: view.type,
+            name: view.name,
+            markup: view.markup,
+        }))),
+        tui: snapshot.tui,
+        refIndex: hardenRefIndex(snapshot.refIndex),
+        visibleTools: hardenVisibleTools(snapshot.visibleTools),
+    });
+}
 export function createSnapshotBundle(input) {
     const generatedAt = Date.now();
     snapshotCounter += 1;
-    return {
+    const views = input.views ?? [];
+    const derivedMarkup = views.length > 0 ? views.map((view) => view.markup).join("") : undefined;
+    const markup = input.markup ?? derivedMarkup ?? input.tui ?? "";
+    const tui = input.tui ?? markup;
+    return hardenSnapshotBundle({
         snapshotId: `snap_${generatedAt}_${snapshotCounter}`,
         generatedAt,
-        tui: input.tui,
+        markup,
+        views,
+        tui,
         refIndex: input.refIndex,
         visibleTools: input.visibleTools,
-    };
+    });
 }

package/dist/core/snapshot/createSnapshotRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { SnapshotRegistry } from "../types.js";
+export declare function createSnapshotRegistry(config?: {
+    maxEntries?: number;
+}): SnapshotRegistry;

package/dist/core/snapshot/createSnapshotRegistry.js

@@ -0,0 +1,52 @@
+import { hardenSnapshotBundle } from "./createSnapshotBundle.js";
+function evictOldSnapshots(snapshots, maxEntries) {
+    while (snapshots.size > maxEntries) {
+        const oldestSnapshotId = snapshots.keys().next().value;
+        if (!oldestSnapshotId) {
+            return;
+        }
+        snapshots.delete(oldestSnapshotId);
+    }
+}
+export function createSnapshotRegistry(config) {
+    const maxEntries = Math.max(1, config?.maxEntries ?? 2);
+    const snapshots = new Map();
+    const seenSnapshotIds = new Set();
+    function createEntry(snapshot, status) {
+        return Object.freeze({
+            snapshot,
+            status,
+        });
+    }
+    return {
+        create(snapshot) {
+            const hardenedSnapshot = hardenSnapshotBundle(snapshot);
+            if (seenSnapshotIds.has(hardenedSnapshot.snapshotId)) {
+                throw new Error(`Snapshot ${hardenedSnapshot.snapshotId} is already registered`);
+            }
+            seenSnapshotIds.add(hardenedSnapshot.snapshotId);
+            snapshots.set(hardenedSnapshot.snapshotId, createEntry(hardenedSnapshot, "active"));
+            evictOldSnapshots(snapshots, maxEntries);
+            return hardenedSnapshot;
+        },
+        lookup(snapshotId) {
+            return snapshots.get(snapshotId);
+        },
+        markStale(snapshotId) {
+            const entry = snapshots.get(snapshotId);
+            if (!entry) {
+                return;
+            }
+            snapshots.set(snapshotId, createEntry(entry.snapshot, "stale"));
+        },
+        markAllStale() {
+            for (const snapshotId of snapshots.keys()) {
+                const entry = snapshots.get(snapshotId);
+                if (!entry || entry.status === "stale") {
+                    continue;
+                }
+                snapshots.set(snapshotId, createEntry(entry.snapshot, "stale"));
+            }
+        },
+    };
+}

package/dist/core/state/createStore.d.ts

@@ -1,4 +1,4 @@
-import type { StateReducer, Store } from "../types";
+import type { StateReducer, Store } from "../types.js";
 export declare function createStore<State, Event>(config: {
     initialState: State;
     reduce: StateReducer<State, Event>;

package/dist/core/trace/createTraceStore.d.ts

@@ -0,0 +1,2 @@
+import type { TraceStore } from "./types.js";
+export declare function createTraceStore(): TraceStore;

package/dist/core/trace/createTraceStore.js

@@ -0,0 +1,38 @@
+export function createTraceStore() {
+    let nextTraceId = 1;
+    let state = {
+        entries: [],
+        recent: null,
+    };
+    const listeners = new Set();
+    function notify() {
+        listeners.forEach((listener) => listener());
+    }
+    function record(entry) {
+        const record = {
+            id: `trace_${nextTraceId++}`,
+            actionName: entry.actionName,
+            status: entry.status,
+            summary: entry.summary,
+            recordedAt: Date.now(),
+        };
+        state = {
+            entries: [...state.entries, record],
+            recent: record,
+        };
+        notify();
+        return record;
+    }
+    return {
+        getState() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        record,
+    };
+}

package/dist/core/trace/types.d.ts

@@ -0,0 +1,21 @@
+export type TraceStatus = "started" | "updated" | "succeeded" | "failed";
+export type TraceRecord = {
+    id: string;
+    actionName: string;
+    status: TraceStatus;
+    summary: string;
+    recordedAt: number;
+};
+export type TraceState = {
+    entries: TraceRecord[];
+    recent: TraceRecord | null;
+};
+export type TraceStore = {
+    getState(): TraceState;
+    subscribe(listener: () => void): () => void;
+    record(entry: {
+        actionName: string;
+        status: TraceStatus;
+        summary: string;
+    }): TraceRecord;
+};

package/dist/core/trace/types.js

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

package/dist/core/types.d.ts

@@ -1,26 +1,77 @@
+import type { ComponentChild } from "preact";
+import type { ZodTypeAny } from "zod";
+export type { TraceRecord, TraceState, TraceStatus, TraceStore, } from "./trace/types.js";
 export type StateReducer<State, Event> = (state: State, event: Event) => State;
+export type StoreListener = () => void;
+export type StoreUnsubscribe = () => void;
 export type Store<State, Event> = {
     getState(): State;
     emit(event: Event): void;
-    subscribe(listener: () => void): () => void;
+    subscribe(listener: StoreListener): StoreUnsubscribe;
 };
 export type RefIndexEntry = {
-    type: string;
-    value: unknown;
+    readonly type: string;
+    readonly value: unknown;
 };
+export type ToolMetadata = Readonly<Record<string, unknown>>;
 export type ToolDefinition = {
-    name: string;
-    description: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodTypeAny;
+    readonly meta: ToolMetadata;
+    readonly viewType?: string;
+};
+export type ViewTypeToolDefinition = ToolDefinition & {
+    readonly viewType: string;
+};
+export type ViewFragment = {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+    readonly markup: string;
+};
+export type StaticViewCatalogEntry = {
+    readonly type: string;
+    readonly description: string;
+    readonly enterFrom?: readonly string[];
+    readonly actions: readonly string[];
+};
+export type MountedViewDescriptor<State = unknown> = {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+    readonly render: (state: State) => ComponentChild;
+};
+export type SnapshotAssemblerInput<State = unknown> = {
+    readonly rootView: ViewFragment;
+    readonly mountedViews: readonly ViewFragment[];
+    readonly refIndex: Readonly<Record<string, RefIndexEntry>>;
+    readonly visibleTools: readonly ToolDefinition[];
+    readonly tui?: string;
 };
 export type SnapshotBundle = {
-    snapshotId: string;
-    generatedAt: number;
-    tui: string;
-    refIndex: Record<string, RefIndexEntry>;
-    visibleTools: ToolDefinition[];
+    readonly snapshotId: string;
+    readonly generatedAt: number;
+    readonly markup: string;
+    readonly views: readonly ViewFragment[];
+    readonly tui: string;
+    readonly refIndex: Readonly<Record<string, RefIndexEntry>>;
+    readonly visibleTools: readonly ToolDefinition[];
+};
+export type SnapshotStatus = "active" | "stale";
+export type SnapshotRegistryEntry = {
+    readonly snapshot: SnapshotBundle;
+    readonly status: SnapshotStatus;
+};
+export type SnapshotRegistry = {
+    create(snapshot: SnapshotBundle): SnapshotBundle;
+    lookup(snapshotId: string): SnapshotRegistryEntry | undefined;
+    markStale(snapshotId: string): void;
+    markAllStale?(): void;
 };
 export type ActionResult<T = unknown> = {
     success: boolean;
+    mutated?: boolean;
     message?: string;
     data?: T;
     error?: {

package/dist/demo/inbox/InboxGUI.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
 /** @jsxImportSource preact */
-import { useAppState } from "../../projection/gui/hooks";
+import { useRuntimeState } from "../../projection/react/hooks.js";
 export function InboxGUI() {
-    const { state } = useAppState();
-    return (_jsxs("gui-screen", { children: [_jsx("gui-trace", { children: state.shell.recentTrace ?? "" }), _jsx("gui-opened", { children: state.inbox.openedMessageId ?? "" }), state.inbox.items.map((item) => (_jsx("gui-item", { children: item.subject }, item.id)))] }));
+    const recentTrace = useRuntimeState((state) => state.shell.recentTrace ?? "");
+    const openedMessageId = useRuntimeState((state) => state.inbox.openedMessageId ?? "");
+    const items = useRuntimeState((state) => state.inbox.items);
+    return (_jsxs("gui-screen", { children: [_jsx("gui-trace", { children: recentTrace }), _jsx("gui-opened", { children: openedMessageId }), items.map((item) => (_jsx("gui-item", { children: item.subject }, item.id)))] }));
 }

package/dist/demo/inbox/InboxTUI.d.ts

@@ -1 +1,3 @@
-export declare function InboxTUI(): import("preact").JSX.Element;
+import type { ToolDefinition } from "../../core/types.js";
+import type { InboxState } from "./state.js";
+export declare function createInboxSnapshotBundle(state: InboxState, visibleTools: readonly ToolDefinition[]): import("../..").SnapshotBundle;