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

package/GUIDE.md

@@ -0,0 +1,317 @@
+# GUIDE: Building an Agent Native iOS Calendar App
+
+This guide is for a developer who wants to build a high-quality Agent Native calendar app on iOS using `@aotui/mobile-ai-native`.
+
+The goal is simple:
+
+- humans use a normal GUI calendar
+- the LLM uses tools through a TUI snapshot
+- both operate on the same app state
+- the human can see the result of the LLM's actions
+
+## 1. What You Are Actually Building
+
+Do not think of this as:
+
+- "an AI that clicks buttons"
+
+Think of it as:
+
+- "one calendar app with two input channels"
+
+Those two channels are:
+
+1. human input through GUI
+2. LLM input through tools
+
+They must meet in the same place:
+
+- the same `State`
+- the same `Action` layer
+
+That is the whole trick.
+
+## 2. Why This Architecture Matters
+
+If the LLM drives the GUI by fake taps, your system becomes fragile.
+
+Why?
+
+- the UI layout changes and the AI breaks
+- the AI acts on pixels, not meaning
+- debugging becomes miserable
+
+Instead, this framework makes the LLM act on meaning:
+
+- `openEvent`
+- `createEvent`
+- `moveEvent`
+- `searchEvents`
+- `changeCalendarView`
+
+The GUI is one projection of state.
+The TUI snapshot is another projection of state.
+
+The LLM should never guess ids from the screen.
+It should receive semantic refs from the current `SnapshotBundle`.
+
+## 3. The Core Mental Model
+
+Your calendar app should follow this loop:
+
+`State -> GUI`
+`State -> TUI Snapshot`
+`Tool -> Action -> Event/Effect -> State`
+`GUI Event -> Action -> Event/Effect -> State`
+
+That means:
+
+- GUI controls do not own business logic
+- TUI does not own business logic
+- tools do not own business logic
+- `Action` is the one real business entry
+
+## 4. Calendar App State
+
+A good Agent Native calendar app should have state shaped more like this:
+
+```ts
+type CalendarState = {
+  shell: {
+    currentView: "day" | "week" | "month";
+    selectedDate: string;
+    recentTrace: string | null;
+  };
+  events: {
+    items: CalendarEvent[];
+    selectedEventId: string | null;
+    searchQuery: string;
+    isLoading: boolean;
+  };
+};
+```
+
+Good rule:
+
+- if it affects GUI, TUI, tool visibility, or trace, it belongs in framework state
+- if it is only a tiny render helper, keep it local
+
+## 5. Calendar Actions
+
+Your first calendar app should expose a very small action set:
+
+- `openEvent`
+- `searchEvents`
+- `createEvent`
+- `moveEvent`
+- `changeCalendarView`
+
+Start smaller than you want.
+You can always add more later.
+
+The important rule is:
+
+- actions should be domain actions
+- not UI actions like `tapButton` or `scrollList`
+
+## 6. Why Refs Matter in Calendar Apps
+
+Calendars are full of structured data:
+
+- one day
+- one week
+- one event
+- one search result list
+
+The LLM should see semantic markers like:
+
+```text
+(1:1 with Sarah at 14:00)[event:events[0]]
+(Today)[day:visible_days[0]]
+```
+
+That is what `useDataRef` and `useArrayRef` are for.
+
+### Use `useDataRef`
+
+Use it for one event, one selected day, one active calendar.
+
+```tsx
+const selectedEventRef = useDataRef("event", selectedEvent, "selected_event");
+<text>{selectedEventRef("Selected event")}</text>;
+```
+
+### Use `useArrayRef`
+
+Use it for event lists, visible day buckets, agenda results.
+
+```tsx
+const [eventsRef, eventRef] = useArrayRef("event", visibleEvents, "events");
+<text>{eventsRef("Visible events")}</text>
+{visibleEvents.map((event, index) => (
+  <item key={event.id}>{eventRef(index, event.title)}</item>
+))}
+```
+
+## 7. Why `snapshotId` Is Non-Negotiable
+
+The screen can change after the LLM reads it.
+
+Maybe:
+
+- the selected day changed
+- search results refreshed
+- the event was deleted
+
+So tool execution must always be tied to the exact snapshot the LLM saw:
+
+```ts
+await bridge.executeTool("openEvent", { event: "events[0]" }, snapshotId);
+```
+
+This prevents the runtime from guessing against the latest UI.
+
+That is a big deal.
+It is the difference between:
+
+- a reliable system
+- and a haunted house
+
+## 8. How To Build the iOS App
+
+### Step 1: Keep this package as the core
+
+Use `@aotui/mobile-ai-native` for:
+
+- state
+- refs
+- snapshot bundle creation
+- tool bridge
+
+### Step 2: Build a thin React Native host
+
+The React Native app should do only host work:
+
+- render native GUI
+- host the agent session
+- ask the framework for `SnapshotBundle`
+- pass tool calls into `executeTool`
+
+### Step 3: Build GUI and TUI as separate projections
+
+Do not auto-generate TUI from GUI.
+
+For calendar apps this is especially important because:
+
+- GUI cares about touch and spatial layout
+- TUI cares about semantic clarity for the model
+
+### Step 4: Start with one vertical slice
+
+Do not build the whole calendar app at once.
+
+Start with:
+
+- month or week view
+- visible event list
+- `openEvent`
+- `searchEvents`
+
+Only after that is stable, add:
+
+- create
+- move
+- delete
+- recurring events
+
+## 9. Suggested First Calendar TUI
+
+Your first TUI should be boring and clear, not clever:
+
+```tsx
+<screen name="Calendar">
+  <text>View: week</text>
+  <text>Date: 2026-03-24</text>
+  <text>{daysRef("Visible days")}</text>
+  {events.map((event, index) => (
+    <item key={event.id}>{eventRef(index, `${event.title} at ${event.startTime}`)}</item>
+  ))}
+</screen>
+```
+
+The LLM does not need visual beauty.
+It needs:
+
+- stable structure
+- meaningful refs
+- clear tool choices
+
+## 10. Quality Bar for a Good Agent Native Calendar App
+
+Before you call the app "good", verify these:
+
+### State correctness
+
+- GUI and TUI always reflect the same event state
+- tool calls only act on snapshot-scoped refs
+
+### Tool correctness
+
+- invisible tools are not callable
+- stale `snapshotId` fails cleanly
+- missing refs fail with explicit errors
+
+### UX correctness
+
+- human sees the result of AI actions
+- recent AI action summary is visible
+- event openings, searches, and edits are understandable
+
+### Product correctness
+
+- no tool is named after a button
+- tools match domain intent
+- TUI exposes enough semantic data without dumping noise
+
+## 11. What This Package Does Not Give You Yet
+
+Be honest with yourself:
+
+this package is still an alpha core.
+
+It does not yet give you:
+
+- a full React Native adapter
+- iOS simulator harness
+- production persistence
+- production networking
+- voice or background agent integration
+
+That is okay.
+
+It gives you the hardest part first:
+
+- the protocol spine
+
+## 12. Recommended Build Order
+
+If your friend is building the calendar app, this is the order I recommend:
+
+1. build one RN screen shell
+2. integrate framework state and tool bridge
+3. implement week view with event refs
+4. implement `openEvent`
+5. implement `searchEvents`
+6. add trace banner for recent AI action
+7. add create/edit flows
+8. only then add advanced calendar features
+
+## 13. The One Sentence To Remember
+
+An Agent Native iOS app is not:
+
+- "AI controlling UI"
+
+It is:
+
+- "one app where GUI and LLM share the same domain actions and the same state"

