@batterai/strapi-plugin-canvas 0.1.0

package/src/server/services/collaboration-service.ts

@@ -0,0 +1,180 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { locale, pageId } from "@batterai/bind-core";
+import type { CanvasPage } from "@batterai/contract";
+import type { CollabPageRecord, PageOp } from "@batterai/collab-protocol";
+import { createCollabHttpHandler, createCollabServer, type CollabTokenClaims } from "@batterai/collab-server";
+import {
+  PageDocConflict,
+  PageDraftVersionConflict,
+  cmsSessionFromToken,
+  createPageDocPageDraftStore,
+  delegatedViewer,
+  type PageDocPort,
+  type PageDocStoredPageDraftRoom,
+  type PageDraftStore,
+  type StoredPageDoc,
+  type Viewer,
+} from "@batterai/host";
+import { canvasPageKey } from "../../constants";
+import { CanvasPageConflict, createPageDocStore, createStrapiPageDocRepository } from "./page-doc-store";
+import { defaultHomePage } from "./site-store";
+
+type Room = PageDocStoredPageDraftRoom<CollabPageRecord, PageOp>;
+type CollaborationConfig = {
+  readonly secret: string;
+  readonly origins?: readonly string[];
+  readonly tokenTtlSeconds?: number;
+};
+
+function encode(value: string | Uint8Array): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+function sign(payload: string, secret: string): string {
+  return encode(createHmac("sha256", secret).update(payload).digest());
+}
+
+function decodeToken(token: string, secret: string): CollabTokenClaims {
+  const [payload, signature, extra] = token.split(".");
+  if (!payload || !signature || extra) throw new Error("Malformed collaboration token");
+  const expected = Buffer.from(sign(payload, secret));
+  const actual = Buffer.from(signature);
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) throw new Error("Invalid collaboration token");
+  return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as CollabTokenClaims;
+}
+
+function toRecord(page: CanvasPage): CollabPageRecord {
+  const { id, root, ...canvasSettings } = page;
+  return { page: { id: pageId(id), path: page.path ?? "", root }, canvasSettings };
+}
+
+function fromRecord(record: CollabPageRecord): CanvasPage {
+  return {
+    id: String(record.page.id),
+    title: record.canvasSettings?.title ?? String(record.page.id),
+    ...(record.canvasSettings?.path !== undefined ? { path: record.canvasSettings.path } : {}),
+    ...(record.canvasSettings?.parentId !== undefined ? { parentId: record.canvasSettings.parentId } : {}),
+    ...(record.canvasSettings?.contentBinding !== undefined ? { contentBinding: record.canvasSettings.contentBinding } : {}),
+    ...(record.canvasSettings?.seo !== undefined ? { seo: record.canvasSettings.seo } : {}),
+    ...(record.canvasSettings?.layout !== undefined ? { layout: record.canvasSettings.layout } : {}),
+    root: record.page.root,
+  };
+}
+
+export function createStrapiCollaborationService(strapi: any) {
+  const config = (strapi.config.get("plugin::canvas")?.collaboration ?? null) as CollaborationConfig | null;
+  if (!config) return null;
+  const roomDocs = createPageDocStore<StoredPageDoc<Room>>(createStrapiPageDocRepository(strapi));
+  const pages = createPageDocStore<CanvasPage>(createStrapiPageDocRepository(strapi));
+  const port: PageDocPort<Room> = {
+    async read(key) {
+      const row = await roomDocs.read(key);
+      return row?.document.page;
+    },
+    async write(key, doc, options) {
+      try {
+        await roomDocs.save(key, doc, options.expectedDocVersion);
+      } catch (error) {
+        if (error instanceof CanvasPageConflict) throw new PageDocConflict(key, options.expectedDocVersion, error.actualDocVersion);
+        throw error;
+      }
+    },
+  };
+  const durable = createPageDocPageDraftStore<CollabPageRecord, PageOp>({
+    port,
+    authorize: (viewer) => viewer.session ? true : "Authenticated CMS editor required",
+    keyPrefix: "canvas-collab-room",
+  });
+  const bridged: PageDraftStore<CollabPageRecord, PageOp> = {
+    ...durable,
+    async flushDraft(room, input) {
+      const key = canvasPageKey(String(room.pageId));
+      const existing = await pages.read(key);
+      if (!existing) throw new PageDraftVersionConflict(input.previousDraftVersion, undefined);
+      const target = fromRecord(input.record);
+      if (JSON.stringify(existing.document.page) !== JSON.stringify(target)) {
+        try {
+          await pages.save(key, target, existing.docVersion);
+        } catch (error) {
+          if (error instanceof CanvasPageConflict) throw new PageDraftVersionConflict(input.previousDraftVersion, undefined);
+          throw error;
+        }
+      }
+      return durable.flushDraft(room, input);
+    },
+  };
+  const server = createCollabServer({
+    store: bridged,
+    verifier: {
+      async verify(token) {
+        const claims = decodeToken(token, config.secret);
+        const now = Math.floor(Date.now() / 1000);
+        if (claims.iss !== "strapi-canvas" || claims.aud !== "battery-collab" || claims.exp <= now || (claims.nbf ?? 0) > now) {
+          throw new Error("Expired or invalid collaboration token");
+        }
+        return { viewer: delegatedViewer(cmsSessionFromToken(token), locale(claims.locale)), claims };
+      },
+      async isRevoked() { return false; },
+    },
+    opAdmission: {
+      canEditBlockField: () => true,
+      canRemoveBlockField: () => true,
+      canInsertNode: () => true,
+    },
+    participantIdentity: ({ claims }) => ({
+      displayName: claims.sub,
+      color: `#${createHmac("sha256", config.secret).update(claims.userId).digest("hex").slice(0, 6)}`,
+    }),
+    now: () => new Date().toISOString(),
+    origins: config.origins ?? [],
+    requireSecureTransport: process.env.NODE_ENV === "production",
+    requireWriteLocks: true,
+  });
+  const handler = createCollabHttpHandler(server, { basePath: "/collab" });
+  const sessionOwners = new Map<string, string>();
+
+  async function ensurePage(canvasPageId: string) {
+    let row = await pages.read(canvasPageKey(canvasPageId));
+    if (!row && canvasPageId === "home") {
+      row = await pages.save(canvasPageKey(canvasPageId), defaultHomePage(), 0);
+    }
+    if (!row) throw new Error(`Canvas page ${canvasPageId} does not exist`);
+    await durable.refreshDraft({ ref: { pageId: pageId(canvasPageId) }, record: toRecord(row.document.page) });
+  }
+
+  return {
+    mintToken(user: { readonly id: string | number; readonly firstname?: string; readonly lastname?: string; readonly username?: string; readonly roles?: readonly { readonly id?: string | number; readonly code?: string; readonly name?: string }[] }) {
+      const now = Math.floor(Date.now() / 1000);
+      const displayName = [user.firstname, user.lastname].filter(Boolean).join(" ") || user.username || `User ${user.id}`;
+      const claims: CollabTokenClaims = {
+        iss: "strapi-canvas",
+        aud: "battery-collab",
+        sub: displayName,
+        jti: randomUUID(),
+        exp: now + (config.tokenTtlSeconds ?? 300),
+        nbf: now - 5,
+        tenant: "strapi",
+        userId: String(user.id),
+        roles: (user.roles ?? []).map((role) => String(role.id ?? role.code ?? role.name ?? "unknown")),
+        locale: "nl",
+      };
+      const payload = encode(JSON.stringify(claims));
+      return { token: `${payload}.${sign(payload, config.secret)}`, expiresAt: new Date(claims.exp * 1000).toISOString() };
+    },
+    ensurePage,
+    async readAudit(canvasPageId: string) {
+      await ensurePage(canvasPageId);
+      return durable.readAuditEvents({ pageId: pageId(canvasPageId) });
+    },
+    assertTokenOwner(token: string, userId: string | number) {
+      if (decodeToken(token, config.secret).userId !== String(userId)) throw new Error("Collaboration token belongs to another CMS user");
+    },
+    assertSessionOwner(sessionId: string, userId: string | number) {
+      if (sessionOwners.get(sessionId) !== String(userId)) throw new Error("Collaboration session belongs to another CMS user");
+    },
+    claimSession(sessionId: string, userId: string | number) {
+      sessionOwners.set(sessionId, String(userId));
+    },
+    handler,
+  };
+}

