@mixd-id/web-scaffold 0.2.250801013 → 0.2.250801014

package/docs/components/AIDashboard.md

@@ -0,0 +1,472 @@
+# AIDashboard.vue
+
+## TLDR
+
+An AI-chat-style **dashboard builder** (think Claude web / ChatGPT, but the main
+content is a dashboard), split into three panels:
+
+- **Left** — a tabbed builder: **Presets** (the saved dashboards), **Build** (a
+  `TreeView` structure editor + node inspector), and **Data** (the data sources
+  available to query).
+- **Middle** — the **dashboard** itself: the active preset's widgets (metrics,
+  charts, tables), rendered top-to-bottom, groups as sections laid out per their
+  `layout` (grid / flex).
+- **Right** — an **AI chat** panel (same look as `AIChat`) that generates /
+  edits widgets. Chat history is kept **per preset**.
+
+The `config` object mirrors the server's **UserConfig model** (`UserConfig`
+hasMany `UserPreset`).
+
+The component runs in **two modes**, chosen by whether it is given a `socket` +
+`controller`:
+
+- **Offline** (no socket/controller) — makes **no** network calls. Sample data
+  comes from the `samples` prop, the chat appends canned widgets, and the host
+  page owns persistence. This is how `pages/Dashboard.vue` uses it.
+- **Connected** — mirrors the server `@mixd-id/web-scaffold/ai-dashboard`
+  mixin + the `ai-dashboard` socket controller: data sources load from
+  `<controller>.load-datasource`, widget data is hydrated by
+  `<controller>.load-dashboard`, chat calls `<controller>.chat`, and the config
+  is persisted through `<controller>.save`.
+
+```vue
+<!-- offline (host owns persistence + samples) -->
+<AIDashboard :config="config" :samples="samples" />
+
+<!-- connected (server-backed data via the ai-dashboard controller) -->
+<AIDashboard :config="config" :socket="socket" controller="ai-dashboard" />
+```
+
+---
+
+## Component family
+
+| Component | Responsibility |
+|-----------|----------------|
+| `AIDashboard` | Orchestrator. Owns preset CRUD + selection, the tabbed left builder (presets / structure tree / data sources), the three-panel layout + resizing, chat (offline canned **or** server-driven), and server sync (datasource load, hydration, persistence). |
+| `Widget` (inline) | Pure renderer for **one** node, branching on `node.type` (`metric` / `chart` / `table`). Render-function component; emits `remove`, never mutates the node. Charts use **vue-chartjs**; tables use **`VirtualTable`**. |
+| `AIChatItem` | Reused from `AIChat`. Renders one chat message. See `AIChat.md`. |
+| `AIChatTextbox` | Reused from `AIChat`. The composer input; emits the typed string. See `AIChat.md`. |
+| `AIDashboardMixin` (server) | `web-scaffold/src/utils/ai-dashboard.js` — socket-controller mixin persisting the same config shape to `UserConfig`/`UserPreset`, plus `load-dashboard` hydration and overridable `chat` / `analyze-node`. |
+| `AiDashboardController` (server) | `server/src/controllers/sockets/ai-dashboard.js` — the concrete controller: mixes in the above, exposes hardcoded **data sources** via `load-datasource`, and folds query **filters** into a Sequelize `where`. |
+
+---
+
+## Layout
+
+```
+┌──────────────────┬────────────────────────────────────┬────────────────┐
+│ [Presets|Build|Data]  Active preset name [Load samples] │ ✦ AI Assistant │ ← headers
+│ ──────────────── ├────────────────────────────────────┼────────────────┤
+│ Presets tab:     │  Overview                        ✕  │                │
+│   ▦ My Dash   ⋮  │   ┌──────┐ ┌──────┐ ┌──────┐ ┌────┐ │  assistant ▍   │
+│   ▦ Sales     ⋮  │   │metric│ │metric│ │metric│ │ …  │ │  reply…        │
+│                  │   └──────┘ └──────┘ └──────┘ └────┘ │                │
+│ Build tab:       │  ┌───────────────────────────────┐  │   ┌──────────┐ │
+│   ▸ Overview     │  │  chart (vue-chartjs)        ✕ │  │   │ user msg │ │
+│     • Revenue    │  └───────────────────────────────┘  │   └──────────┘ │
+│   ▸ Sales table  │  ┌───────────────────────────────┐  ├────────────────┤
+│   ── inspector ─ │  │  table (VirtualTable)       ✕ │  │ [ input  ] [▶] │ ← composer
+└──────────────────┴──┴───────────────────────────────┴──┴────────────────┘
+   ↑ resizable                                          ↑ resizable
+   220–520px                                            280–560px
+```
+
+- Three columns separated by hairline dividers. Left and right are fixed-width
+  (from `config.params`), the middle flexes to fill.
+- **Left** grab handle on its **right** edge; `leftWidth` clamped **220–520px**
+  (default **260**).
+- **Right** grab handle on its **left** edge; `rightWidth` clamped **280–560px**
+  (default **360**; delta *subtracted* — the panel grows when its left edge is
+  dragged left).
+- The left panel is a `Tabs` bar switching between **Presets**, **Build** and
+  **Data** (`config.params.leftTab`).
+- The chat message area uses a **reverse column** (`flex-col-reverse`) so it
+  stays pinned to the latest message as text streams in.
+- A floating `Card` handles preset renaming (replaces `window.prompt`).
+
+---
+
+## Data model — `config` mirrors UserConfig
+
+```js
+config = {
+  key:   String,                 // UserConfig.key (e.g. 'ai-dashboard') — sent on save
+  name:  String,                 // UserConfig.name
+  params: {                      // UserConfig.params — UI state
+    leftWidth:  Number,          //   builder panel width, px, 220–520, default 260
+    rightWidth: Number,          //   chat panel width, px, 280–560, default 360
+    leftTab:    String,          //   'presets' | 'build' | 'data', default 'presets'
+    presetIdx:  String|null,     //   uid of the active preset
+  },
+  presets: [ Preset, ... ],      // UserConfig.presets → UserPreset[] (array order = seq)
+}
+```
+
+`config` is a **plain object** (not a ref) and is **mutated in place** — access
+as `config.params.X`, never `config.value.params.X`. The parent owns the ref.
+
+---
+
+## Preset
+
+A **preset is one saved dashboard**. `config.presets` is the ordered list;
+array order becomes the server `seq`. The active preset is the one whose `uid`
+equals `config.params.presetIdx`.
+
+```js
+Preset = {
+  uid:  String,                  // unique id; client-generated 'p-<ts36>-<n>', server keeps it
+  name: String,                  // shown in the Presets tab + middle header
+  params: {                      // UserPreset.params — the dashboard content
+    structure: Node[],           //   the widget tree (groups + leaf widgets)
+    messages:  Message[],        //   chat history for THIS preset
+  },
+}
+```
+
+### Preset properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `uid` | `String` | ✅ | Stable unique id. Created by the component (`p-<timestamp36>-<counter>`) if missing; the server preserves the client value. Used for selection (`presetIdx`), reorder/seq, and targeted `remove-preset`. |
+| `name` | `String` | ✅ | Display name in the Presets tab and the middle header. Edited via the rename `Card`. |
+| `params` | `Object` | ✅ | The dashboard payload. Always normalized to contain `structure` and `messages`. |
+| `params.structure` | `Node[]` | ✅ | The widget tree (see **Node**). Empty array for a blank preset. |
+| `params.messages` | `Message[]` | ✅ | Per-preset chat history. On load, any message left `isLoading` by a reload is frozen (`body = display \|\| 'Cancelled.'`). |
+
+> Persistence-only preset fields (`UserPreset` also has `columns`, `filters`,
+> `sorts`, `pivot`, `datasource`, `search`, `views`). The AIDashboard component
+> does not use them; the server `save` passes any present through. Ignore them
+> for dashboards.
+
+### Node (recursive) — an entry in `params.structure`
+
+```js
+Node = {
+  uid:    String,                 // unique id, assigned by the component (NOT in samples)
+  name:   String,                 // widget title / section heading
+  type:   'group' | 'metric' | 'chart' | 'table',
+  items:  Node[],                 // children — 'group' only
+  layout: { mode, cols },         // 'group' only — how children are laid out
+  data:   Object,                 // type-specific render payload (see below)
+  query:  Object,                 // connected mode — how the server computes `data`
+}
+```
+
+| Property | Type | Applies to | Description |
+|----------|------|-----------|-------------|
+| `uid` | `String` | all | Unique id (`w-<ts36>-<n>`). Assigned on creation / instantiation; drives selection, removal (`removeFromTree`) and hydration merge-by-uid. |
+| `name` | `String` | all | Section heading (group) or widget card title. |
+| `type` | `String` | all | `group`, `metric`, `chart`, or `table`. |
+| `items` | `Node[]` | group | Child nodes. Only groups can contain children. |
+| `layout` | `Object` | group | `{ mode: 'grid' \| 'flex', cols: 1–4 }`. `grid` lays children in `cols` equal columns; `flex` wraps them. Defaults to `{ mode:'grid', cols: metricOnly ? 4 : 2 }`. |
+| `data` | `Object` | leaf | Render payload (see **Per-type `data`**). In offline mode you author it directly; in connected mode it is **derived** (hydrated) and stripped before save. |
+| `query` | `Object` | leaf | Data-source query used by `load-dashboard` / `analyze-node` to compute `data` (see **Per-type `query`**). Present only when a data source is bound. |
+
+### Per-type `data` (render payload)
+
+```js
+// metric — a single KPI
+data = { label: String, value: Number|String, delta: Number /* optional ±% */ }
+
+// chart — rendered as a vue-chartjs Bar
+data = { series: [ { label: String, value: Number }, ... ] }   // (also accepts `rows`)
+
+// table — rendered with VirtualTable
+data = {
+  columns: [ { key: String, label: String }, ... ],   // plain string allowed → key & label
+  rows:    [ { [key]: cellValue, ... }, ... ],
+}
+
+// group — no data; renders as a section heading + `layout`-driven children
+```
+
+### Per-type `query` (connected mode)
+
+Bound via the Build-tab inspector; resolved server-side against the controller's
+data sources. All types also accept a shared **`filters`** array.
+
+```js
+// metric
+query = { datasource, aggregation: 'count'|'sum'|'avg'|'min'|'max', field, filters }
+
+// chart
+query = { datasource, groupBy, dateModifier: ''|'day'|'week'|'month'|'year', limit, filters }
+
+// table
+query = { datasource, pageSize, order: [[field,'desc']], columns, filters }
+
+// filters (all types) — folded into a Sequelize `where` on the server
+filters = [ { field: String, op: '='|'!='|'>'|'>='|'<'|'<='|'contains'|'in', value }, ... ]
+```
+
+### Chat message — an entry in `params.messages`
+
+Same shape as `AIChat` (see `AIChat.md`):
+
+```js
+{ direction: 1|2, body, display, isLoading, model, ellapsed }
+```
+
+Messages live in `preset.params.messages`, so each preset has its own
+conversation, persisted with the config.
+
+### `samples` prop (offline seed, supplied by the page)
+
+```js
+samples = {
+  structure: Node[],              // dashboard used to seed the first preset; UID-LESS templates
+  widgets:   { [key]: Node },     // widgets the offline chat can append; UID-LESS templates
+}
+```
+
+Chat-understood keys: `metric`, `chart`, `table`, `group`. Templates **must
+not** carry `uid` — the component deep-clones each template and assigns fresh
+ids via `instantiate()` on every use.
+
+---
+
+## Modes: offline vs connected
+
+`connected = !!(socket && controller)`. Two further flags fine-tune a connected
+mount so a host can keep owning parts it already handles:
+
+| Flag | Default | Effect when **on** |
+|------|---------|--------------------|
+| `connected` (derived) | — | Enables the **Data** tab, `load-datasource`, and `load-dashboard` hydration. |
+| `autoSave` | `true` | Persists edits via debounced `<controller>.save`. Turn **off** when the host page persists (avoids a double write). |
+| `serverChat` | `true` | Routes chat through `<controller>.chat`. Turn **off** to keep the offline canned-widget generator even while connected. |
+
+`pages/Dashboard.vue` connects for **data only**: it passes `socket` +
+`controller="ai-dashboard"` but sets `:auto-save="false"` and
+`:server-chat="false"`, so it keeps its `loadConfig`/`saveConfig` persistence
+and the offline chat demo while gaining the Data tab and query hydration.
+
+---
+
+## Left panel — the tabbed builder
+
+### Presets tab (CRUD)
+
+- `activePreset` = the preset whose `uid === config.params.presetIdx`.
+- **Add** — pushes a blank preset (`name:'New Preset'`, empty structure) and
+  jumps to the **Build** tab.
+- **Rename** — opens the floating rename `Card` (Textbox + Save/Cancel).
+- **Duplicate** — deep-clones the preset with a fresh preset uid **and** fresh
+  uids for every node, inserts after the original, selects it.
+- **Remove** — splices it; if it was active, selection falls back to the first
+  preset (or `null`). In connected mode also calls `<controller>.remove-preset`.
+- Each row has a "⋮" button opening a context menu anchored to it.
+
+### Build tab (structure editor + inspector)
+
+- A **`TreeView`** of the active preset's `structure`. Each row shows a
+  type-colored icon + name; groups show their layout mode. Selecting a row sets
+  the inspected node; `TreeView` provides drag-reorder, drag-into-group, inline
+  add (groups → quick metric), duplicate and remove.
+- **Add component** (toolbar `+`) opens a menu (Section / Metric / Chart /
+  Table) that inserts into the selected group, else at the root.
+- **Node inspector** (bottom): edits `name`; for **groups** the `layout`
+  (mode + columns); for **leaves** the data source, aggregation / group-by /
+  page-size, eligible field, and the **Filters** editor (field / operator /
+  value rows). A **Refresh** button (connected) re-hydrates on demand; query
+  edits re-hydrate automatically (debounced ~450ms).
+
+### Data tab (data sources)
+
+- Lists the data sources returned by `<controller>.load-datasource` (or the
+  `datasources` prop offline). Each source expands to show its fields + types,
+  with a **"+ New metric from this source"** shortcut that drops a bound metric
+  into the current section and jumps to Build.
+- Data source descriptor shape:
+
+```js
+{ key: String, label: String,
+  aggregations: ['count','sum','avg','min','max'],   // supported metric aggregations
+  fields: [ { key, label, type: 'number'|'string'|'date' }, ... ] }
+```
+
+---
+
+## Middle panel — rendering
+
+The active preset's `structure` renders top-to-bottom (`flex flex-col gap-6`):
+
+- **group** → a section: heading (`node.name`) + its `items` laid out per
+  `node.layout` via **inline styles** (grid `repeat(cols, minmax(0,1fr))`, or
+  flex-wrap) — inline to survive Tailwind purge of dynamic column counts.
+- **leaf** (metric/chart/table) → a full-width `Widget` card.
+- Every widget card and section heading has a hover-revealed **✕** that removes
+  the node.
+- Empty preset / no preset → an empty-state illustration + hint.
+- Header: active preset name + a **Load samples** button that replaces the
+  active preset's structure with a fresh instantiation of `samples.structure`.
+
+### Widget rendering rules (`Widget`)
+
+Card (`bg-base-300 rounded-xl p-5`) with a title row (name + hover ✕), then:
+
+1. **metric** — caption (`data.label || node.name`), a large
+   `toLocaleString()` number, optional delta line (`▲ n%` green / `▼ n%` red).
+2. **chart** — a **vue-chartjs `Bar`** in a 240px-tall box. Bar/grid/tick colors
+   are read from the active theme's CSS variables (`--primary`, `--border-50`,
+   `--text-300`) with SSR-safe fallbacks; empty series shows a "No data." hint.
+3. **table** — a **`VirtualTable`** built from `columns` / `rows` (string column
+   doubles as key + label); height caps at 320px.
+4. **anything else** — muted placeholder.
+
+---
+
+## Chat
+
+`send(prompt)` routes to server chat when `serverChat` is on and connected,
+otherwise the offline generator.
+
+### Offline (canned, generates into the ACTIVE preset)
+
+1. Push user message + assistant placeholder into `activePreset.params.messages`.
+2. Compute `reply = pickReply(prompt)` (keyword table below).
+3. **Stream** the reply: every **28ms** advance a cursor by
+   `max(2, ceil(remaining/24))` chars. When done, apply the widgets once and
+   finalize (`model:'offline-demo'`, `ellapsed`).
+
+| Keywords | Result |
+|----------|--------|
+| `overview`, `dashboard`, `build` | rebuild from `samples.structure` |
+| `table`, `customer`, `list` | append `widgets.table` |
+| `chart`, `bar`, `revenue`, `trend`, `graph` | append `widgets.chart` |
+| `metric`, `kpi`, `card`, `number` | append `widgets.metric` (into the last root group) |
+| `group`, `section` | append `widgets.group` |
+| (none) | help message listing available widget keys |
+
+`cancel()` stops the timer and freezes the in-flight message; the dashboard only
+changes once a reply fully streams in.
+
+### Connected (`serverChat`)
+
+`sendConnected` posts `{ messages, structure }` to `<controller>.chat` and
+applies the result: `reply` → assistant body; `structure` → replace the active
+preset's tree; `nodes` → instantiate + append (metrics into the last root
+group). Then re-hydrates and persists. Missing uids are backfilled.
+
+---
+
+## Persistence & hydration (connected)
+
+- **Hydrate** — on mount, preset switch, data-source change, query edit
+  (debounced) and the Refresh button, `hydrateActive()` posts the preset's
+  structure to `<controller>.load-dashboard` and **merges** returned `data` into
+  the live nodes **by uid**. Derived data is never authored by hand.
+- **Persist** — a deep `watch(config)` calls debounced (**700ms**)
+  `<controller>.save` with a cleaned config: node `data` is stripped from any
+  node that has a `query` (the server recomputes it), and `messages` are frozen.
+  No-op unless `connected && autoSave`.
+
+### Offline persistence (host-owned)
+
+```js
+// pages/Dashboard.vue
+const config = ref(await loadConfig('dashboard', {
+  name: 'Dashboard',
+  params: { leftWidth: 260, rightWidth: 360, presetIdx: null },
+  presets: [],
+}))
+watch(() => config.value, to => saveConfig('dashboard', to), { deep: true })
+```
+
+> Web detail: this project's Tailwind config sets `important: true`, so panel
+> widths and group layouts are applied as **inline styles** with no competing
+> class.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `Object` | required | UserConfig-shaped object (see **Data model**). Mutated in place. |
+| `samples` | `Object` | `{ structure: [], widgets: {} }` | Offline seed layout + generatable widgets. Nodes are uid-less templates. |
+| `socket` | `Object` | `null` | Socket transport. With `controller`, switches the component to **connected** mode. |
+| `controller` | `String` | `''` | Socket namespace prefixing every call (`<controller>.load-datasource`, `.load-dashboard`, `.save`, `.chat`, `.remove-preset`). |
+| `datasources` | `Object` | `{}` | Optional client-side data-source descriptor `{ [key]: { label, fields, aggregations } }`; used only if the server returns none. |
+| `autoSave` | `Boolean` | `true` | Persist edits via `<controller>.save`. Set `false` when the host page owns persistence. |
+| `serverChat` | `Boolean` | `true` | Route chat through `<controller>.chat`. Set `false` to keep the offline generator while connected. |
+
+`AIDashboard` emits no events and exposes no methods.
+
+---
+
+## Server side
+
+### `ai-dashboard` socket controller
+
+`server/src/controllers/sockets/ai-dashboard.js` (registered as
+`routes['ai-dashboard']`) mixes in `AIDashboardMixin` and adds:
+
+- **`load-datasource`** → `loadDatasource()` returns `{ datasources: [...] }`,
+  a **hardcoded** list (`order`, `message`, `inbox`, `customer`, `product`)
+  with typed fields + supported aggregations.
+- **`get datasources()`** maps each `key` to a real Sequelize model, so
+  `load-dashboard` / `analyze-node` can compute widget data.
+- **Filtering** — `buildWhere(filters)` maps `{field, op, value}` rows to a
+  Sequelize `where` (`= != > >= < <= contains in` → `Op.eq/ne/gt/gte/lt/lte/like/in`,
+  blanks dropped, `in` comma-split). An `analyzeNode` override folds
+  `query.filters` into `where` before delegating to the mixin analyzers.
+
+### `AIDashboardMixin` (`@mixd-id/web-scaffold/ai-dashboard`)
+
+Host-class contract (getters): `Models` `{ UserConfig, UserPreset }`,
+`Sequelize` (for `Op`), `configKey` (the `UserConfig.key`), `conn` and
+`datasources` (for hydration). `this.socket.token.userId` comes from the base
+socket `Controller`.
+
+Methods (socket path → method, kebab→camel):
+
+| Socket path | Method | Does |
+|-------------|--------|------|
+| `<controller>.load` | `load()` | UserConfig + presets (seq-ordered), or `null` |
+| `<controller>.save` | `save({ config })` | Upsert UserConfig; sync presets (array order → `seq`, missing uids destroyed); returns fresh `load()` |
+| `<controller>.save-preset` | `savePreset({ preset })` | Upsert one preset (appends `seq` for new rows) |
+| `<controller>.remove-preset` | `removePreset({ uid })` | Destroy one preset → `{ removed }` |
+| `<controller>.load-dashboard` | `loadDashboard({ preset })` | Hydrate: walk the structure, compute `data` for every node with a `query`, recurse into groups; returns the hydrated preset |
+| `<controller>.load-datasource` | `loadDatasource()` | *(controller, not mixin)* the available data sources |
+| `<controller>.analyze-node` | `analyzeNode({ node })` | Compute one node's `data`: metric → `{ value }`, chart → `{ series }`, table → `{ columns, rows, hasNext }` |
+| `<controller>.chat` | `chat({ messages, structure })` | **Overridable stub** — real controllers return `{ reply, structure?, nodes?, model? }` |
+
+`mixin(Class, overrides)` copies mixin methods onto the prototype **without
+clobbering** methods the class already defines (e.g. the controller's own
+`analyzeNode`); `overrides` always win.
+
+---
+
+## Constants & tunables
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| Left width clamp | `220–520px` | builder panel resize bounds |
+| Left default width | `260px` | initial `leftWidth` |
+| Right width clamp | `280–560px` | chat panel resize bounds |
+| Right default width | `360px` | initial `rightWidth` |
+| Resize handle width | `3px` | grab strip on each inner panel edge |
+| Default group layout | `{ mode:'grid', cols: metricOnly ? 4 : 2 }` | new / seeded group layout |
+| Chart height | `240px` | vue-chartjs Bar container |
+| Table max height | `320px` | VirtualTable cap |
+| Save debounce | `700ms` | `<controller>.save` |
+| Hydrate debounce | `450ms` | `<controller>.load-dashboard` after query edits |
+| Reveal interval / step | `28ms` / `max(2, ceil(remaining/24))` | offline chat streaming |
+| First preset name | `'My Dashboard'` | auto-created on first run, seeded from samples |
+| Assistant `model` tag (offline) | `'offline-demo'` | footer label on generated replies |
+
+---
+
+## Files
+
+| File | Role |
+|------|------|
+| `src/components/AIDashboard.vue` | Orchestrator + inline `Widget` (this doc's subject). |
+| `src/components/AIChatItem.vue` | Reused chat message renderer (see `AIChat.md`). |
+| `src/components/AIChatTextbox.vue` | Reused composer input (see `AIChat.md`). |
+| `src/pages/Dashboard.vue` | Page host; owns `samples`, connects to `ai-dashboard` for data only (auto-save + server-chat off). |
+| `web-scaffold/src/utils/ai-dashboard.js` | Server-side `AIDashboardMixin` + `mixin()` for socket controllers. |
+| `server/src/controllers/sockets/ai-dashboard.js` | Concrete `ai-dashboard` controller: hardcoded `load-datasource` + filter→`where`. |

package/docs/components/WebPageBuilder.md

@@ -0,0 +1,125 @@
+# WebPageBuilder
+A full-screen visual page builder widget. It renders a three-pane editor — settings panel (page info / layout / components / chat), a live preview iframe, and a per-component setting panel — and talks to a socket controller for loading, saving and previewing pages.
+
+Registered globally by the scaffold plugin as an async component, so it can be used directly without importing.
+
+## Requirements
+- `vue-router` must be installed; the page uid is read from `$route.params.uid`, and a navigation guard warns about unsaved changes.
+- The host app must provide the scaffold injections: `alert`, `appStyle`, `confirm`, `useSocket`, `toast` (all provided by the standard scaffold app setup).
+- A preview route (returned by the server as `previewHost`, e.g. `/web-preview`) that renders the page inside the iframe and implements the iframe message protocol below.
+
+## Props
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| controller | String | `undefined` | Socket controller namespace. Every server call is prefixed with it, e.g. `web-page.open` |
+| presetKey | String | `undefined` | Key used to persist UI state (tab index, panel widths, zoom level…) via `${controller}.preset` |
+| canManageLayout | Boolean | `false` | Whether the user may manage layouts |
+| excludeComponents | Array | `[]` | Component `type` strings to hide from the component selector |
+| moreComponents | Array | `[]` | Extra component definitions added to the selector (`{ type, name, group, props }`) |
+| uploadConfig | Object | `undefined` | Axios-style config (`{ method, url, data }`) used to upload images when `uploadImageFn` is not given |
+| uploadImageFn | Function | `undefined` | `(image, extra?, opt?) => Promise` — custom image upload handler; takes precedence over `uploadConfig` |
+| useChat | Boolean | `false` | Shows the AI chat tab; requires a `${controller}.chat` handler on the server |
+| useDatasource | Array | `undefined` | Datasource support tuple; the second element is the socket path used to load datasource data (the Datasource tab is currently disabled) |
+
+## Events
+| Event | Payload | Description |
+|-------|---------|-------------|
+| close | - | Emitted when the close (✕) button is clicked. The parent decides where to navigate |
+| unmount | `{ uid }` | Emitted when the builder unmounts, with the page uid |
+
+## Methods
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| getPage | - | Returns the current (reactive) page object |
+
+## Server contract
+The widget expects these socket paths on `controller` (base controller paths included):
+
+| Path | Payload | Returns |
+|------|---------|---------|
+| `${controller}.open` | `{ uid }` | `{ page, previewHost, debugMode? }` — `page.app.hosts[0].name` is used to build the public URL |
+| `${controller}.save` | `{ ...page, layout }` | - |
+| `${controller}.load-layouts` | `{}` | Array of layout objects |
+| `${controller}.create-layout` | layout | The created layout |
+| `${controller}.load-templates` | - | `{ items }` — component templates for the selector |
+| `${controller}.subscribe` / `.unsubscribe` | `{ name:'page' }` | - |
+| `${controller}.preset` | `{ key }` / `{ key, config }` | Persisted UI config |
+| `${controller}.chat` | `{ key, prompt, attachments, pageId, input }` | `{ messages }` — only needed when `useChat` is set |
+
+## Preview iframe protocol
+Messages are exchanged with the preview iframe via `postMessage`.
+
+Sent to the iframe:
+| Message | Description |
+|---------|-------------|
+| `{ action:'update', page }` | Full page JSON (headers, footers, components, stylesheet, data, editMode). Throttled; sent on every page/layout change |
+| `{ action:'select', uid }` | Scrolls/highlights the component with `uid` |
+| `{ action:'reload' }` | Reloads the preview |
+
+Received from the iframe:
+| Message | Description |
+|---------|-------------|
+| `{ type:'mounted' }` | Preview is ready; triggers the first update |
+| `{ type:'component-click', uid }` | Selects the clicked component in the editor |
+| `{ type:'setProp', uid, value }` | Merges `value` into the component's props (inline editing) |
+| `{ type:'setSubAction', value }` | Forwarded to the active setting component |
+
+## Provided injections
+`*Setting` components rendered in the right panel can inject: `imageUrl`, `imageSrc`, `store`, `postIframe`, `getPage`, `uploadImage`, `openComponentSelector`, `setUid`, `openRightPane2`, `getRightPane`, `pageHistory`, `duplicate`.
+
+Each component type `Foo` resolves its setting panel as a globally registered `FooSetting` component.
+
+## Keyboard shortcuts
+| Shortcut | Action |
+|----------|--------|
+| Alt+1 | Mobile view |
+| Alt+2 | Tablet view (`md:`) |
+| Alt+3 | Desktop view (`xl:`) |
+| Alt+4 | Wide view (`2xl:`) |
+
+## Samples
+
+### Page builder page (see `admin/src/pages/WebPageEdit.vue`)
+```vue
+<template>
+  <div class="flex-1 flex flex-col">
+    <WebPageBuilder class="flex-1"
+                    controller="web-page"
+                    preset-key="web-page"
+                    :more-components="components"
+                    :upload-image-fn="uploadImage"
+                    :use-chat="true"
+                    @close="$router.push({ name:'WebPage' })" />
+  </div>
+</template>
+
+<script setup>
+import {inject, ref} from 'vue'
+
+const socket = inject('useSocket')()
+
+const components = ref([
+  { type:'SaasRegister', name:'SAAS Register', group:'SAAS', props:{ items:[] }},
+])
+
+async function uploadImage(image){
+  return socket.send('web-page.upload-image', { image })
+}
+</script>
+```
+
+The route must carry the page uid, e.g.:
+```js
+{
+  name: 'WebPageEdit',
+  path: 'web-page/:uid',
+  component: () => import('./pages/WebPageEdit.vue')
+}
+```
+
+### Upload via config instead of a function
+```vue
+<WebPageBuilder controller="web-page"
+                :upload-config="{ method:'post', url:'/api/upload' }"
+                @close="$router.back()" />
+```