@abinnovision/payloadcms-viewfinder 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -10,16 +10,17 @@ rendered block, resolves that identifier back to a path in the admin's own form
 messages between the two windows. In the preview, hovering a block outlines and names it and
 clicking anywhere inside it scrolls the matching form row into view. In the admin, hovering anywhere
 in a block row outlines that block in the preview, and a button in the row header scrolls the
-preview to it.
+preview to it. All of it is off until an editor turns it on, from one toggle in the document
+controls.
 
 Inline editing is deliberately not part of it. A visual editor needs to know which DOM node belongs
 to which field before it can do anything else, and that layer is useful on its own.
 [`docs/concepts.md`](./docs/concepts.md) describes the addressing model;
 [`docs/limitations.md`](./docs/limitations.md) states what is out of scope and why.
 
-Viewfinder works in any Payload app. [`@abinnovision/payloadcms-montage`](../montage) is not
-required, but when it is present its `wrapBlock` registry option makes the whole block tree
-addressable in one hook. See [`docs/integration.md`](./docs/integration.md) for both paths.
+Viewfinder works in any Payload app and takes no view on how blocks are rendered.
+[`@abinnovision/payloadcms-montage`](../montage) is not required; a block marks itself the same way
+either way. See [`docs/integration.md`](./docs/integration.md) for the wiring.
 
 ## Install
 
@@ -89,36 +90,44 @@ names it, and a click anywhere inside that block selects it. The whole block is
 plain click on a link inside a marked block selects rather than navigates while the page is framed.
 Modified and secondary clicks are left alone, so an editor can still open a link in a new tab.
 
-Finally, mark the blocks. Wrap each one in `<Marked>`, passing the Payload row `id` and your own
-preview flag:
+A crosshair toggle sits in the document controls, beside Payload's own live-preview button, on any
+document that has a live preview configured. It is greyed out until a preview is actually open, and
+**it starts off**: a previewed page behaves like the real site until an editor asks for the
+addressing, so no outline appears and a link inside a marked block navigates normally. Turning it
+on lights up both directions and the row buttons. The choice is a per-user Payload preference under
+the key `viewfinder`, so it follows the editor across documents and browsers.
+
+Finally, mark the blocks. A block addresses itself by spreading `markBlock()` onto its own root
+element, passing the Payload row `id`:
 
 ```tsx
-import { Marked } from "@abinnovision/payloadcms-viewfinder/client";
+import { markBlock, markField } from "@abinnovision/payloadcms-viewfinder";
 
-<Marked id={block.id} blockType={block.blockType} enabled={isPreview}>
-  <HeroModule block={block} />
-</Marked>;
+export const HeroModule = ({ block }) => (
+  <section {...markBlock(block.id, block.blockType)}>
+    <h2 {...markField("heading")}>{block.heading}</h2>
+  </section>
+);
 ```
 
-With `enabled={false}` the children render untouched, with no wrapper and no attributes, so
-production output is unaffected by having viewfinder installed.
+Import from the package root, not `./client`. `markBlock` is a pure function that returns a plain
+object, so a server component can spread it without crossing a client boundary.
 
-`Marked` adds nothing to the tree when its child is a DOM element: the attributes go onto that
-element. Only a component element, a fragment, an array, text or a promise gets a
-`display: contents` wrapper, since a component may not forward unknown props to any DOM node. A
-block can settle it either way by spreading `markBlock()` onto its own element:
+Call it only when your own preview flag is on, and only for a row that has an `id`. Nothing in the
+package enforces either: an unsaved row would emit an address that resolves to nothing, and an
+empty `data-vf-id` still matches, shadowing the nearest real ancestor. A one-line helper is the
+usual answer:
 
 ```tsx
-import {
-  markBlock,
-  markField,
-} from "@abinnovision/payloadcms-viewfinder/client";
-
-<section {...markBlock(block.id, block.blockType)}>
-  <h2 {...markField("heading")}>{block.heading}</h2>
-</section>;
+const mark = (block, isPreview) =>
+  isPreview && block.id ? markBlock(block.id, block.blockType) : {};
 ```
 
+A block that renders no element of its own — because it returns a fragment, an array, or a
+third-party component that will not forward `data-*` — needs to grow one to be addressable. Add
+that element deliberately rather than reaching for `display: contents`: a real element has a real
+box, which is what the overlay measures.
+
 `markField` is optional and opt-in. Its argument is relative to the enclosing block (`"heading"`,
 or `"items.0.label"` for something nested), never an absolute document path, which is what lets the
 address survive the block moving to a different index.
@@ -127,7 +136,7 @@ address survive the block moving to a different index.
 
 ```
 "."        attributes, protocol, path resolution. Imports nothing.
-"./client" ViewfinderBridge, Marked, markBlock, markField
+"./client" ViewfinderBridge, markBlock, markField
 "./config" viewfinderPlugin, loaded from payload.config.ts
 "./admin"  ViewfinderFormBridge, mounted by the plugin through the import map
 ```

package/dist/admin/bridge.d.mts