package/src/server/services/document-command-service.ts

@@ -0,0 +1,495 @@
+import {
+  applyCanvasChangeSet,
+  hostConcurrencyToken,
+  parseCanvasDocument,
+  parseCanvasPage,
+  type CanvasChange,
+  type CanvasChangeSet,
+  type CanvasDocument,
+  type CanvasHostIssue,
+  type CanvasHostResult,
+  type CanvasPage,
+  type HostConcurrencyToken,
+  type HostPageState,
+  type HostPublishReceipt,
+  type HostSaveReceipt,
+  type HostStageReceipt,
+} from "@batterai/contract";
+import { CANVAS_PAGE_PREFIX, canvasPageKey } from "../../constants";
+import {
+  CanvasPageConflict,
+  createPageDocStore,
+  createStrapiPageDocRepository,
+  type CanvasPageRow,
+} from "./page-doc-store";
+import {
+  CanvasSiteConflict,
+  createSiteStore,
+  defaultHomePage,
+  type CanvasSiteDocument,
+} from "./site-store";
+
+const CONCURRENCY_PREFIX = "strapi:canvas:v1:";
+
+type CommandPageStore = {
+  list(): Promise<CanvasPageRow<CanvasPage>[]>;
+  save(pageKey: string, page: CanvasPage, expectedDocVersion: number): Promise<CanvasPageRow<CanvasPage>>;
+  remove(pageKey: string, expectedDocVersion: number): Promise<void>;
+  publish(pageKey: string, expectedDocVersion: number, publishedAt?: Date): Promise<CanvasPageRow<CanvasPage>>;
+  stage(pageKey: string, expectedDocVersion: number): Promise<CanvasPageRow<CanvasPage>>;
+  unstage(pageKey: string, expectedDocVersion: number): Promise<CanvasPageRow<CanvasPage>>;
+  publishStaged(pageKey: string, expectedDocVersion: number, publishedAt?: Date): Promise<CanvasPageRow<CanvasPage>>;
+};
+
+type CommandSiteStore = {
+  readOrCreate(): Promise<CanvasSiteDocument>;
+  updateIfVersion(
+    expectedDocVersion: number,
+    mutator: (document: CanvasSiteDocument) => CanvasSiteDocument,
+  ): Promise<CanvasSiteDocument>;
+};
+
+export type CanvasDocumentCommandTransaction = {
+  readonly pageStore: CommandPageStore;
+  readonly siteStore: CommandSiteStore;
+};
+
+export type CanvasDocumentCommandTransactionRunner = <T>(
+  work: (transaction: CanvasDocumentCommandTransaction) => Promise<T>,
+) => Promise<T>;
+
+export type CanvasDocumentCommandServiceOptions = {
+  readonly now?: () => Date;
+  readonly runTransaction?: CanvasDocumentCommandTransactionRunner;
+};
+
+class CanvasDocumentCommandValidationError extends Error {
+  constructor(readonly issues: readonly CanvasHostIssue[]) {
+    super(issues.map((issue) => issue.message).join(" "));
+    this.name = "CanvasDocumentCommandValidationError";
+  }
+}
+
+export function strapiCanvasConcurrency(revision: number): HostConcurrencyToken {
+  return hostConcurrencyToken(`${CONCURRENCY_PREFIX}${revision}`);
+}
+
+export function createDocumentCommandService(
+  strapi: any,
+  options: CanvasDocumentCommandServiceOptions = {},
+) {
+  const now = options.now ?? (() => new Date());
+  const config = strapi.config.get("plugin::canvas") ?? {};
+
+  async function productionTransaction<T>(
+    work: (transaction: CanvasDocumentCommandTransaction) => Promise<T>,
+  ): Promise<T> {
+    return strapi.db.transaction(async ({ trx }: { readonly trx: (tableName: string) => any }) => work({
+      pageStore: createPageDocStore<CanvasPage>(createStrapiPageDocRepository<CanvasPage>(strapi, trx)),
+      siteStore: createSiteStore(strapi, config.seedLibrary, trx),
+    }));
+  }
+
+  const runTransaction = options.runTransaction ?? productionTransaction;
+
+  return {
+    async saveDocument(request: unknown): Promise<CanvasHostResult<HostSaveReceipt>> {
+      let expectedRevision: number | undefined;
+      try {
+        const body = record(request, "$", "Document command request must be an object.");
+        expectedRevision = parseExpectedRevision(body.expected);
+        const changes = parseChangeSet(body.changes);
+        const receipt = await runTransaction(async ({ pageStore, siteStore }) => {
+          const site = await siteStore.readOrCreate();
+          assertAggregateRevision(site, expectedRevision!);
+          const rows = canvasPageRows(await pageStore.list());
+          const current = validateDocument(draftDocument(site, rows));
+          const next = validateDocument(normalizeDocumentOrder(applyCanvasChangeSet(current, changes)));
+          const operations = pageOperations(rows, current, next);
+          const nextSite = await siteStore.updateIfVersion(expectedRevision!, (stored) => ({
+            ...stored,
+            docVersion: expectedRevision! + 1,
+            pageOrder: next.pages.map((page) => page.id),
+            canvas: {
+              theme: next.theme,
+              assets: next.assets,
+              variables: next.variables,
+              layout: next.layout,
+            },
+          }));
+          for (const operation of operations) {
+            if (operation.kind === "remove") {
+              await pageStore.remove(operation.pageKey, operation.expectedDocVersion);
+            } else {
+              await pageStore.save(operation.pageKey, operation.page, operation.expectedDocVersion);
+            }
+          }
+          const nextRows = canvasPageRows(await pageStore.list());
+          return {
+            concurrency: strapiCanvasConcurrency(nextSite.docVersion),
+            state: { pages: hostPageStates(nextRows, next.pages) },
+          } satisfies HostSaveReceipt;
+        });
+        return { ok: true, value: receipt };
+      } catch (error) {
+        return commandError(error, expectedRevision);
+      }
+    },
+
+    async publishDocument(request: unknown): Promise<CanvasHostResult<HostPublishReceipt>> {
+      let expectedRevision: number | undefined;
+      try {
+        const body = record(request, "$", "Publish command request must be an object.");
+        expectedRevision = parseExpectedRevision(body.expected);
+        const receipt = await runTransaction(async ({ pageStore, siteStore }) => {
+          const site = await siteStore.readOrCreate();
+          assertAggregateRevision(site, expectedRevision!);
+          const initialRows = canvasPageRows(await pageStore.list());
+          const stagedRows = initialRows.filter((row) => Boolean(row.document.staged));
+          if (stagedRows.length === 0) {
+            throw new CanvasDocumentCommandValidationError([
+              { path: "$.pages", message: "Stage at least one page before publishing a release." },
+            ]);
+          }
+          const publishedAt = now();
+          for (const row of [...stagedRows].sort((left, right) => left.pageKey.localeCompare(right.pageKey))) {
+            await pageStore.publishStaged(row.pageKey, row.docVersion, publishedAt);
+          }
+          const nextRows = canvasPageRows(await pageStore.list());
+          const document = validateDocument(publishedDocument(site, nextRows));
+          const nextSite = await siteStore.updateIfVersion(expectedRevision!, (stored) => ({
+            ...stored,
+            docVersion: expectedRevision! + 1,
+            published: {
+              document,
+              content: structuredClone(stored.content),
+              library: structuredClone(stored.library),
+              publishedAt: publishedAt.toISOString(),
+              sourceDocVersion: expectedRevision!,
+            },
+          }));
+          return {
+            concurrency: strapiCanvasConcurrency(nextSite.docVersion),
+            state: {
+              publicationLabel: "Published",
+              pages: hostPageStates(nextRows, draftDocument(nextSite, nextRows).pages),
+            },
+          } satisfies HostPublishReceipt;
+        });
+        return { ok: true, value: receipt };
+      } catch (error) {
+        return commandError(error, expectedRevision);
+      }
+    },
+
+    async stagePage(request: unknown): Promise<CanvasHostResult<HostStageReceipt>> {
+      return changePageStage(request, true);
+    },
+
+    async unstagePage(request: unknown): Promise<CanvasHostResult<HostStageReceipt>> {
+      return changePageStage(request, false);
+    },
+  };
+
+  async function changePageStage(request: unknown, staged: boolean): Promise<CanvasHostResult<HostStageReceipt>> {
+    let expectedRevision: number | undefined;
+    try {
+      const body = record(request, "$", "Page stage command request must be an object.");
+      assertKeys(body, new Set(["expected", "pageId"]), "$");
+      expectedRevision = parseExpectedRevision(body.expected);
+      if (typeof body.pageId !== "string" || !body.pageId) validation("$.pageId", "pageId must be a non-empty string.");
+      const pageId = body.pageId;
+      const receipt = await runTransaction(async ({ pageStore, siteStore }) => {
+        const site = await siteStore.readOrCreate();
+        assertAggregateRevision(site, expectedRevision!);
+        const rows = canvasPageRows(await pageStore.list());
+        let row = pageRowsById(rows).get(pageId);
+        if (!row) {
+          const virtualDraft = draftDocument(site, rows).pages.find((page) => page.id === pageId);
+          if (!virtualDraft) {
+            throw new CanvasDocumentCommandValidationError([{ path: "$.pageId", message: `Page ${pageId} does not exist.` }]);
+          }
+          row = await pageStore.save(canvasPageKey(pageId), virtualDraft, 0);
+        }
+        if (staged && !row.document.page) {
+          throw new CanvasDocumentCommandValidationError([{ path: "$.pageId", message: `Page ${pageId} has no draft revision.` }]);
+        }
+        const nextSite = await siteStore.updateIfVersion(expectedRevision!, (stored) => ({
+          ...stored,
+          docVersion: expectedRevision! + 1,
+        }));
+        if (staged) await pageStore.stage(row.pageKey, row.docVersion);
+        else if (row.document.staged) await pageStore.unstage(row.pageKey, row.docVersion);
+        const nextRows = canvasPageRows(await pageStore.list());
+        const pages = draftDocument(nextSite, nextRows).pages;
+        return {
+          concurrency: strapiCanvasConcurrency(nextSite.docVersion),
+          state: { pages: hostPageStates(nextRows, pages) },
+        } satisfies HostStageReceipt;
+      });
+      return { ok: true, value: receipt };
+    } catch (error) {
+      return commandError(error, expectedRevision);
+    }
+  }
+}
+
+function parseExpectedRevision(value: unknown): number {
+  if (typeof value !== "string" || !value.startsWith(CONCURRENCY_PREFIX)) {
+    throw new CanvasDocumentCommandValidationError([
+      { path: "$.expected", message: "A Strapi Canvas aggregate concurrency token is required." },
+    ]);
+  }
+  const revision = Number(value.slice(CONCURRENCY_PREFIX.length));
+  if (!Number.isInteger(revision) || revision < 0 || value !== `${CONCURRENCY_PREFIX}${revision}`) {
+    throw new CanvasDocumentCommandValidationError([
+      { path: "$.expected", message: "The Strapi Canvas aggregate concurrency token is invalid." },
+    ]);
+  }
+  return revision;
+}
+
+function assertAggregateRevision(site: CanvasSiteDocument, expectedRevision: number): void {
+  if (site.docVersion !== expectedRevision) {
+    throw new CanvasSiteConflict(expectedRevision, site.docVersion);
+  }
+}
+
+function parseChangeSet(value: unknown): CanvasChangeSet {
+  const candidate = record(value, "$.changes", "Canvas changes must be an object.");
+  if (!Array.isArray(candidate.changes) || candidate.changes.length === 0) {
+    throw new CanvasDocumentCommandValidationError([
+      { path: "$.changes.changes", message: "Canvas changes must contain at least one change." },
+    ]);
+  }
+  const changes = candidate.changes.map((change, index) => parseChange(change, `$.changes.changes[${index}]`));
+  return { changes };
+}
+
+function parseChange(value: unknown, path: string): CanvasChange {
+  const change = record(value, path, "Canvas change must be an object.");
+  const kind = change.kind;
+  if (kind === "upsert-page") {
+    assertKeys(change, new Set(["kind", "page"]), path);
+    return { kind, page: change.page as CanvasPage };
+  }
+  if (kind === "remove-page") {
+    assertKeys(change, new Set(["kind", "pageId"]), path);
+    if (typeof change.pageId !== "string" || !change.pageId) validation(path, "pageId must be a non-empty string.");
+    return { kind, pageId: change.pageId as never };
+  }
+  if (kind === "set-theme") {
+    assertKeys(change, new Set(["kind", "theme"]), path);
+    return { kind, theme: change.theme as never };
+  }
+  if (kind === "set-assets") {
+    assertKeys(change, new Set(["kind", "assets"]), path);
+    return { kind, assets: change.assets as never };
+  }
+  if (kind === "set-variable") {
+    assertKeys(change, new Set(["kind", "name", "value"]), path);
+    if (typeof change.name !== "string" || !change.name || !("value" in change)) {
+      validation(path, "set-variable requires a non-empty name and value.");
+    }
+    return { kind, name: change.name, value: change.value as never };
+  }
+  if (kind === "remove-variable") {
+    assertKeys(change, new Set(["kind", "name"]), path);
+    if (typeof change.name !== "string" || !change.name) validation(path, "remove-variable requires a name.");
+    return { kind, name: change.name };
+  }
+  if (kind === "set-layout") {
+    assertKeys(change, new Set(["kind", "layout"]), path);
+    return { kind, layout: change.layout as never };
+  }
+  validation(`${path}.kind`, "Unsupported Canvas change kind.");
+}
+
+function draftDocument(site: CanvasSiteDocument, rows: readonly CanvasPageRow<CanvasPage>[]): CanvasDocument {
+  const byId = pageRowsById(rows);
+  if (byId.size === 0) {
+    const home = defaultHomePage();
+    byId.set(home.id, { pageKey: canvasPageKey(home.id), docVersion: 0, document: { kind: "canvas-editor-page", docVersion: 0, page: home, updatedAt: "" } });
+  }
+  const ordered = site.pageOrder.flatMap((id) => byId.get(id)?.document.page ?? []);
+  const orderedIds = new Set(ordered.map((page) => page.id));
+  const pages = [...ordered, ...[...byId.values()].map((row) => row.document.page).filter((page) => !orderedIds.has(page.id))];
+  return {
+    schemaVersion: 1,
+    pages,
+    ...site.canvas,
+  };
+}
+
+function publishedDocument(site: CanvasSiteDocument, rows: readonly CanvasPageRow<CanvasPage>[]): CanvasDocument {
+  // Start from the last public release so an unrelated release cannot
+  // accidentally unpublish a page whose draft was deleted. Explicit staged
+  // unpublish commands can remove that baseline in a future workflow slice.
+  const previouslyPublished = site.published?.document.pages ?? [];
+  const rowPublications = rows.flatMap((row) => row.document.published?.page ?? []);
+  const byId = new Map(previouslyPublished.map((page) => [page.id, page]));
+  for (const page of rowPublications) byId.set(page.id, page);
+  const requestedOrder = site.pageOrder.filter((id) => byId.has(id));
+  const extras = [...byId.values()].filter((page) => !requestedOrder.includes(page.id));
+  const pages = [...requestedOrder.map((id) => byId.get(id)!), ...extras];
+  return normalizeDocumentOrder({
+    schemaVersion: 1,
+    pages,
+    ...site.canvas,
+    layout: { ...site.canvas.layout, pageOrder: pages.map((page) => page.id) as never },
+  });
+}
+
+function normalizeDocumentOrder(document: CanvasDocument): CanvasDocument {
+  const pagesById = new Map(document.pages.map((page) => [page.id, page]));
+  const requested = document.layout?.pageOrder ?? [];
+  const pageOrder: string[] = [];
+  for (const id of requested) {
+    if (pagesById.has(id) && !pageOrder.includes(id)) pageOrder.push(id);
+  }
+  for (const page of document.pages) {
+    if (!pageOrder.includes(page.id)) pageOrder.push(page.id);
+  }
+  return {
+    ...document,
+    pages: pageOrder.map((id) => pagesById.get(id)!),
+    layout: { ...document.layout, pageOrder: pageOrder as never },
+  };
+}
+
+function validateDocument(document: CanvasDocument): CanvasDocument {
+  const parsed = parseCanvasDocument(document);
+  const issues: CanvasHostIssue[] = parsed.ok ? [] : [...parsed.issues];
+  const paths = new Map<string, string>();
+  for (const page of document.pages) {
+    if (!page.path) continue;
+    const path = normalizePath(page.path);
+    const existing = paths.get(path);
+    if (existing) {
+      issues.push({ path: `$.pages.${page.id}.path`, message: `Route ${path} is already used by page ${existing}.` });
+    } else {
+      paths.set(path, page.id);
+    }
+  }
+  if (issues.length) throw new CanvasDocumentCommandValidationError(issues);
+  return parsed.ok ? parsed.document : document;
+}
+
+function pageOperations(
+  rows: readonly CanvasPageRow<CanvasPage>[],
+  current: CanvasDocument,
+  next: CanvasDocument,
+) {
+  const rowsById = pageRowsById(rows);
+  const currentById = new Map(current.pages.map((page) => [page.id, page]));
+  const nextById = new Map(next.pages.map((page) => [page.id, page]));
+  const operations: Array<
+    | { readonly kind: "remove"; readonly pageKey: string; readonly expectedDocVersion: number }
+    | { readonly kind: "upsert"; readonly pageKey: string; readonly expectedDocVersion: number; readonly page: CanvasPage }
+  > = [];
+  for (const [pageId] of currentById) {
+    if (nextById.has(pageId)) continue;
+    const row = rowsById.get(pageId);
+    if (row) operations.push({ kind: "remove", pageKey: row.pageKey, expectedDocVersion: row.docVersion });
+  }
+  for (const [pageId, page] of nextById) {
+    const existing = currentById.get(pageId);
+    if (existing && JSON.stringify(existing) === JSON.stringify(page)) continue;
+    const row = rowsById.get(pageId);
+    operations.push({
+      kind: "upsert",
+      pageKey: row?.pageKey ?? canvasPageKey(pageId),
+      expectedDocVersion: row?.docVersion ?? 0,
+      page,
+    });
+  }
+  return operations.sort((left, right) => left.pageKey.localeCompare(right.pageKey));
+}
+
+function pageRowsById(rows: readonly CanvasPageRow<CanvasPage>[]) {
+  return new Map(rows.map((row) => [row.document.page.id, row]));
+}
+
+function canvasPageRows(rows: readonly CanvasPageRow<CanvasPage>[]): CanvasPageRow<CanvasPage>[] {
+  return rows
+    .filter((row) => row.pageKey.startsWith(CANVAS_PAGE_PREFIX))
+    .map((row) => {
+      const parsed = parseCanvasPage(row.document?.page);
+      if (!parsed.ok) {
+        throw new CanvasDocumentCommandValidationError(parsed.issues.map((issue) => ({
+          path: `$.storedPages[${JSON.stringify(row.pageKey)}]${issue.path.slice(1)}`,
+          message: `Stored Canvas page ${row.pageKey} is invalid: ${issue.message}`,
+        })));
+      }
+      return {
+        ...row,
+        document: { ...row.document, page: parsed.page },
+      };
+    });
+}
+
+function hostPageStates(
+  rows: readonly CanvasPageRow<CanvasPage>[],
+  pages: readonly CanvasPage[],
+): Record<string, HostPageState> {
+  const rowsById = pageRowsById(rows);
+  return Object.fromEntries(pages.map((page) => {
+    const row = rowsById.get(page.id);
+    const published = row?.document.published;
+    const staged = row?.document.staged;
+    const draftDiffersFromPublished = Boolean(published && JSON.stringify(page) !== JSON.stringify(published.page));
+    const draftDiffersFromStaged = Boolean(staged && JSON.stringify(page) !== JSON.stringify(staged.page));
+    const workflowLabel = staged
+      ? (draftDiffersFromStaged ? "Staged · newer draft changes" : "Staged")
+      : published
+        ? (draftDiffersFromPublished ? "Draft changes" : undefined)
+        : "Not published";
+    return [page.id, {
+      publication: published ? "published" as const : "draft" as const,
+      hasPublishedVersion: Boolean(published),
+      hasStagedVersion: Boolean(staged),
+      draftDiffersFromPublished,
+      draftDiffersFromStaged,
+      ...(workflowLabel ? { workflowLabel } : {}),
+      ...(published?.publishedAt ? { lastSavedLabel: published.publishedAt } : {}),
+    }];
+  }));
+}
+
+function commandError<T>(error: unknown, expectedRevision?: number): CanvasHostResult<T> {
+  if (error instanceof CanvasDocumentCommandValidationError) {
+    return { ok: false, error: { kind: "validation", issues: error.issues } };
+  }
+  if (error instanceof CanvasSiteConflict) {
+    return { ok: false, error: { kind: "conflict", latest: strapiCanvasConcurrency(error.actualDocVersion) } };
+  }
+  if (error instanceof CanvasPageConflict) {
+    return {
+      ok: false,
+      error: {
+        kind: "conflict",
+        ...(expectedRevision === undefined ? {} : { latest: strapiCanvasConcurrency(expectedRevision) }),
+      },
+    };
+  }
+  return { ok: false, error: { kind: "unavailable", retryable: true } };
+}
+
+function record(value: unknown, path: string, message: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) validation(path, message);
+  return value as Record<string, unknown>;
+}
+
+function assertKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, path: string): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.has(key));
+  if (unexpected) validation(`${path}.${unexpected}`, `Unexpected Canvas change field ${unexpected}.`);
+}
+
+function validation(path: string, message: string): never {
+  throw new CanvasDocumentCommandValidationError([{ path, message }]);
+}
+
+function normalizePath(path: string): string {
+  if (path === "/") return path;
+  return `/${path.replace(/^\/+|\/+$/g, "")}`;
+}