pagepilot-visual-editor 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-07-06
+
+Initial public release.
+
+### Added
+- `<PagePilotEditor>` component — Style / Layout / Inspect / Layers panels
+  packaged for standalone use in any React app.
+- Built-in light + dark themes (`pagePilotEditorLightTheme`,
+  `pagePilotEditorDarkTheme`) plus a topbar sun/moon toggle that persists
+  the user's choice to `localStorage`.
+- `mode` and full `theme` props for host-controlled theming.
+- `translations` prop + `setPagePilotEditorTranslations()` for runtime i18n.
+- `topbar` prop to hide any control (Back, Save, Publish, Undo/Redo,
+  Preview, Fullscreen, Theme, More).
+- `blocks` prop to hide individual Add-Block tiles.
+- `panels` prop to hide any of the four sidebar tabs.
+- Multi-section pages via `record.sections[]` with an Add Section dialog,
+  a sections dropdown in the topbar (shown when > 1 section), and section
+  edit/delete flows.
+- Save Changes button with dirty tracking — disabled until the user makes
+  a real edit, re-enables on every subsequent change, and greys out again
+  after a successful `onSaveChanges`.
+- Undo / Redo wired to the editor's own history stack with a settle-window
+  guard so mount-time echoes don't preload undo entries.
+- Publish flow with three integration points: `onPublish` for a simple
+  callback, `onPublishMenu(anchor, payload)` to render the host's own
+  dropdown under the split-button arrow, and `renderPublish` to fully
+  replace the split-button with a custom control.
+- Add-Block picker with search + empty state.
+- Palette → canvas drag-and-drop: drag any block tile onto the canvas to
+  drop it before / after / inside the hovered block, with a live drop
+  indicator (line for before/after, tint for inside on single-list
+  containers).
+- Copy / Paste Style painter in the Inspect panel with same-type inline
+  text markup transfer, cross-type block-level style transfer, and
+  in-progress inline-edit safety (flushes the live DOM edit into the store
+  before capturing / applying so pending typing isn't lost).
+- Copy / Paste Layer at row-level and page-level, with clipboard-vs-in-memory
+  fallback resolution, whole-page validation (`isFullPageDocument` guard)
+  and automatic sanitization of clipboard payloads that contain block
+  types the standalone editor doesn't ship (e.g. MenuPicker, DemoPicker).
+- Hide-block support in the tune menu — hidden blocks are collapsed on
+  the canvas (`display: none`), the preview iframe, the save HTML, and
+  the publish HTML. Unhide from the Layers panel.
+- Container block: `alignment` (left / center / right) for non-fill widths
+  and an optional `showLink` / `linkHref` / `linkTarget` mode that renders
+  the container as a clickable `<a>` wrapper.
+- Grid block: removed the 1–5 column/row cap and added per-device
+  overrides (`columnsCountTablet`, `columnsCountMobile`).
+- Toast layer (Snackbar-style) for editor feedback — no antd dependency.
+- Re-exports: `Reader`, `ReaderBlock`, `renderToStaticMarkup`,
+  `ReaderBlockSchema`, `ReaderDocumentSchema`, and the full
+  `EditorContext` namespace for advanced integration.
+
+[Unreleased]: https://github.com/FAB-Builder/pagepilot-visual-editor/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/FAB-Builder/pagepilot-visual-editor/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PagePilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,553 @@
+# @pagepilot/visual-editor
+
+A standalone, prop-driven **React page-type visual editor**. Drop
+`<PagePilotEditor />` into your host application, pass the host record through
+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.
+
+
+---
+
+## Install
+
+```bash
+npm install @pagepilot/visual-editor
+# or
+pnpm add @pagepilot/visual-editor
+# or
+yarn add @pagepilot/visual-editor
+```
+
+Peer dependencies (your host should provide these):
+
+| Peer | Range | Notes |
+|---|---|---|
+| `react` | `>=18` | React 18 and 19 both supported |
+| `react-dom` | `>=18` | 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 |
+
+**Also required at runtime** (not currently listed as a peer, but the built
+bundle keeps them external — install these alongside the peers above):
+
+```bash
+npm install styled-components zustand
+```
+
+If you want to render exported types like `TReaderBlockProps` or use the
+`ReaderBlockSchema`, add `zod` too:
+
+```bash
+npm install zod
+```
+
+---
+
+## Quick start
+
+```tsx
+import { PagePilotEditor } from "@pagepilot/visual-editor";
+
+export default function PageEditorScreen() {
+  const [record, setRecord] = useState(initialRecord);
+
+  // The container MUST have an explicit height (100vh, a fixed pixel value,
+  // or a flex parent that gives it space). The editor fills its parent 100%;
+  // if the parent has 0 height, so does the editor. `width: 100%` is
+  // inherited from the ScopedCssBaseline root inside the component.
+  return (
+    <div style={{ width: "100%", height: "100vh" }}>
+      <PagePilotEditor
+        record={record}
+        recordTitle={record.title}
+        recordStatus={record.status}
+        onUpdateRecord={setRecord}
+        onSaveChanges={async ({ record, html }) => {
+          await api.savePage(record.id, { record, html });
+        }}
+        onPublish={async ({ record, html }) => {
+          await api.publishPage(record.id, { record, html });
+        }}
+        onBack={() => navigate(-1)}
+      />
+    </div>
+  );
+}
+```
+
+The editor renders its own MUI `ThemeProvider` + `ScopedCssBaseline`, so it
+works inside hosts that already use MUI — you don't need to import our CSS
+separately. If your host sets a non-default `html { font-size }`, our
+`ScopedCssBaseline` re-anchors REM sizing at 14 px inside the editor so the
+built-in layout doesn't scale unexpectedly.
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ← Back  My Page  ● Draft  [Section ▾]   ↶ ↷  Save  ⋮  ⤢  ▶  Publish ▾   │  Topbar
+├──────┬───────────────────┬─────────────────────────────────────────────┤
+│Style │ Appearance        │                                             │
+│Layout│  Color  ▢ ...     │     (canvas — block-based editor)           │
+│Inspct│  Font   ▾         │                                             │
+│Layers│  Radius PX        │                                             │
+│      │ Layout            │                                             │
+│      │  Width  100 %     │                                             │
+└──────┴───────────────────┴─────────────────────────────────────────────┘
+```
+
+- **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.
+- **Canvas** — the block-based page editor. Click the empty-state "Add first section" or the ⋮ → Add Section.
+- **3-dot menu** — currently exposes a single item, **Add Section**. Hidden by default; set `topbar.moreMenu` to `true`.
+
+---
+
+## `<PagePilotEditor>` props — full reference
+
+### 1. Host data
+
+| Prop | Type | Default | Behavior |
+|---|---|---|---|
+| `record` | `PageRecord` | `undefined` | The full page record. Mutations are echoed back through `onUpdateRecord`. |
+| `contentMetadata` | `PageRecord["contentMetadata"]` | `undefined` | Top-level override for `record.contentMetadata`. When supplied, wins over `record.contentMetadata`. |
+| `sections` | `PageRecord["sections"]` | `undefined` | Top-level override for `record.sections`. Section array for multi-section pages. |
+| `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. |
+
+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`.
+
+#### `PageRecord` shape
+
+```ts
+interface PageRecord {
+  id?: string;
+  type?: string;                       // keep "page" for the page editor
+  title?: string;                      // displayed when `recordTitle` is not set
+  name?: string;                       // fallback for title
+  status?: string;                     // displayed as status pill ("draft" | "live" | ...)
+  contentMetadata?: {
+    document?: any;                    // the editor's source-of-truth document tree
+    html?: string;                     // set by the editor on save
+    [key: string]: any;
+  };
+  behaviour?: Record<string, any>;
+  steps?: Array<{                      // for tour/tooltip flows
+    contentMetadata?: { document?: any; [key: string]: any };
+    behaviour?: Record<string, any>;
+    [key: string]: any;
+  }>;
+  sections?: PageSection[];            // for multi-section pages
+  [key: string]: any;                  // free-form passthrough
+}
+
+interface PageSection {
+  _id?: string;
+  title?: string;
+  identifier?: string;
+  sectionType?: "internal" | "external";
+  content?: string;                    // per-section rendered HTML (set by editor on save)
+  contentMetadata?: {
+    document?: any;                    // per-section editor document
+    [key: string]: any;
+  };
+  [key: string]: any;
+}
+```
+
+---
+
+### 2. UI configuration
+
+| Prop | Type | Default | Behavior |
+|---|---|---|---|
+| `panels` | `EditorPanelToggles` | all 4 visible | Toggle the four left-rail panels independently. |
+| `title` | `string` | `"Back"` | Label rendered on the back button. |
+| `recordTitle` | `string` | `record.title ?? record.name` | Text shown after the back button. Hidden when empty. |
+| `recordStatus` | `string` | `record.status` | Pill shown after the title. Built-in color coding for `draft` (orange), `live` / `published` (green), `scheduled` (indigo). Any other string gets a neutral gray pill. |
+| `mode` | `"light"` \| `"dark"` | `"dark"` | Selects the built-in theme. Ignored when `theme` is set. |
+| `theme` | `Theme` (MUI) | `undefined` | Full MUI theme override. Wins over `mode`. |
+| `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. |
+| `headerExtra` | `ReactNode` | `undefined` | Rendered immediately below the topbar — use for custom banners/announcement bars. |
+| `children` | `ReactNode` | `undefined` | Rendered after the editor body. |
+
+#### `EditorPanelToggles`
+
+```ts
+interface EditorPanelToggles {
+  style?: boolean;     // default true
+  layout?: boolean;    // default true
+  inspect?: boolean;   // default true
+  layers?: boolean;    // default true
+}
+```
+
+#### `TopbarToggles`
+
+```ts
+interface TopbarToggles {
+  back?: boolean;              // default true
+  title?: boolean;             // default true — record title
+  status?: boolean;            // default true — status pill
+  sectionsDropdown?: boolean;  // default true — still requires sections.length > 1
+  undo?: boolean;              // default true
+  redo?: boolean;              // default true
+  save?: boolean;              // default true
+  themeToggle?: boolean;       // default true — sun/moon button flipping light/dark
+  fullscreen?: boolean;        // default true
+  preview?: boolean;           // default true
+  moreMenu?: boolean;          // default FALSE
+  publish?: boolean;           // default FALSE
+}
+```
+
+**Defaults note:** `moreMenu` and `publish` are **off by default** — they only appear when explicitly enabled. Everything else is on by default.
+
+#### `BlockToggles`
+
+Per-tile visibility for the Add-Block menu. Each key defaults to `true`.
+
+```ts
+type BlockKey =
+  | "heading" | "text" | "button" | "image" | "logo" | "video"
+  | "avatar" | "divider" | "spacer" | "html"
+  | "columns" | "flexColumns" | "grid"
+  | "buttonGroup" | "container"
+  | "stepper" | "accordion" | "pricingAccordion"
+  | "tabs" | "carousel" | "rating" | "marquee"
+  | "iframe" | "skipToMain" | "accessibilityTools";
+
+type BlockToggles = Partial<Record<BlockKey, boolean>>;
+```
+
+```tsx
+<PagePilotEditor
+  blocks={{
+    iframe: false,         // hide the iFrame tile
+    accessibilityTools: false,
+    marquee: false,
+  }}
+/>
+```
+
+---
+
+### 3. Callbacks
+
+| Prop | Signature | When it fires |
+|---|---|---|
+| `onUpdateRecord` | `(record: PageRecord) => void` | Whenever the editor mutates the document, adds/removes/reorders sections, etc. The host owns the record state and should call `setState`/equivalent here. |
+| `onChange` | `(document: any) => void` | Lower-level: fires on every document tree mutation. Use when you only need the canvas document, not the full record. |
+| `onSaveChanges` | `(payload: SaveChangesPayload) => Promise<boolean \| void> \| boolean \| void` | Fires when **Save Changes** is clicked. Receives the full payload (record + document + rendered HTML). Return `true` (or void) for success, `false` to indicate the save failed. |
+| `onPublish` | `(payload: SaveChangesPayload) => Promise<void> \| void` | Fires when the **Publish** button is clicked. Same payload as Save. |
+| `onPublishMenu` | `(anchorEl: HTMLElement, payload: SaveChangesPayload) => void` | Fires when the small ▾ arrow next to Publish is clicked. The host can open any custom popover/menu/dialog anchored to `anchorEl`. **Omit to disable the arrow.** |
+| `renderPublish` | `({ payload, onPublish }) => ReactNode` | **Fully replaces** the Publish split-button group with the host's component. When provided, `onPublish` / `onPublishMenu` are ignored — host owns the slot. |
+| `onBack` | `() => void` | Fires when the ← Back button is clicked. |
+| `onTogglePreview` | `(html: string, doc: any) => void` | Optional preview hook. **If provided**, the host owns the preview UI (typically opening its own dialog with `html`). **If omitted**, the editor opens its built-in in-page preview dialog with desktop/tablet/mobile size toggles. |
+| `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. |
+
+#### `SaveChangesPayload`
+
+Every save/publish callback receives this shape:
+
+```ts
+interface SaveChangesPayload {
+  record: PageRecord;       // updated record with sections + html flushed in
+  document?: any;           // present in single-doc mode; OMITTED in multi-
+                            // section mode (there's no single page-level doc —
+                            // read record.sections[i].contentMetadata.document
+                            // per section instead)
+  html: string;             // rendered HTML — for multi-section pages, every
+                            // section's fragment is concatenated inside one
+                            // <html> shell with viewport meta + base font
+}
+```
+
+**Multi-section deduplication.** When `record.sections[]` is present, the
+payload's `record` is stripped down — the record-level `contentMetadata`
+and any empty `behaviour` / `steps` are removed because sections are the
+source of truth. Non-empty host-provided `behaviour` or `steps` are
+preserved so real host-owned config data isn't dropped.
+
+```jsonc
+// multi-section save payload — nothing duplicated
+{
+  "record": {
+    "id": "demo-1", "type": "page", "title": "My Page", "status": "draft",
+    "sections": [
+      {
+        "title": "Section 1",
+        "content": "<div ...>…</div>",
+        "contentMetadata": { "document": { /* per-section doc */ } }
+      }
+    ]
+    // no contentMetadata, no empty behaviour, no empty steps
+  },
+  "html": "<!doctype html>…combined…"
+  // no outer document
+}
+```
+
+Single-doc mode (no `sections`) is unchanged — the payload still carries
+`document` + `record.contentMetadata.document` + `record.contentMetadata.html`.
+
+---
+
+## Behavior reference
+
+### Topbar buttons
+
+| Button | Behavior |
+|---|---|
+| **← 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. |
+| **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`. |
+| **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. |
+| **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`. |
+| **Publish ▾** | Calls `onPublishMenu(anchorEl, payload)` so the host can open a custom dialog/popover anchored to the button. |
+
+### 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.
+   - 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.
+4. Once there are 2+ sections, the section dropdown appears in the topbar.
+
+To take over completely, pass `onAddSection={() => /* your custom flow */}`.
+
+### Inline images in a Text block
+
+Double-click a **Text** block to open the floating formatting toolbar and
+click the image icon. A dialog prompts for two fields:
+
+- **Image URL** — required. Any absolute URL your host serves images from.
+- **Alt text** — optional. Written to the `<img alt="…">` attribute for
+  accessibility.
+
+The image is inserted at the caret position and can then be resized
+(`100% / 50% / 25%`), floated left/right, or deleted via the popover that
+appears when you click it. The standalone editor deliberately doesn't ship
+a media-library backend — the URL field is the integration point.
+
+### 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.
+
+### Image block sidebar
+
+The Image block's Inspect panel exposes a **Media** text input for the
+image URL. There is no Upload Media button — the standalone editor
+doesn't ship a media backend. Consumers who want an upload flow can
+either upload through their own host storage before setting `record.…url`,
+or wrap `<PagePilotEditor>` and inject a custom uploader via `children`
+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.
+- **Custom UI**: pass `onTogglePreview={(html, doc) => myDialog.open(html)}` to skip the built-in dialog and render your own.
+
+### Save / Publish payload generation
+
+When the user clicks **Save Changes** or **Publish**, the editor does the following before invoking the callback:
+
+1. Reads the current canvas document from the internal store.
+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`.
+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`.
+
+This guarantees **Preview ≡ Save Changes ≡ Publish** — all three see the exact same rendered output.
+
+### Themes
+
+```tsx
+import {
+  PagePilotEditor,
+  pagePilotEditorDarkTheme,
+  pagePilotEditorLightTheme,
+} from "@pagepilot/visual-editor";
+
+// Built-in themes — these are full MUI Theme objects.
+<PagePilotEditor mode="dark" />
+<PagePilotEditor mode="light" />
+
+// Or pass your own:
+<PagePilotEditor theme={myCustomTheme} />
+```
+
+Both built-in themes carry the editor's custom palette keys (`performanceHeader`, `moduleIcon`, `moduleListComponentName`, `grayCloseIcon`, `codeBlock`, `brand.blue`) tuned per mode so icons and dividers stay legible. If you pass your own theme, you'll likely want to copy those keys.
+
+**Runtime toggle + persistence.** The topbar's sun/moon button lets the
+user flip between the built-in light/dark themes at any time; the choice
+is written to `localStorage["pagepilot.editor.mode.v1"]` and outranks
+subsequent `props.mode` changes so the preference survives page reloads
+and host re-renders. To hand control back to the host, clear that key.
+Hide the toggle entirely with `topbar={{ themeToggle: false }}`.
+
+**Isolation from host CSS.** The editor wraps its subtree in a MUI
+`ScopedCssBaseline` (not global `CssBaseline`), so it plays nicely with
+hosts that already run their own MUI theme. `ScopedCssBaseline` anchors
+REM sizing at 14 px inside the editor's subtree, so a host with
+`html { font-size: 12px }` (or any other non-default) doesn't shrink the
+editor's layout. The editor root is flex-pinned to fill its parent
+(width/height 100%, `minHeight: 480` floor) — give it a parent with a
+real height and it fills the rest.
+
+### Translations
+
+Two ways:
+
+**Per-mount via prop:**
+```tsx
+<PagePilotEditor
+  translations={{
+    "pagePilotEditor.tabs.style": "Stile",
+    "pagePilotEditor.tabs.layout": "Layout",
+    "pagePilotEditor.templatePanel.mainPanel.page.addFirstSection": "Aggiungi sezione",
+    // missing keys fall back to built-in English
+  }}
+/>
+```
+
+**Imperatively (from anywhere outside the component):**
+```ts
+import {
+  setPagePilotEditorTranslations,
+  resetPagePilotEditorTranslations,
+} from "@pagepilot/visual-editor";
+
+setPagePilotEditorTranslations(myDict);   // merges on top of defaults
+resetPagePilotEditorTranslations();       // back to English defaults
+```
+
+The full set of keys the editor reads is documented inline at `src/host-stubs/i18n.ts` in the package.
+
+---
+
+## Block types
+
+Out of the box the Add-Block menu exposes 25 block types:
+
+| 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 |
+
+Hide any of them via the `blocks` prop. Tile labels can be re-translated via `translations`.
+
+---
+
+## Imperative API (advanced)
+
+The original Pagepilot `EditorContext` Zustand store is re-exported under the `EditorContext` namespace so advanced consumers can drive document state imperatively from outside the component:
+
+```ts
+import { EditorContext } from "@pagepilot/visual-editor";
+
+EditorContext.setDocument({ root: ... });
+EditorContext.resetDocument(myDoc);
+EditorContext.useDocument();          // hook
+EditorContext.editorStateStore;       // raw Zustand store
+```
+
+The built-in Reader is also re-exported so you can render saved documents outside the editor:
+
+```ts
+import { Reader, renderToStaticMarkup } from "@pagepilot/visual-editor";
+
+const html = renderToStaticMarkup(myDoc, { rootBlockId: "root" });
+```
+
+---
+
+## Exports
+
+```ts
+// Component + imperative document setters
+export { PagePilotEditor, setDocument, resetDocument } from "@pagepilot/visual-editor";
+
+// Themes
+export { pagePilotEditorDarkTheme, pagePilotEditorLightTheme } from "@pagepilot/visual-editor";
+
+// Translation helpers
+export {
+  setPagePilotEditorTranslations,
+  resetPagePilotEditorTranslations,
+} from "@pagepilot/visual-editor";
+
+// Reader / renderer
+export {
+  Reader, ReaderBlock,
+  renderToStaticMarkup,
+  ReaderBlockSchema, ReaderDocumentSchema,
+} from "@pagepilot/visual-editor";
+
+// Imperative store access
+export * as EditorContext from "@pagepilot/visual-editor";
+
+// Types
+export type {
+  PagePilotEditorProps, PageRecord, SaveChangesPayload,
+  EditorPanelToggles, TopbarToggles,
+  BlockKey, BlockToggles,
+  TReaderBlock, TReaderDocument, TReaderBlockProps, TReaderProps,
+} from "@pagepilot/visual-editor";
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev       # demo at http://localhost:5175
+npm run build     # produces dist/index.js + index.cjs + index.d.ts
+npm run typecheck
+```
+
+
+The demo entry is at `example/src/main.tsx` — it shows every prop in action including theme switching, translations, custom Publish-menu popover, and a seeded multi-section record.
+
+---
+
+## License
+
+MIT
+

package/dist/PagePilotEditor.d.ts

@@ -0,0 +1,17 @@
+import { PagePilotEditorProps } from './editor/types';
+/**
+ * Standalone page-type visual editor.
+ *
+ * - **Undo / Redo**: wired directly to the editor's history store; buttons
+ *   disable when their stack is empty.
+ * - **Save Changes**: renders the current document (or every section, for
+ *   multi-section pages) to static HTML via
+ *   `@usewaypoint/email-builder.renderToStaticMarkup` and hands the host
+ *   `{ record, document, html }` through the `onSaveChanges` callback.
+ * - **Fullscreen**: requests the editor's container via the Fullscreen API.
+ * - **Preview**: renders the same HTML into an in-page iframe (or calls
+ *   `onTogglePreview` if the host provides one).
+ * - **Publish**: same payload as Save Changes, routed to `onPublish`.
+ */
+export declare function PagePilotEditor(props: PagePilotEditorProps): import("react").JSX.Element;
+export { setDocument, resetDocument, } from './editor-sample/documents/editor/EditorContext';

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

@@ -0,0 +1,18 @@
+export declare const ArrowLeft: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowDown: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowDownLeft: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowDownRight: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowLeft: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowRight: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowUp: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowUpLeft: (props: any) => import("react").JSX.Element;
+export declare const ArrowNarrowUpRight: (props: any) => import("react").JSX.Element;
+export declare const ArrowRight: (props: any) => import("react").JSX.Element;
+export declare const ChevronDown: (props: any) => import("react").JSX.Element;
+export declare const ChevronDownDouble: (props: any) => import("react").JSX.Element;
+export declare const ChevronLeft: (props: any) => import("react").JSX.Element;
+export declare const ChevronLeftDouble: (props: any) => import("react").JSX.Element;
+export declare const ChevronRight: (props: any) => import("react").JSX.Element;
+export declare const ChevronRightDouble: (props: any) => import("react").JSX.Element;
+export declare const ChevronUp: (props: any) => import("react").JSX.Element;
+export declare const ChevronUpDouble: (props: any) => import("react").JSX.Element;