pagepilot-visual-editor 1.0.4 → 1.0.6

package/README.md

@@ -5,9 +5,16 @@ A standalone, prop-driven **React page-type visual editor**. Drop
 props, and listen for `onSaveChanges` / `onPublish` callbacks — the editor
 handles the UI, block creation, multi-section management, and HTML rendering.
 
-The package is **purely the editor**. No backend calls, no host-app coupling.
-The host owns persistence, navigation, plan gating, theming overrides, and
-everything else.
+Two integration modes:
+
+1. **Callback-only** *(default)*. The package is purely the editor: no
+   backend calls, no host coupling. The host owns persistence, navigation,
+   plan gating, theming overrides, and everything else.
+2. **Service-account API** *(opt-in via the `apiConfig` prop)*. Point the
+   editor at a pagepilot API instance and it takes over save / publish /
+   template listing / section library / tenant-plan gating for you. Same
+   auth pattern ahd-fe uses internally (`Authorization: Bearer <token>`),
+   configured once at mount time. See [Pagepilot API integration](#pagepilot-api-integration-optional).
 
 
 ---
@@ -27,35 +34,12 @@ Peer dependencies (your host should provide these):
 | Peer | Range | Notes |
 |---|---|---|
 | `react` | `^18.0.0 \|\| ^19.0.0` | React 18 and 19 both supported |
-| `react-dom` | `^18.0.0 \|\| ^19.0.0` | **Must be the exact same version as `react`** |
+| `react-dom` | `^18.0.0 \|\| ^19.0.0` | Match your `react` version |
 | `@mui/material` | `>=5` | v6 tested; v5 works |
 | `@mui/icons-material` | `>=5` | |
 | `@emotion/react` | `>=11` | Required by MUI |
 | `@emotion/styled` | `>=11` | Required by MUI |
 
-> **Avoiding "Incompatible React versions" at runtime**
->
-> npm 7+ auto-installs peer deps, which can pull `react-dom@latest` into your
-> app even when your `react` is pinned to an older patch. React refuses to
-> boot when the two versions differ. Force alignment by adding this to your
-> host app's `package.json`:
->
-> ```json
-> {
->   "overrides": {
->     "react-dom": "$react",
->     "@types/react-dom": "$@types/react"
->   },
->   "resolutions": {
->     "react-dom": "$react",
->     "@types/react-dom": "$@types/react"
->   }
-> }
-> ```
->
-> Then delete `node_modules` + `package-lock.json` and re-run `npm install`
-> (`overrides` is npm/pnpm, `resolutions` is yarn — safe to keep both).
-
 **Also required at runtime** (not currently listed as a peer, but the built
 bundle keeps them external — install these alongside the peers above):
 
@@ -116,21 +100,25 @@ built-in layout doesn't scale unexpectedly.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────┐
-│ ← Back  My Page  ● Draft  [Section ▾]   ↶ ↷  Save  ⋮  ⤢  ▶  Publish ▾   │  Topbar
+│ ← Back  My Page  ● Draft  [Section ▾]   ↶ ↷ ⊟  Save  ⋮  ⤢  ▶  Publish ▾  │  Topbar
 ├──────┬───────────────────┬─────────────────────────────────────────────┤
 │Style │ Appearance        │                                             │
 │Layout│  Color  ▢ ...     │     (canvas — block-based editor)           │
 │Inspct│  Font   ▾         │                                             │
 │Layers│  Radius PX        │                                             │
-│      │ Layout            │                                             │
-│      │  Width  100 %     │                                             │
+│Vars* │ Layout            │                                             │
+│SEO   │  Width  100 %     │                                             │
+│PgPlt │                   │                                             │
 └──────┴───────────────────┴─────────────────────────────────────────────┘
+                                              * only when template has vars
 ```
 
-- **Left rail** — 4 panels: **Style**, **Layout**, **Inspect**, **Layers** (each can be toggled off via the `panels` prop).
-- **Topbar** — every control is individually toggleable via the `topbar` prop.
+- **Left rail** — up to 7 panels: **Style**, **Layout**, **Inspect**, **Layers**, **Variables**, **SEO**, **Pagepilot** (each can be toggled off via the `panels` prop). Variables auto-hides unless a template with fields is applied or a repeatable container is selected. Pagepilot currently renders a "Coming soon" placeholder — the full AI page generator lands in a future release.
+- **Topbar** — every control is individually toggleable via the `topbar` prop. Includes undo / redo / **deselect block** (auto-hidden when nothing is selected) / save / more menu / fullscreen / preview / publish.
 - **Canvas** — the block-based page editor. Click the empty-state "Add first section" or the ⋮ → Add Section.
+- **Block TuneMenu** — appears above any selected block: move up / move down / delete / **open in Layers** / **more menu** (Save as template / Duplicate / Copy / Paste / **Replace** / Hide).
 - **3-dot menu** — currently exposes a single item, **Add Section**. Hidden by default; set `topbar.moreMenu` to `true`.
+- **Layout panel** — the Blocks palette is grouped into six categories (`Text/Content`, `Media`, `Layout/Structure`, `Actions/Controls`, `Embeds/Integrations`, `Support/Utility`). When `apiConfig` is passed, two additional tabs appear: **Templates** (global page templates) and **Saved** (per-tenant templates), plus a **Section Library** tile that opens a full gallery of section templates.
 
 ---
 
@@ -146,6 +134,7 @@ built-in layout doesn't scale unexpectedly.
 | `activeStepIndex` | `number` | `0` | Index of the currently-active section in the canvas. The editor also tracks this internally via the section dropdown. |
 | `behaviour` | `Record<string, any>` | `undefined` | **Passthrough only** — the editor does not consume this. Preserved in the save/publish payload if non-empty so host-owned config survives a round-trip. |
 | `steps` | `PageRecord["steps"]` | `undefined` | **Passthrough only** — legacy shape from the original tour/tooltip editor. The page editor does not read or render `steps`; it's preserved in the save payload when non-empty. |
+| `apiConfig` | `PagepilotApiConfig` | `undefined` | Opt-in pagepilot API integration. When passed, save/publish PUT the record through the API, Layout gets Templates / Saved tabs, Add-Block menu gets the Section Library tile, Publish opens a rich dialog, Variables panel gates on tenant plan. See [Pagepilot API integration](#pagepilot-api-integration-optional). |
 
 The editor reads `record.contentMetadata.document` (or `record.sections[activeStepIndex].contentMetadata.document` for multi-section pages) and seeds the canvas on first mount. After that the editor owns the document state; the host receives mutations via `onUpdateRecord`.
 
@@ -213,6 +202,11 @@ interface EditorPanelToggles {
   layout?: boolean;    // default true
   inspect?: boolean;   // default true
   layers?: boolean;    // default true
+  variables?: boolean; // default true — auto-hides when no template forms
+                       //                and no repeatable container selected
+  seo?: boolean;       // default true
+  pagepilot?: boolean; // default true — Pagepilot AI tab (currently
+                       //                renders a "Coming soon" placeholder)
 }
 ```
 
@@ -226,6 +220,8 @@ interface TopbarToggles {
   sectionsDropdown?: boolean;  // default true — still requires sections.length > 1
   undo?: boolean;              // default true
   redo?: boolean;              // default true
+  unselect?: boolean;          // default true — Deselect Block button
+                               //                (auto-hides when nothing selected)
   save?: boolean;              // default true
   themeToggle?: boolean;       // default true — sun/moon button flipping light/dark
   fullscreen?: boolean;        // default true
@@ -249,7 +245,10 @@ type BlockKey =
   | "buttonGroup" | "container"
   | "stepper" | "accordion" | "pricingAccordion"
   | "tabs" | "carousel" | "rating" | "marquee"
-  | "iframe" | "skipToMain" | "accessibilityTools";
+  | "iframe" | "skipToMain" | "accessibilityTools"
+  | "timer" | "pagination" | "table"
+  | "demoPicker" | "menuPicker" | "formsPicker"
+  | "appBannerPicker" | "faqPicker";
 
 type BlockToggles = Partial<Record<BlockKey, boolean>>;
 ```
@@ -281,6 +280,8 @@ type BlockToggles = Partial<Record<BlockKey, boolean>>;
 | `onBackgroundChange` | `(image: string) => void` | Fires when the page-level background image changes. |
 | `onNavigateBranding` | `() => void` | Fires from the Brand panel (currently stripped from the standalone build — kept for forward-compat). |
 | `onAddSection` | `() => void` | Custom Add-Section handler. **If provided**, the editor delegates entirely to the host — no built-in dialog. **If omitted**, clicking ⋮ → Add Section opens the built-in dialog. |
+| `onApiError` | `(error: Error, action: "save" \| "publish") => void` | Fires when a save/publish through `apiConfig` fails (network error, non-2xx response, invalid credentials, missing page id, etc.). Without this callback, failures only surface via `console.error` — the Save button stays "dirty" with no user-visible feedback. Use it to show a toast, refresh the auth token, redirect to a login screen, etc. Only relevant when `apiConfig` is set. |
+| `onUpgrade` | `() => void` | Fires when the user clicks the **Upgrade to unlock** CTA on the Variables-panel paywall. Route it to your billing / upgrade UI. Without this callback the button is a no-op. Only relevant when `apiConfig` is set. |
 
 #### `SaveChangesPayload`
 
@@ -329,6 +330,190 @@ Single-doc mode (no `sections`) is unchanged — the payload still carries
 
 ---
 
+## Pagepilot API integration (optional)
+
+Passing `apiConfig` to `<PagePilotEditor>` turns the editor into a full page-management surface. Under the hood it uses the exact auth + endpoint shapes that ahd-fe uses internally (`Authorization: Bearer <serviceAccountToken>`), so pages saved from the standalone editor round-trip identically to pages saved from ahd-fe.
+
+### What you get
+
+| Feature | Where it appears |
+|---|---|
+| Save Changes → `POST /tenant/:tenantId/upsert-page-item` | Topbar Save button + `apiClient.updatePage` fallback |
+| Publish → same endpoint with `status: "live"` + schedule | Topbar Publish opens a rich `PagePublishDialog` |
+| Templates tab (global page templates) | Layout panel > Templates |
+| Saved tab (per-tenant `my-templates`) | Layout panel > Saved |
+| Section Library gallery | Add-Block menu → Section Library tile |
+| Template preview dialog (Use / Use Styles / Add Section) | Clicking any template card |
+| Menu Links tab (add page to tenant menu) | Publish dialog |
+| Variables panel with paywall gated on tenant plan | Left rail → Variables (auto-shown when template has fields) |
+| `getTenant()` for plan detection | Runs once on mount when `apiConfig` is set |
+
+### Setup
+
+```tsx
+import { PagePilotEditor } from "pagepilot-visual-editor";
+
+<PagePilotEditor
+  record={page}
+  apiConfig={{
+    baseUrl: "https://pagepilot.fabbuilder.com/api",  // no trailing slash, no "/tenant"
+    tenantId: "6655bc2b30a6760d8f897581",             // your pagepilot tenant id
+    authToken: "eyJhbGciOi…",                         // pre-issued service-account bearer
+  }}
+  onApiError={(err, action) => toast.error(`${action}: ${err.message}`)}
+  onUpgrade={() => openBillingModal()}
+  // onSaveChanges / onPublish still fire AFTER a successful API write
+  // if you also want to react (e.g. clear a dirty flag, refresh a listing).
+  onSaveChanges={async ({ record }) => { revalidatePageList(); }}
+/>
+```
+
+Requirements for the API path to actually fire:
+
+- `record.id` must be a real backend id (a MongoDB ObjectId in the tenant). The built-in seed id `"doc-1"` is intentionally skipped so demo records don't POST to a non-existent page.
+- The `authToken` must be a valid service-account bearer for the given `tenantId`. Get one from your pagepilot admin console (same token ahd-fe stores in `VITE_PAGEPILOT_SERVICE_AUTH_TOKEN`).
+
+### PagepilotApiConfig shape
+
+```ts
+interface PagepilotApiConfig {
+  /** API root without a trailing slash, e.g. "https://pagepilot.fabbuilder.com/api". */
+  baseUrl: string;
+  /** Tenant id used in `/tenant/${tenantId}/...` paths. */
+  tenantId: string;
+  /** Pre-issued service-account bearer. Sent as `Authorization: Bearer <token>`. */
+  authToken: string;
+}
+```
+
+### Save + Publish request shape
+
+The editor batches the render + payload build for you. When the user clicks **Save Changes** or **Publish**, this exact request goes out:
+
+```http
+POST https://pagepilot.fabbuilder.com/api/tenant/${tenantId}/upsert-page-item
+Content-Type: application/json
+Authorization: Bearer ${authToken}
+
+{
+  "data": {
+    ...record,                    // full record — id, name, slug, tags, groups, tenant, …
+    "pageId": "6a43bc20…",        // === record.id
+    "status": "live" | "draft",   // "draft" for Save Changes, "live" for Publish
+    "sections": [                 // rendered sections (source of truth for multi-section pages)
+      {
+        "title": "Section 1",
+        "sectionType": "internal",
+        "identifier": "section-1784032010220",
+        "content": "<div …>…rendered HTML…</div>",
+        "contentMetadata": {
+          "document": { "root": { "type": "EmailLayout", … }, "block-…": {…} }
+        }
+      }
+    ],
+    "startDate": "…",             // optional — only when Publish schedule is set
+    "endDate": "…"                // optional — only when Publish schedule is set
+  }
+}
+```
+
+**Same shape ahd-fe writes.** The rendered `sections[].content` HTML is what the pagepilot public page-serving layer reads.
+
+**Failure handling.** Any non-2xx response throws inside the editor. Without `onApiError`, the error is logged to `console.error` and the Save button stays visually "dirty" (no state change). Passing `onApiError` lets you surface it to the user:
+
+```tsx
+<PagePilotEditor
+  apiConfig={apiConfig}
+  onApiError={(err, action) => {
+    console.error(`[pagepilot] ${action} failed`, err);
+    toast.error(err.message);
+  }}
+/>
+```
+
+### The Publish dialog
+
+When `apiConfig` is set, clicking **Publish** opens a full dialog instead of firing `onPublish` immediately. The dialog mirrors ahd-fe's `PagePublishDialog`:
+
+- **Basic Info** tab: page name, slug, publish date, "All Time Live" toggle, end date (when off).
+- **Menu Links** tab: pick a tenant menu (fetched via `apiClient.listMenus`) and append this page as a new item to that menu's `configuration`.
+- **Save Draft** and **Publish** buttons at the bottom. Both use the same `upsert-page-item` endpoint above; the CTA differs by the `status` field.
+
+If you'd rather keep the direct one-click publish (fires `onPublish` without a dialog), set `apiConfig` to `undefined` — the direct callback flow still works.
+
+### Templates + Saved + Section Library
+
+- **Templates tab** (`Layout > Templates`): fetches `GET /global-template?filter[type]=page&limit=10&offset=0`. Click a card → preview dialog with three actions:
+  - **Use this Template** — replaces the canvas with the template's document.
+  - **Use this Styles** — overlays only the template's root visual styles (colors, fonts, radius, padding) onto your current document; blocks stay put.
+  - **Add this section** — appends the template's blocks to the current document (id-remapped so a second apply doesn't collide with the first).
+- **Saved tab** (`Layout > Saved`): same UI, fetches `GET /tenant/${tenantId}/mytemplate?filter[type]=page&limit=10&offset=0`. Includes a delete affordance on hover.
+- **Section Library** modal: opened from the "Section Library" tile in the Add-Block menu. Fetches `GET /global-template?filter[type]=block&limit=100&offset=0`, groups by category (`hero`, `features`, `testimonial`, `pricing`, `cta`, `faq`, `about`, `team`, `contact`, `footer`, …), and inserts the picked block as a new section.
+
+Every apply route also populates the Variables panel from the template's declared `formFields`, so template tokens (`{{name}}`, `{{price}}`, `{{FAQs}}`, …) are ready to fill in immediately.
+
+**Paywall.** Templates with a `supportedPlans: ["proCombo"]` (or higher) show an "Upgrade to unlock" prompt in the preview dialog when the tenant plan is below that tier. The `onUpgrade` callback routes the CTA to your billing UI.
+
+### Variables panel + tenant plan gating
+
+The Variables tab surfaces template tokens for filling at edit time. Visibility is controlled by:
+
+1. **The template must declare fields.** The tab auto-hides on documents with no template forms and no repeatable container selected.
+2. **The tenant plan must be Pro or above** (or the template must be unrestricted). The gate is checked once via `apiClient.getTenant()` on mount:
+   - `plan === "proCombo" | "enterprise"` → real field editors render.
+   - Anything else (including `"free"`, `"starterCombo"`, missing plan, failed fetch) → paywall renders.
+3. **The paywall CTA** ("Upgrade to unlock") fires `onUpgrade` if the host provided it; otherwise it's a no-op with a console message.
+
+The whole gating logic mirrors ahd-fe's `useTenantPlan` hook and can be safely disabled by passing `panels={{ variables: false }}` — the whole tab disappears from the rail.
+
+### Direct API client access
+
+The `PagepilotApiClient` class the editor uses internally is also exported so hosts can hit the same endpoints outside the editor tree — e.g. to create a page before mounting:
+
+```ts
+import { PagepilotApiClient } from "pagepilot-visual-editor";
+
+const client = new PagepilotApiClient({
+  baseUrl: "https://pagepilot.fabbuilder.com/api",
+  tenantId: "6655bc2b30a6760d8f897581",
+  authToken: process.env.PAGEPILOT_SERVICE_TOKEN!,
+});
+
+const created = await client.createPage({
+  name: "New Onboarding Page",
+  slug: "onboarding",
+  groups: [],
+});
+
+// Then mount the editor pointing at the new page.
+<PagePilotEditor record={{ id: created.id, name: created.name }} apiConfig={...} />
+```
+
+Available methods:
+
+| Method | Endpoint |
+|---|---|
+| `createPage(data)` | `POST /tenant/:tenantId/page` |
+| `updatePage(id, data)` | `PUT /tenant/:tenantId/page/:id` |
+| `quickSavePage(id, data)` | `PATCH /tenant/:tenantId/page/:id` |
+| `upsertPage(data)` | `POST /tenant/:tenantId/upsert-page-item` (used by save + publish) |
+| `findPage(id)` | `GET /tenant/:tenantId/page/:id` |
+| `getTenant()` | `GET /tenant/:tenantId` (used by plan gate) |
+| `listGlobalTemplates(params)` | `GET /global-template` |
+| `findGlobalTemplate(id)` | `GET /global-template/:id` |
+| `destroyGlobalTemplates(ids)` | `DELETE /global-template` |
+| `listTenantTemplates(params)` | `GET /tenant/:tenantId/template` |
+| `findTenantTemplate(id)` | `GET /tenant/:tenantId/template/:id` |
+| `listMyTemplates(params)` | `GET /tenant/:tenantId/mytemplate` |
+| `createTemplate(data)` | `POST /tenant/:tenantId/template` |
+| `destroyTenantTemplates(ids)` | `DELETE /tenant/:tenantId/template` |
+| `listMenus(params)` | `GET /tenant/:tenantId/menu` |
+| `updateMenu(id, data)` | `PUT /tenant/:tenantId/menu/:id` |
+
+All methods send `Content-Type: application/json` + the bearer token automatically.
+
+---
+
 ## Behavior reference
 
 ### Topbar buttons
@@ -339,7 +524,8 @@ Single-doc mode (no `sections`) is unchanged — the payload still carries
 | **Page title + status pill** | Display-only. Sourced from `recordTitle` / `recordStatus` (or `record.title / record.name / record.status`). |
 | **Section dropdown** | Only appears when `record.sections.length > 1`. Lets the user pick / edit / delete sections. Switching a section flushes the current canvas edits into the active section, then loads the target section's document onto the canvas. |
 | **Undo / Redo** | Hooked to the editor's internal history stack. Buttons disable when there's nothing to undo/redo. A settle-window guard on mount prevents block-level `useEffect`s (auto-seed, positioning re-measure, etc.) from preloading spurious entries — Undo starts disabled on every fresh load until the user makes a real edit. |
-| **Save Changes** | **Dirty-tracked.** Disabled with tooltip "No unsaved changes" until the user makes their first edit; enables on every subsequent edit; disables again after `onSaveChanges` resolves (unless the handler returns `false`). Builds the payload (renders document → HTML, flushes sections) and calls `onSaveChanges`. |
+| **Deselect Block** ⊟ | Only appears when a block is selected on the canvas. Clears `selectedBlockId` so the block's TuneMenu / handles collapse and the Inspect panel unfocuses. Same behavior as ahd-fe's `TabUnselectedOutlined` button. Hidden entirely via `topbar={{ unselect: false }}`. |
+| **Save Changes** | **Dirty-tracked.** Disabled with tooltip "No unsaved changes" until the user makes their first edit; enables on every subsequent edit; disables again after `onSaveChanges` resolves (unless the handler returns `false`). Builds the payload (renders document → HTML, flushes sections) and calls `onSaveChanges`. When `apiConfig` is set, the editor **first** persists via `POST /upsert-page-item`, then fires `onSaveChanges` — errors surface via `onApiError`. |
 | **Theme toggle** ☀/🌙 | Sun/moon icon flips between the built-in light and dark themes. The choice is persisted in `localStorage` under `pagepilot.editor.mode.v1`, so a page reload keeps the user's preference — even if `props.mode` changes. Hidden automatically when the host passes a custom `theme` prop (no `mode` to flip). |
 | **3-dot menu** ⋮ | Single item: **+ Add Section**. Off by default — enable via `topbar.moreMenu`. |
 | **Fullscreen** ⤢ | Toggles the editor's container via the browser Fullscreen API. Icon swaps to "exit fullscreen" while active; pressing `Esc` exits. |
@@ -347,13 +533,36 @@ Single-doc mode (no `sections`) is unchanged — the payload still carries
 | **Publish** | Calls `onPublish`. |
 | **Publish ▾** | Calls `onPublishMenu(anchorEl, payload)` so the host can open a custom dialog/popover anchored to the button. |
 
+### Block TuneMenu
+
+Selecting any block on the canvas surfaces a floating action popover just above it. The strip contains, in order:
+
+| Action | Behavior |
+|---|---|
+| **↑ Move up** | Swaps this block with its previous sibling under the same parent. |
+| **↓ Move down** | Swaps with the next sibling. |
+| **🗑 Delete** | Removes the block and its subtree. Also prunes any `formFields` whose `sourceBlockId` pointed at this block. |
+| **⧉ Open in Layers** | Selects this block and flips the sidebar to the **Layers** tab so you can see (and drag/reorder) the block inside the tree. |
+| **⋯ More menu** | Opens the secondary popover below. |
+
+The **⋯ More** popover contains:
+
+| Item | Behavior |
+|---|---|
+| **Save as template** | Serialises the selected block into a template configuration. Only wired when the host provides its own persistence path — the standalone build has no built-in "save template" dialog. |
+| **Duplicate** | Deep-clones the block (all descendants get fresh ids) and inserts the copy right after the original. |
+| **Copy** | Writes the block's configuration to the editor's clipboard slot. Persists across selection changes so you can paste onto a different block. |
+| **Paste** | Enabled only when there's a copied block. Appends the copied block as a child of THIS block (id-remapped so nothing collides). |
+| **Replace** | Enabled only when there's a copied block. Swaps THIS block in place with a fresh id-remapped copy of the clipboard's block — same position, new content. |
+| **Hide** | Toggles the block's canvas visibility (collapses to `display: none`). Unhide from the Layers panel. |
+
 ### Add Section flow
 
 1. User clicks ⋮ → **+ Add Section** (or the empty-state button).
 2. A modal asks for a **Title**.
 3. On submit:
    - The active section's in-progress canvas document is flushed into `record.sections[activeIndex].contentMetadata.document` (no edits lost).
-   - A new section is appended, seeded with a default empty `PagePilotLayout` document.
+   - A new section is appended, seeded with a default empty `EmailLayout` document.
    - The host receives the updated record via `onUpdateRecord`.
    - The canvas swaps to the new section's document so the user can immediately edit it.
    - The active step index is bumped.
@@ -375,12 +584,20 @@ The image is inserted at the caret position and can then be resized
 appears when you click it. The standalone editor deliberately doesn't ship
 a media-library backend — the URL field is the integration point.
 
+### Pagepilot AI panel
+
+Currently a **Coming soon** placeholder. The tab has the purple `AiPanelIcon` in the rail and opens a centered card that says AI-driven page generation is on the way. When the full generator is ported (prompt input + model picker + voice input, per the ahd-fe reference), the panel body swaps in without any other API changes. Hide the tab entirely via `panels={{ pagepilot: false }}`.
+
 ### Layout panel
 
-The Layout panel shows a single tile grid — the **Blocks** picker. The
-Templates and Saved-templates tabs from the Pagepilot host app are
-intentionally omitted; those require the host's team-template backend.
-Add-Block tile visibility is controlled per-block via the `blocks` prop.
+The Layout panel always shows the **Blocks** picker — a category-grouped tile grid (`Text/Content`, `Media`, `Layout/Structure`, `Actions/Controls`, `Embeds/Integrations`, `Support/Utility`). Add-Block tile visibility is controlled per-block via the `blocks` prop.
+
+When `apiConfig` is set, two additional tabs appear at the top of the Layout panel:
+
+- **Templates** — global page templates from `/global-template?filter[type]=page`. Click any card → template preview dialog with three CTAs (Use Template / Use Styles / Add Section).
+- **Saved** — per-tenant `/mytemplate` list. Same card UI with an on-hover delete button.
+
+The Add-Block menu also gains a highlighted **Section Library** tile (opens a full-screen gallery of block-type templates grouped by category). Without `apiConfig`, all three affordances are hidden — the Layout panel stays a lean block palette.
 
 ### Image block sidebar
 
@@ -393,7 +610,7 @@ if the standalone integration model doesn't fit.
 
 ### Preview
 
-- **Default behavior** (no `onTogglePreview`): the editor renders every section through `renderToStaticMarkup`, concatenates the fragments inside a minimal HTML shell (with viewport meta + base font + canvas color from `PagePilotLayout.canvasColor`), and shows it in an in-page MUI dialog with desktop / tablet / mobile size toggles. The iframe uses `srcDoc` (inline HTML) so no network round-trip and no blob-URL flake. The "Open in new tab" header icon is hidden in this mode (nothing to link to — the HTML is inline). A host that supplies a real `previewUrl` (via internal preview server) gets the icon.
+- **Default behavior** (no `onTogglePreview`): the editor renders every section through `renderToStaticMarkup`, concatenates the fragments inside a minimal HTML shell (with viewport meta + base font + canvas color from `EmailLayout.canvasColor`), and shows it in an in-page MUI dialog with desktop / tablet / mobile size toggles. The iframe uses `srcDoc` (inline HTML) so no network round-trip and no blob-URL flake. The "Open in new tab" header icon is hidden in this mode (nothing to link to — the HTML is inline). A host that supplies a real `previewUrl` (via internal preview server) gets the icon.
 - **Custom UI**: pass `onTogglePreview={(html, doc) => myDialog.open(html)}` to skip the built-in dialog and render your own.
 
 ### Save / Publish payload generation
@@ -404,7 +621,7 @@ When the user clicks **Save Changes** or **Publish**, the editor does the follow
 2. If the record has `sections`, flushes the canvas document into `sections[activeIndex].contentMetadata.document` so the active section is up-to-date.
 3. Renders every section's document via `renderToStaticMarkup({ rootBlockId: "root", injectElementIds: true, minifyCss: true, includePageCSS: true, lang, skipLink, accessibilityTools })`.
 4. Per-section HTML is written to `section.content` and per-section documents to `section.contentMetadata.document`.
-5. All section fragments are concatenated inside a single HTML document with viewport meta, base font, and canvas color from `PagePilotLayout`.
+5. All section fragments are concatenated inside a single HTML document with viewport meta, base font, and canvas color from `EmailLayout`.
 6. **Multi-section payload**: `{ record, html }` with the record's redundant `contentMetadata` / empty `behaviour` / empty `steps` stripped, and the outer `document` key omitted.  
    **Single-doc payload**: `{ record, document, html }` where `record.contentMetadata` carries `document` + `html`.
 
@@ -478,20 +695,22 @@ The full set of keys the editor reads is documented inline at `src/host-stubs/i1
 
 ## Block types
 
-Out of the box the Add-Block menu exposes 25 block types:
+Out of the box the Add-Block menu exposes 33 block types, grouped into six categories:
 
-| Layout | Content | Media | Specialized |
-|---|---|---|---|
-| Container | Heading | Image | Stepper |
-| Columns | Text | Logo | Accordion |
-| Flex Columns | Button | Video | Pricing |
-| Grid | Button Group | Avatar | Tabs |
-| Spacer | Html | | Carousel |
-| Divider | | | Rating |
-| | | | Marquee |
-| | | | iFrame |
-| | | | Skip Link |
-| | | | Accessibility |
+| Text/Content | Media | Layout/Structure | Actions/Controls | Embeds/Integrations | Support/Utility |
+|---|---|---|---|---|---|
+| Heading | Image | Container | Button | Timer | Rating |
+| Text | Logo | Columns | Button Group | YouTube Url | Skip Link |
+| Table | Video | Flex Columns | Accordion | Demo Picker¹ | Accessibility |
+| | Avatar | Grid | Tabs | Header¹ (MenuPicker) | |
+| | | Spacer | Stepper | Forms¹ | |
+| | | Divider | | App Banner¹ | |
+| | | Html | | FAQs¹ | |
+| | | Carousel | | IFrame | |
+| | | Pagination | | Calendly | |
+| | | Marquee | | | |
+
+¹ Picker blocks (Demo / Header / Forms / App Banner / FAQs) surface tenant-managed records. Without host-provided data (via `record.contentMetadata.document` or a bespoke integration) they render their empty state.
 
 Hide any of them via the `blocks` prop. Tile labels can be re-translated via `translations`.
 
@@ -545,11 +764,15 @@ export {
 // Imperative store access
 export * as EditorContext from "pagepilot-visual-editor";
 
+// Pagepilot API client (for hosts using `apiConfig`)
+export { PagepilotApiClient } from "pagepilot-visual-editor";
+
 // Types
 export type {
   PagePilotEditorProps, PageRecord, SaveChangesPayload,
   EditorPanelToggles, TopbarToggles,
   BlockKey, BlockToggles,
+  PagepilotApiConfig, ListParams, PageListRow, PageListResponse,
   TReaderBlock, TReaderDocument, TReaderBlockProps, TReaderProps,
 } from "pagepilot-visual-editor";
 ```

package/dist/api/ApiClientContext.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { PagepilotApiClient, PagepilotApiConfig } from './PagepilotApiClient';
+interface ProviderProps {
+    config?: PagepilotApiConfig;
+    /**
+     * Override the base URL used for the public `/global-template` fetch.
+     * Defaults to `DEFAULT_GLOBAL_TEMPLATES_BASE_URL`. If `config.baseUrl` is
+     * present it wins (same origin as the authed calls, keeps the environment
+     * consistent).
+     */
+    globalTemplatesBaseUrl?: string;
+    children: ReactNode;
+}
+export declare function PagepilotApiClientProvider({ config, globalTemplatesBaseUrl, children, }: ProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function usePagepilotApiClient(): PagepilotApiClient | null;
+export declare function useGlobalTemplatesBaseUrl(): string;
+export {};

package/dist/api/PagepilotApiClient.d.ts

@@ -0,0 +1,63 @@
+export interface PagepilotApiConfig {
+    /** API root without trailing slash, e.g. "https://pagepilot.fabbuilder.com/api" */
+    baseUrl: string;
+    /** Tenant id used in `/tenant/${tenantId}/...` paths. */
+    tenantId: string;
+    /** Pre-issued service-account bearer token. Sent as `Authorization: Bearer <token>`. */
+    authToken: string;
+}
+export interface ListParams {
+    filter?: Record<string, unknown>;
+    orderBy?: string | null;
+    limit?: number;
+    offset?: number;
+}
+export interface PageListRow {
+    id: string;
+    [key: string]: any;
+}
+export interface PageListResponse {
+    rows: PageListRow[];
+    count?: number;
+}
+export declare class PagepilotApiClient {
+    readonly baseUrl: string;
+    readonly tenantId: string;
+    private readonly authToken;
+    constructor(cfg: PagepilotApiConfig);
+    private headers;
+    private buildUrl;
+    private request;
+    createPage(data: Record<string, unknown>): Promise<any>;
+    updatePage(id: string, data: Record<string, unknown>): Promise<any>;
+    /** PATCH — matches PageService.quickSave. */
+    quickSavePage(id: string, data: Record<string, unknown>): Promise<any>;
+    /**
+     * POST /tenant/:tenantId/upsert-page-item — matches `PageService.upsert`.
+     * This is the endpoint ahd-fe's editor uses for both save-draft and
+     * publish (via `useSaveHandler.saveContent`). The full record — including
+     * `pageId`, `status`, rendered `sections[]`, and optional
+     * `startDate`/`endDate` — travels inside `data`.
+     */
+    upsertPage(data: Record<string, unknown>): Promise<any>;
+    findPage(id: string): Promise<any>;
+    listGlobalTemplates(params?: ListParams): Promise<PageListResponse>;
+    findGlobalTemplate(id: string): Promise<any>;
+    destroyGlobalTemplates(ids: string[]): Promise<any>;
+    listTenantTemplates(params?: ListParams): Promise<PageListResponse>;
+    findTenantTemplate(id: string): Promise<any>;
+    listMyTemplates(params?: ListParams): Promise<PageListResponse>;
+    createTemplate(data: Record<string, unknown>): Promise<any>;
+    destroyTenantTemplates(ids: string[]): Promise<any>;
+    listMenus(params?: ListParams): Promise<PageListResponse>;
+    updateMenu(id: string, data: Record<string, unknown>): Promise<any>;
+    getTenant(): Promise<{
+        id: string;
+        plan?: string;
+        [key: string]: any;
+    }>;
+}
+/** Default public API root. Hosts can override via `globalTemplatesBaseUrl`. */
+export declare const DEFAULT_GLOBAL_TEMPLATES_BASE_URL = "https://pagepilot.fabbuilder.com/api";
+export declare function listGlobalTemplatesPublic(baseUrl: string, params?: ListParams): Promise<PageListResponse>;
+export declare function findGlobalTemplatePublic(baseUrl: string, id: string): Promise<any>;

package/dist/api/useTenantPlan.d.ts

@@ -0,0 +1,25 @@
+/** Plan tiers ranked lowest → highest, mirrors ahd-fe's `Plans.values`. */
+export declare const PLAN_RANK: Record<string, number>;
+export declare const isProOrAboveTenant: (tenant?: {
+    plan?: string;
+}) => boolean;
+export interface UseTenantPlanReturn {
+    currentTenant: {
+        id?: string;
+        plan?: string;
+        [key: string]: any;
+    } | null;
+    isPlanProOrAbove: boolean;
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * Resolve the tenant plan for gating paid features.
+ *
+ * Behaviour:
+ *   - No apiClient          → returns `{ currentTenant: null, isPlanProOrAbove: false }`
+ *   - apiClient present     → GETs `/tenant/:tenantId` once and caches
+ *   - Fetch fails           → `error` is set, `isPlanProOrAbove` defaults to `false`
+ *                             (safe-fail: paywall stays up when we can't verify plan)
+ */
+export declare function useTenantPlan(): UseTenantPlanReturn;

package/dist/blocks-internal/block-button/src/index.d.ts

@@ -35,12 +35,12 @@ export declare const ButtonPropsSchema: z.ZodObject<{
             BEBAS_NEUE: "BEBAS_NEUE";
         }>>>;
         fontWeight: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            bold: "bold";
             400: "400";
             500: "500";
             600: "600";
             700: "700";
             normal: "normal";
-            bold: "bold";
         }>>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             right: "right";
@@ -83,13 +83,41 @@ export declare const ButtonPropsSchema: z.ZodObject<{
             fixed: "fixed";
             fit: "fit";
         }>>>;
+        widthTypeTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            fill: "fill";
+            fixed: "fixed";
+            fit: "fit";
+        }>>>;
+        widthTypeMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            fill: "fill";
+            fixed: "fixed";
+            fit: "fit";
+        }>>>;
         width: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        widthUnit: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            px: "px";
+            "%": "%";
+        }>>>;
+        widthTablet: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        widthMobile: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         size: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             small: "small";
             "x-small": "x-small";
             large: "large";
             medium: "medium";
         }>>>;
+        sizeTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            small: "small";
+            "x-small": "x-small";
+            large: "large";
+            medium: "medium";
+        }>>>;
+        sizeMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            small: "small";
+            "x-small": "x-small";
+            large: "large";
+            medium: "medium";
+        }>>>;
         text: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         url: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         action: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
@@ -115,12 +143,15 @@ export declare const ButtonPropsSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ButtonProps = z.infer<typeof ButtonPropsSchema>;
+export declare const isValidButtonColor: (c: unknown) => c is string;
+export declare const isValidButtonFontFamily: (f: unknown) => f is string;
 export declare const ButtonPropsDefaults: {
     readonly text: "";
     readonly url: "";
     readonly fullWidth: false;
     readonly widthType: "fit";
     readonly width: 200;
+    readonly widthUnit: "px";
     readonly size: "medium";
     readonly borderRadius: 4;
     readonly borderColor: "";