package/README.md

@@ -0,0 +1,114 @@
+# @aotui/mobile-ai-native
+
+This package is an alpha host-agnostic core for building Agent Native mobile apps.
+
+It currently proves the smallest end-to-end loop of the framework:
+
+`State -> SnapshotBundle -> Tool Call(ref_id + snapshotId) -> Action -> Event/Effect -> State -> GUI/TUI refresh`
+
+If you want a practical build guide for a real iOS app, read [GUIDE.md](./GUIDE.md).
+
+## What This Slice Proves
+
+- one shared state system drives both GUI and TUI
+- TUI is handwritten and can expose semantic refs with `useDataRef` and `useArrayRef`
+- the framework builds one atomic `SnapshotBundle`
+- tools execute against the exact `snapshotId` the LLM saw
+- `refIndex` stores serializable snapshot payloads, not live object references
+- one pure local action and one effect-driven action both work
+
+## Core Contract
+
+The LLM does not operate on guessed ids.
+It sees semantic markers like:
+
+```text
+(Welcome back)[message:messages[0]]
+```
+
+Then it calls a tool with:
+
+```ts
+await bridge.executeTool("openMessage", { message: "messages[0]" }, snapshotId);
+```
+
+The runtime resolves that `ref_id` from the `SnapshotBundle.refIndex` for the same `snapshotId`.
+
+## Ref APIs
+
+### `useDataRef`
+
+Use for a single object:
+
+```tsx
+const pinnedRef = useDataRef("message", message, "messages[0]");
+<text>{pinnedRef("Pinned message")}</text>;
+```
+
+### `useArrayRef`
+
+Use for an array:
+
+```tsx
+const [listRef, itemRef] = useArrayRef("message", messages, "messages");
+<text>{listRef("Inbox messages")}</text>;
+<item>{itemRef(0, "Welcome back")}</item>;
+```
+
+## SnapshotBundle
+
+The LLM-facing read model is:
+
+```ts
+type SnapshotBundle = {
+  snapshotId: string;
+  generatedAt: number;
+  tui: string;
+  refIndex: Record<string, { type: string; value: unknown }>;
+  visibleTools: ToolDefinition[];
+};
+```
+
+This is intentionally atomic:
+
+- `tui`
+- `visibleTools`
+- `refIndex`
+
+must all come from the same render tick.
+
+## Why `refIndex` Stores Serializable Payloads
+
+Screens can change after the LLM reads them.
+Live object references may already be gone.
+
+So `refIndex` stores serializable snapshot payloads.
+When the LLM later calls a tool, the framework reconstructs the action input from the payload attached to that `snapshotId`.
+
+## Current Status
+
+This is not yet a full React Native runtime or iOS shell.
+
+What it gives you today:
+
+- shared state core
+- semantic refs with `useDataRef` and `useArrayRef`
+- atomic `SnapshotBundle`
+- snapshot-scoped tool execution
+- a working inbox vertical slice
+
+What you still need for a production iOS app:
+
+- a thin React Native host adapter
+- real GUI components
+- model orchestration and networking
+- product-level trace UI and persistence
+
+## Current Demo
+
+The inbox demo exposes:
+
+- `openMessage`
+- `searchMessages`
+
+and proves that GUI and TUI both refresh from the same state after tool execution.

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

