@conradsix/c4m-preview 0.0.0-stage → 0.1.0-preview.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Tyler
+
+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

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @conradsix/c4m-preview
 
-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.
+Live preview for [C4M](https://github.com/conradsix/c4m). An editor opens the site's preview tab with a signed token;
+the tab says when it's ready, and the editor sends it the unsaved page or menu over `postMessage`.
+
+```ts
+import { createPreviewProtocol } from "@conradsix/c4m-preview";
+import { signPreviewToken, verifyPreviewToken } from "@conradsix/c4m-preview/server";
+
+const preview = createPreviewProtocol({ block: BlockSchema, menuAction: MenuActionSchema });
+```
+
+- `createPreviewProtocol` builds the message schemas from your block and menu action schemas. Pass `messageTypes` to
+  keep message names you already use.
+- `@conradsix/c4m-preview/server` signs and checks preview tokens with `node:crypto`, so import it only on the server.
+
+ESM only, with `zod` 4 as a peer dependency.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createPreviewProtocol, defaultMessageTypes, PREVIEW_PROTOCOL_VERSION, } from "./protocol.js";
+export type { PreviewMenuItem, PreviewMessageTypes, PreviewProtocol } from "./protocol.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createPreviewProtocol, defaultMessageTypes, PREVIEW_PROTOCOL_VERSION, } from "./protocol.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,68 @@
+import { PageSeoInputSchema } from "@conradsix/c4m-schema";
+import { z } from "zod";
+declare const PREVIEW_PROTOCOL_VERSION: 1;
+type PreviewMessageTypes = {
+    readonly pageReady: string;
+    readonly pageSnapshot: string;
+    readonly menuReady: string;
+    readonly menuSnapshot: string;
+};
+declare const defaultMessageTypes: PreviewMessageTypes;
+type PreviewMenuItem<TAction> = {
+    readonly key: string;
+    readonly title: string;
+    readonly action: TAction;
+    readonly children: readonly PreviewMenuItem<TAction>[];
+};
+type PreviewPageDocumentSchema<TBlock extends z.ZodType> = z.ZodObject<{
+    pageId: z.ZodUUID;
+    pageVersionId: z.ZodUUID;
+    revision: z.ZodNumber;
+    slug: z.ZodString;
+    parentPageId: z.ZodNullable<z.ZodUUID>;
+    seo: typeof PageSeoInputSchema;
+    blocks: z.ZodArray<TBlock>;
+}>;
+type PreviewMenuDocumentSchema<TMenuAction extends z.ZodType> = z.ZodObject<{
+    name: z.ZodString;
+    items: z.ZodArray<z.ZodType<PreviewMenuItem<z.output<TMenuAction>>>>;
+}>;
+type ProtocolVersion = z.ZodLiteral<typeof PREVIEW_PROTOCOL_VERSION>;
+type PreviewProtocol<TBlock extends z.ZodType, TMenuAction extends z.ZodType> = {
+    readonly messageTypes: PreviewMessageTypes;
+    readonly PreviewPageDocumentSchema: PreviewPageDocumentSchema<TBlock>;
+    readonly PreviewReadyMessageSchema: z.ZodObject<{
+        type: z.ZodLiteral<string>;
+        protocolVersion: ProtocolVersion;
+        pageId: z.ZodUUID;
+        pageVersionId: z.ZodUUID;
+        sessionId: z.ZodUUID;
+    }>;
+    readonly PreviewSnapshotMessageSchema: z.ZodObject<{
+        type: z.ZodLiteral<string>;
+        protocolVersion: ProtocolVersion;
+        sessionId: z.ZodUUID;
+        document: PreviewPageDocumentSchema<TBlock>;
+    }>;
+    readonly PreviewMenuItemSchema: z.ZodType<PreviewMenuItem<z.output<TMenuAction>>>;
+    readonly PreviewMenuDocumentSchema: PreviewMenuDocumentSchema<TMenuAction>;
+    readonly MenuPreviewReadyMessageSchema: z.ZodObject<{
+        type: z.ZodLiteral<string>;
+        protocolVersion: ProtocolVersion;
+        sessionId: z.ZodUUID;
+    }>;
+    readonly MenuPreviewSnapshotMessageSchema: z.ZodObject<{
+        type: z.ZodLiteral<string>;
+        protocolVersion: ProtocolVersion;
+        sessionId: z.ZodUUID;
+        document: PreviewMenuDocumentSchema<TMenuAction>;
+    }>;
+};
+declare const createPreviewProtocol: <TBlock extends z.ZodType, TMenuAction extends z.ZodType>(options: {
+    readonly block: TBlock;
+    readonly menuAction: TMenuAction;
+    readonly messageTypes?: Partial<PreviewMessageTypes>;
+}) => PreviewProtocol<TBlock, TMenuAction>;
+export { createPreviewProtocol, defaultMessageTypes, PREVIEW_PROTOCOL_VERSION };
+export type { PreviewMenuItem, PreviewMessageTypes, PreviewProtocol };
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,71 @@
+import { PageSeoInputSchema } from "@conradsix/c4m-schema";
+import { z } from "zod";
+// The editor and the site talk over postMessage: the site's preview tab says it's ready, and the editor sends it the
+// unsaved page or menu. Both sides must agree on this version.
+const PREVIEW_PROTOCOL_VERSION = 1;
+const defaultMessageTypes = {
+    pageReady: "c4m:preview-ready",
+    pageSnapshot: "c4m:preview-snapshot",
+    menuReady: "c4m:menu-preview-ready",
+    menuSnapshot: "c4m:menu-preview-snapshot",
+};
+// The messages for one host's blocks and menu actions.
+const createPreviewProtocol = (options) => {
+    const types = { ...defaultMessageTypes, ...options.messageTypes };
+    const PreviewPageDocumentSchema = z.object({
+        pageId: z.uuid(),
+        pageVersionId: z.uuid(),
+        revision: z.number().int().nonnegative(),
+        slug: z.string(),
+        parentPageId: z.uuid().nullable(),
+        seo: PageSeoInputSchema,
+        blocks: z.array(options.block),
+    });
+    const PreviewReadyMessageSchema = z.object({
+        type: z.literal(types.pageReady),
+        protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+        pageId: z.uuid(),
+        pageVersionId: z.uuid(),
+        sessionId: z.uuid(),
+    });
+    const PreviewSnapshotMessageSchema = z.object({
+        type: z.literal(types.pageSnapshot),
+        protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+        sessionId: z.uuid(),
+        document: PreviewPageDocumentSchema,
+    });
+    // TypeScript can't see through a lazy schema over a generic action, so the item's type is stated.
+    const PreviewMenuItemSchema = z.lazy(() => z.object({
+        key: z.string().min(1),
+        title: z.string().trim().min(1).max(200),
+        action: options.menuAction,
+        children: z.array(PreviewMenuItemSchema),
+    }));
+    const PreviewMenuDocumentSchema = z.object({
+        name: z.string().min(1),
+        items: z.array(PreviewMenuItemSchema).max(20),
+    });
+    const MenuPreviewReadyMessageSchema = z.object({
+        type: z.literal(types.menuReady),
+        protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+        sessionId: z.uuid(),
+    });
+    const MenuPreviewSnapshotMessageSchema = z.object({
+        type: z.literal(types.menuSnapshot),
+        protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+        sessionId: z.uuid(),
+        document: PreviewMenuDocumentSchema,
+    });
+    return {
+        messageTypes: types,
+        PreviewPageDocumentSchema,
+        PreviewReadyMessageSchema,
+        PreviewSnapshotMessageSchema,
+        PreviewMenuItemSchema,
+        PreviewMenuDocumentSchema,
+        MenuPreviewReadyMessageSchema,
+        MenuPreviewSnapshotMessageSchema,
+    };
+};
+export { createPreviewProtocol, defaultMessageTypes, PREVIEW_PROTOCOL_VERSION };
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qHAAqH;AACrH,+DAA+D;AAC/D,MAAM,wBAAwB,GAAG,CAAU,CAAC;AAW5C,MAAM,mBAAmB,GAAwB;IAC/C,SAAS,EAAE,mBAAmB;IAC9B,YAAY,EAAE,sBAAsB;IACpC,SAAS,EAAE,wBAAwB;IACnC,YAAY,EAAE,2BAA2B;CAC1C,CAAC;AAyDF,uDAAuD;AACvD,MAAM,qBAAqB,GAAG,CAA0D,OAIvF,EAAwC,EAAE;IACzC,MAAM,KAAK,GAAG,EAAE,GAAG,mBAAmB,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAElE,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;QACzC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE;QAChB,aAAa,EAAE,CAAC,CAAC,IAAI,EAAE;QACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;QACjC,GAAG,EAAE,kBAAkB;QACvB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;QACzC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC;QAChC,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;QACpD,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE;QAChB,aAAa,EAAE,CAAC,CAAC,IAAI,EAAE;QACvB,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;KACpB,CAAC,CAAC;IAEH,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;QACnC,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;QACpD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;QACnB,QAAQ,EAAE,yBAAyB;KACpC,CAAC,CAAC;IAEH,kGAAkG;IAClG,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxC,CAAC,CAAC,MAAM,CAAC;QACP,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACtB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACxC,MAAM,EAAE,OAAO,CAAC,UAAU;QAC1B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;KACzC,CAAC,CAC6D,CAAC;IAElE,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;QACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC;IAEH,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC;QAChC,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;QACpD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;KACpB,CAAC,CAAC;IAEH,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;QAChD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;QACnC,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;QACpD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;QACnB,QAAQ,EAAE,yBAAyB;KACpC,CAAC,CAAC;IAEH,OAAO;QACL,YAAY,EAAE,KAAK;QACnB,yBAAyB;QACzB,yBAAyB;QACzB,4BAA4B;QAC5B,qBAAqB;QACrB,yBAAyB;QACzB,6BAA6B;QAC7B,gCAAgC;KACjC,CAAC;AACJ,CAAC,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+declare const PagePreviewTokenClaimsSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"page">;
+    pageId: z.ZodUUID;
+    pageVersionId: z.ZodUUID;
+    sessionId: z.ZodUUID;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+declare const MenuPreviewTokenClaimsSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"menu">;
+    sessionId: z.ZodUUID;
+    path: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+declare const PreviewTokenClaimsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"page">;
+    pageId: z.ZodUUID;
+    pageVersionId: z.ZodUUID;
+    sessionId: z.ZodUUID;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"menu">;
+    sessionId: z.ZodUUID;
+    path: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+type PreviewTokenClaims = z.infer<typeof PreviewTokenClaimsSchema>;
+type PagePreviewTokenClaims = z.infer<typeof PagePreviewTokenClaimsSchema>;
+type MenuPreviewTokenClaims = z.infer<typeof MenuPreviewTokenClaimsSchema>;
+declare const signPreviewToken: (claims: PreviewTokenClaims, secret: string) => string;
+declare const verifyPreviewToken: (token: string, secret: string) => PreviewTokenClaims | undefined;
+export { signPreviewToken, verifyPreviewToken };
+export type { MenuPreviewTokenClaims, PagePreviewTokenClaims, PreviewTokenClaims };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,QAAA,MAAM,4BAA4B;;;;;;iBAMhC,CAAC;AAEH,QAAA,MAAM,4BAA4B;;;;;iBAKhC,CAAC;AAEH,QAAA,MAAM,wBAAwB;;;;;;;;;;;2BAG5B,CAAC;AAEH,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AACnE,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAC3E,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAK3E,QAAA,MAAM,gBAAgB,WAAY,kBAAkB,UAAU,MAAM,KAAG,MAItE,CAAC;AAEF,QAAA,MAAM,kBAAkB,UAAW,MAAM,UAAU,MAAM,KAAG,kBAAkB,GAAG,SAmBhF,CAAC;AAEF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;AAChD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/server.js