@@ -13,7 +13,10 @@ import { ReactNode } from "react";
  * Only the button scrolls. Driving the scroll from focus or from an ordinary
  * click, as an earlier version did, moved the preview while an editor was
  * merely placing a caret.
+ *
+ * All of it stands down when the editor turns the toggle off. This side owns
+ * that setting and tells the preview what it is, both on change and whenever
+ * the preview announces itself.
  */
-declare const ViewfinderFormBridge: () => ReactNode;
-//#endregion
-export { ViewfinderFormBridge };
+export declare const ViewfinderFormBridge: () => ReactNode;
+//#endregion

package/dist/admin/bridge.mjs

@@ -4,13 +4,18 @@ import { resolveAddressForPath, resolveAddressPath } from "../resolve-path.mjs";
 import { revealPath } from "./reveal.mjs";
 import { RowButton } from "./row-button.mjs";
 import { blockPaths, findRows, rowControls, rowPathAt, sameRows } from "./rows.mjs";
-import { Fragment, jsx } from "react/jsx-runtime";
+import { ViewfinderToggle } from "./toggle.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import { useAllFormFields } from "@payloadcms/ui";
+import { useAllFormFields, useLivePreviewContext, usePreferences } from "@payloadcms/ui";
 //#region src/admin/bridge.tsx
 /** Payload renders exactly one live-preview iframe, with this id. */ const PREVIEW_IFRAME_ID = "live-preview-iframe";
 /** Long enough to coalesce a burst of admin re-renders, short enough to feel instant. */ const RESCAN_MS = 50;
+/**
+* Payload preference key. Holds an object rather than a bare boolean so a
+* later second setting fits without a new key or a migration.
+*/ const PREFERENCE_KEY = "viewfinder";
 const previewIframe = () => document.getElementById(PREVIEW_IFRAME_ID);
 /**
 * Posts into the preview frame, addressed to the origin that frame is
@@ -35,18 +40,47 @@ const previewIframe = () => document.getElementById(PREVIEW_IFRAME_ID);
 * Only the button scrolls. Driving the scroll from focus or from an ordinary
 * click, as an earlier version did, moved the preview while an editor was
 * merely placing a caret.
+*
+* All of it stands down when the editor turns the toggle off. This side owns
+* that setting and tells the preview what it is, both on change and whenever
+* the preview announces itself.
 */ const ViewfinderFormBridge = () => {
 	const [fields] = useAllFormFields();
+	const { getPreference, setPreference } = usePreferences();
+	const { isLivePreviewing, url: livePreviewURL } = useLivePreviewContext();
 	const [rows, setRows] = useState(/* @__PURE__ */ new Map());
+	const [enabled, setEnabled] = useState(void 0);
 	const formState = useRef(fields);
 	formState.current = fields;
+	const enabledState = useRef(false);
+	enabledState.current = enabled ?? false;
+	const loaded = useRef(false);
+	useEffect(() => {
+		if (loaded.current) return;
+		loaded.current = true;
+		getPreference(PREFERENCE_KEY).then((preference) => {
+			setEnabled(preference?.enabled === true);
+		}).catch(() => {
+			setEnabled(false);
+		});
+	}, [getPreference]);
+	useEffect(() => {
+		if (enabled === void 0) return;
+		post(adminMessage.enabled(enabled));
+		if (!enabled) post(adminMessage.clear());
+	}, [enabled]);
 	const rowPaths = useRef(/* @__PURE__ */ new Map());
 	rowPaths.current = useMemo(() => new Map([...rows].map(([path, row]) => [row, path])), [rows]);
 	const pathsKey = useMemo(() => blockPaths(fields).join("|"), [fields]);
 	useEffect(() => {
 		const onMessage = (event) => {
 			if (event.source !== previewIframe()?.contentWindow) return;
-			if (!isPreviewMessage(event.data) || event.data.type !== "select") return;
+			if (!isPreviewMessage(event.data)) return;
+			if (event.data.type === "ready") {
+				post(adminMessage.enabled(enabledState.current));
+				return;
+			}
+			if (event.data.type !== "select" || !enabledState.current) return;
 			const path = resolveAddressPath(formState.current, event.data.address);
 			if (path !== void 0) revealPath(document, path);
 		};
@@ -78,6 +112,10 @@ const previewIframe = () => document.getElementById(PREVIEW_IFRAME_ID);
 	useEffect(() => {
 		let hovered;
 		const highlight = (path) => {
+			if (!enabledState.current) {
+				hovered = void 0;
+				return;
+			}
 			if (path === hovered) return;
 			hovered = path;
 			const address = path === void 0 ? void 0 : resolveAddressForPath(formState.current, path);
@@ -96,7 +134,14 @@ const previewIframe = () => document.getElementById(PREVIEW_IFRAME_ID);
 			document.removeEventListener("pointerleave", onPointerLeave);
 		};
 	}, []);
-	return /*#__PURE__*/ jsx(Fragment, { children: [...rows].map(([path, row]) => {
+	return /*#__PURE__*/ jsxs(Fragment, { children: [livePreviewURL ? /*#__PURE__*/ jsx(ViewfinderToggle, {
+		disabled: !isLivePreviewing || enabled === void 0,
+		enabled: enabled ?? false,
+		onToggle: (next) => {
+			setEnabled(next);
+			setPreference(PREFERENCE_KEY, { enabled: next });
+		}
+	}) : null, enabled !== true ? null : [...rows].map(([path, row]) => {
 		const controls = rowControls(row);
 		return controls === null ? null : /*#__PURE__*/ createPortal(/*#__PURE__*/ jsx(RowButton, {
 			label: "Scroll the preview to this block",
@@ -105,7 +150,7 @@ const previewIframe = () => document.getElementById(PREVIEW_IFRAME_ID);
 				if (address) post(adminMessage.scrollTo(address));
 			}
 		}), controls, path);
-	}) });
+	})] });
 };
 //#endregion
 export { ViewfinderFormBridge };

package/dist/admin/icons.mjs

@@ -0,0 +1,33 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/admin/icons.tsx
+/**
+* The one mark viewfinder draws in the admin, shared by the row button and
+* the toggle so the two read as the same feature. Stroke and size come from
+* the button around it, so the icon carries no colour of its own.
+*/ const Crosshair = (props) => /*#__PURE__*/ jsxs("svg", {
+	"aria-hidden": true,
+	fill: "none",
+	height: "14",
+	stroke: "currentColor",
+	strokeWidth: "1.6",
+	viewBox: "0 0 16 16",
+	width: "14",
+	children: [
+		/*#__PURE__*/ jsx("circle", {
+			cx: "8",
+			cy: "8",
+			r: "3.2"
+		}),
+		/*#__PURE__*/ jsx("path", {
+			d: "M8 1v2.2M8 12.8V15M1 8h2.2M12.8 8H15",
+			strokeLinecap: "round"
+		}),
+		props.slashed ? /*#__PURE__*/ jsx("path", {
+			d: "M2.5 13.5 13.5 2.5",
+			strokeLinecap: "round"
+		}) : null
+	]
+});
+//#endregion
+export { Crosshair };

package/dist/admin/row-button.mjs

@@ -1,5 +1,6 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Crosshair } from "./icons.mjs";
+import { jsx } from "react/jsx-runtime";
 import { useState } from "react";
 //#region src/admin/row-button.tsx
 /**
@@ -67,23 +68,7 @@ import { useState } from "react";
 		},
 		title: props.label,
 		type: "button",
-		children: /*#__PURE__*/ jsxs("svg", {
-			"aria-hidden": true,
-			fill: "none",
-			height: "14",
-			stroke: "currentColor",
-			strokeWidth: "1.6",
-			viewBox: "0 0 16 16",
-			width: "14",
-			children: [/*#__PURE__*/ jsx("circle", {
-				cx: "8",
-				cy: "8",
-				r: "3.2"
-			}), /*#__PURE__*/ jsx("path", {
-				d: "M8 1v2.2M8 12.8V15M1 8h2.2M12.8 8H15",
-				strokeLinecap: "round"
-			})]
-		})
+		children: /*#__PURE__*/ jsx(Crosshair, {})
 	});
 };
 //#endregion

