@abinnovision/payloadcms-viewfinder 1.0.0-beta.1

package/dist/config/plugin.mjs

@@ -0,0 +1,73 @@
+//#region src/config/plugin.ts
+/**
+* Payload resolves admin components by import path, so this string has to
+* match the `./admin` export. Consumers must run
+* `payload generate:importmap` after adding the plugin, as for any plugin
+* that contributes admin components.
+*/ const BRIDGE_COMPONENT = "@abinnovision/payloadcms-viewfinder/admin#ViewfinderFormBridge";
+const append = (existing) => {
+	const components = existing ?? [];
+	return components.includes(BRIDGE_COMPONENT) ? void 0 : [...components, BRIDGE_COMPONENT];
+};
+/**
+* `beforeDocumentControls` is the mount point because it renders inside the
+* document `<Form>`, which is what gives the bridge access to form state. The
+* global `admin.components.providers` slot wraps the dashboard from outside
+* every form, so a provider mounted there could never resolve a field path.
+*
+* Collections nest that slot under `components.edit` and globals under
+* `components.elements`, hence the two shapes.
+*/ const withCollectionBridge = (entity) => {
+	const edit = entity.admin?.components?.edit;
+	const beforeDocumentControls = append(edit?.beforeDocumentControls);
+	if (!beforeDocumentControls) return entity;
+	return {
+		...entity,
+		admin: {
+			...entity.admin,
+			components: {
+				...entity.admin?.components,
+				edit: {
+					...edit,
+					beforeDocumentControls
+				}
+			}
+		}
+	};
+};
+const withGlobalBridge = (entity) => {
+	const elements = entity.admin?.components?.elements;
+	const beforeDocumentControls = append(elements?.beforeDocumentControls);
+	if (!beforeDocumentControls) return entity;
+	return {
+		...entity,
+		admin: {
+			...entity.admin,
+			components: {
+				...entity.admin?.components,
+				elements: {
+					...elements,
+					beforeDocumentControls
+				}
+			}
+		}
+	};
+};
+const apply = (entities, slugs, transform) => (entities ?? []).map((entity) => slugs === void 0 || slugs.includes(entity.slug) ? transform(entity) : entity);
+/**
+* Makes documents addressable from their live preview.
+*
+* The bridge it mounts is inert until a framed page announces itself, so
+* enabling it for a collection that has no live preview configured costs
+* nothing beyond the component itself.
+*/ const viewfinderPlugin = (args = {}) => {
+	const plugin = (config) => ({
+		...config,
+		collections: apply(config.collections, args.collections, withCollectionBridge),
+		globals: apply(config.globals, args.globals, withGlobalBridge)
+	});
+	plugin.slug = "viewfinder";
+	return plugin;
+};
+//#endregion
+export { viewfinderPlugin };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { BLOCK_ID_ATTRIBUTE, BLOCK_TYPE_ATTRIBUTE, BlockMarkerAttributes, FIELD_ATTRIBUTE, FieldMarkerAttributes, markBlock, markField } from "./attributes.mjs";
+import { AdminMessage, BlockAddress, PreviewMessage, VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, previewMessage } from "./protocol.mjs";
+import { FormStateLike, resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath } from "./resolve-path.mjs";
+export { type AdminMessage, BLOCK_ID_ATTRIBUTE, BLOCK_TYPE_ATTRIBUTE, type BlockAddress, type BlockMarkerAttributes, FIELD_ATTRIBUTE, type FieldMarkerAttributes, type FormStateLike, type PreviewMessage, VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, markBlock, markField, previewMessage, resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { BLOCK_ID_ATTRIBUTE, BLOCK_TYPE_ATTRIBUTE, FIELD_ATTRIBUTE, markBlock, markField } from "./attributes.mjs";
+import { VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, previewMessage } from "./protocol.mjs";
+import { resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath } from "./resolve-path.mjs";
+export { BLOCK_ID_ATTRIBUTE, BLOCK_TYPE_ATTRIBUTE, FIELD_ATTRIBUTE, VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, markBlock, markField, previewMessage, resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath };

package/dist/protocol.d.mts

@@ -0,0 +1,51 @@
+//#region src/protocol.d.ts
+/**
+ * Both windows are untrusted from the other's point of view: the preview is a
+ * consumer page and the admin is a separate origin. Every message therefore
+ * carries a source tag and a version, and is validated structurally on
+ * arrival rather than cast.
+ */
+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.
+ */
+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 {
+  id: string;
+  blockType?: string;
+  field?: string;
+}
+interface Envelope<TType extends string> {
+  source: typeof VIEWFINDER_SOURCE;
+  version: typeof VIEWFINDER_PROTOCOL_VERSION;
+  type: TType;
+}
+interface AddressedEnvelope<TType extends string> extends Envelope<TType> {
+  address: BlockAddress;
+}
+/** 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">;
+/** Narrows the untrusted `event.data` of a `message` event from the iframe. */
+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: {
+  readonly ready: () => PreviewMessage;
+  readonly leave: () => PreviewMessage;
+  readonly hover: (address: BlockAddress) => PreviewMessage;
+  readonly select: (address: BlockAddress) => PreviewMessage;
+};
+declare const adminMessage: {
+  readonly clear: () => 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 };

package/dist/protocol.mjs

@@ -0,0 +1,63 @@
+//#region src/protocol.ts
+/**
+* Both windows are untrusted from the other's point of view: the preview is a
+* consumer page and the admin is a separate origin. Every message therefore
+* carries a source tag and a version, and is validated structurally on
+* arrival rather than cast.
+*/ 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.
+*/ const VIEWFINDER_PROTOCOL_VERSION = 1;
+const PREVIEW_TYPES = /* @__PURE__ */ new Set([
+	"hover",
+	"select",
+	"leave",
+	"ready"
+]);
+const ADMIN_TYPES = /* @__PURE__ */ new Set([
+	"highlight",
+	"scrollTo",
+	"clear"
+]);
+const ADDRESSED_TYPES = /* @__PURE__ */ new Set([
+	"hover",
+	"select",
+	"highlight",
+	"scrollTo"
+]);
+const isAddress = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate["id"] === "string" && candidate["id"].length > 0 && (candidate["blockType"] === void 0 || typeof candidate["blockType"] === "string") && (candidate["field"] === void 0 || typeof candidate["field"] === "string");
+};
+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"]);
+};
+/** 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);
+const bare = (type) => ({
+	source: VIEWFINDER_SOURCE,
+	version: 1,
+	type
+});
+const addressed = (type, address) => ({
+	...bare(type),
+	address
+});
+const previewMessage = {
+	ready: () => bare("ready"),
+	leave: () => bare("leave"),
+	hover: (address) => addressed("hover", address),
+	select: (address) => addressed("select", address)
+};
+const adminMessage = {
+	clear: () => bare("clear"),
+	highlight: (address) => addressed("highlight", address),
+	scrollTo: (address) => addressed("scrollTo", address)
+};
+//#endregion
+export { VIEWFINDER_PROTOCOL_VERSION, VIEWFINDER_SOURCE, adminMessage, isAdminMessage, isPreviewMessage, previewMessage };

package/dist/resolve-path.d.mts

@@ -0,0 +1,46 @@
+import { BlockAddress } from "./protocol.mjs";
+//#region src/resolve-path.d.ts
+/**
+ * The single place this package assumes anything about Payload internals.
+ *
+ * Payload's admin form state is already flat-keyed by field path — a block
+ * three levels deep appears as discrete `layout.0.modules.2.heading` entries,
+ * not as a nested document. That is what makes id lookup a scan rather than a
+ * tree walk, and it is why nothing here needs to reconstruct the document or
+ * 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, {
+  value?: unknown;
+} | undefined>>;
+/**
+ * Resolves a Payload row `id` to its form path (`layout.0.modules.2`).
+ *
+ * Ids are unique in practice; if two rows somehow carry the same one, the
+ * shallowest path wins so the result stays deterministic rather than
+ * depending on key order.
+ */
+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;
+/**
+ * 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;
+/**
+ * The inverse, for the admin-to-preview direction: given any form path, finds
+ * the id of the nearest enclosing block.
+ *
+ * Walks ancestors deepest-first and requires a sibling `blockType`, which is
+ * 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;
+/**
+ * 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 };

package/dist/resolve-path.mjs

@@ -0,0 +1,63 @@
+//#region src/resolve-path.ts
+const ID_SUFFIX = ".id";
+const BLOCK_TYPE_SUFFIX = ".blockType";
+/**
+* The document's own `id` lives at the bare key `"id"`, which has no dot and
+* so is never a candidate. Every other `*.id` is a block row or an array row.
+*/ const isRowIdKey = (key) => key.endsWith(ID_SUFFIX);
+/**
+* Resolves a Payload row `id` to its form path (`layout.0.modules.2`).
+*
+* Ids are unique in practice; if two rows somehow carry the same one, the
+* shallowest path wins so the result stays deterministic rather than
+* depending on key order.
+*/ const resolveBlockPath = (formState, id) => {
+	let best;
+	for (const key of Object.keys(formState)) {
+		if (!isRowIdKey(key) || formState[key]?.value !== id) continue;
+		const path = key.slice(0, -3);
+		if (best === void 0 || path.length < best.length) best = path;
+	}
+	return best;
+};
+/** Joins a block path and a block-relative field name into a form path. */ const resolveFieldPath = (blockPath, field) => `${blockPath}.${field}`;
+/**
+* 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.
+*/ const resolveAddressPath = (formState, address) => {
+	const blockPath = resolveBlockPath(formState, address.id);
+	if (blockPath === void 0 || address.field === void 0) return blockPath;
+	return resolveFieldPath(blockPath, address.field);
+};
+/**
+* The inverse, for the admin-to-preview direction: given any form path, finds
+* the id of the nearest enclosing block.
+*
+* Walks ancestors deepest-first and requires a sibling `blockType`, which is
+* what distinguishes a block row from a plain array row — array rows also
+* carry an `id`, but the preview knows nothing about them.
+*/ const resolveBlockIdForPath = (formState, path) => {
+	const segments = path.split(".");
+	for (let end = segments.length; end > 0; end--) {
+		const prefix = segments.slice(0, end).join(".");
+		if (formState[`${prefix}${BLOCK_TYPE_SUFFIX}`] === void 0) continue;
+		const id = formState[`${prefix}${ID_SUFFIX}`]?.value;
+		if (typeof id === "string" && id.length > 0) return id;
+	}
+};
+/**
+* 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.
+*/ const resolveAddressForPath = (formState, path) => {
+	const id = resolveBlockIdForPath(formState, path);
+	if (id === void 0) return;
+	const blockPath = resolveBlockPath(formState, id);
+	const blockType = formState[`${blockPath ?? path}${BLOCK_TYPE_SUFFIX}`]?.value;
+	return {
+		id,
+		...typeof blockType === "string" ? { blockType } : {},
+		...blockPath === void 0 || blockPath === path ? {} : { field: path.slice(blockPath.length + 1) }
+	};
+};
+//#endregion
+export { resolveAddressForPath, resolveAddressPath, resolveBlockIdForPath, resolveBlockPath, resolveFieldPath };

