@hsafa/ui-sdk 0.3.3 → 0.4.1

package/docs/handbook/00-Overview.md

@@ -0,0 +1,69 @@
+# 00 — Overview
+
+This overview orients you across the SDK codebase, the Agent Studio client, and the server agent runtime.
+
+- SDK package root: `sdk/`
+- Public entry: `sdk/src/index.ts`
+- Provider: `sdk/src/providers/HsafaProvider.tsx`
+- Primary UI: `sdk/src/components/HsafaChat.tsx`
+- Headless hooks: `sdk/src/hooks/*`
+- Dynamic pages: `sdk/src/components/dynamic-page/`
+- Built-in tools/UI for the agent: `sdk/src/components/hsafa-chat/utils/`
+- Client Agent Studio: `client/src/features/agent/`
+- Server agent runtime: `server/src/modules/agents/`
+
+## Repository map (selected)
+
+- `sdk/`
+  - `src/index.ts` — re-exports components, hooks, providers, dynamic page utilities, types.
+  - `src/providers/HsafaProvider.tsx` — context with config, streaming/open state, dynamic page type registration.
+  - `src/components/HsafaChat.tsx` — production chat component built on Vercel AI SDK v5. Integrates tools, UI injection, persistence, and dynamic page tools.
+  - `src/components/hsafa-chat/` — child UI parts (header, input, history, message list, editor, error boundary) and streaming helpers.
+  - `src/components/hsafa-chat/utils/`
+    - `transport.ts` — `createHsafaTransport(baseUrl, agentId, chatId)` using `DefaultChatTransport`.
+    - `builtInTools.ts` — `getDomComponents`, `controlCursor`, `fillActiveInput`, `requestInput`.
+    - `renderUserForm.ts` — runtime-rendered inline forms for `requestInput` tool.
+  - `src/components/web-controler/` — DOM discovery and cursor control utilities for built-in tools.
+  - `src/hooks/` — `useHsafaAgent`, `useChatStorage`, `useFileUploadHook`, `useMessageEditor`, `useAutoScroll`.
+  - `src/components/dynamic-page/` — dynamic page runtime, operations, storage, and tools factory.
+  - `src/types/` — shared public types (`chat.ts`, `messages.ts`).
+  - `docs/` — Advanced guide and generated API (`docs/api/`).
+
+- `client/src/features/agent/` — Agent Studio (builder):
+  - `AgentPage.tsx`, `components/AgentFlow.tsx`, `hooks/useAgentFlow.ts`, `components/nodes/*`.
+  - Designs agents as flow graphs (nodes/edges); persists in database via GraphQL/backend.
+
+- `server/src/modules/agents/`
+  - `run-agent-handler.ts` — HTTP handler for `POST /api/run/:id` streaming via Vercel AI SDK v5 (`streamText` + `toUIMessageStream`).
+  - `run-core/*` — model providers, MCP, tools setup, prompts, utilities.
+  - `agent-service.ts` — CRUD for agents with Prisma.
+
+## High-level data flow
+
+```mermaid
+flowchart LR
+  UI[HsafaChat/useHsafaAgent] -- UIMessage[] --> /api/run/:agentId
+  Server -- stream NDJSON --> UI
+  subgraph Client
+    UI --> Tools[built-in + custom tools]
+    Tools --> UI
+    UI --> Storage[useChatStorage]
+  end
+  subgraph Server
+    Handler[run-agent-handler.ts]\nconvertToModelMessages
+    Handler --> streamText --> UIStream
+    UIStream --> toUIMessageStream --> NDJSON
+    ToolsSetup[run-core/tools.ts]\nMCP
+  end
+```
+
+## Public exports (from `src/index.ts`)
+
+- Components: `HsafaChat`, `ContentContainer`, `Button`, `FloatingChatButton`
+- Provider: `HsafaProvider`, `useHsafa`
+- Hooks: `useHsafaAgent`, `useChatStorage`, `useFileUploadHook`, `useAutoScroll`, `useMessageEditor`
+- Dynamic pages: `DynamicPage`, `useDynamicPage`, `createDynamicPageTools`, storage helpers, types
+- Web controller tools: `getDomComponents`, `guideCursor`, `controlCursor`, `FillActiveInput`, `CursorController`
+- Types: selected chat types
+
+See also `sdk/docs/README.md` and `sdk/docs/api/`.

