@blox-cms/preview 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Blox CMS preview interactions 0.1.1
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared React controls and preview bridge protocol v4. This package contains no
+CMS persistence, credentials, site templates or database code. The npm package
+name is `@blox-cms/preview`; this release provides the preview integration,
+not a complete CMS SDK or content delivery client.
+
+## Integration
+
+- Managed previews use `SectionToolbar` and `SectionInsertionBoundary` directly.
+- Dedicated client previews mount `PreviewOverlay` as a **sibling** of the site's
+  content root. Keep the public renderer memoized; hover/geometry state belongs
+  only to the overlay. `src/next/LivePreviewClient.tsx` is the reference adapter.
+- Pass the page's own section IDs/types, current selection and a document key.
+  Each rendered section must expose `data-blockforge-block-id`. Descendants of
+  compositions/shared references resolve to their owning page section. Child
+  editing remains in the existing sidebar; page actions never mutate a shared
+  source or guess which nested container to alter.
+- Transport action intents, never content mutations. Check frame source, exact
+  origin, document ID, route path, action allowlist and section membership in the
+  host. The CMS owns persistence, selection and structural undo.
+- In Tailwind v4, explicitly include this package's sources in the consuming
+  stylesheet: `@source "../node_modules/@blox-cms/preview/src";` (adjust the
+  relative path to the stylesheet). The monorepo already scans `packages`.
+- Consumers need React 18/19 and a TS/TSX-capable bundler. No new database tables,
+  migrations, public-site scripts or server secrets are required.
+
+## Controlled distribution
+
+Install the published package in a client repository:
+
+```sh
+npm install --save-exact @blox-cms/preview@0.1.1
+```
+
+Import the controls from `@blox-cms/preview` or the protocol from
+`@blox-cms/preview/protocol`. Consumers need a TS/TSX-capable bundler.
+For local verification before publication, use `npm pack ./packages/preview`
+and install the resulting artifact.
+Do not copy and maintain separate control implementations. Release/pin a new
+package version for future client upgrades. Publishing and deployment are
+separate explicit release steps; changing the CMS does not update client builds.
+
+### Content renderer capabilities (0.1.1)
+
+The optional `contentCapabilities` list in the ready handshake describes the
+**website renderer**, independently of overlay protocol v4. Advertise
+`content-spacer-v1` only after both `SPACER` sections (`content.height`) and
+rich-text `spacer` nodes (`attrs.height`) are implemented in public and preview
+rendering, using the 4/8/12/16/20px presets. Updating this package alone does not
+add a content renderer. The CMS gates both insertion locations until the client
+advertises support; missing/legacy capabilities are treated as unsupported.
+
+Deploy the CMS host first. v2/v3 clients retain the old subject updates/insertion
+behaviour and visible sidebar controls; the CMS reports missing capabilities.
+Then deploy one client with the package, adapter and Tailwind source inclusion.
+Only show section-action controls after the host advertises `section-actions` in
+its render handshake. Verify the host reports both insertion and section actions
+before rolling out the same artifact to other clients.
+
+## Acceptance checks
+
+1. Hover shows a label/outline without changing sidebar selection or rendering
+   the site again. Click/tap/Enter selects the owning section.
+2. Insertion lines span the section, track resize/scroll/image loading, and never
+   represent an offscreen boundary as a viewport-edge insertion point.
+3. Up/down, duplicate, remove, add-before/after and empty-page insertion work.
+   Undo move/remove/duplicate preserves unrelated field edits. It is structural
+   undo (last 30 actions), not global text undo/redo or editor navigation history.
+4. Keyboard toolbar navigation skips disabled actions; Escape dismisses controls
+   and restores focus. Sidebar actions remain available at all screen sizes.
+5. Browse mode stops intercepting site interactions. The managed CMS switches to
+   its public renderer; dedicated clients keep their existing renderer. Remote
+   navigation links open in a new tab to keep the preview bridge connected.
+6. Reject stale-page, unknown-action and nested-child mutation messages.
+
+Local checks:
+
+```
+node --import tsx --test tests/preview-interactions.test.ts
+node --test tests/preview-overlay.browser.test.mjs
+npm run typecheck -- --incremental false
+```
+
+Browser checks use only an in-memory fixture and localhost, never production
+content. Field-level remote inspection and freeform canvas dragging are later
+capabilities; the sidebar remains the precise nested-editing/reordering surface.

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@blox-cms/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Blox CMS React preview controls and bridge protocol for independent client websites",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "files": ["src", "README.md"],
+  "exports": { ".": "./src/index.ts", "./protocol": "./src/protocol.ts" },
+  "peerDependencies": { "react": ">=18 <20" }
+}

