pagepilot-visual-editor 1.0.7 → 1.0.8

package/README.md

@@ -114,10 +114,10 @@ built-in layout doesn't scale unexpectedly.
 ```
 
 - **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`.
+- **Topbar** — every control is individually toggleable via the `topbar` prop. Includes zoom out / zoom-% / zoom in (also driven by Ctrl/Cmd + wheel) / undo / redo / **deselect block** (auto-hidden when nothing is selected) / save / **auto save** (opt-in) / desktop-tablet-mobile / theme / more menu / fullscreen / preview / publish.
+- **Canvas** — the block-based page editor. Click the empty-state "Add first section" or the ⋮ → Add Section. A **minimap** overview (togglable from the 3-dot menu) docks to the bottom-right and lets you click / drag to scroll long pages. Unsaved edits show the browser's native "Leave site?" prompt on tab close or reload.
+- **Block TuneMenu** — appears above any selected block: **drag handle** (native reorder) / move up / move down / delete / **open in Layers** / **edit variables** (template-bound blocks only) / **more menu** (Save as template / Duplicate / Copy / Paste / **Replace** / Hide).
+- **3-dot menu** — hidden by default; enable via `topbar.moreMenu`. Contains **Add Section** and **Show / Hide Minimap**.
 - **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.
 
 ---
