@swarm.ing/pieui 2.1.5 → 2.1.7

package/README.md

@@ -1,22 +1,93 @@
 # PieUI
 
-PieUI is a React component library for rendering server-driven UI "cards" with optional real-time and AJAX updates. It provides a component registry, root wrappers that set up providers, and helpers for styling and class name management.
-
-**Install**
+**PieUI** (`@swarm.ing/pieui`) is a React library for rendering **server-driven UIs**. A backend returns a JSON description of a screen, and PieUI turns it into a React tree by looking up each node in a component **registry**. On top of rendering it ships real-time messaging (Socket.IO, Centrifuge, Mitt), server-driven AJAX updates, host integrations (Telegram Mini Apps, MAX, React Native), an OpenAI voice-agent bridge, a Storybook addon, and a `pieui` CLI for scaffolding apps, pages, and cards.
+
+- **Server-driven** — screens are described by data (`UIConfigType`), not code.
+- **Registry-based** — register components by name; the backend references them by that name.
+- **Real-time** — cards can subscribe to Socket.IO, Centrifuge, or in-process Mitt events.
+- **Multi-platform** — web, Telegram Mini Apps, MAX (VK), and React Native from one core.
+- **Tooling** — a CLI that scaffolds Next.js apps, generates cards/pages, and syncs a component registry.
+
+> React and React DOM `>=19` are peer dependencies. React Native `>=0.74` and `@openai/agents` are **optional** peers (only needed for the `/native` and `/agent` entries).
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Core concepts](#core-concepts)
+- [Quick start](#quick-start)
+- [Package entry points](#package-entry-points)
+- [Root components](#root-components)
+- [Registering components](#registering-components)
+- [Component prop shapes](#component-prop-shapes)
+- [Built-in cards](#built-in-cards)
+- [Real-time messaging](#real-time-messaging)
+- [Server-driven AJAX updates](#server-driven-ajax-updates)
+- [`depsNames` — client-side submit sources](#depsnames--client-side-submit-sources)
+- [Configuration & environment](#configuration--environment)
+- [Registry API](#registry-api)
+- [Styling helpers](#styling-helpers)
+- [Platform integrations](#platform-integrations)
+  - [Telegram Mini Apps](#telegram-mini-apps)
+  - [MAX (VK Messenger)](#max-vk-messenger)
+  - [React Native](#react-native)
+- [OpenAI agent integration](#openai-agent-integration)
+- [Storybook integration](#storybook-integration)
+- [CLI reference](#cli-reference)
+- [API reference](#api-reference)
+- [License](#license)
+
+---
+
+## Installation
 
 ```sh
 bun add @swarm.ing/pieui
+# or
 npm install @swarm.ing/pieui
+# or
+pnpm add @swarm.ing/pieui
+```
+
+```jsonc
+// peerDependencies
+"react": ">=19",
+"react-dom": ">=19",
+"react-native": ">=0.74",     // optional — only for @swarm.ing/pieui/native
+"@openai/agents": "^0.4.5"     // optional — only for @swarm.ing/pieui/agent
 ```
 
-React and React DOM `>=19` are peer dependencies.
+---
+
+## Core concepts
+
+**Server-driven UI.** The backend describes a screen as a tree of `UIConfigType` nodes:
+
+```ts
+interface UIConfigType {
+    card: string                              // registry name of the component to render
+    data: any                                 // props bag passed to the component as `data`
+    content: UIConfigType | UIConfigType[]    // nested child config(s), if any
+}
+```
+
+**The registry.** Every renderable component is registered under a `name`. The renderer (`UI`) reads `config.card`, looks it up in the registry, and renders it — passing `data`, `content`, and `setUiAjaxConfiguration` as appropriate.
+
+**Cards.** A "card" is just a registered React component. PieUI ships a handful of built-in container/leaf cards (`SequenceCard`, `BoxCard`, `HTMLEmbedCard`, …) and you register your own for everything app-specific.
+
+**Side-effect registration.** Importing from `@swarm.ing/pieui` (or `@swarm.ing/pieui/components`) registers the built-in cards automatically as a side effect — there is **no `initializePieComponents()` call to make** anymore. Your own cards register themselves when their module is imported (see [Registering components](#registering-components)).
+
+---
 
-**Quick Start**
+## Quick start
 
 ```tsx
-import { PieRoot, initializePieComponents } from '@swarm.ing/pieui'
+'use client'
 
-initializePieComponents()
+import { PieRoot } from '@swarm.ing/pieui'
+// Importing your registry module triggers side-effect registration of your cards.
+import './piecomponents/registry'
 
 export function App() {
     return (
@@ -25,8 +96,8 @@ export function App() {
                 pathname: window.location.pathname,
                 search: window.location.search,
             }}
-            fallback={<>Loading...</>}
-            onError={() => console.error('Failed to load UI')}
+            fallback={<>Loading…</>}
+            onError={() => window.location.reload()}
             onNavigate={(url) => {
                 window.location.href = url
             }}
@@ -36,17 +107,77 @@ export function App() {
                     'wss://realtime.example.com/connection/websocket',
                 enableRenderingLog: false,
             }}
-            initializePie={() => {
-                // Register custom components here if needed.
-            }}
         />
     )
 }
 ```
 
-If you are embedding PieUI inside a Telegram WebApp, use `PieTelegramRoot` instead of `PieRoot`.
+`PieRoot` fetches the screen config from `` `${config.apiServer}/api/content${pathname}?${search}` `` with React Query + Axios, sets up every provider PieUI needs, and renders the resulting tree.
+
+- **Telegram Mini App?** Use `PieTelegramRoot` from `@swarm.ing/pieui/telegram`.
+- **MAX mini-app?** Use `PieMaxRoot` from `@swarm.ing/pieui/max`.
+- **React Native?** Use `PieRoot`/`PieNativeRoot` from `@swarm.ing/pieui/native`.
+
+---
+
+## Package entry points
+
+PieUI is split into focused entry points so apps only ship what they use:
+
+| Import path                        | Contents                                                                                  |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| `@swarm.ing/pieui`                 | Main barrel: roots, `UI`, `PieCard`, registry API, hooks, types, built-in card side-effect |
+| `@swarm.ing/pieui/components`      | Just the built-in cards + `UI`/`PieCard` (registers built-ins on import)                  |
+| `@swarm.ing/pieui/telegram`        | `PieTelegramRoot`, Telegram WebApp hooks, `CloudStorageCard`/`SecureStorageCard`          |
+| `@swarm.ing/pieui/max`             | `PieMaxRoot` and MAX (VK) WebApp hooks                                                     |
+| `@swarm.ing/pieui/native`          | React Native core + native card variants + native source wiring                          |
+| `@swarm.ing/pieui/agent`           | OpenAI agent tools (`getMittAgentTools`, `useOpenAIWebRTC`) — pulls in `@openai/agents`   |
+| `@swarm.ing/pieui/storybook`       | Storybook providers/decorators for testing cards in isolation                            |
+| `@swarm.ing/pieui/storybook/addon` | Storybook addon (panel + manager) for firing PieCard methods from the Storybook UI       |
+
+The Telegram, MAX, and agent integrations are deliberately split out so apps that don't target those hosts never bundle their code.
+
+---
+
+## Root components
+
+All roots wrap children in the PieUI provider stack (React Query, Mitt, Socket.IO, Centrifuge, config, navigation, and — unless disabled — a global `<form>`).
+
+### `PieRoot`
 
-**Register Custom Components**
+Fetches a `UIConfigType` from `api/content{pathname}{search}` and renders it.
+
+| Prop                | Type                                          | Description                                                                                                   |
+| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `location`          | `{ pathname: string; search: string }`        | Current route. Used to build the request URL and as part of the React Query key.                             |
+| `config`            | `PieConfig`                                    | Runtime configuration (API URLs, logging, page processor). **Required.**                                     |
+| `fallback`          | `ReactNode`                                    | Rendered while loading or on fetch failure.                                                                   |
+| `piecache`          | `Record<string, UIConfigType>`                 | Optional per-pathname snapshot; a cached shell is shown via `UILoading` instead of the plain `fallback`.     |
+| `onError`           | `(error?: unknown) => void`                    | Called on a render-blocking error (config fetch throws, or a lazy card chunk fails after retries).           |
+| `onNavigate`        | `(url: string) => void`                        | Navigation handler forwarded through `NavigateContext` so cards route via the host router, not a full reload. |
+| `queryOptions`      | `PieQueryOptions`                              | React Query overrides (everything except `queryKey`/`queryFn`/`enabled`, which PieRoot manages).             |
+| `queryClient`       | `QueryClient`                                  | Supply a stable (module-singleton) client so the config cache survives remounts. Otherwise one is made per mount. |
+| `disableGlobalForm` | `boolean`                                      | When `true`, the implicit `<form id="piedata_global_form">` wrapper is not rendered.                          |
+
+### `PieBaseRoot`
+
+The provider stack **without** any fetch. Renders `children` inside the same providers and (optional) form shell. Use it when you already have a `UIConfigType` (render it with `UI`) or want PieUI context without a network round-trip.
+
+### `PiePreviewRoot`
+
+A root tailored to the CLI preview harness (`pieui registry dev`/`build`) for previewing a single card.
+
+### Platform roots
+
+- **`PieTelegramRoot`** (`/telegram`) — like `PieRoot`, but appends Telegram WebApp `initData` to the request query string via `useWebApp`. Throws if `apiServer` is missing.
+- **`PieMaxRoot`** (`/max`) — MAX (VK) equivalent.
+- **`PieNativeRoot`** (`/native`) — `PieBaseRoot` for React Native (no HTML form).
+
+---
+
+## Registering components
+
+A card is any React component registered under a name. The CLI generates a per-card `index.ts` that calls `registerPieComponent`, and a `piecomponents/registry.ts` that side-effect-imports each card. Registering manually:
 
 ```tsx
 import { registerPieComponent } from '@swarm.ing/pieui'
@@ -55,167 +186,507 @@ import MyCard from './MyCard'
 registerPieComponent({
     name: 'MyCard',
     component: MyCard,
-    metadata: {
-        author: 'You',
-        description: 'Custom card',
+    metadata: { author: 'You', version: '1.0.0', description: 'A custom card' },
+})
+```
+
+**Lazy / code-split cards** — pass a `loader` instead of `component`; PieUI wraps it in `React.lazy` and renders it inside `Suspense` (with an optional `fallback`):
+
+```tsx
+registerPieComponent({
+    name: 'HeavyChart',
+    loader: () => import('./HeavyChart'),
+    fallback: <Spinner />,
+})
+```
+
+`ComponentRegistration` shape:
+
+```ts
+interface ComponentRegistration<TProps> {
+    name: string
+    component?: ComponentType<TProps>
+    loader?: () => Promise<{ default: ComponentType<TProps> }>
+    fallback?: ComponentType<{}>
+    metadata?: { author?: string; version?: string; description?: string; tags?: string[] }
+}
+```
+
+> A registration must provide a `name` **and** either `component` or `loader`, otherwise `registerPieComponent` throws.
+
+---
+
+## Component prop shapes
+
+The renderer passes different props depending on a card's "kind". Pick the matching prop type for your component:
+
+| Kind                | Prop type                              | Props received                                            | `card add` type     |
+| ------------------- | -------------------------------------- | -------------------------------------------------------- | ------------------- |
+| Simple              | `PieSimpleComponentProps<T>`           | `{ data }`                                                | `simple`            |
+| Complex             | `PieComplexComponentProps<T>`          | `{ data, setUiAjaxConfiguration? }`                      | `complex`           |
+| Container           | `PieContainerComponentProps<T>`        | `{ data, content: UIConfigType, setUiAjaxConfiguration? }` | `simple-container`  |
+| Complex container   | `PieComplexContainerComponentProps<T>` | `{ data, content: UIConfigType[], setUiAjaxConfiguration? }` | `complex-container` |
+
+Each has an `InputPie…ComponentProps<T, TStored>` variant that adds a typed `stored` prop (used when a card needs locally stored state — wired through `<PieCard stored={…} />`).
+
+```tsx
+import type { PieContainerComponentProps } from '@swarm.ing/pieui'
+
+interface MyData { title: string }
+
+export default function Panel({
+    data,
+    content,
+}: PieContainerComponentProps<MyData>) {
+    return (
+        <section>
+            <h2>{data.title}</h2>
+            <UI uiConfig={content} />
+        </section>
+    )
+}
+```
+
+---
+
+## Built-in cards
+
+These register automatically when you import `@swarm.ing/pieui` (or `/components`).
+
+### Containers
+
+| Card            | Kind              | Description                                                                    |
+| --------------- | ----------------- | ----------------------------------------------------------------------------- |
+| `SequenceCard`  | complex-container | Renders an array of children sequentially inside a styled wrapper.            |
+| `UnionCard`     | complex-container | Renders an array of children with no wrapping element.                        |
+| `OneOfCard`     | complex-container | Renders children in a styled wrapper (typically for conditional selection).  |
+| `BoxCard`       | container         | Single-child wrapper with optional click-to-navigate and inline styling.     |
+| `AjaxGroupCard` | container         | Single-child group that loads/replaces its content via AJAX and emits events. |
+
+### Common (leaf)
+
+| Card                 | Kind   | Description                                                                          |
+| -------------------- | ------ | ----------------------------------------------------------------------------------- |
+| `HiddenCard`         | simple | Renders a hidden input with state management and real-time value sync.              |
+| `HTMLEmbedCard`      | simple | Parses and renders arbitrary HTML (optionally driven by OpenAI WebRTC generation).  |
+| `AutoRedirectCard`   | simple | Redirects on mount (internal route or external URL).                                |
+| `IOEventsCard`       | simple | Handles toast notifications, alerts, push notifications, and redirect/reload events. |
+| `DeviceStorageCard`  | simple | Persists data to `localStorage`, mirrored into a hidden input for form submission.  |
+| `SessionStorageCard` | simple | Persists data to `sessionStorage`, mirrored into a hidden input.                    |
+
+### Telegram-only (register via `@swarm.ing/pieui/telegram`)
+
+| Card                | Kind   | Description                                                       |
+| ------------------- | ------ | ----------------------------------------------------------------- |
+| `CloudStorageCard`  | simple | Persists data to Telegram `CloudStorage` (async), hidden-input mirror. |
+| `SecureStorageCard` | simple | Persists data to Telegram `SecureStorage` (async), hidden-input mirror. |
+
+The storage cards pair with the AJAX `depsNames` prefixes: `localStorage:` ↔ `DeviceStorageCard`, `sessionStorage:` ↔ `SessionStorageCard`, `telegram:cloud:` ↔ `CloudStorageCard`, `telegram:secure:` ↔ `SecureStorageCard` (see [`depsNames`](#depsnames--client-side-submit-sources)).
+
+---
+
+## Real-time messaging
+
+`PieCard` wires a card into PieUI's real-time transports. It renders no UI of its own — it returns its `children` and, on mount, subscribes the supplied `methods` map to whichever transports are enabled:
+
+| Transport     | Event / channel format                              | Enable with             |
+| ------------- | --------------------------------------------------- | ----------------------- |
+| **Socket.IO** | `pie{methodName}_{data.name}`                       | `useSocketioSupport`    |
+| **Centrifuge**| `pie{methodName}_{data.name}_{centrifugeChannel}`   | `useCentrifugeSupport` + `centrifugeChannel` |
+| **Mitt**      | `pie{methodName}_{data.name}`                       | `useMittSupport`        |
+
+```tsx
+import { PieCard } from '@swarm.ing/pieui'
+
+function LiveCounter({ data }) {
+    const [count, setCount] = useState(0)
+    return (
+        <PieCard
+            card="LiveCounter"
+            data={data}
+            useMittSupport
+            useSocketioSupport
+            methods={{
+                increment: (payload) => setCount((c) => c + (payload?.by ?? 1)),
+                reset: () => setCount(0),
+            }}
+        >
+            <span>{count}</span>
+        </PieCard>
+    )
+}
+```
+
+The `methods` map is held in a ref, so you can pass freshly-created closures every render without re-subscribing. Cleanup runs on unmount or when `data.name`/the support flags change.
+
+### Emitting Mitt events — `usePieEmit`
+
+Trigger a card's Mitt-subscribed method from anywhere in the tree:
+
+```tsx
+import { usePieEmit } from '@swarm.ing/pieui'
+
+function Controls() {
+    const emit = usePieEmit('LiveCounter') // card name
+    return <button onClick={() => emit('increment', { by: 5 })}>+5</button>
+}
+```
+
+`getEmitter()` returns the shared emitter for imperative use outside React.
+
+---
+
+## Server-driven AJAX updates
+
+Cards that trigger updates receive a `setUiAjaxConfiguration` callback. Combined with `useAjaxSubmit`, a card can POST to the backend and swap part of the UI — or stream UI events — without a full reload.
+
+```tsx
+import { useAjaxSubmit } from '@swarm.ing/pieui'
+
+function SubmitButton({ data, setUiAjaxConfiguration }) {
+    const submit = useAjaxSubmit(
+        setUiAjaxConfiguration,
+        data.kwargs,          // static key/values from the card config
+        data.deps_names,      // client-side values resolved at submit time
+        data.pathname,        // backend handler path
+        { timeout: 10_000, retryPolicy: { maxRetries: 2, baseDelay: 1000 } }
+    )
+    return <button onClick={() => submit({ extra: 'value' })}>Submit</button>
+}
+```
+
+The request is `POST {apiServer}/api/ajax_content{pathname}`, and the response either replaces the `UIConfigType` subtree or streams JSON-line UI events through `setUiAjaxConfiguration`. The body is assembled from three sources:
+
+1. **`kwargs`** — static key/value pairs from the card config.
+2. **`extraKwargs`** — values passed to the returned submit function at call time.
+3. **`depsNames`** — names whose **current client-side value** is read at submit time (see below).
+
+### `RetryPolicy`
+
+```ts
+type RetryPolicy = {
+    maxRetries?: number   // default 0 (no retries)
+    baseDelay?: number    // default 1000 ms; doubled each attempt
+    retryOn?: number[]    // default [502, 503, 504]; timeouts/network errors always retry
+}
+```
+
+---
+
+## `depsNames` — client-side submit sources
+
+Each entry in `depsNames` is a "magic name": an optional **source prefix** plus a key. The value is submitted under the **bare key** (the part after the prefix), so `localStorage:token` is sent as the field `token`.
+
+| `depsNames` entry        | Read from                                                      |
+| ------------------------ | ------------------------------------------------------------- |
+| `email` *(no prefix)*    | DOM input named `email` (`document.getElementsByName`)        |
+| `sid`                    | `window.sid` — Socket.IO session id (awaits the socket)       |
+| `localStorage:<key>`     | `localStorage.getItem(key)`                                   |
+| `sessionStorage:<key>`   | `sessionStorage.getItem(key)`                                 |
+| `cookie:<name>`          | matching cookie from `document.cookie` (URL-decoded)          |
+| `url:<param>`            | `?<param>` query params (repeated → multiple values)          |
+| `telegram:cloud:<key>`   | `Telegram.WebApp.CloudStorage.getItem` *(async)*              |
+| `telegram:secure:<key>`  | `Telegram.WebApp.SecureStorage.getItem` *(async)*             |
+
+```ts
+depsNames: ['email', 'localStorage:token', 'url:ref', 'sid']
+// POST body fields: email, token, ref, sid
+```
+
+Notes:
+
+- A **missing value contributes nothing** — the field is simply omitted (same as an absent DOM input).
+- A single entry can yield **multiple values** (a multi-file `<input>`, repeated `url:` params); each is appended under the same bare key.
+- `telegram:cloud:` / `telegram:secure:` are **async**. The submit flow awaits them; the sync `readAjaxKey` returns `[]` for them, so use `readAjaxKeyAsync` to read directly. `parseDepName(name)` returns `{ source, key }`.
+- `depsNames` is normally supplied by the backend `UIConfig` at runtime — it is data interpreted by the frontend, not a CLI surface.
+
+---
+
+## Configuration & environment
+
+`PieConfig` (passed to roots as `config`):
+
+```ts
+interface PieConfig {
+    apiServer: string            // base URL of the PieUI API (build endpoints from it)
+    centrifugeServer?: string    // Centrifuge websocket URL
+    enableRenderingLog?: boolean // verbose render/AJAX/realtime logging
+    pageProcessor?: string       // page-processing configuration
+}
+```
+
+When PieUI is wired through the CLI scaffold, these are read from environment variables (multiple framework prefixes supported):
+
+- `PIE_API_SERVER` / `VITE_PIE_API_SERVER` / `NEXT_PUBLIC_PIE_API_SERVER`
+- `PIE_CENTRIFUGE_SERVER` / `VITE_PIE_CENTRIFUGE_SERVER` / `NEXT_PUBLIC_PIE_CENTRIFUGE_SERVER`
+- `PIE_ENABLE_RENDERING_LOG` (optional)
+- `PIE_PAGE_PROCESSOR` (optional)
+
+Use the literal value `auto-api` for a server URL to derive it automatically from the current hostname.
+
+---
+
+## Registry API
+
+All exported from `@swarm.ing/pieui` (and `/native`):
+
+| Function                          | Description                                                                  |
+| --------------------------------- | ---------------------------------------------------------------------------- |
+| `registerPieComponent(reg)`       | Register a component or lazy loader. Returns the (possibly lazy) component.   |
+| `registerMultipleComponents([…])` | Register an array of registrations at once.                                  |
+| `unregisterComponent(name)`       | Remove a component from the registry.                                        |
+| `hasComponent(name)`              | `true` if a name is registered.                                              |
+| `getRegistryEntry(name)`          | Full `ComponentRegistration` (incl. `fallback` / `isLazy`).                  |
+| `getComponentMeta(name)`          | The `metadata` supplied at registration, if any.                            |
+| `getAllRegisteredComponents()`    | Array of all registered names.                                              |
+| `getRegistrySize()`               | Number of registered components.                                            |
+| `getLazyComponentNames()`         | Names of code-split (lazy) components.                                      |
+| `preloadComponent(name)`          | Warm a single lazy chunk so the next render resolves without a fallback flash. |
+| `prefetchLazyComponents()`        | Idle-time, connection-aware background warm-up of every lazy chunk (idempotent). |
+| `registry`                        | The underlying `Map` (shared singleton across all entry points).            |
+| `trackLazy(loader, name)`         | Low-level `React.lazy` wrapper with named tracking.                          |
+
+> The registry is stored on `globalThis` under a shared `Symbol.for` key, so a card registered through one entry point (`/components`) is visible to a renderer loaded from another (`/telegram`). This avoids "[UI] Component not found in registry" across bundles.
+
+---
+
+## Styling helpers
+
+- **`cn(...classes)`** — class-name merge built on `clsx` + `tailwind-merge` (dedupes conflicting Tailwind utilities).
+- **`sx2radium(style)`** — converts a style object into Radium-friendly `CSSProperties`, including turning an object `animationName` into Radium keyframes.
+- **`PIEBREAK`** — the `__piedemo__` delimiter used internally to build form field names.
+- **`pieName(...)`** — helper for composing Pie event/field names.
+- **`submitGlobalForm()`** — programmatically submits the implicit global `<form>`.
+
+---
+
+## Platform integrations
+
+### Telegram Mini Apps
+
+```tsx
+import { PieTelegramRoot, useWebApp, useInitData } from '@swarm.ing/pieui/telegram'
+
+function App() {
+    return <PieTelegramRoot location={location} config={config} />
+}
+```
+
+- `useWebApp()` — the full `Telegram.WebApp` object (typed: `MainButton`, `BackButton`, `HapticFeedback`, `CloudStorage`, `BiometricManager`, theme params, safe-area insets, fullscreen/orientation, and the Bot API methods).
+- `useInitData()` — the parsed init data.
+- Importing this entry also registers `CloudStorageCard` and `SecureStorageCard`.
+
+### MAX (VK Messenger)
+
+```tsx
+import {
+    PieMaxRoot,
+    useMaxWebApp,
+    useMaxInitData,
+    useMaxBackButton,
+    useMaxHapticFeedback,
+} from '@swarm.ing/pieui/max'
+```
+
+Typed access to the MAX bridge (`BackButton`, `HapticFeedback`, `DeviceStorage`/`SecureStorage`, `BiometricManager`, share/download helpers, screen capture, etc.).
+
+### React Native
+
+The `/native` entry exposes the platform-agnostic core (registry, `UI`, `PieCard`, real-time contexts, AJAX helpers) plus native-specific wiring. It deliberately does **not** export the DOM container/leaf cards — on native the host registers its own React Native leaf components and renders them through `UI`/`PieCard`. Metro resolves the `.native` platform layer automatically.
+
+Wire the host's storage / route / form sources once at startup:
+
+```ts
+import { configureNativeClientSources } from '@swarm.ing/pieui/native'
+import { MMKV } from 'react-native-mmkv'
+
+const mmkv = new MMKV()
+
+configureNativeClientSources({
+    storage: {
+        getItem: (k) => mmkv.getString(k) ?? null,
+        setItem: (k, v) => mmkv.set(k, v),
+        removeItem: (k) => mmkv.delete(k),
     },
+    getRouteParams: (key) => getCurrentRoute().params[key] ?? [],
+    getInput: (name) => readNativeField(name),
+    submitForm: () => {/* host submit */},
 })
 ```
 
-**Exports**
-Runtime exports:
+`NativeClientConfig` supports sync (`storage`, `sessionStorage`) and async (`asyncStorage`, `asyncSessionStorage`) adapters, `getCookie`, `getRouteParams`, `getInput`, and `submitForm`. Unconfigured sources degrade to the same "missing value" semantics as web (`null` / `[]`). Render with `PieRoot`/`PieNativeRoot` and pass `disableGlobalForm` (there is no HTML form on native). A small native form store is exposed via `setNativeField` / `clearNativeField` / `readNativeField`.
+
+---
+
+## OpenAI agent integration
 
-- `UI`: Renders a `UIConfigType` by looking up `uiConfig.card` in the registry. Supports lazy components via `Suspense` and passes `data`, `content`, and `setUiAjaxConfiguration` into the rendered component.
-- `PieRoot`: Fetches UI configuration from `config.apiServer + "/api/content"` using the current `location` and renders `UI` inside PieUI providers (React Query, Socket.IO, Centrifuge, Mitt, Radium). Calls `initializePieComponents()` and your `initializePie` callback once.
-- `PieTelegramRoot`: Same as `PieRoot`, but adds Telegram WebApp `initData` to the request query string via `useWebApp`. Throws if `apiServer` is missing.
-- `PieBaseRoot`: Provider wrapper without fetching UI configuration. Renders `children` inside the same PieUI provider stack and form shell.
-- `PieCard`: Wrapper for card components that wires optional Socket.IO, Centrifuge, or Mitt event handlers based on `methods` and `data.name`. Returns `children` unchanged.
-- `registerPieComponent`: Registers a component (or lazy loader) into the PieUI registry, with optional metadata and fallback.
-- `initializePieComponents`: Registers the built-in card components once (SequenceCard, BoxCard, UnionCard, AjaxGroupCard, AjaxButtonCard, RedirectButtonCard, ChatCard, HiddenCard, AutoRedirectCard, HTMLEmbedCard, IOEventsCard, OpenAIVoiceAgentCard, TableCard).
-- `isPieComponentsInitialized`: Returns `true` if `initializePieComponents` has already been called.
-- `useAjaxSubmit`: Hook that returns a function to `POST` to `api/ajax_content` and updates UI state via `setUiAjaxConfiguration`. Supports streamed JSON line events.
-- `sx2radium`: Converts a style object to Radium-friendly `CSSProperties`, including converting object `animationName` into Radium keyframes.
-- `cn`: Class name merge helper using `clsx` and `tailwind-merge`.
-- `PIEBREAK`: String delimiter (`__piedemo__`) used internally to build form field names.
+The `/agent` entry exposes PieCard methods as OpenAI function tools and provides a WebRTC voice hook. It pulls in `@openai/agents`, so it's a separate entry to keep it out of apps that don't need it.
 
-Type exports:
+```tsx
+import {
+    usePieMittAgentTools,  // hook: build tools from the active Mitt emitter
+    getMittAgentTools,     // imperative variant
+    useOpenAIWebRTC,       // WebRTC voice session hook
+} from '@swarm.ing/pieui/agent'
+```
 
-- `PieComponentProps`: Union type of the supported Pie component prop shapes.
-- `PieSimpleComponentProps`: `{ data }` props for simple components.
-- `PieComplexComponentProps`: `{ data, setUiAjaxConfiguration? }` props for components that trigger AJAX or updates.
-- `PieContainerComponentProps`: `{ data, content, setUiAjaxConfiguration? }` props for components that render a single nested `UIConfigType`.
-- `PieComplexContainerComponentProps`: `{ data, content: UIConfigType[], setUiAjaxConfiguration? }` props for components that render an array of nested configs.
-- `PieConfig`: Configuration object for Pie roots. Includes `apiServer` and optional `centrifugeServer`, `enableRenderingLog`, `pageProcessor`.
-- `UIConfigType`: Server-driven UI configuration with `card`, `data`, and `content` (nested `UIConfigType` or array).
-- `SetUiAjaxConfigurationType`: Setter type for updating the UI configuration or streaming UI events.
+- `getMittAgentTools(descriptors, options)` / `usePieMittAgentTools(...)` — turn PieCard methods into agent tools. Options: `filter`, `describe`, and `nameFor` to control which descriptors become tools, their descriptions, and tool names.
+- `useOpenAIWebRTC(audioElement?, onEvent?)` — returns `{ isSessionActive, startSession(ephemeralKey, useMicrophone?), stopSession(), sendTextMessage(text) }` for an OpenAI Realtime WebRTC session (pass an `<audio>` element to play remote audio). Pairs with `HTMLEmbedCard`'s AI-generation support.
 
-## CLI Template Scaffolding
+---
 
-Create a fresh Next.js app and initialize PieUI in it:
+## Storybook integration
 
-```sh
-bunx pieui create my-app-name
+Test cards in isolation with the PieUI providers and fire their real-time methods from the Storybook UI.
+
+```tsx
+// .storybook/preview.tsx
+import { withPieCard } from '@swarm.ing/pieui/storybook'
+export const decorators = [withPieCard]
+```
+
+```tsx
+// MyCard.stories.tsx
+import { PieStorybookProviders, PieMethodTrigger } from '@swarm.ing/pieui/storybook'
+
+export const Live = () => (
+    <PieStorybookProviders>
+        <MyCard data={{ name: 'MyCard' }} />
+        <PieMethodTrigger card="MyCard" method="increment" payload={{ by: 1 }} />
+    </PieStorybookProviders>
+)
 ```
 
-This command:
+- `PieStorybookProviders` — mounts the full provider stack with a stubbed config and a local Mitt emitter.
+- `withPieCard` — decorator wrapping a story in those providers + a channel bridge.
+- `PieMethodTrigger` — a button that fires a `pie{method}_{card}` Mitt event.
+- `firePieMethod(emitter, card, method, payload)` / `usePieStorybookEmitter()` — imperative helpers.
+- The **addon** (`@swarm.ing/pieui/storybook/addon`) adds a Storybook panel to fire methods interactively; register it in `.storybook/main` (the CLI's `card add-story` does this automatically).
+
+---
 
-- runs `bun create next-app@latest my-app-name --yes`
-- initializes `piecomponents/registry.ts` and PieUI config in the new app
-- prepares the app for `bunx pieui card add ...`
+## CLI reference
 
-Create a blank Next.js web app template with PieUI CLI:
+The CLI ships as `pieui` (run via `bunx pieui …` or the installed bin). It mirrors the backend `pie` Python CLI — subcommand names, positionals, and flags are kept in sync.
+
+### Scaffolding
 
 ```sh
-bunx pieui create-pie-app my-pie-app
-# or alias:
-bunx pieui create-pieui my-pie-app
+pieui create <AppName>          # create a Next.js app and run `pieui init` inside it
+pieui create-pie-app <AppName>  # create a blank PieUI Next.js template (alias: create-pieui)
+pieui init [--out-dir <dir>]    # add piecomponents/, registry.ts, Tailwind & Next config to an existing app
 ```
 
-This command:
+`create` scaffolds Next.js (`next-app@latest`), installs `@swarm.ing/pieui`, runs `init`, installs Storybook, then `bun run dev`. `init` also searches your home directory (depth ≤ 2) for a backend project with `pages/` and `components/` dirs and, in a TTY, offers to link them (saved to `.pie/config.json`).
 
-- runs `bun create next-app@latest my-pie-app --yes`
-- copies a standard `_shared` folder into the new app (sourced from `ai-exchange-bot` when found)
-- rewrites `dev/build/start` scripts to `bun --bun next ...`
-- appends a TODO marker in `app/page.tsx` for future backend (Python Unicorn) linking
+### Build
 
-If the `_shared` source cannot be found automatically, PieUI now creates a fallback `_shared/simple.tsx` scaffold and continues.
+```sh
+pieui postbuild [--src-dir <dir>] [--out-dir <dir>] [--append]
+```
 
-To force a specific shared source, set:
+Scans for `registerPieComponent()` calls, generates a JSON Schema per card data type, and writes `pieui.components.json`. Defaults: `--src-dir src`, `--out-dir public`. `--append` merges with the library manifest in `node_modules`.
 
 ```sh
-PIEUI_SHARED_TEMPLATE_DIR=/absolute/path/to/_shared bunx pieui create-pie-app my-pie-app
+pieui self-upgrade [--pm <bun|pnpm|yarn|npm>]   # upgrade the global CLI
 ```
 
-Planned create flow target:
+### Auth
 
 ```sh
-bun create pieui@latest my-pie-app
+pieui login   # browser auth; writes .pie/config.json and PIE_* keys into .env
 ```
 
-Create a page scaffold inside an existing Next app:
+### Pages (`pieui page …`)
 
 ```sh
-bunx pieui page add chat
+pieui page add <path>                         # create app/<path>/page.tsx from the Pie page template
+pieui page view <path>                        # print the page source
+pieui page ajax <path> <add|remove> <handler> # add/remove an AJAX handler (delegates to the backend)
 ```
 
-This command writes `app/chat/page.tsx` with the standard Suspense-wrapped Pie page shell:
+`add` normalizes the path under `app/`, derives a `PascalCasePage` component name, and rejects traversal outside `app/`.
 
-```tsx
-'use client'
+### Cards (`pieui card …`)
+
+```sh
+pieui card add [<type>] <Name> [--io] [--ajax] [--input] [--from <ref>]
+```
 
-import PiePage from '@/app/_shared/simple'
-import { Suspense } from 'react'
-import LoadingScreen from '@/components/LoadingScreen'
+Creates `piecomponents/<Name>/` (`index.ts`, `types/index.ts`, `ui/<Name>.tsx`) and registers it in `registry.ts`. `<type>` is one of `simple`, `complex`, `simple-container`, `complex-container` (default). Flags:
 
-export default function ChatPage() {
-    return (
-        <Suspense fallback={<LoadingScreen />}>
-            <PiePage />
-        </Suspense>
-    )
-}
+- `--io` — add real-time support fields (`use_*_support`) to the data interface.
+- `--ajax` — add AJAX fields (`pathname`, `deps_names`, `kwargs`).
+- `--input` — generate the `InputPie…ComponentProps` variant with a typed `stored` prop.
+- `--from <ref>` — port from backend Python metadata (a `.py`/JSON path, a card name, or auto-detected from the configured `backendComponentsDir`).
+
+```sh
+pieui card list [<filter>] [--src-dir <dir>]   # list cards (filter: all|simple|complex|simple-container|complex-container)
+pieui card view <Name>                          # print a card's props, ajax, io, and events
+pieui card remove <Name>                        # delete a card directory
+pieui card list-events <Name>                   # list a card's methods (event handlers)
+pieui card add-event <Name> <EventName>         # add a method to a card
+pieui card pull <ref>                           # restore a card from a URL, local JSON file, or remote name
 ```
 
-Create a component scaffold inside `piecomponents/`:
+Metadata & Storybook:
 
 ```sh
-bunx pieui card add simple StatusCard
+pieui card dump-metadata <Name> [--out <file.json>]  # emit full PieMetadata JSON (props/events/imports/ajax/io)
+pieui card check-sync <Name>                          # compare TypeScript ↔ Python metadata, report mismatches
+pieui card add-story <Name> [--force]                 # generate <Name>.stories.tsx wired to PieCard methods
+pieui card generate-preview <Name> [--out <file.png>] # render the story via storycap to a PNG
 ```
 
-Add optional realtime and AJAX fields to the generated `types/index.ts`:
+### Remote card storage (`pieui card remote …`)
 
 ```sh
-bunx pieui card add simple LiveCard --io --ajax
+pieui card remote list [--user <id>] [--project <slug>]
+pieui card remote push <Name>
+pieui card remote pull <Name>[@rev]
+pieui card remote remove <Name>
+pieui card remote history <Name> [--page <n>] [--per-page <n>] [--from <r>] [--to <r>]
+pieui card remote public <Name>     # make readable as r/<user>/<Name>
+pieui card remote private <Name>    # revert to private
 ```
 
-## AJAX `depsNames` sources
+### Registry preview harness (`pieui registry …`)
 
-An Ajax card (`AjaxGroupCard`, `AjaxButtonCard`, …) submits to
-`api/ajax_content{pathname}` via `useAjaxSubmit`. The request body is built from
-three places:
+```sh
+pieui registry dev [--port <n>] [--api-server <url>]   # run the PiePreviewRoot harness (default port 3210)
+pieui registry build [--out <dir>]                     # static-export the harness (default .pie/registry/out)
+```
 
-1. `kwargs` — static key/value pairs from the card config.
-2. `extraKwargs` — values passed at call time.
-3. `depsNames` — names whose **current client-side value** is read and appended
-   at submit time.
+### Configuration & environment
 
-Each entry in `depsNames` is a "magic name": an optional source prefix plus a
-key. The value is always submitted under the **bare key** (the part after the
-prefix), so `localStorage:token` is sent as the field `token`.
+`.pie/config.json` (written by `login` / `init`) holds `user_id`, `project`, `api_key`, and optional `backendPagesDir` / `backendComponentsDir`. Notable env vars: `PIE_USER_ID`, `PIE_PROJECT`/`PIE_PROJECT_SLUG`, `PIE_API_KEY`; `PIEUI_CREATE_NEXT_APP_SPEC`, `PIEUI_CREATE_PACKAGE_SPEC`, `PIEUI_CREATE_BUN_BIN`, `PIEUI_CREATE_SKIP_STORYBOOK`; `PIEUI_LOGIN_CONNECT_BASE`, `PIEUI_LOGIN_CREDENTIALS_API`. Add `--help`/`-h` to any command for scoped help.
 
-| `depsNames` entry         | Read from                                                     |
-| ------------------------- | ------------------------------------------------------------- |
-| `email` _(no prefix)_     | DOM input named `email` (`document.getElementsByName`)        |
-| `sid`                     | `window.sid` — SocketIO session id (awaits the socket)        |
-| `localStorage:<key>`      | `localStorage.getItem(key)`                                   |
-| `sessionStorage:<key>`    | `sessionStorage.getItem(key)`                                 |
-| `cookie:<name>`           | matching cookie from `document.cookie` (URL-decoded)          |
-| `url:<param>`             | `?<param>` query params (repeated params → multiple values)   |
-| `telegram:cloud:<key>`    | `Telegram.WebApp.CloudStorage.getItem` _(async)_              |
-| `telegram:secure:<key>`   | `Telegram.WebApp.SecureStorage.getItem` _(async)_             |
+---
 
-Notes:
+## API reference
 
-- A **missing value contributes nothing** — same as an absent DOM input. The
-  field is simply omitted from the request.
-- A single entry can yield **multiple values** (a multi-file `<input>`, repeated
-  `url:` params); each is appended under the same bare key.
-- `telegram:cloud:` / `telegram:secure:` are **asynchronous**. The submit flow
-  awaits them automatically; the sync `readAjaxKey` returns `[]` for them, so use
-  `readAjaxKeyAsync` if reading directly.
-- The storage prefixes mirror the storage cards: `localStorage:` ↔
-  `DeviceStorageCard`, `sessionStorage:` ↔ `SessionStorageCard`,
-  `telegram:cloud:` ↔ `CloudStorageCard`, `telegram:secure:` ↔
-  `SecureStorageCard`. The Telegram cards live under the
-  `@swarm.ing/pieui/telegram` entry.
-
-Example — submit a DOM field, a localStorage token, a URL param and the socket
-id together:
+### Runtime exports (`@swarm.ing/pieui`)
 
-```ts
-depsNames: ['email', 'localStorage:token', 'url:ref', 'sid']
-// POST body fields: email, token, ref, sid
-```
+| Export | Description |
+| ------ | ----------- |
+| `UI` | Renders a `UIConfigType` by resolving `uiConfig.card` from the registry (Suspense for lazy cards; passes `data`, `content`, `setUiAjaxConfiguration`). |
+| `UILoading` | Renders a cached/placeholder shell while a screen loads. |
+| `UIRendererContext` | Context carrying renderer props (`UIRendererProps`). |
+| `PieRoot` / `PieBaseRoot` / `PiePreviewRoot` | Root components (see [Root components](#root-components)). |
+| `PieCard` | Wires a card into Socket.IO / Centrifuge / Mitt messaging. |
+| `registerPieComponent` & registry helpers | See [Registry API](#registry-api). |
+| `trackLazy` | Named `React.lazy` wrapper. |
+| `useAjaxSubmit` / `readAjaxKey` / `readAjaxKeyAsync` / `parseDepName` | AJAX submit + dep-name resolution. |
+| `usePieEmit` / `getEmitter` / `MittContext` | Mitt event emission. |
+| `SocketIOContext` / `CentrifugeIOContext` / `FallbackContext` / `PieConfigContext` | PieUI contexts. |
+| `cn` / `sx2radium` / `pieName` / `submitGlobalForm` / `PIEBREAK` | Utilities. |
+
+### Type exports
+
+`PieComponentProps`, `PieSimpleComponentProps`, `PieComplexComponentProps`, `PieContainerComponentProps`, `PieComplexContainerComponentProps`, and their `InputPie…` variants; `PieConfig`, `UIConfigType`, `SetUiAjaxConfigurationType`, `PieQueryOptions`, `RetryPolicy`, `DepSource`. Telegram/MAX entries export their respective `WebApp`/init-data types; the `/native` entry adds `PieRootProps`, `PieBaseRootProps`, and the `NativeClientConfig`/adapter types.
+
+---
+
+## License
 
-`depsNames` is normally supplied by the backend `UIConfig` at runtime — for the
-Python card field that produces it, see the `pie` repo (`deps_names`).
+MIT