package/src/PreviewOverlay.tsx

@@ -0,0 +1,226 @@
+"use client";
+
+import { useEffect, useRef, useState, type RefObject } from "react";
+import { SectionInsertionBoundary, SectionToolbar } from "./SectionControls";
+import { sectionLabel, type PreviewSection, type SectionAction } from "./protocol";
+
+type Box = { id: string; left: number; top: number; width: number; height: number };
+type Geometry = { selected: Box | null; hovered: Box | null; boundary: (Box & { before: boolean }) | null };
+const emptyGeometry: Geometry = { selected: null, hovered: null, boundary: null };
+
+export function findOwningSection(target: Element | null, root: HTMLElement, ids: Set<string>): HTMLElement | null {
+  let owner: HTMLElement | null = null;
+  for (let element = target; element && element !== root; element = element.parentElement) {
+    const id = element.getAttribute("data-blockforge-block-id");
+    if (id && ids.has(id)) owner = element as HTMLElement;
+  }
+  return owner;
+}
+
+/** Sibling overlay: pointer/geometry updates never render the site's content tree. */
+export function PreviewOverlay({ rootRef, sections, activeBlockId, documentKey, canAct, onSelect, onAction, onInsert }: {
+  rootRef: RefObject<HTMLDivElement | null>;
+  sections: PreviewSection[];
+  activeBlockId: string | null;
+  documentKey: string;
+  canAct: boolean;
+  onSelect: (id: string) => void;
+  onAction: (id: string, action: SectionAction) => void;
+  onInsert: (options: { afterBlockId?: string; atIndex?: number }) => void;
+}) {
+  const [browsing, setBrowsing] = useState(false);
+  const [geometry, setGeometry] = useState<Geometry>(emptyGeometry);
+  const [dismissed, setDismissed] = useState(false);
+  const hoveredRef = useRef<{ id: string; before: boolean } | null>(null);
+  const previousOrderRef = useRef<string | null>(null);
+  const callbacks = useRef({ onSelect, onAction, onInsert });
+  callbacks.current = { onSelect, onAction, onInsert };
+  const sectionKey = JSON.stringify(sections.map(({ id, type }) => [id, type]));
+
+  useEffect(() => { setDismissed(false); hoveredRef.current = null; }, [documentKey, activeBlockId]);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const previous = root.getAttribute("data-blockforge-editing");
+    root.setAttribute("data-blockforge-editing", String(!browsing));
+    return () => {
+      if (previous === null) root.removeAttribute("data-blockforge-editing");
+      else root.setAttribute("data-blockforge-editing", previous);
+    };
+  }, [rootRef, documentKey, browsing]);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) { setGeometry(emptyGeometry); return; }
+    const doc = root.ownerDocument;
+    const win = doc.defaultView!;
+    if (browsing) {
+      setGeometry(emptyGeometry);
+      const openLink = (event: MouseEvent) => {
+        const anchor = (event.target as Element).closest<HTMLAnchorElement>("a[href]");
+        if (!anchor || anchor.hasAttribute("download")) return;
+        const destination = new URL(anchor.href, win.location.href);
+        if (!["http:", "https:"].includes(destination.protocol)) return;
+        if (destination.hash && destination.origin === win.location.origin
+          && destination.pathname === win.location.pathname && destination.search === win.location.search) return;
+        // Keep the bridge alive while allowing the actual destination to open.
+        event.preventDefault();
+        event.stopPropagation();
+        win.open(destination.href, "_blank", "noopener,noreferrer");
+      };
+      root.addEventListener("click", openLink, true);
+      return () => root.removeEventListener("click", openLink, true);
+    }
+    const ids = new Set(sections.map((section) => section.id));
+    let frame = 0;
+    const elements = () => Array.from(root.querySelectorAll<HTMLElement>("[data-blockforge-block-id]"))
+      .filter((element) => ids.has(element.dataset.blockforgeBlockId!) && findOwningSection(element, root, ids) === element);
+    const nodes = elements();
+    const byId = new Map(nodes.map((node) => [node.dataset.blockforgeBlockId, node]));
+    if (previousOrderRef.current !== null && previousOrderRef.current !== sectionKey && activeBlockId) {
+      byId.get(activeBlockId)?.scrollIntoView({ block: "nearest", behavior: "instant" });
+    }
+    previousOrderRef.current = sectionKey;
+    const boxFor = (id: string | null): Box | null => {
+      const element = id ? byId.get(id) : null;
+      if (!element || !id) return null;
+      const rect = element.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0 || rect.bottom <= 0 || rect.top >= win.innerHeight) return null;
+      return { id, left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    };
+    const measure = () => {
+      frame = 0;
+      const selected = boxFor(activeBlockId);
+      const hovered = boxFor(hoveredRef.current?.id ?? null);
+      const boundaryBox = hovered ?? selected;
+      const before = hovered ? hoveredRef.current?.before ?? false : false;
+      const y = boundaryBox ? boundaryBox.top + (before ? 0 : boundaryBox.height) : -1;
+      // Never pin an offscreen insertion point to a false viewport boundary.
+      const boundary = boundaryBox && y >= 16 && y <= win.innerHeight - 16 ? { ...boundaryBox, before, top: y } : null;
+      const next = { selected, hovered, boundary };
+      setGeometry((previous) => JSON.stringify(previous) === JSON.stringify(next) ? previous : next);
+    };
+    const schedule = () => { if (!frame) frame = win.requestAnimationFrame(measure); };
+    const hover = (event: PointerEvent) => {
+      if (event.pointerType !== "mouse" && event.pointerType !== "pen") return;
+      const target = event.target as Element;
+      if (target.closest("[data-blockforge-preview-control]")) return;
+      const owner = findOwningSection(target, root, ids);
+      const rect = owner?.getBoundingClientRect();
+      const id = owner?.dataset.blockforgeBlockId;
+      if (id !== hoveredRef.current?.id) setDismissed(false);
+      hoveredRef.current = id && rect ? { id, before: event.clientY - rect.top < Math.min(40, rect.height / 2) } : null;
+      schedule();
+    };
+    const select = (event: MouseEvent) => {
+      const target = event.target as Element;
+      if (target.closest("[data-blockforge-preview-control]")) return;
+      const owner = findOwningSection(target, root, ids);
+      if (owner || target.closest("a,button,input,textarea,select,summary")) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      if (owner?.dataset.blockforgeBlockId) {
+        setDismissed(false);
+        callbacks.current.onSelect(owner.dataset.blockforgeBlockId);
+      }
+    };
+    const keydown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") { hoveredRef.current = null; setDismissed(true); return; }
+      if (event.key !== "Enter" && event.key !== " ") return;
+      const owner = findOwningSection(event.target as Element, root, ids);
+      if (owner !== event.target) return;
+      event.preventDefault();
+      setDismissed(false);
+      if (owner?.dataset.blockforgeBlockId) callbacks.current.onSelect(owner.dataset.blockforgeBlockId);
+    };
+    const focus = (event: FocusEvent) => {
+      const owner = findOwningSection(event.target as Element, root, ids);
+      if (!owner) return;
+      setDismissed(false);
+      hoveredRef.current = { id: owner.dataset.blockforgeBlockId!, before: false };
+      schedule();
+    };
+    const leave = (event: PointerEvent) => {
+      if ((event.relatedTarget as Element | null)?.closest?.("[data-blockforge-preview-control]")) return;
+      hoveredRef.current = null; schedule();
+    };
+    const previousAttributes = nodes.map((node) => [node, node.getAttribute("tabindex"), node.getAttribute("aria-label"), node.getAttribute("role"), node.classList.contains("cursor-pointer")] as const);
+    nodes.forEach((node) => {
+      node.tabIndex = 0;
+      node.setAttribute("role", "group");
+      node.setAttribute("aria-label", `Select ${sectionLabel(sections.find((section) => section.id === node.dataset.blockforgeBlockId)!)} section`);
+      node.classList.add("cursor-pointer");
+    });
+    const observer = new ResizeObserver(schedule);
+    observer.observe(root);
+    nodes.forEach((node) => observer.observe(node));
+    root.addEventListener("pointermove", hover);
+    root.addEventListener("pointerleave", leave);
+    root.addEventListener("click", select, true);
+    root.addEventListener("keydown", keydown);
+    root.addEventListener("focusin", focus);
+    root.addEventListener("load", schedule, true);
+    win.addEventListener("scroll", schedule, true);
+    win.addEventListener("resize", schedule);
+    schedule();
+    return () => {
+      observer.disconnect(); win.cancelAnimationFrame(frame);
+      root.removeEventListener("pointermove", hover); root.removeEventListener("pointerleave", leave);
+      root.removeEventListener("click", select, true); root.removeEventListener("keydown", keydown);
+      root.removeEventListener("focusin", focus); root.removeEventListener("load", schedule, true);
+      win.removeEventListener("scroll", schedule, true); win.removeEventListener("resize", schedule);
+      previousAttributes.forEach(([node, tabIndex, label, role, hadCursorClass]) => {
+        if (tabIndex === null) node.removeAttribute("tabindex"); else node.setAttribute("tabindex", tabIndex);
+        if (label === null) node.removeAttribute("aria-label"); else node.setAttribute("aria-label", label);
+        if (role === null) node.removeAttribute("role"); else node.setAttribute("role", role);
+        if (!hadCursorClass) node.classList.remove("cursor-pointer");
+      });
+    };
+  }, [rootRef, documentKey, sectionKey, activeBlockId, browsing]);
+
+  const selected = sections.find((section) => section.id === activeBlockId);
+  const hovered = sections.find((section) => section.id === geometry.hovered?.id);
+  const boundarySection = sections.find((section) => section.id === geometry.boundary?.id);
+  const selectedIndex = sections.findIndex((section) => section.id === activeBlockId);
+  const outline = (box: Box, active: boolean) => <div key={box.id} aria-hidden="true"
+    className={`pointer-events-none fixed z-[2147483645] ${active ? "border-2 border-violet-600" : "border border-violet-400"}`}
+    style={{ left: box.left, top: box.top, width: box.width, height: box.height }} />;
+  return <>
+    <div data-blockforge-preview-control className="fixed bottom-3 right-3 z-[2147483647] flex items-center gap-2 rounded-lg border border-slate-200 bg-white px-2 py-1 text-xs text-slate-700 shadow-sm">
+      <span className="hidden sm:inline">{browsing ? "Links open in a new tab" : "Select a section to edit or move it"}</span>
+      <button type="button" aria-pressed={browsing} onClick={() => { setBrowsing(!browsing); setDismissed(false); }}
+        className="min-h-8 rounded-md px-2 font-bold text-violet-700 hover:bg-violet-50 focus-visible:ring-2 focus-visible:ring-violet-500">{browsing ? "Return to editing" : "Browse preview"}</button>
+    </div>
+    {!browsing && !dismissed && <>
+      {geometry.selected && selected && geometry.selected.id === selected.id && outline(geometry.selected, true)}
+      {geometry.hovered && hovered && geometry.hovered.id !== activeBlockId && outline(geometry.hovered, false)}
+      {geometry.hovered && hovered && geometry.hovered.id !== activeBlockId && <span aria-hidden="true"
+        className="pointer-events-none fixed z-[2147483646] rounded bg-violet-600 px-2 py-1 text-xs font-bold text-white"
+        style={{ left: geometry.hovered.left + 4, top: Math.max(0, geometry.hovered.top) }}>{sectionLabel(hovered)}</span>}
+      {canAct && geometry.selected && selected && geometry.selected.id === selected.id && <div className="fixed z-[2147483646] max-w-[calc(100vw-16px)]"
+        style={{ left: Math.max(8, geometry.selected.left), top: Math.max(4, geometry.selected.top - 44), maxWidth: `calc(100vw - ${Math.max(8, geometry.selected.left) + 8}px)` }}>
+        <SectionToolbar key={selected.id} label={sectionLabel(selected)} isFirst={selectedIndex === 0} isLast={selectedIndex === sections.length - 1}
+          onDismiss={() => {
+            Array.from(rootRef.current?.querySelectorAll<HTMLElement>("[data-blockforge-block-id]") ?? []).find((node) => node.dataset.blockforgeBlockId === selected.id)?.focus({ preventScroll: true });
+            setDismissed(true);
+          }} onAction={(action) => callbacks.current.onAction(selected.id, action)} />
+      </div>}
+      {geometry.boundary && boundarySection && <div className="fixed z-[2147483647] -translate-y-1/2"
+        style={{ left: geometry.boundary.left, top: geometry.boundary.top, width: geometry.boundary.width }}>
+        <SectionInsertionBoundary label={`Add section ${geometry.boundary.before ? "before" : "after"} ${sectionLabel(boundarySection)}`}
+          onInsert={() => {
+            const boundary = geometry.boundary!;
+            if (boundary.before && canAct) callbacks.current.onAction(boundary.id, "insert-before");
+            else callbacks.current.onInsert(boundary.before
+              ? { atIndex: sections.findIndex((section) => section.id === boundary.id) } : { afterBlockId: boundary.id });
+          }} />
+      </div>}
+      {sections.length === 0 && <div className="fixed left-6 right-6 top-1/2 z-[2147483646] rounded-xl bg-white p-6 text-center shadow-lg">
+        <p className="mb-4 text-sm font-semibold text-slate-700">Add your first section</p>
+        <SectionInsertionBoundary label="Add first section" onInsert={() => callbacks.current.onInsert({ atIndex: 0 })} />
+      </div>}
+    </>}
+  </>;
+}