@@ -191,6 +191,8 @@ interface PageSection {
 | `translations` | `Record<string, string>` | `{}` | Merged on top of the built-in English dictionary. Missing keys fall back to defaults; missing default keys fall back to humanizing the last segment of the key. |
 | `topbar` | `TopbarToggles` | see below | Per-control visibility for the topbar. |
 | `blocks` | `BlockToggles` | all true | Per-tile visibility for the Add-Block menu. |
+| `autoSaveEnabled` | `boolean` | `undefined` | Controlled value for the Auto Save switch. When `undefined` the switch is uncontrolled and its state is persisted to `localStorage` under `pagepilot.editor.autoSave.v1`. When set, the host owns the checked state and must update it via `onAutoSaveChange`. The switch itself is only rendered when `topbar.autoSave === true`. |
+| `autoSaveIntervalMs` | `number` | `60000` | Autosave interval in milliseconds. Matches ahd-fe's 60-second cadence. Set to `0` to disable the interval while still showing the switch (useful for tests). |
 | `headerExtra` | `ReactNode` | `undefined` | Rendered immediately below the topbar — use for custom banners/announcement bars. |
 | `children` | `ReactNode` | `undefined` | Rendered after the editor body. |
 
@@ -223,6 +225,10 @@ interface TopbarToggles {
   unselect?: boolean;          // default true — Deselect Block button
                                //                (auto-hides when nothing selected)
   save?: boolean;              // default true
+  autoSave?: boolean;          // default FALSE — Auto Save switch next to Save Changes
+  screenSize?: boolean;        // default true — Desktop/Tablet/Mobile icon strip
+                               //                (also drives which per-device slice
+                               //                 the sidebar is editing)
   themeToggle?: boolean;       // default true — sun/moon button flipping light/dark
   fullscreen?: boolean;        // default true
   preview?: boolean;           // default true
@@ -231,7 +237,7 @@ interface TopbarToggles {
 }
 ```
 
-**Defaults note:** `moreMenu` and `publish` are **off by default** — they only appear when explicitly enabled. Everything else is on by default.
+**Defaults note:** `autoSave`, `moreMenu`, and `publish` are **off by default** — they only appear when explicitly enabled. Everything else is on by default.
 
 #### `BlockToggles`
 
@@ -239,7 +245,7 @@ Per-tile visibility for the Add-Block menu. Each key defaults to `true`.
 
 ```ts
 type BlockKey =
-  | "heading" | "text" | "button" | "image" | "logo" | "video"
+  | "heading" | "list" | "text" | "button" | "image" | "logo" | "video"
   | "avatar" | "divider" | "spacer" | "html"
   | "columns" | "flexColumns" | "grid"
   | "buttonGroup" | "container"
@@ -280,8 +286,9 @@ 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. |
+| `onAutoSaveChange` | `(enabled: boolean) => void` | Fires when the user flips the Auto Save switch. Always fires (both controlled and uncontrolled use) so hosts can mirror the flag to their own settings store. Only relevant when `topbar.autoSave === true`. |
 | `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. |
+| `onUpgrade` | `() => void` | Fires when the user clicks the **Upgrade to unlock** CTA on the Variables-panel paywall. Route it to your billing / upgrade UI and the host owns the whole flow. **Without this callback the built-in `<UpgradeDialog>` opens instead** — a lightweight fallback whose "Upgrade Plan" button links to the pagepilot billing URL in a new tab. Only relevant when `apiConfig` is set. |
 
 #### `SaveChangesPayload`
 
@@ -348,6 +355,191 @@ Passing `apiConfig` to `<PagePilotEditor>` turns the editor into a full page-man
 | 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 |
 
+### Getting your credentials
+
+Before you can pass `apiConfig`, you need two things from your pagepilot admin console: a **`tenantId`** and an **`authToken`**. Both come from screens inside pagepilot itself. Skim the subsections in order — steps 1 and 2 are the actual credentials, the rest is production plumbing.
+
+- [Prerequisites](#prerequisites)
+- [Step 1 — Get your tenantId](#step-1--get-your-tenantid)
+- [Step 2 — Mint an authToken](#step-2--mint-an-authtoken)
+- [Storing credentials safely](#storing-credentials-safely)
+- [Rotating a token](#rotating-a-token)
+- [Troubleshooting credentials](#troubleshooting-credentials)
+- [Verifying your setup](#verifying-your-setup)
+
+#### Prerequisites
+
+- A pagepilot account on [pagepilot.fabbuilder.com](https://pagepilot.fabbuilder.com) with access to at least one **workspace** (called a "tenant" everywhere in the API). The Free plan is enough to get save + publish working; some features gate behind Pro (see [Variables panel + tenant plan gating](#variables-panel--tenant-plan-gating)).
+- **Owner or Admin** role in that workspace. Members with `Editor` / `Viewer` roles can't mint service accounts — the "Create Service Account" link is hidden.
+- The workspace must already have at least one **page record** created (via `pagepilot.fabbuilder.com` or a direct `POST /tenant/:tenantId/page`). The editor's `record.id` must be a real backend id — see [Setup](#setup).
+
+#### Step 1 — Get your tenantId
+
+*(Workspaces → Workspace Id)*
+
+Open [pagepilot.fabbuilder.com/tenant](https://pagepilot.fabbuilder.com/tenant). The page lists every workspace you belong to; the one shown at the top with the green **Active** badge is the workspace whose pages the editor will read + write. The **Workspace Id** printed under the workspace name IS your `tenantId` — copy it.
+
+![Workspaces page — the Workspace Id field is your tenantId](./src/assets/integration-guide/step-1-workspace-id.svg)
+
+Notes:
+- The id is a 24-char MongoDB ObjectId (e.g. `69e34f656c1eca798ec815bd`). If yours has dashes or spaces, you've grabbed something else.
+- If you belong to multiple workspaces, each has its own tenantId — pages don't cross tenant boundaries. Pick the workspace that owns the pages you want to edit.
+- Switching workspaces? Change the Active workspace in pagepilot first (via the top-left workspace picker), then re-copy the id — or just remember that `tenantId` is a per-workspace value.
+
+> Tip: use the copy icon next to the id — the workspace name in the header is a link and can trigger a navigation if you double-click into the text.
+
+#### Step 2 — Mint an authToken
+
+*(Settings → Teams → Service Account)*
+
+The editor authenticates to the pagepilot API with a **service-account bearer token** (a long-lived JWT scoped to the workspace). To create one:
+
+1. Go to **Settings → Teams** in pagepilot ([pagepilot.fabbuilder.com/settings/invite-members](https://pagepilot.fabbuilder.com/settings/invite-members)).
+2. Toggle **Show Service Accounts** on (top-right, next to "Invite Member"). This reveals the **Create Service Account** link — service accounts are hidden by default so the Teams tab stays clean for admins who don't use them.
+3. Click **Create Service Account**.
+
+![Settings → Teams tab with "Create Service Account" highlighted](./src/assets/integration-guide/step-2-service-accounts.svg)
+
+In the modal that opens, fill in three fields:
+
+| Field | What to enter | Notes |
+|---|---|---|
+| **Service Account ID** | A descriptive name, e.g. `visual-editor-prod`. | Free-form. Shows up in the Teams table so you can revoke it later. |
+| **Access** | Pick the **lowest** role that satisfies your use case. | See the access-level table below. `Admin` is a safe default for editing + publishing. |
+| **Expiration** | Any horizon from 7 days to 1 year. | The editor **does not refresh the token itself** — pick a window that matches your rotation policy. 30 days is a reasonable default; use a shorter window for dev / demo tokens. |
+
+**Access levels (which one to pick):**
+
+| Role | Can read pages | Can save (draft) | Can publish (`status: "live"`) | Can list / create templates |
+|---|---|---|---|---|
+| `Viewer` | ✅ | ❌ | ❌ | Read-only |
+| `Editor` | ✅ | ✅ | ❌ | Read + save-as-template |
+| `Admin` | ✅ | ✅ | ✅ | Full |
+| `Owner` | ✅ | ✅ | ✅ | Full + billing |
+
+**For most editor integrations, pick `Admin`** — the editor needs both save + publish and reads Templates / Saved / global-template endpoints. Only drop to `Editor` if the embedded editor is a "draft-only" surface where publishing happens elsewhere.
+
+![Service Account creation modal — click Create to mint the token](./src/assets/integration-guide/step-3-service-account-form.svg)
+
+Click **Create**. Pagepilot shows the generated token **exactly once** in the row that appears in the Teams table — copy it into your secret store immediately. If you miss it, revoke the account and mint a new one; there's no way to re-view the token later.
+
+This is the same value ahd-fe stores in `VITE_PAGEPILOT_SERVICE_AUTH_TOKEN`, so if you're migrating from an ahd-fe integration you already have one.
+
+#### Storing credentials safely
+
+Anyone with the token can read + write every page under your tenant, so treat it like a database password.
+
+**Never commit it to the repo.** Read it from an env var at build time (Vite / Next.js) or fetch it from your own backend at runtime (recommended for browser apps that don't want a long-lived admin token shipped to the client).
+
+**Vite** — put the token in `.env.local` (already gitignored by the Vite starter):
+
+```bash
+# .env.local
+VITE_PAGEPILOT_BASE_URL=https://pagepilot.fabbuilder.com/api
+VITE_PAGEPILOT_TENANT_ID=6655bc2b30a6760d8f897581
+VITE_PAGEPILOT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+```tsx
+<PagePilotEditor
+  apiConfig={{
+    baseUrl: import.meta.env.VITE_PAGEPILOT_BASE_URL,
+    tenantId: import.meta.env.VITE_PAGEPILOT_TENANT_ID,
+    authToken: import.meta.env.VITE_PAGEPILOT_TOKEN,
+  }}
+/>
+```
+
+**Next.js** — use a **server component + prop drilling** (or a server action) so the token never enters the client bundle:
+
+```tsx
+// app/editor/[id]/page.tsx  — server component
+import { PagePilotEditorClient } from "./PagePilotEditorClient";
+
+export default async function EditorPage({ params }: { params: { id: string } }) {
+  const token = process.env.PAGEPILOT_TOKEN!; // server-only, no NEXT_PUBLIC_
+  return (
+    <PagePilotEditorClient
+      pageId={params.id}
+      baseUrl={process.env.PAGEPILOT_BASE_URL!}
+      tenantId={process.env.PAGEPILOT_TENANT_ID!}
+      authToken={token}
+    />
+  );
+}
+```
+
+```tsx
+// app/editor/[id]/PagePilotEditorClient.tsx  — "use client"
+"use client";
+import { PagePilotEditor } from "pagepilot-visual-editor";
+export function PagePilotEditorClient(props: { pageId: string; baseUrl: string; tenantId: string; authToken: string }) {
+  return (
+    <PagePilotEditor
+      record={{ id: props.pageId, type: "page" }}
+      apiConfig={{ baseUrl: props.baseUrl, tenantId: props.tenantId, authToken: props.authToken }}
+    />
+  );
+}
+```
+
+**Backend proxy (safest for multi-user apps).** Instead of shipping a service-account token to the browser, put your own backend in front of pagepilot: the browser authenticates to *your* backend with the user's session cookie, and your backend adds the pagepilot bearer server-side. Point `apiConfig.baseUrl` at your proxy (`https://myapp.com/pagepilot-proxy`), keep `authToken` empty (or a proxy-side session id — the editor sends whatever you give it verbatim), and enforce per-user auth on the proxy. This is how ahd-fe handles pagepilot in production.
+
+#### Rotating a token
+
+The editor doesn't refresh tokens itself — when yours expires, every save + publish call returns **401 Unauthorized** and lands in `onApiError`. The rotation flow is manual:
+
+1. Mint a new service account (or edit the existing one's expiration) in pagepilot Settings → Teams.
+2. Update the token in your env var / secret store.
+3. Redeploy (or trigger a config refresh — the editor re-reads `apiConfig` on prop change, so hot-swapping in-place works if you can update the prop).
+4. **Revoke the old service account** in the Teams table so a leaked copy stops working.
+
+Handle expiration gracefully in `onApiError`:
+
+```tsx
+<PagePilotEditor
+  apiConfig={apiConfig}
+  onApiError={(err, action) => {
+    if (err.message.includes("401") || err.message.includes("Unauthorized")) {
+      // Token expired or was revoked. Redirect to your re-auth flow.
+      window.location.href = "/reauth-pagepilot?returnTo=" + encodeURIComponent(window.location.pathname);
+      return;
+    }
+    toast.error(`${action} failed: ${err.message}`);
+  }}
+/>
+```
+
+#### Troubleshooting credentials
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `401 Unauthorized` on every save | Token expired, revoked, or copied incompletely. | Mint a fresh token; make sure you copied the whole `eyJ…` string with no trailing whitespace. |
+| `403 Forbidden` on Publish only | Service account role is `Editor` (or lower). | Recreate as `Admin`, or move publish to a separate token / server route. |
+| `404 Not Found` on save, but the page exists in pagepilot | `record.id` doesn't match a page in this tenant, OR `tenantId` points at the wrong workspace. | Double-check the Active workspace on the Workspaces page. `record.id` must be a MongoDB ObjectId that already exists — the editor doesn't create pages, it only updates them. |
+| CORS error in the browser console (`Access-Control-Allow-Origin`) | Origin isn't in pagepilot's allowed origins for this tenant. | Add your dev / prod origin to the tenant's allowed origins in pagepilot Configurations, OR proxy the request through your own backend. |
+| Save appears silent — no error, no persisted change | `apiConfig` is set but `record.id === "doc-1"` (the demo seed). | Pass a real backend id via `record.id` before the API path fires. Demo ids are intentionally skipped. |
+| `onApiError` never fires but Save is stuck "dirty" | `onApiError` isn't set and errors are going to `console.error` only. | Wire `onApiError` — see the snippet in [Rotating a token](#rotating-a-token). |
+
+#### Verifying your setup
+
+Before wiring the credentials into the editor, sanity-check them with a plain `curl` (or fetch) from a terminal:
+
+```bash
+curl -i \
+  -H "Authorization: Bearer $VITE_PAGEPILOT_TOKEN" \
+  "https://pagepilot.fabbuilder.com/api/tenant/$VITE_PAGEPILOT_TENANT_ID/page?limit=1&offset=0"
+```
+
+Expected: **HTTP/1.1 200 OK** and a JSON body with a `rows` array. If you see:
+
+- **401** — token is wrong or expired. Re-mint.
+- **403** — token is valid but role too low for reads. Mint an Admin token.
+- **404** — the `tenantId` doesn't exist. Re-copy from the Workspaces page.
+- **200 with `rows: []`** — credentials are fine; the tenant just has no pages yet. Create one in pagepilot, then use its id in `record.id`.
+
+Once the curl returns 200, drop the same three values into `apiConfig` and the editor's Save + Publish will hit the same endpoint.
+
 ### Setup
 
 ```tsx
@@ -357,8 +549,8 @@ import { PagePilotEditor } from "pagepilot-visual-editor";
   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
+    tenantId: "6655bc2b30a6760d8f897581",             // from step 1 above
+    authToken: "eyJhbGciOi…",                         // from step 2 above
   }}
   onApiError={(err, action) => toast.error(`${action}: ${err.message}`)}
   onUpgrade={() => openBillingModal()}
@@ -371,7 +563,7 @@ import { PagePilotEditor } from "pagepilot-visual-editor";
 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`).
+- The `authToken` must be a valid service-account bearer for the given `tenantId` — see [Getting your credentials](#getting-your-credentials) above.
 
 ### PagepilotApiConfig shape
 
@@ -437,6 +629,7 @@ When `apiConfig` is set, clicking **Publish** opens a full dialog instead of fir
 
 - **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`.
+- **Scripts & Styles** tab: paste a stylesheet snippet that's inlined into the published HTML, and flip per-page injection toggles for the built-in tabs scroll-sync and carousel scripts. Both toggles default on inside `renderToStaticMarkup`; setting them here lets a page opt out.
 - **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.
@@ -462,7 +655,7 @@ The Variables tab surfaces template tokens for filling at edit time. Visibility
 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.
+3. **The paywall CTA** ("Upgrade to unlock") fires `onUpgrade` if the host provided it; otherwise it opens the built-in `<UpgradeDialog>`, which links to the pagepilot billing URL in a new tab.
 
 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.
 
@@ -523,11 +716,14 @@ All methods send `Content-Type: application/json` + the bearer token automatical
 | **← Back** | Calls `onBack`. The host typically navigates away. |
 | **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. |
+| **Zoom controls** (− / % / +) | Zoom out, current zoom level (click to reset to 100%), zoom in. Range is 25%–100%; buttons disable at the endpoints. Users can also hold **Ctrl / Cmd** and scroll on the canvas to zoom cursor-anchored. Hidden together with Undo/Redo via `topbar={{ undo: false }}` (they share the toggle since they sit in the same group). |
 | **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. |
 | **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`. |
+| **Auto Save** | **Opt-in** — hidden unless `topbar={{ autoSave: true }}`. Bordered label + toggle switch rendered immediately left of Save Changes. While on, the editor re-runs the same handler `Save Changes` uses on a fixed interval (`autoSaveIntervalMs`, default 60s), gated by the same dirty flag — a clean editor never fires. The switch is uncontrolled by default and its checked state is persisted to `localStorage` under `pagepilot.editor.autoSave.v1`; pass `autoSaveEnabled` + `onAutoSaveChange` to control it from the host. Every flip fires `onAutoSaveChange` so hosts can mirror the flag to their own settings. |
+| **Screen size** (Desktop / Tablet / Mobile) | Three-way icon strip that constrains the canvas preview width and keeps the sidebar's per-device tabs in lock-step — switching here also switches which per-device slice the Inspect panel is editing. Hidden via `topbar={{ screenSize: false }}`. |
 | **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`. |
+| **3-dot menu** ⋮ | Off by default — enable via `topbar.moreMenu`. Contains **+ Add Section** and **Show / Hide Minimap** (the minimap is a click-to-jump / drag-to-scroll canvas overview that docks to the bottom-right corner). |
 | **Fullscreen** ⤢ | Toggles the editor's container via the browser Fullscreen API. Icon swaps to "exit fullscreen" while active; pressing `Esc` exits. |
 | **Preview** ▶ | Opens the in-page Preview dialog with desktop/tablet/mobile size toggles. The iframe renders the **same HTML** that's sent to `onSaveChanges` / `onPublish`. If `onTogglePreview` is supplied, that callback fires instead. |
 | **Publish** | Calls `onPublish`. |
@@ -539,10 +735,12 @@ Selecting any block on the canvas surfaces a floating action popover just above
 
 | Action | Behavior |
 |---|---|
+| **⋮⋮ Drag handle** | Native HTML5 drag source. Grab the leftmost dots to drag this block onto another block's drop target and reorder it on the canvas — no need to open the Layers panel. |
 | **↑ 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. |
+| **✎ Edit Variables** | Only appears on blocks that participate in template forms (repeatable containers + blocks bound to `formFields`). Opens the Variables panel focused on this block's fields. |
 | **⋯ More menu** | Opens the secondary popover below. |
 
 The **⋯ More** popover contains:
@@ -594,7 +792,7 @@ The Layout panel always shows the **Blocks** picker — a category-grouped tile
 
 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).
+- **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). A **Templates / Blocks** toggle at the top of the tab flips the fetch between `type=page` and `type=block`, matching ahd-fe. A refresh icon re-fetches the current list.
 - **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.
@@ -695,14 +893,14 @@ 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 33 block types, grouped into six categories:
+Out of the box the Add-Block menu exposes 34 block types, grouped into six categories:
 
 | 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) | |
+| List | Video | Flex Columns | Accordion | Demo Picker¹ | Accessibility |
+| Table | Avatar | Grid | Tabs | Header¹ (MenuPicker) | |
 | | | Spacer | Stepper | Forms¹ | |
 | | | Divider | | App Banner¹ | |
 | | | Html | | FAQs¹ | |

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

@@ -36,21 +36,21 @@ export declare const ButtonPropsSchema: z.ZodObject<{
         }>>>;
         fontWeight: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             bold: "bold";
+            normal: "normal";
             400: "400";
             500: "500";
             600: "600";
             700: "700";
-            normal: "normal";
         }>>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         buttonTextAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         padding: z.ZodNullable<z.ZodOptional<z.ZodObject<{
             top: z.ZodNumber;
@@ -58,6 +58,12 @@ export declare const ButtonPropsSchema: z.ZodObject<{
             right: z.ZodNumber;
             left: z.ZodNumber;
         }, z.core.$strip>>>;
+        margin: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+            top: z.ZodNumber;
+            bottom: z.ZodNumber;
+            right: z.ZodNumber;
+            left: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     props: z.ZodNullable<z.ZodOptional<z.ZodObject<{
         buttonBackground: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodString, z.ZodLiteral<"transparent">]>>>;
@@ -102,21 +108,21 @@ export declare const ButtonPropsSchema: z.ZodObject<{
         widthMobile: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         size: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             small: "small";
-            "x-small": "x-small";
             large: "large";
             medium: "medium";
+            "x-small": "x-small";
         }>>>;
         sizeTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             small: "small";
-            "x-small": "x-small";
             large: "large";
             medium: "medium";
+            "x-small": "x-small";
         }>>>;
         sizeMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             small: "small";
-            "x-small": "x-small";
             large: "large";
             medium: "medium";
+            "x-small": "x-small";
         }>>>;
         text: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         url: z.ZodNullable<z.ZodOptional<z.ZodString>>;
@@ -134,8 +140,8 @@ export declare const ButtonPropsSchema: z.ZodObject<{
         iconEnabled: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         iconName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         iconAlignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
             left: "left";
+            right: "right";
         }>>>;
         ariaLabel: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         goToStep: z.ZodNullable<z.ZodOptional<z.ZodString>>;

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

@@ -26,21 +26,21 @@ export declare const ButtonGroupPropsSchema: z.ZodObject<{
         gap: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         alignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             center: "center";
-            "space-between": "space-between";
-            start: "start";
             end: "end";
+            start: "start";
+            "space-between": "space-between";
         }>>>;
         alignmentTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             center: "center";
-            "space-between": "space-between";
-            start: "start";
             end: "end";
+            start: "start";
+            "space-between": "space-between";
         }>>>;
         alignmentMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             center: "center";
-            "space-between": "space-between";
-            start: "start";
             end: "end";
+            start: "start";
+            "space-between": "space-between";
         }>>>;
         wrap: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         ariaLabel: z.ZodNullable<z.ZodOptional<z.ZodString>>;

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

@@ -52,18 +52,18 @@ export declare const ColumnsContainerPropsSchema: z.ZodObject<{
             vertical: "vertical";
         }>>>;
         contentAlignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            top: "top";
             bottom: "bottom";
+            top: "top";
             middle: "middle";
         }>>>;
         contentAlignmentTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            top: "top";
             bottom: "bottom";
+            top: "top";
             middle: "middle";
         }>>>;
         contentAlignmentMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            top: "top";
             bottom: "bottom";
+            top: "top";
             middle: "middle";
         }>>>;
     }, z.core.$strip>>>;

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

@@ -64,37 +64,37 @@ export declare const ContainerPropsSchema: z.ZodObject<{
         heightMobile: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         overflow: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         alignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         alignmentTablet: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         alignmentMobile: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         tag: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            div: "div";
-            section: "section";
             article: "article";
-            nav: "nav";
             aside: "aside";
-            header: "header";
+            div: "div";
             footer: "footer";
+            header: "header";
             main: "main";
+            nav: "nav";
+            section: "section";
         }>>>;
         ariaLabel: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         elementId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         showLink: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         linkHref: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         linkTarget: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            _self: "_self";
             _blank: "_blank";
+            _self: "_self";
         }>>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;

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

@@ -24,8 +24,8 @@ export declare const GridPropsSchema: z.ZodObject<{
         columnsGap: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         rowsGap: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         contentAlignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            top: "top";
             bottom: "bottom";
+            top: "top";
             middle: "middle";
         }>>>;
     }, z.core.$strip>>>;

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

@@ -56,11 +56,11 @@ export declare const HeadingPropsSchema: z.ZodObject<{
         fontSize: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         fontWeight: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             bold: "bold";
+            normal: "normal";
             400: "400";
             500: "500";
             600: "600";
             700: "700";
-            normal: "normal";
         }>>>;
         fontStyle: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             normal: "normal";
@@ -68,14 +68,14 @@ export declare const HeadingPropsSchema: z.ZodObject<{
         }>>>;
         textDecoration: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
             none: "none";
-            underline: "underline";
             "line-through": "line-through";
+            underline: "underline";
             "underline line-through": "underline line-through";
         }>>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         padding: z.ZodNullable<z.ZodOptional<z.ZodObject<{
             top: z.ZodNumber;
@@ -83,6 +83,12 @@ export declare const HeadingPropsSchema: z.ZodObject<{
             right: z.ZodNumber;
             left: z.ZodNumber;
         }, z.core.$strip>>>;
+        margin: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+            top: z.ZodNumber;
+            bottom: z.ZodNumber;
+            right: z.ZodNumber;
+            left: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type HeadingProps = z.infer<typeof HeadingPropsSchema>;
@@ -96,4 +102,4 @@ export declare const HeadingPropsDefaults: {
     readonly openInNewTab: false;
 };
 export declare function Heading({ props, style }: HeadingProps): import("react/jsx-runtime").JSX.Element;
-export declare function getFontSize(level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'): 16 | 32 | 20 | 24 | 18 | 14;
+export declare function getFontSize(level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'): 14 | 16 | 18 | 20 | 24 | 32;

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

@@ -36,9 +36,9 @@ export declare const HtmlPropsSchema: z.ZodObject<{
         }>>>;
         fontSize: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
         padding: z.ZodNullable<z.ZodOptional<z.ZodObject<{
             top: z.ZodNumber;

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

@@ -12,9 +12,9 @@ export declare const IframePropsSchema: z.ZodObject<{
             left: z.ZodNumber;
         }, z.core.$strip>>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
     }, z.core.$strip>>>;
     props: z.ZodNullable<z.ZodOptional<z.ZodObject<{

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

@@ -9,9 +9,9 @@ export declare const ImagePropsSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         backgroundColor: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodString, z.ZodLiteral<"transparent">]>>>>;
         textAlign: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
             center: "center";
+            left: "left";
+            right: "right";
         }>>>;
     }, z.core.$strip>>>;
     props: z.ZodNullable<z.ZodOptional<z.ZodObject<{
@@ -37,8 +37,8 @@ export declare const ImagePropsSchema: z.ZodObject<{
         decorative: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
         linkHref: z.ZodNullable<z.ZodOptional<z.ZodString>>;
         contentAlignment: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
-            top: "top";
             bottom: "bottom";
+            top: "top";
             middle: "middle";
         }>>>;
         borderRadius: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{