@@ -0,0 +1,13 @@
+import type { ActionDefinition } from "./defineAction";
+import type { ActionResult, Store, ToolDefinition } from "../types";
+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>;
+}): {
+    executeAction: (name: string, input: Record<string, unknown>) => Promise<ActionResult>;
+    listVisibleTools: () => ToolDefinition[];
+};

package/dist/core/action/createActionRuntime.js

@@ -0,0 +1,69 @@
+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) { },
+    };
+    async function executeAction(name, input) {
+        const action = actionsByName.get(name);
+        if (!action) {
+            return {
+                success: false,
+                error: {
+                    code: "ACTION_NOT_FOUND",
+                    message: `Action ${name} was not found`,
+                },
+            };
+        }
+        if (!action.visibility(config.store.getState())) {
+            return {
+                success: false,
+                error: {
+                    code: "ACTION_NOT_VISIBLE",
+                    message: `Action ${name} is not currently visible`,
+                },
+            };
+        }
+        const parsed = action.schema.safeParse(input);
+        if (!parsed.success) {
+            return {
+                success: false,
+                error: {
+                    code: "ACTION_INVALID_INPUT",
+                    message: parsed.error.message,
+                },
+            };
+        }
+        const ctx = {
+            getState: () => config.store.getState(),
+            emit: (event) => config.store.emit(event),
+            runEffect: async (name, input) => {
+                const effect = config.effects?.[name];
+                if (!effect) {
+                    return;
+                }
+                await effect({
+                    getState: () => config.store.getState(),
+                    emit: (event) => config.store.emit(event),
+                }, input);
+            },
+            trace,
+        };
+        return await action.handler(ctx, parsed.data);
+    }
+    function listVisibleTools() {
+        const state = config.store.getState();
+        return config.actions
+            .filter((action) => action.visibility(state))
+            .map((action) => ({
+            name: action.name,
+            description: action.description,
+        }));
+    }
+    return {
+        executeAction,
+        listVisibleTools,
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { ZodType } from "zod";
+import type { ActionResult } from "../types";
+export type ActionContext<State, Event> = {
+    getState(): State;
+    emit(event: Event): void;
+    runEffect(name: string, input: unknown): Promise<void>;
+    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>;
+    visibility(state: State): boolean;
+    handler(ctx: ActionContext<State, Event>, input: Input): Promise<ActionResult> | ActionResult;
+};
+export declare function defineAction<State, Event, Input>(config: ActionDefinition<State, Event, Input>): ActionDefinition<State, Event, Input>;

package/dist/core/action/defineAction.js

@@ -0,0 +1,3 @@
+export function defineAction(config) {
+    return config;
+}

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

@@ -0,0 +1 @@
+export type EffectMap = Record<string, (input: unknown) => Promise<void> | void>;

package/dist/core/effect/types.js

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

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

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

package/dist/core/ref/ref-index.js

@@ -0,0 +1,11 @@
+export function createRefCollector() {
+    const refIndex = {};
+    return {
+        register(refId, entry) {
+            refIndex[refId] = structuredClone(entry);
+        },
+        snapshot() {
+            return structuredClone(refIndex);
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { SnapshotBundle, ToolDefinition, RefIndexEntry } from "../types";
+export declare function createSnapshotBundle(input: {
+    tui: string;
+    refIndex: Record<string, RefIndexEntry>;
+    visibleTools: ToolDefinition[];
+}): SnapshotBundle;

package/dist/core/snapshot/createSnapshotBundle.js

@@ -0,0 +1,12 @@
+let snapshotCounter = 0;
+export function createSnapshotBundle(input) {
+    const generatedAt = Date.now();
+    snapshotCounter += 1;
+    return {
+        snapshotId: `snap_${generatedAt}_${snapshotCounter}`,
+        generatedAt,
+        tui: input.tui,
+        refIndex: input.refIndex,
+        visibleTools: input.visibleTools,
+    };
+}

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

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

package/dist/core/state/createStore.js

@@ -0,0 +1,19 @@
+export function createStore(config) {
+    let state = config.initialState;
+    const listeners = new Set();
+    return {
+        getState() {
+            return state;
+        },
+        emit(event) {
+            state = config.reduce(state, event);
+            listeners.forEach((listener) => listener());
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/core/types.d.ts

@@ -0,0 +1,30 @@
+export type StateReducer<State, Event> = (state: State, event: Event) => State;
+export type Store<State, Event> = {
+    getState(): State;
+    emit(event: Event): void;
+    subscribe(listener: () => void): () => void;
+};
+export type RefIndexEntry = {
+    type: string;
+    value: unknown;
+};
+export type ToolDefinition = {
+    name: string;
+    description: string;
+};
+export type SnapshotBundle = {
+    snapshotId: string;
+    generatedAt: number;
+    tui: string;
+    refIndex: Record<string, RefIndexEntry>;
+    visibleTools: ToolDefinition[];
+};
+export type ActionResult<T = unknown> = {
+    success: boolean;
+    message?: string;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+};

package/dist/core/types.js

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

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

@@ -0,0 +1 @@
+export declare function InboxGUI(): import("preact").JSX.Element;

package/dist/demo/inbox/InboxGUI.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+import { useAppState } from "../../projection/gui/hooks";
+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)))] }));
+}

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