package/docs/handbook/01-Quickstart.md

@@ -0,0 +1,133 @@
+# 01 — Quickstart
+
+This quickstart shows how to install the SDK, render the chat UI, and optionally build a custom headless UI.
+
+## Install
+
+```bash
+pnpm add @hsafa/ui-sdk
+# or
+yarn add @hsafa/ui-sdk
+# or
+npm i @hsafa/ui-sdk
+```
+
+Peer deps: React 18+, React DOM 18+.
+
+## Minimal UI setup
+
+Wrap your app with the provider and render `HsafaChat`.
+
+```tsx
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+
+export default function App() {
+  return (
+    <HsafaProvider baseUrl={process.env.NEXT_PUBLIC_API_BASE || ''}>
+      <HsafaChat agentId="my-agent" theme="dark" />
+    </HsafaProvider>
+  );
+}
+```
+
+- `baseUrl` points to your backend. The chat posts to `POST {baseUrl}/api/run/:agentId`.
+- File uploads post to `POST {baseUrl}/api/uploads`.
+
+## Customizing the chat
+
+`HsafaChat` supports theming and UI options (see `sdk/src/types/chat.ts`).
+
+```tsx
+<HsafaChat
+  agentId="my-agent"
+  theme="light"
+  primaryColor="#3b82f6"
+  backgroundColor="#ffffff"
+  borderColor="#e5e7eb"
+  textColor="#111827"
+  accentColor="#F9FAFB"
+/>
+```
+
+## Adding custom UI components and tools
+
+- UI components: pass via `HsafaUI` prop or via the headless hook (see below). The agent can render them by name via the `ui` tool.
+
+```tsx
+function ProductCard({ name, price }: { name: string; price: number }) {
+  return <div>{name}: ${price}</div>;
+}
+
+<HsafaChat agentId="my-agent" HsafaUI={{ ProductCard }} />
+```
+
+- Frontend tools: pass as `HsafaTools` to `HsafaChat`. Each tool is a function or `{ tool, executeEachToken }`.
+
+```tsx
+const tools = {
+  add: async ({ a, b }: any) => ({ sum: a + b })
+};
+
+<HsafaChat agentId="my-agent" HsafaTools={tools} />
+```
+
+## Headless: build your own chat UI
+
+Use `useHsafaAgent` for full control over rendering.
+
+```tsx
+import { useHsafaAgent } from '@hsafa/ui-sdk';
+
+export function MyChat() {
+  const agent = useHsafaAgent({
+    agentId: 'my-agent',
+    baseUrl: '',
+    tools: {
+      add: async ({ a, b }) => ({ sum: a + b }),
+    },
+    uiComponents: {
+      ProductCard: ({ name, price }: any) => <div>{name}: ${price}</div>,
+    },
+  });
+
+  return (
+    <div>
+      {agent.messages.map((m) => (
+        <pre key={m.id}>{JSON.stringify(m, null, 2)}</pre>
+      ))}
+      <input value={agent.input} onChange={(e) => agent.setInput(e.target.value)} />
+      <button onClick={() => agent.sendMessage()}>Send</button>
+    </div>
+  );
+}
+```
+
+## Persist chat history
+
+Use `useChatStorage` to manage chat history, switching, and metadata. `HsafaChat` uses the same storage utility under the hood.
+
+```tsx
+import { useChatStorage } from '@hsafa/ui-sdk';
+
+function History({ agentId, chatId, messages, setMessages }: any) {
+  const storage = useChatStorage({ agentId, chatId, messages, isLoading: false });
+  return (
+    <div>
+      {storage.chatList.map((m) => (
+        <button key={m.id} onClick={() => storage.switchToChat(m.id, setMessages)}>
+          {m.title}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## Backend endpoint
+
+Implement `POST /api/run/:agentId` using the Vercel AI SDK v5. Reference: `server/src/modules/agents/run-agent-handler.ts`.
+
+- Input: `{ messages: UIMessage[], ... }` (the SDK automatically adds `chatId` via `createHsafaTransport`).
+- Output: NDJSON stream produced via `createUIMessageStreamResponse`.
+
+If you already use the provided server code, the SDK will work out of the box.

package/docs/handbook/02-Architecture.md

@@ -0,0 +1,75 @@
+# 02 — Architecture
+
+This section explains how the SDK layers fit together across UI, hooks, storage, transport, and the server runtime.
+
+## Layers
+
+- **Provider**: `sdk/src/providers/HsafaProvider.tsx`
+  - Holds SDK config (`baseUrl`, `dir`, `theme`).
+  - Tracks per-chat streaming/open state and dynamic page types.
+- **Chat UI**: `sdk/src/components/HsafaChat.tsx`
+  - Vercel AI SDK v5 `useChat` based.
+  - Integrates tools (`HsafaTools`) and renderable UI components (`HsafaUI`), plus inline form rendering for `requestInput`.
+  - Persists chat history via `createChatStorage()` and `useChatStorage()`.
+- **Headless Agent**: `sdk/src/hooks/useHsafaAgent.ts`
+  - Same semantics as `HsafaChat` without UI.
+  - Exposes `messages`, `sendMessage()`, `stop()`, `chatId`, `setChatId()`, tool/UI plumbing, and form handling.
+- **Storage**: `sdk/src/hooks/useChatStorage.ts`, `sdk/src/utils/chat-storage.ts`
+  - LocalStorage-based persistence per `agentId`.
+- **Transport**: `sdk/src/components/hsafa-chat/utils/transport.ts`
+  - `createHsafaTransport(baseUrl, agentId, chatId)` wraps `DefaultChatTransport` and injects `chatId`.
+- **Tools & UI**: `sdk/src/components/hsafa-chat/utils/`
+  - Built-in browser tools (cursor control, DOM discovery, fill input) and inline form renderer for `requestInput`.
+- **Dynamic Pages**: `sdk/src/components/dynamic-page/*`
+  - Runtime for rendering complex, tool-driven UI pages.
+
+## Data contracts
+
+- **Client → Server**: UI messages via Vercel AI SDK v5 `useChat()`.
+  - The SDK posts to `POST {baseUrl}/api/run/:agentId` with body `{ messages: UIMessage[], chatId, ... }`.
+- **Server → Client**: NDJSON stream created by `createUIMessageStreamResponse()`.
+  - Contains deltas for text, tool calls/results, reasoning, and final response items.
+
+## Message flow
+
+```mermaid
+sequenceDiagram
+  participant UI as HsafaChat/useHsafaAgent
+  participant S as Server run-agent-handler
+  UI->>S: POST /api/run/:agentId (UIMessage[])
+  S-->>UI: NDJSON stream (toUIMessageStream)
+  UI->>UI: render deltas (text, tool-calls, ui, reasoning)
+  UI->>UI: addToolResult() after tools/inline UI
+```
+
+## Tool execution
+
+- **Frontend tools**: provided as functions in `HsafaTools` (or `tools` for headless). Executed inside `onToolCall` when the tool name matches.
+- **UI tools**: the agent can request `ui` or a registered component name. Rendering is deferred; result posted with `addToolResult()` on success/error.
+- **Request input**: special tool that renders a form inside a message using `renderUserForm.ts` and waits for user.
+
+## Persistence model
+
+Storage keys (from `createChatStorage()`):
+- Index: `hsafaChat_${agentId}.chats`
+- Chat data: `hsafaChat_${agentId}.chat.${chatId}`
+- Current chat id: `hsafaChat_${agentId}.currentChatId`
+- Show chat: `hsafaChat_${agentId}.showChat`
+
+## Dynamic Page integration
+
+- Register dynamic page types via `HsafaProvider.registerDynamicPageTypes()`.
+- Use `useDynamicPage(chatId, types)` and `createDynamicPageTools(getOperations)` to expose operations to the agent.
+
+## Server architecture (overview)
+
+- `server/src/modules/agents/run-agent-handler.ts`:
+  - Loads agent config (nodes/edges) from Prisma.
+  - Builds model/tool stack (including MCP) via `run-core/*`.
+  - Converts `UIMessage[]` to model messages (`convertToModelMessages`).
+  - Streams via `streamText(...).toUIMessageStream()` and returns `createUIMessageStreamResponse()`.
+- `run-core/` includes:
+  - `models.ts` (provider factories),
+  - `mcp.ts` (MCP runtime),
+  - `tools/` (HTTP, web_control, etc.),
+  - `prompts.ts` (system prompt construction).

package/docs/handbook/03-Components-and-Hooks.md

@@ -0,0 +1,81 @@
+# 03 — Components & Hooks
+
+This is a practical catalogue of public components, hooks, and types, with examples and source references.
+
+## Components
+
+- **`HsafaChat`** (`sdk/src/components/HsafaChat.tsx`)
+  - Full-featured chat UI built on Vercel AI SDK v5.
+  - Props (selected — see `sdk/src/types/chat.ts` for all):
+    - `agentId: string` (required)
+    - `theme?: 'dark' | 'light'`
+    - Colors: `primaryColor`, `primaryColorDark`, `primaryColorLight`, `backgroundColor`, `borderColor`, `textColor`, `accentColor`
+    - Layout: `width`, `height`, `defaultOpen`, `floatingButtonPosition`
+    - Behavior/UI: `componentAboveInput`, `editProcessContent`
+    - Extensions: `HsafaTools?: Record<string, HsafaTool>`, `HsafaUI?: Record<string, React.ComponentType<any>>`, `dynamicPageTypes?: any[]`
+  - Example:
+    ```tsx
+    <HsafaChat
+      agentId="my-agent"
+      theme="dark"
+      HsafaTools={{ add: async ({ a, b }) => ({ sum: a + b }) }}
+      HsafaUI={{ ProductCard: (p: any) => <div>{p.name}</div> }}
+    />
+    ```
+
+- **`ContentContainer`** (`sdk/src/components/ContentContainer.tsx`)
+  - Generic content wrapper used across docs/examples.
+
+- **`FloatingChatButton`** (`sdk/src/components/FloatingChatButton.tsx`)
+  - Floating FAB to reopen a minimized chat.
+
+## Provider
+
+- **`HsafaProvider`** (`sdk/src/providers/HsafaProvider.tsx`)
+  - Props: `baseUrl?: string`, `dir?: 'ltr' | 'rtl'`, `theme?: 'dark' | 'light'`.
+  - Context via `useHsafa()`:
+    - Streaming/open state per chat: `setStreamingState(chatId, isStreaming)`, `setChatOpenState(chatId, isOpen)`.
+    - `currentChatId`, dynamic page type registration.
+  - Extensions are passed directly to `HsafaChat` (`HsafaTools`, `HsafaUI`) or to `useHsafaAgent` (`tools`, `uiComponents`).
+
+## Hooks
+
+- **`useHsafaAgent(config)`** (`sdk/src/hooks/useHsafaAgent.ts`)
+  - Headless agent hook used by `HsafaChat`.
+  - Input (selected): `{ agentId, baseUrl?, tools: HsafaTools?, uiComponents: HsafaUI?, dynamicPageTypes?, onFinish?, onError?, initialMessages?, onMessagesChange? }`
+  - Output (selected):
+    - State: `input`, `messages`, `isLoading`, `status`, `error`
+    - Actions: `setInput`, `sendMessage({ text?, files? })`, `stop()`, `newChat()`, `setMessages(messages)`
+    - Advanced: `chatApi`, `chatId`, `setChatId(id)`, `tools`, `uiComponents`, `dynamicPage`
+    - Inline forms/UI: `formHostRef`, `formStateRef`, `cleanupForms()`, `onUISuccess()`, `onUIError()`
+  - Example:
+    ```tsx
+    const agent = useHsafaAgent({ agentId: 'my-agent', baseUrl: '' });
+    agent.setInput('Hello');
+    await agent.sendMessage();
+    ```
+
+- **`useChatStorage(config)`** (`sdk/src/hooks/useChatStorage.ts`)
+  - Input: `{ agentId, chatId, messages, isLoading?, autoSave?, autoRestore? }`
+  - Output: `{ chatList, currentChatMeta, refreshChatList, loadChat, saveCurrentChat, deleteChat, switchToChat, createNewChat, searchChats, storage }`
+  - `storage` is the raw util from `sdk/src/utils/chat-storage.ts` with keys prefixed by `hsafaChat_${agentId}`.
+
+- **`useFileUploadHook(baseUrl?)`** (`sdk/src/hooks/useFileUploadHook.ts`)
+  - Output: `{ attachments, uploading, fileInputRef, formatBytes, handleRemoveAttachment, handleFileSelection, buildUserContent, clearAttachments, setAttachments }`
+  - Posts to `{baseUrl}/api/uploads`.
+
+- **`useMessageEditor(config)`** (`sdk/src/hooks/useMessageEditor.ts`)
+  - Utilities for message editing+regeneration from a point in history.
+  - Output: `{ editingMessageId, editingText, setEditingText, editAttachments, setEditAttachments, editUploading, startEdit, cancelEdit, saveEdit, isEditing, addEditAttachments, removeEditAttachment }`
+
+- **`useAutoScroll<T>()`** (`sdk/src/hooks/useAutoScroll.ts`)
+  - Auto-scroll container to bottom while streaming.
+
+## Types
+
+- From `sdk/src/types/chat.ts` (selected):
+  - `Attachment`, `UserContentPart`, `AssistantContentPart`, `ChatMessage`
+  - `HsafaTool`
+  - `HsafaChatProps`, `EditProcessContent`
+
+Refer to `sdk/src/index.ts` for the full export surface.

package/docs/handbook/04-Streaming-and-Transport.md

@@ -0,0 +1,73 @@
+# 04 — Streaming & Transport
+
+The SDK uses Vercel AI SDK v5 for robust, incremental streaming of assistant responses, tool calls, and UI instructions.
+
+## Transport
+
+- File: `sdk/src/components/hsafa-chat/utils/transport.ts`
+- Function: `createHsafaTransport(baseUrl, agentId, chatId)`
+  - Wraps `DefaultChatTransport` to point to `POST {baseUrl}/api/run/:agentId`.
+  - Injects `chatId` into the request body so the server can correlate sessions.
+
+```ts
+import { DefaultChatTransport } from 'ai';
+
+export function createHsafaTransport(baseUrl: string, agentId: string, chatId: string) {
+  return new DefaultChatTransport({
+    api: `${baseUrl}/api/run/${agentId}`,
+    fetch: async (input, init) => {
+      const body = init?.body ? JSON.parse(init.body as string) : {};
+      const enhancedBody = { ...body, chatId };
+      return fetch(input, { ...init, body: JSON.stringify(enhancedBody) });
+    },
+  });
+}
+```
+
+## Client streaming: useChat (v5)
+
+Both `HsafaChat` and `useHsafaAgent` wire `useChat({ transport, sendAutomaticallyWhen, onToolCall, onFinish, onError })`.
+
+- `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls` — automatically resubmits after tool results are added.
+- `onToolCall` — resolves frontend tools and UI rendering.
+- `addToolResult({ tool, toolCallId, output | state: 'output-error', errorText })` — posts results/errors back to the assistant message.
+
+### UI tool calls
+
+- If the tool name is `'ui'` or matches a registered UI component, rendering is deferred to the message renderer (`MessageList/AssistantMassage`).
+- Success/error is acknowledged via `onUISuccess(toolCallId, toolName)` / `onUIError(toolCallId, toolName, error)` which then call `addToolResult`.
+
+### Request input (inline forms)
+
+- Special tool `'requestInput'` renders a form inside the message using `renderUserForm.ts`.
+- The form posts a tool result when submitted or skipped.
+
+## Server streaming
+
+- File: `server/src/modules/agents/run-agent-handler.ts`
+- Core pipeline:
+  1) Parse `UIMessage[]` from request body (AI SDK v5 format) and convert to model messages via `convertToModelMessages()`.
+  2) Build model/tools (including MCP) using `run-core/*`.
+  3) Call `streamText({ model, tools, messages, ... })`.
+  4) Convert to a UI message stream: `const uiStream = agentResponse.toUIMessageStream({ originalMessages: uiMessages })`.
+  5) Send with `createUIMessageStreamResponse({ stream, originalMessages })`.
+
+### Event types
+
+Common NDJSON events (consumed by the AI SDK v5 UI layer):
+
+- Text: `text-delta`, `text-end`
+- Reasoning: `reasoning-start`, `reasoning-delta`, `reasoning-end`
+- Tools: `tool-call`, `tool-result`, `tool-error`
+- Final: `final` (with `value.items`)
+- Error: `error`
+
+The client’s `useChat` integrates these automatically into assistant messages.
+
+## File uploads
+
+- Hook: `useFileUploadHook(baseUrl?)`
+- Endpoint: `POST {baseUrl}/api/uploads`
+- Response JSON should include: `{ id, name, url, mimeType, size }`.
+
+Uploaded files are attached to the next user message as AI SDK v5 file parts (the SDK converts `url` to proper `data` where needed).

package/docs/handbook/05-Tools-and-UI.md

@@ -0,0 +1,73 @@
+# 05 — Tools & UI
+
+This section documents built-in tools/UI and how to add your own front-end tools and renderable UI components.
+
+## Built-in tools (frontend)
+
+File: `sdk/src/components/hsafa-chat/utils/builtInTools.ts`
+
+- **`getDomComponents`**
+  - Discovers DOM components (optionally including hidden) for web control scenarios.
+  - Signature: `{ includeHidden?: boolean, selector?: string }` → DOM metadata
+- **`controlCursor`**
+  - Guides a visual cursor to move/click/drag on elements for demos or automation.
+  - Signature: `{ target: string | { x,y }, action?: 'move'|'click'|'drag', anchor?, durationMs?, dragTo? }`
+- **`fillActiveInput`**
+  - Fills the currently focused input.
+  - Signature: `{ value: string }`
+- **`requestInput`**
+  - Special tool to request form input from the user inside a message. The form is rendered inline and its submission posts a tool result.
+
+All built-ins are available automatically via `useHsafaAgent`/`HsafaChat` under their tool names.
+
+### Progressive tool execution
+
+If a tool config has `{ executeEachToken: true }`, it will be executed on streaming deltas via `useStreamingToolInput.ts` when the input changes.
+
+```ts
+// Example from dynamic page tools
+editObject: {
+  executeEachToken: true,
+  tool: async (input) => { /* ... */ }
+}
+```
+
+## Built-in UI components
+
+File: `sdk/src/components/hsafa-chat/utils/builtInUI.tsx`
+
+- **`plainText`**: renders markdown text with Mermaid support using `MarkdownRendererWithMermaid`.
+- Always available (no need to register in `HsafaUI`).
+
+## Rendering custom UI from agent
+
+Expose UI to the agent by passing `HsafaUI` to `HsafaChat` (or `uiComponents` to `useHsafaAgent`). The agent can then emit a UI tool call to render the component by name.
+
+```tsx
+<HsafaChat agentId="my-agent" HsafaUI={{ ProductCard }} />
+```
+
+The agent can request a UI component by returning a tool call named `'ui'` or the exact component name. Rendering is deferred and when complete, `addToolResult` is emitted with `{ rendered: true }`.
+
+## Inline forms: `requestInput`
+
+File: `sdk/src/components/hsafa-chat/utils/renderUserForm.ts`
+
+- Renders a form host inside the assistant message for a specific `toolCallId`.
+- Persists form state across rerenders (submitted/skipped/values).
+- Posts results via `addToolResult({ tool: 'requestInput', toolCallId, output })`.
+
+## Adding your own tools
+
+Pass a map of tools to the chat component or the headless hook.
+
+```tsx
+const tools = {
+  add: async ({ a, b }: any) => ({ sum: a + b }),
+  myTool: { executeEachToken: false, tool: async (input: any) => ({ ok: true }) },
+};
+
+<HsafaChat agentId="my-agent" HsafaTools={tools} />
+```
+
+Each tool receives `input` from the agent. Return values are serialized and sent back via `addToolResult`.

package/docs/handbook/06-Storage-and-History.md

@@ -0,0 +1,63 @@
+# 06 — Storage & History
+
+Local persistence is handled via `useChatStorage` and the lower-level `createChatStorage` utility.
+
+## Storage utility
+
+File: `sdk/src/utils/chat-storage.ts`
+
+- Prefix: `hsafaChat_${agentId}`
+- Keys:
+  - Index: `hsafaChat_${agentId}.chats` — array of `{ id, title, createdAt, updatedAt }`
+  - Chat data: `hsafaChat_${agentId}.chat.${chatId}` — `{ id, messages, agentId? }`
+  - Current chat id: `hsafaChat_${agentId}.currentChatId`
+  - Show chat flag: `hsafaChat_${agentId}.showChat`
+- API:
+  - `loadChatsIndex()`, `saveChatsIndex(list)`
+  - `loadChat(id)`, `saveChat(data)`
+  - `upsertChatMeta(meta)`
+  - `deleteChatMeta(id)`, `deleteChatData(id)`, `deleteChat(id)`
+  - `loadShowChatPreference(default)`, `saveShowChatPreference(value)`
+  - `loadCurrentChatId()`, `saveCurrentChatId(id)`, `removeCurrentChatId()`
+
+## Hook: useChatStorage
+
+File: `sdk/src/hooks/useChatStorage.ts`
+
+Input:
+```ts
+useChatStorage({ agentId, chatId, messages, isLoading?, autoSave = true, autoRestore = true })
+```
+
+Output (selected):
+- `chatList: ChatMetadata[]`
+- `currentChatMeta: ChatMetadata | null`
+- `refreshChatList()`
+- `loadChat(chatId)`
+- `saveCurrentChat()`
+- `deleteChat(chatId)`
+- `switchToChat(chatId, setMessages)` — loads and applies stored messages
+- `createNewChat(onNewChat)` — not a saver; executes `onNewChat()` which should set a new `chatId`
+- `searchChats(query)`
+- `storage` — underlying `createChatStorage(agentId)` instance
+
+### Auto-save behavior
+
+- On first user message, inserts a chat meta with a title derived from the first user text part.
+- On subsequent message updates (and when `!isLoading`), saves chat data and updates `updatedAt`.
+- After a streaming session finishes, saves one more time to ensure the final assistant message is captured.
+
+### Using with `HsafaChat` or headless
+
+- `HsafaChat` uses the same storage semantics, saving UI preferences (`.showChat`) as well.
+- In headless UIs, couple `useChatStorage` with `useHsafaAgent` by wiring `chatId`, `messages`, and `setMessages`.
+
+### Example: chat switching
+
+```tsx
+const storage = useChatStorage({ agentId, chatId, messages, isLoading });
+
+function openChat(id: string) {
+  storage.switchToChat(id, agent.setMessages);
+}
+```

package/docs/handbook/07-Dynamic-Pages.md

@@ -0,0 +1,49 @@
+# 07 — Dynamic Pages
+
+Dynamic Pages let the agent construct and manipulate a UI page (grid of objects/components) by calling dedicated tools. This is useful for dashboards, inspectors, and interactive builders.
+
+## Files
+
+- Runtime: `sdk/src/components/dynamic-page/DynamicPage.tsx`
+- Operations: `sdk/src/components/dynamic-page/operations.ts`
+- Tools factory: `sdk/src/components/dynamic-page/tools.ts`
+- Storage: `sdk/src/components/dynamic-page/storage.ts`
+- Types: `sdk/src/components/dynamic-page/types.ts`
+- Hook: `sdk/src/components/dynamic-page/useDynamicPage.ts`
+
+## Enabling in HsafaChat
+
+1) Declare supported dynamic page types in your app and pass as `dynamicPageTypes` prop (or via `useHsafaAgent`).
+2) `HsafaChat` registers types with `HsafaProvider` and creates dynamic page tools using `createDynamicPageTools(getOperations)`.
+
+```tsx
+<HsafaChat
+  agentId="my-agent"
+  dynamicPageTypes={[ /* type configs */ ]}
+/>
+```
+
+## Tools
+
+From `createDynamicPageTools(getOperations)`:
+
+- `setGrid(input)` / `readGrid()` / `validateGrid()`
+- `readAvailableTypes()`
+- `setObject(input)` (streaming friendly)
+- `editObject(input)` (streaming friendly; merges options for safe defaults)
+- `deleteObject(input)`
+- `readAllObjects()` / `readObject(input)` / `readAtPointer(input)`
+- `renameObject(input)` / `moveObject(input)`
+- `readComponentErrors(input)` / `clearComponentErrors()`
+
+All functions call into `DynamicPageOperations` returned by `useDynamicPage().getOperations`.
+
+## Storage helpers
+
+- `saveDynamicPageState(id, state)` / `loadDynamicPageState(id)` / `deleteDynamicPageState(id)` / `dynamicPageExists(id)`
+
+## Recommended usage pattern
+
+- Enable dynamic pages only for specific chats where needed.
+- Let the agent progressively build the page while streaming tool inputs.
+- Use UI components to visualize objects; integrate with your own component library.