@@ -0,0 +1,50 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+// Preview tokens: the editor signs one to open the site's preview of an unsaved page or menu, and the site checks it.
+// They use node:crypto, so they belong on the server.
+const PagePreviewTokenClaimsSchema = z.object({
+    kind: z.literal("page"),
+    pageId: z.uuid(),
+    pageVersionId: z.uuid(),
+    sessionId: z.uuid(),
+    expiresAt: z.number().int().positive(),
+});
+const MenuPreviewTokenClaimsSchema = z.object({
+    kind: z.literal("menu"),
+    sessionId: z.uuid(),
+    path: z.string().startsWith("/"),
+    expiresAt: z.number().int().positive(),
+});
+const PreviewTokenClaimsSchema = z.discriminatedUnion("kind", [
+    PagePreviewTokenClaimsSchema,
+    MenuPreviewTokenClaimsSchema,
+]);
+const signatureFor = (payload, secret) => createHmac("sha256", secret).update(payload).digest("base64url");
+const signPreviewToken = (claims, secret) => {
+    const parsed = PreviewTokenClaimsSchema.parse(claims);
+    const payload = Buffer.from(JSON.stringify(parsed), "utf8").toString("base64url");
+    return `${payload}.${signatureFor(payload, secret)}`;
+};
+const verifyPreviewToken = (token, secret) => {
+    const [payload, signature, unexpected] = token.split(".");
+    if (!payload || !signature || unexpected)
+        return undefined;
+    const expected = signatureFor(payload, secret);
+    const actualBytes = Buffer.from(signature, "utf8");
+    const expectedBytes = Buffer.from(expected, "utf8");
+    if (actualBytes.length !== expectedBytes.length || !timingSafeEqual(actualBytes, expectedBytes)) {
+        return undefined;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        const parsed = PreviewTokenClaimsSchema.safeParse(decoded);
+        if (!parsed.success || parsed.data.expiresAt <= Date.now())
+            return undefined;
+        return parsed.data;
+    }
+    catch {
+        return undefined;
+    }
+};
+export { signPreviewToken, verifyPreviewToken };
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@conradsix/c4m-preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-preview.1",
+  "description": "Live preview for C4M: the editor-to-site postMessage protocol and signed preview tokens.",
+  "keywords": [
+    "c4m",
+    "cms",
+    "preview"
+  ],
+  "license": "MIT",
+  "author": "Brian Tyler",
+  "homepage": "https://github.com/conradsix/c4m#readme",
+  "bugs": "https://github.com/conradsix/c4m/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conradsix/c4m.git",
+    "directory": "typescript/packages/c4m-preview"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "check:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@conradsix/c4m-schema": "^0.1.0-preview.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "zod": "4.6.7"
+  }
 }

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  createPreviewProtocol,
+  defaultMessageTypes,
+  PREVIEW_PROTOCOL_VERSION,
+} from "./protocol.js";
+export type { PreviewMenuItem, PreviewMessageTypes, PreviewProtocol } from "./protocol.js";