package/src/SectionControls.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { useRef, useState } from "react";
+import type { SectionAction } from "./protocol";
+
+const buttonClass = "inline-flex min-h-8 shrink-0 items-center justify-center rounded-md px-2 text-xs font-semibold text-slate-700 hover:bg-violet-50 hover:text-violet-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500 disabled:cursor-not-allowed disabled:opacity-35";
+
+export function SectionToolbar({ label, isFirst, isLast, onAction, onDismiss }: {
+  label: string;
+  isFirst: boolean;
+  isLast: boolean;
+  onAction: (action: SectionAction) => void;
+  onDismiss?: () => void;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const [tabIndex, setTabIndex] = useState(0);
+  const toolbarRef = useRef<HTMLDivElement>(null);
+  const actions: Array<{ action: SectionAction; label: string; text: string; disabled?: boolean }> = [
+    { action: "edit", label: "Edit section fields", text: "Edit" },
+  ];
+  const focusIndex = actions[tabIndex]?.disabled ? 0 : tabIndex;
+  return (
+    <div data-blockforge-preview-control data-cms-inspector-control className="max-w-full rounded-lg border border-violet-200 bg-white p-1 text-slate-900 shadow-lg shadow-slate-950/10" onClick={(event) => event.stopPropagation()}>
+      <div ref={toolbarRef} role="toolbar" aria-label={`${label} section actions`} className="flex max-w-full items-center gap-0.5 overflow-x-auto"
+        onKeyDown={(event) => {
+          if (event.key === "Escape") { setExpanded(false); onDismiss?.(); return; }
+          if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) return;
+          event.preventDefault();
+          const buttons = Array.from(event.currentTarget.querySelectorAll<HTMLButtonElement>("button:not(:disabled)"));
+          const current = buttons.indexOf(event.target as HTMLButtonElement);
+          const next = event.key === "Home" ? 0 : event.key === "End" ? buttons.length - 1
+            : (current + (event.key === "ArrowRight" ? 1 : -1) + buttons.length) % buttons.length;
+          buttons[next]?.focus();
+        }}>
+        <span className="hidden max-w-40 truncate px-2 text-xs font-bold text-violet-700 sm:inline">{label}</span>
+        {actions.map((item, index) => <button key={item.action} type="button" className={buttonClass} title={item.label} aria-label={item.label}
+          disabled={item.disabled} tabIndex={focusIndex === index ? 0 : -1} onFocus={() => setTabIndex(index)} onClick={() => onAction(item.action)}>{item.text}</button>)}
+        <button type="button" className={buttonClass} aria-label="More section actions" title="More section actions" aria-expanded={expanded}
+          tabIndex={focusIndex === actions.length ? 0 : -1} onFocus={() => setTabIndex(actions.length)} onClick={() => setExpanded(!expanded)}>•••</button>
+      </div>
+      {expanded && <div className="mt-1 flex flex-col items-stretch gap-0.5 border-t border-slate-200 pt-1" onKeyDown={(event) => {
+        if (event.key === "Escape") { event.stopPropagation(); setExpanded(false); toolbarRef.current?.querySelector<HTMLButtonElement>("[aria-expanded]")?.focus(); }
+      }}>
+        {([ ["move-up", "Move up", isFirst], ["move-down", "Move down", isLast], ["duplicate", "Duplicate section", false], ["insert-before", "Add before", false], ["insert-after", "Add after", false], ["remove", "Remove section", false] ] as const).map(([action, text, disabled]) =>
+          <button type="button" key={action} disabled={disabled} className={`${buttonClass} justify-start ${action === "remove" ? "text-rose-700" : ""}`} onClick={() => {
+            setExpanded(false);
+            toolbarRef.current?.querySelector<HTMLButtonElement>("[aria-expanded]")?.focus();
+            onAction(action);
+          }}>{text}</button>)}
+        {label.startsWith("Shared section") && <p className="w-full px-2 py-1 text-xs text-slate-500">Remove affects this instance, not the shared source.</p>}
+      </div>}
+    </div>
+  );
+}
+
+export function SectionInsertionBoundary({ label, onInsert }: { label: string; onInsert: () => void }) {
+  return <div data-blockforge-preview-control className="flex w-full items-center gap-2" onClick={(event) => event.stopPropagation()}>
+    <span aria-hidden="true" className="h-px min-w-0 flex-1 bg-violet-400" />
+    <button type="button" title={label} aria-label={label} onClick={onInsert}
+      className="inline-flex min-h-8 shrink-0 items-center gap-1.5 rounded-full border border-violet-400 bg-white px-3 text-xs font-bold text-violet-700 shadow-sm hover:bg-violet-50 focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-violet-200">
+      <span aria-hidden="true">+</span> Add section
+    </button>
+    <span aria-hidden="true" className="h-px min-w-0 flex-1 bg-violet-400" />
+  </div>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./protocol";
+export * from "./SectionControls";
+export * from "./PreviewOverlay";

package/src/protocol.ts

@@ -0,0 +1,85 @@
+export const previewMessageType = {
+  ready: "blockforge:preview:ready",
+  render: "blockforge:preview:render",
+  updateSubject: "blockforge:preview:update-subject",
+  setActiveBlock: "blockforge:preview:set-active-block",
+  selectBlock: "blockforge:preview:select-block",
+  requestSectionInsert: "blockforge:preview:request-section-insert",
+  sectionAction: "blockforge:preview:section-action",
+  scroll: "blockforge:preview:scroll",
+  scrollTo: "blockforge:preview:scroll-to",
+  scrollToElement: "blockforge:preview:scroll-to-element",
+} as const;
+
+export const previewProtocolVersion = 4;
+
+export const previewCapability = {
+  subjectUpdates: "subject-updates",
+  sectionInsertion: "section-insertion",
+  sectionActions: "section-actions",
+} as const;
+
+export type PreviewCapability = typeof previewCapability[keyof typeof previewCapability];
+
+export type RemotePreviewRoute = {
+  mediaPreview?: import("../../../src/images/PrivateImages").MediaPreviewAccess | null;
+  graph: any;
+  subject: any;
+  routeType: "page" | "entry";
+  path: string;
+  page?: number;
+  collection?: any;
+};
+
+export type ParentToPreviewMessage =
+  | { type: typeof previewMessageType.render; route: RemotePreviewRoute; activeBlockId?: string | null; capabilities?: PreviewCapability[] }
+  | { type: typeof previewMessageType.updateSubject; subject: any }
+  | { type: typeof previewMessageType.setActiveBlock; activeBlockId?: string | null }
+  | { type: typeof previewMessageType.scrollTo; position: { x: number; y: number } }
+  | { type: typeof previewMessageType.scrollToElement; attribute: string; value: string };
+
+export type PreviewToParentMessage =
+  | { type: typeof previewMessageType.ready; protocolVersion?: number; capabilities?: PreviewCapability[]; contentCapabilities?: string[] }
+  | ({ type: typeof previewMessageType.selectBlock; blockId: string } & Partial<PreviewScope>)
+  | ({ type: typeof previewMessageType.requestSectionInsert; afterBlockId?: string; atIndex?: number } & Partial<PreviewScope>)
+  | ({ type: typeof previewMessageType.sectionAction } & SectionActionRequest)
+  | { type: typeof previewMessageType.scroll; position: { x: number; y: number } };
+
+export const isPreviewMessage = (value: unknown): value is { type: string } =>
+  Boolean(value && typeof value === "object" && typeof (value as { type?: unknown }).type === "string");
+
+export const sectionActions = ["edit", "move-up", "move-down", "duplicate", "remove", "insert-before", "insert-after"] as const;
+export type SectionAction = typeof sectionActions[number];
+export type PreviewSection = { id: string; type: string };
+export type PreviewScope = { subjectId: string; path: string };
+export type SectionActionRequest = PreviewScope & { blockId: string; action: SectionAction };
+
+export function matchesPreviewScope(request: Partial<PreviewScope>, scope: PreviewScope, allowLegacy = false) {
+  if (request.subjectId === undefined && request.path === undefined) return allowLegacy;
+  return request.subjectId === scope.subjectId && request.path === scope.path;
+}
+
+export function resolveSectionInsertion(request: { afterBlockId?: unknown; atIndex?: unknown }, sections: PreviewSection[]) {
+  if (typeof request.afterBlockId === "string") {
+    return request.atIndex === undefined && sections.some((section) => section.id === request.afterBlockId)
+      ? { afterBlockId: request.afterBlockId } : null;
+  }
+  return request.afterBlockId === undefined && typeof request.atIndex === "number"
+    && Number.isInteger(request.atIndex) && request.atIndex >= 0 && request.atIndex <= sections.length
+    ? { atIndex: request.atIndex } : null;
+}
+
+// Only page-owned sections may be mutated by the page-level action handlers.
+export function isSectionActionRequest(value: unknown, scope: PreviewScope, sections: PreviewSection[]): value is SectionActionRequest {
+  if (!value || typeof value !== "object") return false;
+  const request = value as Record<string, unknown>;
+  return request.subjectId === scope.subjectId && request.path === scope.path
+    && typeof request.blockId === "string" && sections.some((section) => section.id === request.blockId)
+    && sectionActions.includes(request.action as SectionAction);
+}
+
+export function sectionLabel(section: PreviewSection) {
+  if (section.type === "SHARED_BLOCK") return "Shared section · instance";
+  if (section.type === "TWO_COLUMN") return "Columns";
+  return section.type.replace(/[_-]/g, " ").toLowerCase().replace(/^./, (letter) => letter.toUpperCase());
+}