package/dist/admin/toggle.mjs

@@ -0,0 +1,62 @@
+"use client";
+import { Crosshair } from "./icons.mjs";
+import { jsx } from "react/jsx-runtime";
+import { Button } from "@payloadcms/ui";
+//#region src/admin/toggle.tsx
+/**
+* The same box in both states, because it is the box Payload's live-preview
+* toggler already draws beside it: `subtle` resolves to `--theme-elevation-100`
+* on `--theme-elevation-200`, which is that button exactly. State is carried by
+* the icon, as it is on the toggler, whose eye slashes rather than reboxing.
+*
+* Not `secondary`, which is the one that looks wrong here: its border is
+* `--theme-elevation-800`, so an outlined icon button lands as a black square
+* next to Payload's grey ones.
+*/ const STYLE = "subtle";
+/**
+* `Button`'s own sizes are shaped for a label, so an icon-only one comes out a
+* squat rectangle. These are the toggler's own dimensions, in the toggler's own
+* units, which is what makes the two read as one pair of square icon buttons
+* rather than a square beside an oblong.
+*/ const SQUARE = {
+	width: "calc(var(--base) * 1.6)",
+	height: "calc(var(--base) * 1.6)",
+	padding: 0,
+	display: "inline-flex",
+	alignItems: "center",
+	justifyContent: "center"
+};
+const LABEL = {
+	on: "Stop linking the preview and this form",
+	off: "Link the preview and this form",
+	idle: "Open the live preview to link it to this form"
+};
+/**
+* The one control for the whole feature. Off means no outlines in either
+* direction, no row buttons, and no click interception in the preview, so an
+* editor can click through the previewed site the way a visitor would.
+*
+* Built on Payload's own `Button` rather than a styled `<button>`, so the
+* hover, focus and disabled states are the admin's rather than an imitation of
+* them, and stay right through a theme or a Payload upgrade.
+*/ const ViewfinderToggle = (props) => {
+	const label = props.disabled ? LABEL.idle : props.enabled ? LABEL.on : LABEL.off;
+	return /*#__PURE__*/ jsx(Button, {
+		"aria-label": label,
+		buttonStyle: STYLE,
+		disabled: props.disabled,
+		extraButtonProps: {
+			"aria-pressed": props.enabled,
+			style: SQUARE
+		},
+		icon: /*#__PURE__*/ jsx(Crosshair, { slashed: !props.enabled }),
+		margin: false,
+		onClick: () => {
+			props.onToggle(!props.enabled);
+		},
+		size: "small",
+		tooltip: label
+	});
+};
+//#endregion
+export { ViewfinderToggle };