package/package.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@abinnovision/payloadcms-viewfinder",
+  "version": "1.0.0-beta.1",
+  "description": "Two-way block addressing between a rendered frontend and the Payload CMS admin form.",
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "live-preview",
+    "visual-editing",
+    "blocks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abinnovision/payloadcms-commons.git",
+    "directory": "packages/viewfinder"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "abi group GmbH",
+    "email": "info@abigroup.io",
+    "url": "https://abigroup.io"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.mts",
+      "default": "./dist/client/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.mts",
+      "default": "./dist/config/index.mjs"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.mts",
+      "default": "./dist/admin/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts' --fix",
+    "test-unit": "vitest --run --coverage --config vitest.config.mts",
+    "test-unit:watch": "vitest --config vitest.config.mts",
+    "typecheck": "tsc --noEmit"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json{,5},md,y{,a}ml}": "prettier --write"
+  },
+  "prettier": "@abinnovision/prettier-config",
+  "devDependencies": {
+    "@abinnovision/eslint-config-base": "^3.4.2",
+    "@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",
+    "@types/react": "^19.2.18",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.9.1",
+    "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",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.11",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": ">=3.88.0 <4",
+    "payload": ">=3.88.0 <4",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/ui": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "ghpr": true,
+    "npm": true,
+    "npmAccess": "public"
+  }
+}