@@ -0,0 +1 @@
+export declare function InboxTUI(): import("preact").JSX.Element;

package/dist/demo/inbox/InboxTUI.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+import { useDataRef } from "../../ref/useDataRef";
+import { useArrayRef } from "../../ref/useArrayRef";
+import { useAppState } from "../../projection/gui/hooks";
+export function InboxTUI() {
+    const { state } = useAppState();
+    const firstMessage = state.inbox.items[0] ?? { id: "empty", subject: "Empty", opened: false };
+    const openedRef = useDataRef("message", firstMessage, "opened_message");
+    const [listRef, itemRef] = useArrayRef("message", state.inbox.items, "messages");
+    return (_jsxs("screen", { name: "Inbox", children: [_jsx("text", { children: listRef("Inbox messages") }), _jsxs("text", { children: ["Query: ", state.inbox.query || "(empty)"] }), _jsxs("text", { children: ["Opened: ", String(Boolean(state.inbox.openedMessageId))] }), state.inbox.items.map((item, index) => (_jsx("item", { children: itemRef(index, item.subject) }, item.id))), _jsx("text", { children: openedRef("Opened message") })] }));
+}

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

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { InboxEvent, InboxState } from "./state";
+declare const inboxMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    opened: z.ZodBoolean;
+}, z.core.$strip>;
+export declare function createInboxActions(): {
+    openMessage: import("../../core/action/defineAction").ActionDefinition<InboxState, InboxEvent, {
+        message: z.infer<typeof inboxMessageSchema>;
+    }>;
+    searchMessages: import("../../core/action/defineAction").ActionDefinition<InboxState, InboxEvent, {
+        query: string;
+    }>;
+};
+export {};