package/dist/attributes.d.mts

@@ -5,31 +5,32 @@
  * against its own form state. That is what keeps the frontend free of a
  * content source map and the API unchanged.
  */
-declare const BLOCK_ID_ATTRIBUTE = "data-vf-id";
+export declare const BLOCK_ID_ATTRIBUTE = "data-vf-id";
 /** Advisory only: the admin addresses blocks by id, never by type. */
-declare const BLOCK_TYPE_ATTRIBUTE = "data-vf-type";
+export declare const BLOCK_TYPE_ATTRIBUTE = "data-vf-type";
 /** Resolved against the nearest marked block ancestor, so it stays index-free. */
-declare const FIELD_ATTRIBUTE = "data-vf-field";
-interface BlockMarkerAttributes {
+export declare const FIELD_ATTRIBUTE = "data-vf-field";
+export interface BlockMarkerAttributes {
   readonly [BLOCK_ID_ATTRIBUTE]: string;
   readonly [BLOCK_TYPE_ATTRIBUTE]?: string;
 }
-interface FieldMarkerAttributes {
+export interface FieldMarkerAttributes {
   readonly [FIELD_ATTRIBUTE]: string;
 }
 /**
- * Attributes identifying one block in the rendered output. Spread onto a
- * block's own root element to skip the `<Marked>` wrapper, which is worth
- * doing wherever the block already renders a stable element: a real element
- * has a real box, so the highlight overlay does not have to infer geometry
- * from children.
+ * Attributes identifying one block in the rendered output. Spread onto the
+ * block's own root element, and only when the page is a preview: an address
+ * is a preview affordance, not something a visitor's markup needs.
+ *
+ * A block with no root element of its own has to grow one to be addressable.
+ * That element is worth adding deliberately, since a real element has a real
+ * box and the highlight overlay measures it directly.
  */
-declare const markBlock: (id: string, blockType?: string) => BlockMarkerAttributes;
+export declare const markBlock: (id: string, blockType?: string) => BlockMarkerAttributes;
 /**
  * Attributes identifying one field within the enclosing block. `field` is
  * relative to that block (`"heading"`, or `"items.0.label"` for something
  * nested), never an absolute document path.
  */
-declare const markField: (field: string) => FieldMarkerAttributes;
-//#endregion
-export { BLOCK_ID_ATTRIBUTE, BLOCK_TYPE_ATTRIBUTE, BlockMarkerAttributes, FIELD_ATTRIBUTE, FieldMarkerAttributes, markBlock, markField };
+export declare const markField: (field: string) => FieldMarkerAttributes;
+//#endregion

package/dist/attributes.mjs

@@ -8,11 +8,13 @@
 /** Advisory only: the admin addresses blocks by id, never by type. */ const BLOCK_TYPE_ATTRIBUTE = "data-vf-type";
 /** Resolved against the nearest marked block ancestor, so it stays index-free. */ const FIELD_ATTRIBUTE = "data-vf-field";
 /**
-* Attributes identifying one block in the rendered output. Spread onto a
-* block's own root element to skip the `<Marked>` wrapper, which is worth
-* doing wherever the block already renders a stable element: a real element
-* has a real box, so the highlight overlay does not have to infer geometry
-* from children.
+* Attributes identifying one block in the rendered output. Spread onto the
+* block's own root element, and only when the page is a preview: an address
+* is a preview affordance, not something a visitor's markup needs.
+*
+* A block with no root element of its own has to grow one to be addressable.
+* That element is worth adding deliberately, since a real element has a real
+* box and the highlight overlay measures it directly.
 */ const markBlock = (id, blockType) => blockType === void 0 ? { [BLOCK_ID_ATTRIBUTE]: id } : {
 	[BLOCK_ID_ATTRIBUTE]: id,
 	[BLOCK_TYPE_ATTRIBUTE]: blockType

package/dist/client/bridge.d.mts

@@ -1,6 +1,6 @@
 import { ReactNode } from "react";
 //#region src/client/bridge.d.ts
-interface ViewfinderBridgeProps {
+export interface ViewfinderBridgeProps {
   /**
    * Origin of the Payload admin, e.g. `https://cms.example.com`. Required
    * rather than defaulting to `"*"`: this window posts the ids of everything
@@ -17,7 +17,10 @@ interface ViewfinderBridgeProps {
  *
  * Does nothing at all when the page is not framed, so the same tree can be
  * served to real visitors without a second code path.
+ *
+ * The admin owns the on/off setting and announces it. Until it does, and
+ * whenever it says off, this is an untouched page: no outline, and a link
+ * inside a marked block navigates the way it would for a visitor.
  */
-declare const ViewfinderBridge: (props: ViewfinderBridgeProps) => ReactNode;
-//#endregion
-export { ViewfinderBridge, ViewfinderBridgeProps };
+export declare const ViewfinderBridge: (props: ViewfinderBridgeProps) => ReactNode;
+//#endregion

package/dist/client/bridge.mjs

@@ -5,7 +5,7 @@ import { measureElement, scrollBoxIntoView } from "./geometry.mjs";
 import { Overlay } from "./overlay.mjs";
 import { resolveTarget } from "./target.mjs";
 import { jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 //#region src/client/bridge.tsx
 const findBlock = (id) => document.querySelector(`[${BLOCK_ID_ATTRIBUTE}="${CSS.escape(id)}"]`);
 const labelFor = (address) => address.field === void 0 ? address.blockType ?? "block" : `${address.blockType ?? "block"} · ${address.field}`;
@@ -18,10 +18,15 @@ const labelFor = (address) => address.field === void 0 ? address.blockType ?? "b
 *
 * Does nothing at all when the page is not framed, so the same tree can be
 * served to real visitors without a second code path.
+*
+* The admin owns the on/off setting and announces it. Until it does, and
+* whenever it says off, this is an untouched page: no outline, and a link
+* inside a marked block navigates the way it would for a visitor.
 */ const ViewfinderBridge = (props) => {
 	const { adminOrigin } = props;
 	const [active, setActive] = useState(null);
 	const [box, setBox] = useState(void 0);
+	const enabled = useRef(false);
 	useEffect(() => {
 		if (window.parent === window) return;
 		const post = (message) => {
@@ -35,6 +40,7 @@ const labelFor = (address) => address.field === void 0 ? address.blockType ?? "b
 			post(address ? previewMessage.hover(address) : previewMessage.leave());
 		};
 		const onPointerOver = (event) => {
+			if (!enabled.current) return;
 			const resolved = resolveTarget(event.target);
 			if (!resolved) {
 				setActive(null);
@@ -48,6 +54,7 @@ const labelFor = (address) => address.field === void 0 ? address.blockType ?? "b
 			postHover(resolved.address);
 		};
 		const onClick = (event) => {
+			if (!enabled.current) return;
 			if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
 			const resolved = resolveTarget(event.target);
 			if (!resolved) return;
@@ -62,7 +69,15 @@ const labelFor = (address) => address.field === void 0 ? address.blockType ?? "b
 		const onMessage = (event) => {
 			if (event.origin !== adminOrigin || event.source !== window.parent) return;
 			if (!isAdminMessage(event.data)) return;
-			if (event.data.type === "clear") {
+			if (event.data.type === "enabled") {
+				enabled.current = event.data.enabled;
+				if (!event.data.enabled) {
+					setActive(null);
+					hovered = null;
+				}
+				return;
+			}
+			if (!enabled.current || event.data.type === "clear") {
 				setActive(null);
 				return;
 			}

package/dist/client/geometry.mjs

@@ -3,11 +3,13 @@ const isEmpty = (rect) => rect.width === 0 && rect.height === 0;
 /**
 * Viewport-relative box for a marked element.
 *
-* `<Marked>` wraps blocks in a `display: contents` element so that layout is
-* untouched, and such an element generates no box of its own — its rect is
-* all zeroes. A `Range` over its contents measures what it actually renders,
-* covering element and text children alike, which is why this is a range
-* rather than a walk over `children`.
+* A marked element usually has a box of its own and is measured directly.
+* Not always: an element that is `display: contents` generates no box at all,
+* and its rect is all zeroes. A `Range` over its contents measures what it
+* actually renders, covering element and text children alike, which is why
+* this is a range rather than a walk over `children`. The range is an
+* inference — an absolutely positioned or transformed child contributes its
+* own rect, so the box can come out larger or offset.
 */ const measureElement = (element) => {
 	const own = element.getBoundingClientRect();
 	const rect = isEmpty(own) ? rangeRect(element) : own;
@@ -27,9 +29,10 @@ const rangeRect = (element) => {
 /**
 * Centres a measured box in the viewport.
 *
-* Not `Element.scrollIntoView`: a `display: contents` wrapper has no box for
-* the browser to scroll to, so the already-measured box is scrolled to
-* instead. That keeps wrapped and self-marked blocks behaving identically.
+* Not `Element.scrollIntoView`: an element with no box of its own gives the
+* browser nothing to scroll to, so the already-measured box is scrolled to
+* instead. Every marked block then behaves the same way, whether or not it
+* generates a box.
 */ const scrollBoxIntoView = (view, box) => {
 	const top = view.scrollY + box.top - (view.innerHeight - box.height) / 2;
 	view.scrollTo({

package/dist/client/index.d.mts

@@ -1,5 +1,4 @@
 import { ViewfinderBridge, ViewfinderBridgeProps } from "./bridge.mjs";
-import { Marked, MarkedProps } from "./marked.mjs";
 import { BlockMarkerAttributes, FieldMarkerAttributes, markBlock, markField } from "../attributes.mjs";
 import { BlockAddress } from "../protocol.mjs";
-export { type BlockAddress, type BlockMarkerAttributes, type FieldMarkerAttributes, Marked, type MarkedProps, ViewfinderBridge, type ViewfinderBridgeProps, markBlock, markField };
+export { type BlockAddress, type BlockMarkerAttributes, type FieldMarkerAttributes, ViewfinderBridge, type ViewfinderBridgeProps, markBlock, markField };

package/dist/client/index.mjs

@@ -1,5 +1,4 @@
 "use client";
 import { markBlock, markField } from "../attributes.mjs";
 import { ViewfinderBridge } from "./bridge.mjs";
-import { Marked } from "./marked.mjs";
-export { Marked, ViewfinderBridge, markBlock, markField };
+export { ViewfinderBridge, markBlock, markField };

package/dist/config/plugin.d.mts

@@ -1,6 +1,6 @@
 import { Plugin } from "payload";
 //#region src/config/plugin.d.ts
-interface ViewfinderPluginArgs {
+export interface ViewfinderPluginArgs {
   /** Collection slugs to make addressable. Defaults to every collection. */
   collections?: string[] | undefined;
   /** Global slugs to make addressable. Defaults to every global. */
@@ -13,6 +13,5 @@ interface ViewfinderPluginArgs {
  * enabling it for a collection that has no live preview configured costs
  * nothing beyond the component itself.
  */
-declare const viewfinderPlugin: (args?: ViewfinderPluginArgs) => Plugin;
-//#endregion
-export { ViewfinderPluginArgs, viewfinderPlugin };
+export declare const viewfinderPlugin: (args?: ViewfinderPluginArgs) => Plugin;
+//#endregion

package/dist/protocol.d.mts

@@ -5,17 +5,22 @@
  * carries a source tag and a version, and is validated structurally on
  * arrival rather than cast.
  */
-declare const VIEWFINDER_SOURCE = "viewfinder";
+export declare const VIEWFINDER_SOURCE = "viewfinder";
 /**
  * Bumped only on a breaking envelope change. A mismatched version is dropped
  * silently, so a stale frontend deployment cannot drive a newer admin.
+ *
+ * Adding a message type is not a breaking change and does not qualify: a
+ * receiver that predates the type does not have it in its own type set, so it
+ * drops the message and keeps behaving as it did. Bumping the version for that
+ * would instead break every existing pairing at once.
  */
-declare const VIEWFINDER_PROTOCOL_VERSION = 1;
+export declare const VIEWFINDER_PROTOCOL_VERSION = 1;
 /**
  * What one message points at. `field` is relative to the block, which is what
  * lets the same address survive the block moving to a different index.
  */
-interface BlockAddress {
+export interface BlockAddress {
   id: string;
   blockType?: string;
   field?: string;
@@ -28,24 +33,31 @@ interface Envelope<TType extends string> {
 interface AddressedEnvelope<TType extends string> extends Envelope<TType> {
   address: BlockAddress;
 }
+interface FlaggedEnvelope<TType extends string> extends Envelope<TType> {
+  enabled: boolean;
+}
 /** Sent by the rendered page, in the iframe, up to the admin. */
-type PreviewMessage = AddressedEnvelope<"hover"> | AddressedEnvelope<"select"> | Envelope<"leave"> | Envelope<"ready">;
-/** Sent by the admin down into the preview iframe. */
-type AdminMessage = AddressedEnvelope<"highlight"> | AddressedEnvelope<"scrollTo"> | Envelope<"clear">;
+export type PreviewMessage = AddressedEnvelope<"hover"> | AddressedEnvelope<"select"> | Envelope<"leave"> | Envelope<"ready">;
+/**
+ * Sent by the admin down into the preview iframe. `enabled` is the admin
+ * answering for the whole feature: the admin owns the setting, and the preview
+ * is told what it is, on connect and on every change.
+ */
+export type AdminMessage = AddressedEnvelope<"highlight"> | AddressedEnvelope<"scrollTo"> | Envelope<"clear"> | FlaggedEnvelope<"enabled">;
 /** Narrows the untrusted `event.data` of a `message` event from the iframe. */
-declare const isPreviewMessage: (value: unknown) => value is PreviewMessage;
+export declare const isPreviewMessage: (value: unknown) => value is PreviewMessage;
 /** Narrows the untrusted `event.data` of a `message` event from the admin. */
-declare const isAdminMessage: (value: unknown) => value is AdminMessage;
-declare const previewMessage: {
+export declare const isAdminMessage: (value: unknown) => value is AdminMessage;
+export declare const previewMessage: {
   readonly ready: () => PreviewMessage;
   readonly leave: () => PreviewMessage;
   readonly hover: (address: BlockAddress) => PreviewMessage;
   readonly select: (address: BlockAddress) => PreviewMessage;
 };
-declare const adminMessage: {
+export declare const adminMessage: {
   readonly clear: () => AdminMessage;
+  readonly enabled: (enabled: boolean) => AdminMessage;
   readonly highlight: (address: BlockAddress) => AdminMessage;
   readonly scrollTo: (address: BlockAddress) => AdminMessage;
 };
-//#endregion
-export { AdminMessage, BlockAddress, PreviewMessage, VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, previewMessage };
+//#endregion

package/dist/protocol.mjs

@@ -8,6 +8,11 @@
 /**
 * Bumped only on a breaking envelope change. A mismatched version is dropped
 * silently, so a stale frontend deployment cannot drive a newer admin.
+*
+* Adding a message type is not a breaking change and does not qualify: a
+* receiver that predates the type does not have it in its own type set, so it
+* drops the message and keeps behaving as it did. Bumping the version for that
+* would instead break every existing pairing at once.
 */ const VIEWFINDER_PROTOCOL_VERSION = 1;
 const PREVIEW_TYPES = /* @__PURE__ */ new Set([
 	"hover",
@@ -18,7 +23,8 @@ const PREVIEW_TYPES = /* @__PURE__ */ new Set([
 const ADMIN_TYPES = /* @__PURE__ */ new Set([
 	"highlight",
 	"scrollTo",
-	"clear"
+	"clear",
+	"enabled"
 ]);
 const ADDRESSED_TYPES = /* @__PURE__ */ new Set([
 	"hover",
@@ -26,6 +32,7 @@ const ADDRESSED_TYPES = /* @__PURE__ */ new Set([
 	"highlight",
 	"scrollTo"
 ]);
+const FLAGGED_TYPES = /* @__PURE__ */ new Set(["enabled"]);
 const isAddress = (value) => {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
@@ -35,7 +42,8 @@ const isEnvelope = (value, types) => {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
 	if (candidate["source"] !== "viewfinder" || candidate["version"] !== 1 || typeof candidate["type"] !== "string" || !types.has(candidate["type"])) return false;
-	return !ADDRESSED_TYPES.has(candidate["type"]) || isAddress(candidate["address"]);
+	if (ADDRESSED_TYPES.has(candidate["type"]) && !isAddress(candidate["address"])) return false;
+	return !FLAGGED_TYPES.has(candidate["type"]) || typeof candidate["enabled"] === "boolean";
 };
 /** Narrows the untrusted `event.data` of a `message` event from the iframe. */ const isPreviewMessage = (value) => isEnvelope(value, PREVIEW_TYPES);
 /** Narrows the untrusted `event.data` of a `message` event from the admin. */ const isAdminMessage = (value) => isEnvelope(value, ADMIN_TYPES);
@@ -56,6 +64,10 @@ const previewMessage = {
 };
 const adminMessage = {
 	clear: () => bare("clear"),
+	enabled: (enabled) => ({
+		...bare("enabled"),
+		enabled
+	}),
 	highlight: (address) => addressed("highlight", address),
 	scrollTo: (address) => addressed("scrollTo", address)
 };

package/dist/resolve-path.d.mts

@@ -10,7 +10,7 @@ import { BlockAddress } from "./protocol.mjs";
  * know the collection's schema. If a Payload upgrade changes the key shape,
  * this file is the only one that has to move.
  */
-type FormStateLike = Readonly<Record<string, {
+export type FormStateLike = Readonly<Record<string, {
   value?: unknown;
 } | undefined>>;
 /**
@@ -20,14 +20,14 @@ type FormStateLike = Readonly<Record<string, {
  * shallowest path wins so the result stays deterministic rather than
  * depending on key order.
  */
-declare const resolveBlockPath: (formState: FormStateLike, id: string) => string | undefined;
+export declare const resolveBlockPath: (formState: FormStateLike, id: string) => string | undefined;
 /** Joins a block path and a block-relative field name into a form path. */
-declare const resolveFieldPath: (blockPath: string, field: string) => string;
+export declare const resolveFieldPath: (blockPath: string, field: string) => string;
 /**
  * Resolves a whole address to the form path the admin should reveal: the
  * block itself, or a field inside it when the preview named one.
  */
-declare const resolveAddressPath: (formState: FormStateLike, address: BlockAddress) => string | undefined;
+export declare const resolveAddressPath: (formState: FormStateLike, address: BlockAddress) => string | undefined;
 /**
  * The inverse, for the admin-to-preview direction: given any form path, finds
  * the id of the nearest enclosing block.
@@ -36,11 +36,10 @@ declare const resolveAddressPath: (formState: FormStateLike, address: BlockAddre
  * what distinguishes a block row from a plain array row — array rows also
  * carry an `id`, but the preview knows nothing about them.
  */
-declare const resolveBlockIdForPath: (formState: FormStateLike, path: string) => string | undefined;
+export declare const resolveBlockIdForPath: (formState: FormStateLike, path: string) => string | undefined;
 /**
  * The address to send into the preview for a form path, carrying the field
  * suffix when the path pointed inside a block rather than at it.
  */
-declare const resolveAddressForPath: (formState: FormStateLike, path: string) => BlockAddress | undefined;
-//#endregion
-export { FormStateLike, resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath };
+export declare const resolveAddressForPath: (formState: FormStateLike, path: string) => BlockAddress | undefined;
+//#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-viewfinder",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "Two-way block addressing between a rendered frontend and the Payload CMS admin form.",
   "keywords": [
     "payload",
@@ -68,20 +68,20 @@
     "@abinnovision/prettier-config": "^2.2.0",
     "@arethetypeswrong/core": "^0.18.5",
     "@payloadcms/ui": "3.88.0",
-    "@swc/core": "^1.16.1",
-    "@types/node": "^26.3.0",
+    "@swc/core": "^1.16.2",
+    "@types/node": "^26.5.1",
     "@types/react": "^19.2.18",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.9.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
     "payload": "3.88.0",
     "prettier": "^3.9.5",
     "publint": "^0.3.24",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "tsdown": "^0.22.14",
+    "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
-    "unplugin-swc": "^1.5.11",
-    "vitest": "^4.1.10"
+    "unplugin-swc": "^1.6.0",
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
     "@payloadcms/ui": ">=3.88.0 <4",

package/dist/client/marked.d.mts

@@ -1,38 +0,0 @@
-import { ReactNode } from "react";
-//#region src/client/marked.d.ts
-interface MarkedProps {
-  /** The Payload row id of this block. */
-  id: string;
-  /**
-   * Shown in the preview overlay so editors can tell blocks apart.
-   *
-   * Explicitly `| undefined` so that under `exactOptionalPropertyTypes` a
-   * caller can forward a possibly-absent value straight through, which is
-   * what a generic wrapper around a block registry has to do.
-   */
-  blockType?: string | undefined;
-  /**
-   * Gate this on your own preview flag. When false the children render
-   * untouched, with no wrapper and no attributes, so production output is
-   * unaffected by having viewfinder installed.
-   */
-  enabled?: boolean | undefined;
-  children: ReactNode;
-}
-/**
- * Makes one block addressable from the admin.
- *
- * Marks the block's own root element where there is one, and falls back to a
- * `display: contents` wrapper where there is not. The wrapper preserves
- * layout but is still an element in the tree: it breaks `>` and
- * `:nth-child()` selectors aimed at the block, the HTML parser reparents it
- * out of a table or a paragraph, and it has no box, so the overlay measures a
- * range over its children rather than a rect.
- *
- * A block can also spread `markBlock()` onto its own element and skip this
- * component altogether. That is the same outcome as the marked branch here,
- * stated by the block rather than inferred.
- */
-declare const Marked: (props: MarkedProps) => ReactNode;
-//#endregion
-export { Marked, MarkedProps };

package/dist/client/marked.mjs

@@ -1,44 +0,0 @@
-"use client";
-import { markBlock } from "../attributes.mjs";
-import { jsx } from "react/jsx-runtime";
-import { cloneElement, isValidElement } from "react";
-//#region src/client/marked.tsx
-/**
-* `display: contents` removes the wrapper from layout entirely, so marking a
-* block cannot change how it renders. The cost is that the wrapper has no box
-* of its own; `measureElement` handles that.
-*/ const CONTENTS = { display: "contents" };
-/**
-* Whether this is a DOM element, as opposed to a component element, a
-* fragment, a promise or text.
-*
-* `typeof type === "string"` is what makes marking it safe: a host element
-* puts every unknown prop into the markup, so the attributes are certain to
-* land. A component element might forward them to its root or drop them, and
-* there is no way to tell which from here.
-*/ const isHostElement = (node) => /*#__PURE__*/ isValidElement(node) && typeof node.type === "string";
-/**
-* Makes one block addressable from the admin.
-*
-* Marks the block's own root element where there is one, and falls back to a
-* `display: contents` wrapper where there is not. The wrapper preserves
-* layout but is still an element in the tree: it breaks `>` and
-* `:nth-child()` selectors aimed at the block, the HTML parser reparents it
-* out of a table or a paragraph, and it has no box, so the overlay measures a
-* range over its children rather than a rect.
-*
-* A block can also spread `markBlock()` onto its own element and skip this
-* component altogether. That is the same outcome as the marked branch here,
-* stated by the block rather than inferred.
-*/ const Marked = (props) => {
-	if (props.enabled === false || props.id.length === 0) return props.children;
-	const attributes = markBlock(props.id, props.blockType);
-	if (isHostElement(props.children)) return props.children.props["data-vf-id"] === void 0 ? /*#__PURE__*/ cloneElement(props.children, { ...attributes }) : props.children;
-	return /*#__PURE__*/ jsx("div", {
-		style: CONTENTS,
-		...attributes,
-		children: props.children
-	});
-};
-//#endregion
-export { Marked };