package/src/protocol.ts

@@ -0,0 +1,153 @@
+import { PageSeoInputSchema } from "@conradsix/c4m-schema";
+import { z } from "zod";
+
+// The editor and the site talk over postMessage: the site's preview tab says it's ready, and the editor sends it the
+// unsaved page or menu. Both sides must agree on this version.
+const PREVIEW_PROTOCOL_VERSION = 1 as const;
+
+// The postMessage type names. A host that already shipped names of its own keeps them, so its editor and site can
+// deploy apart.
+type PreviewMessageTypes = {
+  readonly pageReady: string;
+  readonly pageSnapshot: string;
+  readonly menuReady: string;
+  readonly menuSnapshot: string;
+};
+
+const defaultMessageTypes: PreviewMessageTypes = {
+  pageReady: "c4m:preview-ready",
+  pageSnapshot: "c4m:preview-snapshot",
+  menuReady: "c4m:menu-preview-ready",
+  menuSnapshot: "c4m:menu-preview-snapshot",
+};
+
+type PreviewMenuItem<TAction> = {
+  readonly key: string;
+  readonly title: string;
+  readonly action: TAction;
+  readonly children: readonly PreviewMenuItem<TAction>[];
+};
+
+type PreviewPageDocumentSchema<TBlock extends z.ZodType> = z.ZodObject<{
+  pageId: z.ZodUUID;
+  pageVersionId: z.ZodUUID;
+  revision: z.ZodNumber;
+  slug: z.ZodString;
+  parentPageId: z.ZodNullable<z.ZodUUID>;
+  seo: typeof PageSeoInputSchema;
+  blocks: z.ZodArray<TBlock>;
+}>;
+
+type PreviewMenuDocumentSchema<TMenuAction extends z.ZodType> = z.ZodObject<{
+  name: z.ZodString;
+  items: z.ZodArray<z.ZodType<PreviewMenuItem<z.output<TMenuAction>>>>;
+}>;
+
+type ProtocolVersion = z.ZodLiteral<typeof PREVIEW_PROTOCOL_VERSION>;
+
+type PreviewProtocol<TBlock extends z.ZodType, TMenuAction extends z.ZodType> = {
+  readonly messageTypes: PreviewMessageTypes;
+  readonly PreviewPageDocumentSchema: PreviewPageDocumentSchema<TBlock>;
+  readonly PreviewReadyMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<string>;
+    protocolVersion: ProtocolVersion;
+    pageId: z.ZodUUID;
+    pageVersionId: z.ZodUUID;
+    sessionId: z.ZodUUID;
+  }>;
+  readonly PreviewSnapshotMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<string>;
+    protocolVersion: ProtocolVersion;
+    sessionId: z.ZodUUID;
+    document: PreviewPageDocumentSchema<TBlock>;
+  }>;
+  readonly PreviewMenuItemSchema: z.ZodType<PreviewMenuItem<z.output<TMenuAction>>>;
+  readonly PreviewMenuDocumentSchema: PreviewMenuDocumentSchema<TMenuAction>;
+  readonly MenuPreviewReadyMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<string>;
+    protocolVersion: ProtocolVersion;
+    sessionId: z.ZodUUID;
+  }>;
+  readonly MenuPreviewSnapshotMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<string>;
+    protocolVersion: ProtocolVersion;
+    sessionId: z.ZodUUID;
+    document: PreviewMenuDocumentSchema<TMenuAction>;
+  }>;
+};
+
+// The messages for one host's blocks and menu actions.
+const createPreviewProtocol = <TBlock extends z.ZodType, TMenuAction extends z.ZodType>(options: {
+  readonly block: TBlock;
+  readonly menuAction: TMenuAction;
+  readonly messageTypes?: Partial<PreviewMessageTypes>;
+}): PreviewProtocol<TBlock, TMenuAction> => {
+  const types = { ...defaultMessageTypes, ...options.messageTypes };
+
+  const PreviewPageDocumentSchema = z.object({
+    pageId: z.uuid(),
+    pageVersionId: z.uuid(),
+    revision: z.number().int().nonnegative(),
+    slug: z.string(),
+    parentPageId: z.uuid().nullable(),
+    seo: PageSeoInputSchema,
+    blocks: z.array(options.block),
+  });
+
+  const PreviewReadyMessageSchema = z.object({
+    type: z.literal(types.pageReady),
+    protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+    pageId: z.uuid(),
+    pageVersionId: z.uuid(),
+    sessionId: z.uuid(),
+  });
+
+  const PreviewSnapshotMessageSchema = z.object({
+    type: z.literal(types.pageSnapshot),
+    protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+    sessionId: z.uuid(),
+    document: PreviewPageDocumentSchema,
+  });
+
+  // TypeScript can't see through a lazy schema over a generic action, so the item's type is stated.
+  const PreviewMenuItemSchema = z.lazy(() =>
+    z.object({
+      key: z.string().min(1),
+      title: z.string().trim().min(1).max(200),
+      action: options.menuAction,
+      children: z.array(PreviewMenuItemSchema),
+    }),
+  ) as unknown as z.ZodType<PreviewMenuItem<z.output<TMenuAction>>>;
+
+  const PreviewMenuDocumentSchema = z.object({
+    name: z.string().min(1),
+    items: z.array(PreviewMenuItemSchema).max(20),
+  });
+
+  const MenuPreviewReadyMessageSchema = z.object({
+    type: z.literal(types.menuReady),
+    protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+    sessionId: z.uuid(),
+  });
+
+  const MenuPreviewSnapshotMessageSchema = z.object({
+    type: z.literal(types.menuSnapshot),
+    protocolVersion: z.literal(PREVIEW_PROTOCOL_VERSION),
+    sessionId: z.uuid(),
+    document: PreviewMenuDocumentSchema,
+  });
+
+  return {
+    messageTypes: types,
+    PreviewPageDocumentSchema,
+    PreviewReadyMessageSchema,
+    PreviewSnapshotMessageSchema,
+    PreviewMenuItemSchema,
+    PreviewMenuDocumentSchema,
+    MenuPreviewReadyMessageSchema,
+    MenuPreviewSnapshotMessageSchema,
+  };
+};
+
+export { createPreviewProtocol, defaultMessageTypes, PREVIEW_PROTOCOL_VERSION };
+export type { PreviewMenuItem, PreviewMessageTypes, PreviewProtocol };