package/dist/demo/inbox/actions.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { defineAction } from "../../core/action/defineAction";
+const inboxMessageSchema = z.object({
+    id: z.string(),
+    subject: z.string(),
+    opened: z.boolean(),
+});
+export function createInboxActions() {
+    const openMessage = defineAction({
+        name: "openMessage",
+        description: "Open a message from the inbox.",
+        schema: z.object({
+            message: inboxMessageSchema,
+        }),
+        visibility(state) {
+            return state.shell.currentTab === "inbox";
+        },
+        handler(ctx, input) {
+            ctx.emit({ type: "MessageOpened", messageId: input.message.id });
+            ctx.emit({
+                type: "TraceUpdated",
+                summary: `Opened message ${input.message.subject}`,
+            });
+            return {
+                success: true,
+                data: { openedMessageId: input.message.id },
+            };
+        },
+    });
+    const searchMessages = defineAction({
+        name: "searchMessages",
+        description: "Search inbox messages.",
+        schema: z.object({
+            query: z.string().min(1),
+        }),
+        visibility(state) {
+            return state.shell.currentTab === "inbox";
+        },
+        async handler(ctx, input) {
+            ctx.emit({ type: "SearchStarted", query: input.query });
+            ctx.emit({
+                type: "TraceUpdated",
+                summary: `Started search for ${input.query}`,
+            });
+            await ctx.runEffect("searchMessages", input);
+            return {
+                success: true,
+                message: `Started search for ${input.query}`,
+            };
+        },
+    });
+    return {
+        openMessage,
+        searchMessages,
+    };
+}

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

@@ -0,0 +1,20 @@
+import { type InboxMessage } from "./state";
+export declare function createInboxApp(config: {
+    initialMessages: InboxMessage[];
+}): {
+    store: import("../../core/types").Store<import("./state").InboxState, import("./state").InboxEvent>;
+    bridge: {
+        listTools(): {
+            name: string;
+            description: string;
+        }[];
+        getSnapshotBundle(): import("../../core/types").SnapshotBundle;
+        executeTool(name: string, input: Record<string, unknown>, snapshotId: string): Promise<import("../../core/types").ActionResult>;
+    };
+    gui: {
+        render: () => string;
+        getVisibleSubjects(): string[];
+        getOpenedMessageId(): string | null;
+        getRecentTrace(): string;
+    };
+};