package/src/server.ts

@@ -0,0 +1,62 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { z } from "zod";
+
+// Preview tokens: the editor signs one to open the site's preview of an unsaved page or menu, and the site checks it.
+// They use node:crypto, so they belong on the server.
+const PagePreviewTokenClaimsSchema = z.object({
+  kind: z.literal("page"),
+  pageId: z.uuid(),
+  pageVersionId: z.uuid(),
+  sessionId: z.uuid(),
+  expiresAt: z.number().int().positive(),
+});
+
+const MenuPreviewTokenClaimsSchema = z.object({
+  kind: z.literal("menu"),
+  sessionId: z.uuid(),
+  path: z.string().startsWith("/"),
+  expiresAt: z.number().int().positive(),
+});
+
+const PreviewTokenClaimsSchema = z.discriminatedUnion("kind", [
+  PagePreviewTokenClaimsSchema,
+  MenuPreviewTokenClaimsSchema,
+]);
+
+type PreviewTokenClaims = z.infer<typeof PreviewTokenClaimsSchema>;
+type PagePreviewTokenClaims = z.infer<typeof PagePreviewTokenClaimsSchema>;
+type MenuPreviewTokenClaims = z.infer<typeof MenuPreviewTokenClaimsSchema>;
+
+const signatureFor = (payload: string, secret: string): string =>
+  createHmac("sha256", secret).update(payload).digest("base64url");
+
+const signPreviewToken = (claims: PreviewTokenClaims, secret: string): string => {
+  const parsed = PreviewTokenClaimsSchema.parse(claims);
+  const payload = Buffer.from(JSON.stringify(parsed), "utf8").toString("base64url");
+  return `${payload}.${signatureFor(payload, secret)}`;
+};
+
+const verifyPreviewToken = (token: string, secret: string): PreviewTokenClaims | undefined => {
+  const [payload, signature, unexpected] = token.split(".");
+  if (!payload || !signature || unexpected) return undefined;
+
+  const expected = signatureFor(payload, secret);
+  const actualBytes = Buffer.from(signature, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  if (actualBytes.length !== expectedBytes.length || !timingSafeEqual(actualBytes, expectedBytes)) {
+    return undefined;
+  }
+
+  try {
+    const decoded: unknown = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    const parsed = PreviewTokenClaimsSchema.safeParse(decoded);
+    if (!parsed.success || parsed.data.expiresAt <= Date.now()) return undefined;
+    return parsed.data;
+  } catch {
+    return undefined;
+  }
+};
+
+export { signPreviewToken, verifyPreviewToken };
+export type { MenuPreviewTokenClaims, PagePreviewTokenClaims, PreviewTokenClaims };