package/dist/demo/inbox/createInboxApp.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+import renderToString from "preact-render-to-string";
+import { createActionRuntime } from "../../core/action/createActionRuntime";
+import { createStore } from "../../core/state/createStore";
+import { renderTUI } from "../../projection/tui/renderTUI";
+import { AppProvider } from "../../projection/gui/AppProvider";
+import { createToolBridge } from "../../tool/createToolBridge";
+import { createInboxActions } from "./actions";
+import { createInboxEffects } from "./effects";
+import { InboxGUI } from "./InboxGUI";
+import { InboxTUI } from "./InboxTUI";
+import { createInitialInboxState, reduceInboxState, } from "./state";
+export function createInboxApp(config) {
+    const store = createStore({
+        initialState: createInitialInboxState(config.initialMessages),
+        reduce: reduceInboxState,
+    });
+    const actions = createInboxActions();
+    const actionRuntime = createActionRuntime({
+        store,
+        actions: [actions.openMessage, actions.searchMessages],
+        effects: createInboxEffects(config.initialMessages),
+    });
+    const bridge = createToolBridge({
+        actionRuntime,
+        renderCurrentSnapshot() {
+            return renderTUI(_jsx(AppProvider, { store: store, actionRuntime: actionRuntime, children: _jsx(InboxTUI, {}) }), { visibleTools: actionRuntime.listVisibleTools() });
+        },
+    });
+    function renderGUI() {
+        return renderToString(_jsx(AppProvider, { store: store, actionRuntime: actionRuntime, children: _jsx(InboxGUI, {}) }));
+    }
+    return {
+        store,
+        bridge,
+        gui: {
+            render: renderGUI,
+            getVisibleSubjects() {
+                return store.getState().inbox.items.map((item) => item.subject);
+            },
+            getOpenedMessageId() {
+                return store.getState().inbox.openedMessageId;
+            },
+            getRecentTrace() {
+                return store.getState().shell.recentTrace ?? "";
+            },
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { InboxEvent, InboxMessage, InboxState } from "./state";
+export declare function createInboxEffects(allMessages: InboxMessage[]): {
+    searchMessages(ctx: {
+        getState(): InboxState;
+        emit(event: InboxEvent): void;
+    }, input: {
+        query: string;
+    }): Promise<void>;
+};

package/dist/demo/inbox/effects.js

@@ -0,0 +1,12 @@
+export function createInboxEffects(allMessages) {
+    return {
+        async searchMessages(ctx, input) {
+            const items = allMessages.filter((item) => item.subject.toLowerCase().includes(input.query.toLowerCase()));
+            ctx.emit({
+                type: "SearchSucceeded",
+                query: input.query,
+                items,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,33 @@
+export type InboxMessage = {
+    id: string;
+    subject: string;
+    opened: boolean;
+};
+export type InboxState = {
+    shell: {
+        currentTab: "inbox" | "settings";
+        recentTrace: string | null;
+    };
+    inbox: {
+        query: string;
+        isLoading: boolean;
+        items: InboxMessage[];
+        openedMessageId: string | null;
+    };
+};
+export type InboxEvent = {
+    type: "MessageOpened";
+    messageId: string;
+} | {
+    type: "SearchStarted";
+    query: string;
+} | {
+    type: "SearchSucceeded";
+    query: string;
+    items: InboxMessage[];
+} | {
+    type: "TraceUpdated";
+    summary: string;
+};
+export declare function createInitialInboxState(messages: InboxMessage[]): InboxState;
+export declare function reduceInboxState(state: InboxState, event: InboxEvent): InboxState;

package/dist/demo/inbox/state.js

@@ -0,0 +1,56 @@
+export function createInitialInboxState(messages) {
+    return {
+        shell: {
+            currentTab: "inbox",
+            recentTrace: null,
+        },
+        inbox: {
+            query: "",
+            isLoading: false,
+            items: messages,
+            openedMessageId: null,
+        },
+    };
+}
+export function reduceInboxState(state, event) {
+    switch (event.type) {
+        case "MessageOpened":
+            return {
+                ...state,
+                inbox: {
+                    ...state.inbox,
+                    openedMessageId: event.messageId,
+                    items: state.inbox.items.map((item) => item.id === event.messageId ? { ...item, opened: true } : item),
+                },
+            };
+        case "SearchStarted":
+            return {
+                ...state,
+                inbox: {
+                    ...state.inbox,
+                    query: event.query,
+                    isLoading: true,
+                },
+            };
+        case "SearchSucceeded":
+            return {
+                ...state,
+                inbox: {
+                    ...state.inbox,
+                    query: event.query,
+                    isLoading: false,
+                    items: event.items,
+                },
+            };
+        case "TraceUpdated":
+            return {
+                ...state,
+                shell: {
+                    ...state.shell,
+                    recentTrace: event.summary,
+                },
+            };
+        default:
+            return state;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export declare const VERSION = "0.0.0";
+export { createStore } from "./core/state/createStore";
+export { createSnapshotBundle } from "./core/snapshot/createSnapshotBundle";
+export { defineAction } from "./core/action/defineAction";
+export { createActionRuntime } from "./core/action/createActionRuntime";
+export { createToolBridge } from "./tool/createToolBridge";
+export { useDataRef } from "./ref/useDataRef";
+export { useArrayRef } from "./ref/useArrayRef";
+export { renderTUI } from "./projection/tui/renderTUI";
+export { createInboxApp } from "./demo/inbox/createInboxApp";

package/dist/index.js

@@ -0,0 +1,10 @@
+export const VERSION = "0.0.0";
+export { createStore } from "./core/state/createStore";
+export { createSnapshotBundle } from "./core/snapshot/createSnapshotBundle";
+export { defineAction } from "./core/action/defineAction";
+export { createActionRuntime } from "./core/action/createActionRuntime";
+export { createToolBridge } from "./tool/createToolBridge";
+export { useDataRef } from "./ref/useDataRef";
+export { useArrayRef } from "./ref/useArrayRef";
+export { renderTUI } from "./projection/tui/renderTUI";
+export { createInboxApp } from "./demo/inbox/createInboxApp";

package/dist/projection/gui/AppProvider.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentChildren } from "preact";
+type AppContextValue = {
+    store: {
+        getState(): unknown;
+    };
+    actionRuntime: {
+        executeAction(name: string, input: Record<string, unknown>): Promise<unknown>;
+        listVisibleTools(): Array<{
+            name: string;
+            description: string;
+        }>;
+    };
+};
+export declare function AppProvider(props: {
+    store: AppContextValue["store"];
+    actionRuntime: AppContextValue["actionRuntime"];
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function useAppContext(): AppContextValue;
+export {};

package/dist/projection/gui/AppProvider.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+const AppContext = createContext(null);
+export function AppProvider(props) {
+    return (_jsx(AppContext.Provider, { value: { store: props.store, actionRuntime: props.actionRuntime }, children: props.children }));
+}
+export function useAppContext() {
+    const context = useContext(AppContext);
+    if (!context) {
+        throw new Error("useAppContext must be used within AppProvider");
+    }
+    return context;
+}

package/dist/projection/gui/hooks.d.ts

@@ -0,0 +1,10 @@
+export declare function useAppState<State>(): {
+    state: State;
+};
+export declare function useActions(): {
+    callAction(name: string, input: Record<string, unknown>): Promise<unknown>;
+    getVisibleTools(): {
+        name: string;
+        description: string;
+    }[];
+};

package/dist/projection/gui/hooks.js

@@ -0,0 +1,18 @@
+import { useAppContext } from "./AppProvider";
+export function useAppState() {
+    const { store } = useAppContext();
+    return {
+        state: store.getState(),
+    };
+}
+export function useActions() {
+    const { actionRuntime } = useAppContext();
+    return {
+        callAction(name, input) {
+            return actionRuntime.executeAction(name, input);
+        },
+        getVisibleTools() {
+            return actionRuntime.listVisibleTools();
+        },
+    };
+}

package/dist/projection/tui/renderTUI.d.ts

@@ -0,0 +1,6 @@
+/** @jsxImportSource preact */
+import type { ComponentChild } from "preact";
+import type { ToolDefinition } from "../../core/types";
+export declare function renderTUI(node: ComponentChild, options: {
+    visibleTools: ToolDefinition[];
+}): import("../../core/types").SnapshotBundle;

package/dist/projection/tui/renderTUI.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+import renderToString from "preact-render-to-string";
+import { createRefCollector } from "../../core/ref/ref-index";
+import { createSnapshotBundle } from "../../core/snapshot/createSnapshotBundle";
+import { RefProvider } from "../../ref/RefContext";
+export function renderTUI(node, options) {
+    const collector = createRefCollector();
+    const tui = renderToString(_jsx(RefProvider, { registry: collector, children: node }));
+    return createSnapshotBundle({
+        tui,
+        refIndex: collector.snapshot(),
+        visibleTools: options.visibleTools,
+    });
+}

package/dist/ref/RefContext.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentChildren } from "preact";
+import type { RefIndexEntry } from "../core/types";
+type RefRegistry = {
+    register(refId: string, entry: RefIndexEntry): void;
+};
+export declare function RefProvider(props: {
+    registry: RefRegistry;
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function useRefRegistry(): RefRegistry;
+export {};

package/dist/ref/RefContext.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+const RefContext = createContext(null);
+export function RefProvider(props) {
+    return (_jsx(RefContext.Provider, { value: props.registry, children: props.children }));
+}
+export function useRefRegistry() {
+    const registry = useContext(RefContext);
+    if (!registry) {
+        throw new Error("useRefRegistry must be used within RefProvider");
+    }
+    return registry;
+}

package/dist/ref/useArrayRef.d.ts

@@ -0,0 +1 @@
+export declare function useArrayRef(type: string, data: object[], refId: string): readonly [(content: string) => string, (index: number, content: string) => string];

package/dist/ref/useArrayRef.js

@@ -0,0 +1,19 @@
+import { useRefRegistry } from "./RefContext";
+export function useArrayRef(type, data, refId) {
+    const registry = useRefRegistry();
+    const listRef = (content) => {
+        registry.register(refId, {
+            type: `${type}[]`,
+            value: data,
+        });
+        return `(${content})[${type}[]:${refId}]`;
+    };
+    const itemRef = (index, content) => {
+        registry.register(`${refId}[${index}]`, {
+            type,
+            value: data[index],
+        });
+        return `(${content})[${type}:${refId}[${index}]]`;
+    };
+    return [listRef, itemRef];
+}

package/dist/ref/useDataRef.d.ts

@@ -0,0 +1 @@
+export declare function useDataRef(type: string, data: object, refId: string): (content: string) => string;

package/dist/ref/useDataRef.js

@@ -0,0 +1,8 @@
+import { useRefRegistry } from "./RefContext";
+export function useDataRef(type, data, refId) {
+    const registry = useRefRegistry();
+    return (content) => {
+        registry.register(refId, { type, value: data });
+        return `(${content})[${type}:${refId}]`;
+    };
+}

package/dist/tool/createToolBridge.d.ts

@@ -0,0 +1,18 @@
+import type { SnapshotBundle, ActionResult } from "../core/types";
+export declare function createToolBridge(config: {
+    actionRuntime: {
+        listVisibleTools(): Array<{
+            name: string;
+            description: string;
+        }>;
+        executeAction(name: string, input: Record<string, unknown>): Promise<ActionResult>;
+    };
+    renderCurrentSnapshot(): SnapshotBundle;
+}): {
+    listTools(): {
+        name: string;
+        description: string;
+    }[];
+    getSnapshotBundle(): SnapshotBundle;
+    executeTool(name: string, input: Record<string, unknown>, snapshotId: string): Promise<ActionResult>;
+};

package/dist/tool/createToolBridge.js

@@ -0,0 +1,57 @@
+function resolveRefArgs(input, refIndex) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value === "string" && value in refIndex) {
+            resolved[key] = refIndex[value].value;
+            continue;
+        }
+        if (typeof value === "string" &&
+            (value.includes("[") || value.includes("]"))) {
+            return {
+                success: false,
+                refId: value,
+            };
+        }
+        resolved[key] = value;
+    }
+    return {
+        success: true,
+        data: resolved,
+    };
+}
+export function createToolBridge(config) {
+    const snapshots = new Map();
+    return {
+        listTools() {
+            return config.actionRuntime.listVisibleTools();
+        },
+        getSnapshotBundle() {
+            const snapshot = config.renderCurrentSnapshot();
+            snapshots.set(snapshot.snapshotId, snapshot);
+            return snapshot;
+        },
+        async executeTool(name, input, snapshotId) {
+            const snapshot = snapshots.get(snapshotId);
+            if (!snapshot) {
+                return {
+                    success: false,
+                    error: {
+                        code: "SNAPSHOT_NOT_FOUND",
+                        message: `Snapshot ${snapshotId} was not found`,
+                    },
+                };
+            }
+            const resolved = resolveRefArgs(input, snapshot.refIndex);
+            if (!resolved.success) {
+                return {
+                    success: false,
+                    error: {
+                        code: "REF_NOT_FOUND",
+                        message: `Reference ${resolved.refId} was not found in snapshot ${snapshotId}`,
+                    },
+                };
+            }
+            return config.actionRuntime.executeAction(name, resolved.data);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@aotui/mobile-ai-native",
+  "version": "0.1.0-alpha.0",
+  "description": "Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "test": "vitest",
+    "test:run": "vitest --run",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "preact": "^10.28.1",
+    "preact-render-to-string": "^6.6.6",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.5.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "GUIDE.md"
+  ],
+  "keywords": [
+    "agent-native",
+    "ios",
+    "mobile",
+    "llm",
+    "tui",
+    "state-machine",
+    "preact"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}