@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/src/server/pages-core.ts

@@ -11,6 +11,13 @@ import type { BlockInstance } from "../blocks/types";
 import { diffBlocks, summarizeChanges } from "../cms/version-diff";
 import type { VersionChange } from "../cms/version-diff";
 import { EDIT_LOCK_TYPES } from "../cms/edit-lock";
+import {
+  DEFAULT_PAGE_STATUS,
+  normalizePageStatus,
+  uniquePageKey,
+  type PageStatus,
+} from "../cms/page-status";
+import { duplicateBlockTree, flattenBlockTree } from "../blocks/block-tree";
 import { assertEditable } from "./edit-locks-core";
 import { actorEmail, assertStaff, assertSuperadmin } from "./guards";
 import type { PlatformAuthContext } from "./guards";
@@ -19,6 +26,16 @@ import {
   withPublishedCache,
 } from "./published-cache";
 import { resolveCountdownTarget } from "../blocks/countdown-time";
+import {
+  nextPublicationBoundary,
+  nextPublicationTransition,
+  publicationStateAt,
+  publicVersionId,
+  toPublicationWindows,
+  type PublicationState,
+  type PublicationTransitionKind,
+  type PublicationWindow,
+} from "../cms/page-publication";
 import { resolveGlobalsDeep } from "./resolve-globals";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -39,6 +56,12 @@ export type ResolvedPage = {
   blocks: BlockInstance[];
   versionId: string | null;
   globals: Record<string, BlockInstance[]>;
+  /**
+   * The next instant this page's public answer can change — the start of a
+   * scheduled version, or the end of the window showing this one. Null when
+   * nothing is scheduled. Caches downstream use it as their ceiling.
+   */
+  revalidateAt: string | null;
 };
 
 const blocksOf = (value: unknown): BlockInstance[] =>
@@ -53,43 +76,218 @@ export async function getPublishedPageCore(
   client: any,
   key: string,
 ): Promise<ResolvedPage | null> {
-  // Cached per key and dropped by every page/global write below, so a preview
-  // reload costs one database round trip instead of several.
-  return withPublishedCache("page", key, () => readPublishedPage(client, key));
+  /*
+   * Cached per key, dropped by every page/global write below, and — through the
+   * boundary the read hands back — never held across the moment a publication
+   * window opens or closes. A cache that outlived a `publish_at` would answer
+   * "not found" for up to twenty seconds after a page went live, which is the
+   * same bug as publishing late.
+   */
+  const read = await withPublishedCache(
+    "page",
+    key,
+    () => readPublishedPage(client, key),
+    (result) => result.revalidateAt,
+  );
+  return read.page;
+}
+
+/** A public answer plus the instant it stops being true. */
+type PublicPageRead = { page: ResolvedPage | null; revalidateAt: number | null };
+
+/** The `page_publications` rows that can affect this page's public answer. */
+async function activePublications(
+  client: any,
+  pageId: string,
+): Promise<PublicationWindow[]> {
+  const { data, error } = await client
+    .from("page_publications")
+    .select("version_id, publish_at, unpublish_at, published_at")
+    .eq("page_id", pageId)
+    .eq("is_active", true)
+    .order("publish_at", { ascending: false });
+  // A database we could not ask is not the same answer as "this page is not
+  // public": one is a 500 the host retries, the other a 404 a CDN may keep.
+  if (error) throw new Error(error.message);
+  return toPublicationWindows(data);
+}
+
+/** The public shape of a page's state, shared by the list and the builder. */
+export type PublicationSummaryFields = {
+  /** What a visitor gets right now. */
+  publication: PublicationState;
+  /** When that changes next, ISO-8601, or null when nothing is due. */
+  publication_at: string | null;
+  /** What happens then — a publish, a replacement, or a hide. */
+  publication_transition: PublicationTransitionKind | null;
+  /** The version showing afterwards, for a publish or a replacement. */
+  publication_next_version_id: string | null;
+};
+
+/** The same four fields, from rows that have already been read. */
+function summarize(
+  windows: readonly PublicationWindow[],
+  now: number,
+): PublicationSummaryFields {
+  const next = nextPublicationTransition(windows, now);
+  return {
+    publication: publicationStateAt(windows, now),
+    publication_at: next === null ? null : new Date(next.at).toISOString(),
+    publication_transition: next?.kind ?? null,
+    publication_next_version_id: next?.versionId ?? null,
+  };
 }
 
-async function readPublishedPage(client: any, key: string): Promise<ResolvedPage | null> {
-  const { data: page } = await client
+/**
+ * What a visitor gets for one page, and what changes next.
+ *
+ * The list screen and the builder header both need this, and neither may
+ * compute it from `pages.status`: that column records the last editorial
+ * decision, not whether the page is reachable.
+ */
+async function publicationOf(
+  client: any,
+  pageId: string,
+  now: number = Date.now(),
+): Promise<PublicationSummaryFields> {
+  return summarize(await activePublications(client, pageId), now);
+}
+
+/*
+ * Publication rows alone decide what a visitor sees. `pages.status` is not
+ * read here: it says whether an editor considers the page finished, and a
+ * finished page is not thereby public — a version scheduled for next week, a
+ * countdown target waiting for its deadline and a page whose window has closed
+ * are all finished and all hidden. The rules themselves live in
+ * `cms/page-publication` so that this route and the sitemap below cannot come
+ * to different conclusions about the same page.
+ */
+async function readPublishedPage(client: any, key: string): Promise<PublicPageRead> {
+  const { data: page, error: pageError } = await client
     .from("pages")
-    .select("id,key,name,current_version_id")
+    .select("id,key,name")
     .eq("key", key)
     .is("deleted_at", null)
     .maybeSingle();
-  if (!page) return null;
+  /*
+   * Every read on this path is checked, because the only other answer a public
+   * route has is "no such page" — and that answer is a 404 the host and its CDN
+   * are entitled to keep. Ignoring the error would turn one bad minute in the
+   * database into an hour of pages that do not exist.
+   */
+  if (pageError) throw new Error(pageError.message);
+  if (!page) return { page: null, revalidateAt: null };
 
-  // Time-based publication: newest active row whose window is open right now.
-  const nowIso = new Date().toISOString();
-  const { data: pub } = await client
-    .from("page_publications")
-    .select("version_id, publish_at")
-    .eq("page_id", page.id)
-    .eq("is_active", true)
-    .lte("publish_at", nowIso)
-    .or(`unpublish_at.is.null,unpublish_at.gt.${nowIso}`)
-    .order("publish_at", { ascending: false })
-    .limit(1)
-    .maybeSingle();
+  const windows = await activePublications(client, page.id);
+  const now = Date.now();
+  const revalidateAt = nextPublicationBoundary(windows, now);
+  const versionId = publicVersionId(windows, now);
+  if (!versionId) return { page: null, revalidateAt };
 
-  const versionId = pub?.version_id ?? page.current_version_id;
-  if (!versionId) return null;
-  const { data: version } = await client
+  const { data: version, error: versionError } = await client
     .from("page_versions")
     .select("id, blocks")
     .eq("id", versionId)
     .maybeSingle();
-  const blocks = blocksOf(version?.blocks);
+  if (versionError) throw new Error(versionError.message);
+  /*
+   * An open publication naming a version that is not there is a broken
+   * database, not a page with nothing on it. Serving 200 and no blocks would
+   * quietly replace the page a visitor asked for with a blank one — and cache
+   * it — so say what is actually wrong and let the host answer 500.
+   */
+  if (!version) {
+    throw new Error(
+      `The page "${key}" is published as version ${versionId}, but that version ` +
+        `is missing from the database.`,
+    );
+  }
+  const blocks = blocksOf(version.blocks);
   const globals = await resolveGlobalsDeep(client, blocks);
-  return { key: page.key, name: page.name, blocks, versionId: version?.id ?? null, globals };
+  return {
+    page: {
+      key: page.key,
+      name: page.name,
+      blocks,
+      versionId: version.id ?? null,
+      globals,
+      revalidateAt: revalidateAt === null ? null : new Date(revalidateAt).toISOString(),
+    },
+    revalidateAt,
+  };
+}
+
+/** Public page keys, and the instant that list stops being true. */
+export type PublishedRoutes = {
+  /** Page keys a visitor may reach right now, in key order. */
+  keys: string[];
+  /**
+   * The earliest publication boundary across every page — the next moment a
+   * key joins or leaves the list — or null when nothing is scheduled. The
+   * sitemap uses it as the ceiling on how long its answer may be cached.
+   */
+  revalidateAt: number | null;
+};
+
+/**
+ * Page keys a visitor may reach right now.
+ *
+ * Sitemap generation and any other public route discovery call this instead of
+ * listing `pages` directly, and it applies the very same window rules as
+ * {@link getPublishedPageCore} — the same function on the same columns — so a
+ * key can never be advertised in `sitemap.xml` by a route that would 404, or
+ * withheld from it by a route that would serve it.
+ */
+export async function listPublishedRoutesCore(client: any): Promise<PublishedRoutes> {
+  const { data: pubs, error } = await client
+    .from("page_publications")
+    .select("page_id, version_id, publish_at, unpublish_at, published_at")
+    .eq("is_active", true)
+    .order("publish_at", { ascending: false });
+  if (error) throw new Error(error.message);
+
+  const now = Date.now();
+  const byPage = new Map<string, PublicationWindow[]>();
+  for (const row of (pubs ?? []) as Array<Record<string, string | null>>) {
+    const pageId = row.page_id;
+    if (!pageId) continue;
+    byPage.set(pageId, [...(byPage.get(pageId) ?? []), ...toPublicationWindows([row])]);
+  }
+
+  const live = new Set<string>();
+  let revalidateAt: number | null = null;
+  for (const [pageId, windows] of byPage) {
+    if (publicVersionId(windows, now) !== null) live.add(pageId);
+    /*
+     * Boundaries are collected for every page, live or not: a page that
+     * appears in ten minutes changes this list exactly as much as one that
+     * disappears in ten minutes, and the sitemap has to stop being cached
+     * before either happens.
+     */
+    const boundary = nextPublicationBoundary(windows, now);
+    if (boundary !== null && (revalidateAt === null || boundary < revalidateAt)) {
+      revalidateAt = boundary;
+    }
+  }
+  if (live.size === 0) return { keys: [], revalidateAt };
+
+  // Deleted pages keep their publication rows until the trash is emptied, so
+  // the page table still has the last word on whether a key exists at all.
+  const { data: pages, error: pageError } = await client
+    .from("pages")
+    .select("id,key")
+    .is("deleted_at", null)
+    .order("key");
+  if (pageError) throw new Error(pageError.message);
+  const keys = ((pages ?? []) as Array<{ id: string; key: string }>)
+    .filter((row) => live.has(row.id))
+    .map((row) => row.key);
+  return { keys, revalidateAt };
+}
+
+/** {@link listPublishedRoutesCore} for callers that only want the keys. */
+export async function listPublishedPageKeysCore(client: any): Promise<string[]> {
+  return (await listPublishedRoutesCore(client)).keys;
 }
 
 export type PageListRow = {
@@ -97,10 +295,14 @@ export type PageListRow = {
   key: string;
   name: string;
   is_system: boolean;
+  /**
+   * Editorial state — whether an editor considers the page finished. It is not
+   * public visibility; `publication` is.
+   */
   status: string;
   updated_at: string;
   current_version_id: string | null;
-};
+} & PublicationSummaryFields;
 
 export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow[]> {
   await assertStaff(context);
@@ -111,7 +313,34 @@ export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow
     .order("is_system", { ascending: false })
     .order("name");
   if (error) throw new Error(error.message);
-  return (data ?? []) as PageListRow[];
+  const rows = (data ?? []) as Array<Omit<PageListRow, keyof PublicationSummaryFields>>;
+  if (rows.length === 0) return [];
+
+  /*
+   * `pages.status` cannot answer "can a visitor reach this page?", and that is
+   * the question a list of pages is really being asked. A draft whose
+   * scheduled window has opened is on the internet; a published page past its
+   * `unpublish_at` is not. One extra query for the listed pages' active
+   * windows, run through the same rule the public reader uses, so the
+   * backoffice and the website cannot disagree about what is live.
+   */
+  const { data: pubs, error: pubError } = await context.supabase
+    .from("page_publications")
+    .select("page_id, version_id, publish_at, unpublish_at, published_at")
+    .eq("is_active", true)
+    .in("page_id", rows.map((row) => row.id))
+    .order("publish_at", { ascending: false });
+  if (pubError) throw new Error(pubError.message);
+
+  const byPage = new Map<string, PublicationWindow[]>();
+  for (const row of (pubs ?? []) as Array<Record<string, string | null>>) {
+    const pageId = row.page_id;
+    if (!pageId) continue;
+    byPage.set(pageId, [...(byPage.get(pageId) ?? []), ...toPublicationWindows([row])]);
+  }
+
+  const now = Date.now();
+  return rows.map((row) => ({ ...row, ...summarize(byPage.get(row.id) ?? [], now) }));
 }
 
 export async function getPageForEditCore({ context }: PagesDeps, key: string) {
@@ -126,14 +355,75 @@ export async function getPageForEditCore({ context }: PagesDeps, key: string) {
   if (!page) throw new Error("Page not found");
   let blocks: BlockInstance[] = [];
   if (page.current_version_id) {
-    const { data: v } = await context.supabase
+    const { data: v, error: versionError } = await context.supabase
       .from("page_versions")
       .select("blocks")
       .eq("id", page.current_version_id)
       .maybeSingle();
+    // Opening the builder on an empty canvas because a read failed invites the
+    // editor to save that emptiness over the real content.
+    if (versionError) throw new Error(versionError.message);
     blocks = blocksOf(v?.blocks);
   }
-  return { page, blocks };
+  /*
+   * The header says whether visitors can reach this page, which is a different
+   * question from the status column beside it and is answered by the same rule
+   * the public routes use.
+   */
+  const publication = await publicationOf(context.supabase, page.id);
+  return { page: { ...page, ...publication }, blocks };
+}
+
+/**
+ * Codes and wording that mean "this installation has not run the publication
+ * migration yet". `PGRST202`/`PGRST203` come from PostgREST, `42883`/`42P01`
+ * from PostgreSQL itself.
+ */
+const FUNCTION_MISSING = new Set(["PGRST202", "PGRST203", "42883", "42P01"]);
+
+/** The migrations that install the functions below, named in the error. */
+const PUBLICATION_MIGRATIONS = [
+  "20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql",
+  "20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql",
+] as const;
+
+/**
+ * One database-function call, for the writes that change what the public sees.
+ *
+ * Publishing is four statements — retire the old publication, write the new
+ * one, move the current-version pointer, flip the status — and a PostgREST
+ * client cannot wrap them in a transaction. Checking each response, which this
+ * code used to do, reports the failure honestly but leaves the site half
+ * published either way: an open publication with the status never flipped, or a
+ * retired publication behind a status that still says published. Only the
+ * database can make the whole change or none of it, so the whole change is
+ * written there and called through here.
+ *
+ * There is deliberately no JavaScript fallback. Compensating for a failed step
+ * with further un-transacted steps is precisely the thing that does not work,
+ * so an installation that has not run the migration is told which one to run
+ * rather than quietly served by the code path this replaces.
+ */
+async function publicationRpc(
+  client: any,
+  fn: string,
+  args: Record<string, unknown>,
+  whenFailed: string,
+): Promise<any> {
+  const { data, error } = await client.rpc(fn, args);
+  if (!error) return data;
+  const code = String(error.code ?? "");
+  const message = String(error.message ?? "");
+  if (
+    FUNCTION_MISSING.has(code) ||
+    /could not find the function|does not exist/i.test(message)
+  ) {
+    throw new Error(
+      `${whenFailed}: this database does not have ${fn}. Apply the migrations ` +
+        `${PUBLICATION_MIGRATIONS.join(" and ")} shipped with this package and try again.`,
+    );
+  }
+  throw new Error(message || whenFailed);
 }
 
 export async function savePageVersionCore(
@@ -153,114 +443,94 @@ export async function savePageVersionCore(
     resourceId: input.pageId,
     sessionId: input.editSessionId,
   });
+  // Before, so a read racing this write cannot serve replaced content, and
+  // again after, so one that raced it does not leave the old answer behind.
   invalidatePublishedCache();
-  const { data: last } = await context.supabase
-    .from("page_versions")
-    .select("version_no")
-    .eq("page_id", input.pageId)
-    .order("version_no", { ascending: false })
-    .limit(1)
-    .maybeSingle();
-  const nextNo = (last?.version_no ?? 0) + 1;
-  const { data: inserted, error } = await context.supabase
-    .from("page_versions")
-    .insert({
-      page_id: input.pageId,
-      version_no: nextNo,
-      blocks: input.blocks as unknown as any,
-      note: input.note ?? null,
-      created_by: context.userId,
-      created_by_email: actorEmail(context),
-    })
-    .select("id")
-    .single();
-  if (error) throw new Error(error.message);
+  /*
+   * Worked out before anything is written, and handed to the database with the
+   * publish itself.
+   *
+   * Scheduling the reveals afterwards, as their own calls, meant a target that
+   * could not be scheduled was reported as a failed publish although the
+   * source page was already live and irrevocably so — and left whichever
+   * reveals came before it scheduled. Passed in here, the page and every
+   * reveal it promises are one transaction: all of them happen or none does,
+   * and a failure is a failure the editor can act on.
+   */
+  const reveals = input.publish ? countdownReveals(input.blocks) : [];
 
-  await context.supabase
-    .from("pages")
-    .update({ current_version_id: inserted.id })
-    .eq("id", input.pageId);
+  const saved = await publicationRpc(
+    context.supabase,
+    "cms_save_page_version",
+    {
+      _page_id: input.pageId,
+      _blocks: input.blocks as unknown,
+      _note: input.note ?? null,
+      _publish: Boolean(input.publish),
+      _actor_email: actorEmail(context),
+      _reveals: reveals,
+      // Named so a countdown pointing at the page being published is refused
+      // rather than hiding it until its own deadline.
+      _source_page_id: input.pageId,
+      _audit: input.publish
+        ? {
+            description:
+              "Published a new version from the page builder — this page is now " +
+              "visible on the public website.",
+          }
+        : {},
+    },
+    input.publish ? "Could not publish the page" : "Could not save the version",
+  );
+  invalidatePublishedCache();
 
-  if (input.publish) {
-    await context.supabase
-      .from("page_publications")
-      .update({ is_active: false })
-      .eq("page_id", input.pageId)
-      .eq("is_active", true);
-    await context.supabase.from("page_publications").insert({
-      page_id: input.pageId,
-      version_id: inserted.id,
-      is_active: true,
-      published_by: context.userId,
-    });
-    await context.supabase.from("pages").update({ status: "published" }).eq("id", input.pageId);
-    await scheduleCountdownReveals(context, input.blocks);
-  }
-  return { versionId: inserted.id as string, versionNo: nextNo };
+  const versionId = typeof saved?.versionId === "string" ? saved.versionId : "";
+  const versionNo = Number(saved?.versionNo ?? 0);
+  if (!versionId) throw new Error("The database saved no version for this page.");
+
+  return { versionId, versionNo };
 }
 
+/** One page a countdown on the saved page reveals when its timer reaches zero. */
+export type RevealInstruction = {
+  key: string;
+  /** ISO instant the target page becomes public. */
+  publishAt: string;
+  /** What the audit log should say about it. */
+  description: string;
+};
+
 /**
+ * The reveals a page's blocks ask for, read off the blocks and nothing else.
+ *
  * A countdown set to "reveal a hidden page" schedules that page to publish at
  * the deadline, reusing the normal time-based publication window. Nothing is
- * ever unpublished or deleted here.
+ * ever unpublished or deleted by one, and the target's status is left alone: it
+ * becomes public when its window opens, not when somebody schedules it, which
+ * is the whole point of a reveal.
  */
-async function scheduleCountdownReveals(
-  context: PagesDeps["context"],
-  blocks: BlockInstance[],
-) {
-  const reveals = blocks
+export function countdownReveals(blocks: BlockInstance[]): RevealInstruction[] {
+  // Flattened: a countdown inside a layout column reveals its page too.
+  const countdowns = flattenBlockTree(blocks)
     .filter((b) => b.type === "countdown")
     .map((b) => b.props as { onExpire?: string; revealPageKey?: string; targetLocal?: string; timezone?: string } | undefined)
     .filter((p): p is { onExpire: string; revealPageKey: string; targetLocal: string; timezone?: string } =>
       Boolean(p && p.onExpire === "revealPage" && p.revealPageKey?.trim() && p.targetLocal?.trim()),
     );
 
-  for (const reveal of reveals) {
-    const at = resolveCountdownTarget(reveal.targetLocal, reveal.timezone);
+  const reveals: RevealInstruction[] = [];
+  for (const countdown of countdowns) {
+    const at = resolveCountdownTarget(countdown.targetLocal, countdown.timezone);
     if (at == null) continue;
+    const key = countdown.revealPageKey.trim();
     const publishAt = new Date(at).toISOString();
-    const { data: target } = await context.supabase
-      .from("pages")
-      .select("id, current_version_id")
-      .eq("key", reveal.revealPageKey.trim())
-      .is("deleted_at", null)
-      .maybeSingle();
-    if (!target?.current_version_id) continue;
-
-    const { data: existing } = await context.supabase
-      .from("page_publications")
-      .select("id")
-      .eq("page_id", target.id)
-      .eq("version_id", target.current_version_id)
-      .eq("publish_at", publishAt)
-      .eq("is_active", true)
-      .maybeSingle();
-    if (existing) continue;
-
-    await context.supabase
-      .from("page_publications")
-      .update({ is_active: false })
-      .eq("page_id", target.id)
-      .eq("is_active", true);
-    await context.supabase.from("page_publications").insert({
-      page_id: target.id,
-      version_id: target.current_version_id,
-      is_active: true,
-      publish_at: publishAt,
-      published_by: context.userId,
-    });
-    await context.supabase.from("pages").update({ status: "published" }).eq("id", target.id);
-    await context.supabase.from("audit_logs").insert({
-      actor_id: context.userId,
-      action: "page.schedule",
-      entity: "pages",
-      entity_id: target.id,
-      meta: {
-        description: `Scheduled the page "${reveal.revealPageKey.trim()}" to go live at ${publishAt} because a countdown block reveals it when the timer reaches zero.`,
-        publish_at: publishAt,
-      },
+    reveals.push({
+      key,
+      publishAt,
+      description: `Scheduled the page "${key}" to go live at ${publishAt} because a countdown block reveals it when the timer reaches zero.`,
     });
   }
+  return reveals;
 }
 
 export async function listPageVersionsCore(deps: PagesDeps, pageId: string) {
@@ -340,10 +610,11 @@ export async function restorePageVersionCore(
 export async function createPageCore({ context }: PagesDeps, input: { key: string; name: string }) {
   await assertStaff(context);
   invalidatePublishedCache();
-  invalidatePublishedCache();
+  // A new page is a draft: it exists in the builder and 404s in public until
+  // somebody publishes it deliberately.
   const { data: page, error } = await context.supabase
     .from("pages")
-    .insert({ key: input.key, name: input.name, is_system: false, status: "draft" })
+    .insert({ key: input.key, name: input.name, is_system: false, status: DEFAULT_PAGE_STATUS })
     .select("id")
     .single();
   if (error) throw new Error(error.message);
@@ -358,6 +629,150 @@ export async function createPageCore({ context }: PagesDeps, input: { key: strin
   return { id: page.id as string };
 }
 
+/**
+ * Publish or unpublish a page from the Pages list, without saving a version.
+ *
+ * Publishing opens a publication window on the current version, which is the
+ * same mechanism `savePageVersionCore({ publish: true })` uses, so there is one
+ * notion of "live". Unpublishing sets the status back to draft *and* closes
+ * every open window, so a page cannot stay live through a stale publication row
+ * or a schedule somebody forgot about.
+ */
+export async function setPageStatusCore(
+  { context }: PagesDeps,
+  input: { pageId: string; status: PageStatus; editSessionId?: string },
+) {
+  await assertStaff(context);
+  await assertEditable(context, {
+    resourceType: EDIT_LOCK_TYPES.page,
+    resourceId: input.pageId,
+    sessionId: input.editSessionId,
+  });
+  const status = normalizePageStatus(input.status);
+  const { data: page, error: readErr } = await context.supabase
+    .from("pages")
+    .select("id,key,name,status,current_version_id")
+    .eq("id", input.pageId)
+    .is("deleted_at", null)
+    .maybeSingle();
+  if (readErr) throw new Error(readErr.message);
+  if (!page) throw new Error("Page not found");
+  if (status === "published" && !page.current_version_id) {
+    throw new Error("This page has no saved content yet, so there is nothing to publish.");
+  }
+
+  invalidatePublishedCache();
+
+  /*
+   * Retiring the old publication is the same act either way: publishing
+   * replaces the live version, unpublishing simply leaves nothing behind it.
+   * Both, plus the status column and the audit row, are one transaction in the
+   * database — including the audit row, because a publication nobody can
+   * account for afterwards is its own kind of half-applied write.
+   */
+  await publicationRpc(
+    context.supabase,
+    "cms_set_page_status",
+    {
+      _page_id: input.pageId,
+      _status: status,
+      _actor_email: actorEmail(context),
+      _audit: {
+        description:
+          status === "published"
+            ? `Published the page "${page.name}" — it is now visible on the public website.`
+            : `Unpublished the page "${page.name}" — it is no longer visible on the public website.`,
+      },
+    },
+    status === "published" ? "Could not publish the page" : "Could not unpublish the page",
+  );
+  invalidatePublishedCache();
+  return { ok: true as const, status };
+}
+
+/**
+ * Copy a page, content and all, into a new draft.
+ *
+ * The copy gets its own row, its own key, its own first version and its own
+ * block ids; the source page is never written to. SEO rows are deliberately not
+ * copied — canonical URLs, slugs and meta titles are per-page facts, and
+ * duplicating them would publish two pages claiming the same canonical address.
+ * The copy starts as a draft whatever the source's status is.
+ */
+export async function duplicatePageCore(
+  { context }: PagesDeps,
+  input: { pageId: string; name: string; key?: string },
+) {
+  await assertStaff(context);
+  const name = input.name.trim();
+  if (!name) throw new Error("A name is required for the copy.");
+
+  const { data: source, error: srcErr } = await context.supabase
+    .from("pages")
+    .select("id,key,name,current_version_id")
+    .eq("id", input.pageId)
+    .is("deleted_at", null)
+    .maybeSingle();
+  if (srcErr) throw new Error(srcErr.message);
+  if (!source) throw new Error("Page not found");
+
+  // Existing keys, including trashed ones: a restored page must not collide.
+  const { data: existing, error: keysErr } = await context.supabase.from("pages").select("key");
+  if (keysErr) throw new Error(keysErr.message);
+  const taken = ((existing ?? []) as Array<{ key: string }>).map((row) => row.key);
+  const key = uniquePageKey(input.key?.trim() || name, taken);
+
+  let blocks: BlockInstance[] = [];
+  if (source.current_version_id) {
+    const { data: version } = await context.supabase
+      .from("page_versions")
+      .select("blocks")
+      .eq("id", source.current_version_id)
+      .maybeSingle();
+    blocks = duplicateBlockTree(blocksOf(version?.blocks));
+  }
+
+  invalidatePublishedCache();
+  const { data: page, error } = await context.supabase
+    .from("pages")
+    .insert({ key, name, is_system: false, status: DEFAULT_PAGE_STATUS })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+
+  const { data: created, error: versionErr } = await context.supabase
+    .from("page_versions")
+    .insert({
+      page_id: page.id,
+      version_no: 1,
+      blocks: blocks as unknown as any,
+      note: `Copied from "${source.name}"`,
+      created_by: context.userId,
+      created_by_email: actorEmail(context),
+    })
+    .select("id")
+    .single();
+  if (versionErr) throw new Error(versionErr.message);
+  await context.supabase
+    .from("pages")
+    .update({ current_version_id: created.id })
+    .eq("id", page.id);
+
+  await context.supabase.from("audit_logs").insert({
+    actor_id: context.userId,
+    action: "page.duplicate",
+    entity: "pages",
+    entity_id: page.id,
+    meta: {
+      key,
+      source_key: source.key,
+      description: `Duplicated the page "${source.name}" as the draft "${name}" (${key}).`,
+    },
+  });
+
+  return { id: page.id as string, key, name, status: DEFAULT_PAGE_STATUS };
+}
+
 export async function renamePageCore(
   { context }: PagesDeps,
   input: { pageId: string; name: string; editSessionId?: string },
@@ -384,7 +799,15 @@ export async function renamePageCore(
   return { ok: true as const };
 }
 
-/** Soft delete: moves the page to the trash bin. Never destroys data. */
+/**
+ * Soft delete: moves the page to the trash bin. Never destroys data.
+ *
+ * Retiring the page's publications happens in the same transaction as setting
+ * `deleted_at`, and that is not tidiness. A trashed page that keeps an open
+ * publication row is a page waiting to come back: clearing `deleted_at` would
+ * put it straight onto the public website again, which turns Restore into a
+ * publishing action nobody confirmed.
+ */
 export async function deletePageCore(
   { context }: PagesDeps,
   pageId: string,
@@ -397,32 +820,21 @@ export async function deletePageCore(
     sessionId: editSessionId,
   });
   invalidatePublishedCache();
-  const email = actorEmail(context);
-  const { data: page } = await context.supabase
-    .from("pages")
-    .select("key,name,is_system")
-    .eq("id", pageId)
-    .maybeSingle();
-  if (page?.is_system) throw new Error("System pages cannot be deleted");
-  const { error } = await context.supabase
-    .from("pages")
-    .update({
-      deleted_at: new Date().toISOString(),
-      deleted_by: context.userId,
-      deleted_by_email: email,
-      status: "draft",
-    })
-    .eq("id", pageId)
-    .is("deleted_at", null);
-  if (error) throw new Error(error.message);
-  await context.supabase.from("audit_logs").insert({
-    actor_id: context.userId,
-    actor_email: email,
-    action: "page.soft_delete",
-    entity: "pages",
-    entity_id: pageId,
-    meta: { key: page?.key ?? null, name: page?.name ?? null },
-  });
+  await publicationRpc(
+    context.supabase,
+    "cms_soft_delete_page",
+    {
+      _page_id: pageId,
+      _actor_email: actorEmail(context),
+      _audit: {
+        description:
+          "Moved the page to the trash bin. It is no longer visible on the public " +
+          "website, and any publication window it had was retired.",
+      },
+    },
+    "Could not move the page to the trash bin",
+  );
+  invalidatePublishedCache();
   return { ok: true as const };
 }
 
@@ -454,22 +866,32 @@ export async function listDeletedPagesCore({
   return { rows: (data ?? []) as DeletedPageRow[], canPurge: !!isSuper };
 }
 
+/**
+ * Takes a page out of the trash bin, as a hidden draft.
+ *
+ * Restoring is not publishing. Whatever the page showed the public before it
+ * was deleted stays retired and its status stays draft, so somebody has to
+ * press Publish before it is on the internet again — which is what the word
+ * restore reads as, and what it did not do before.
+ */
 export async function restorePageCore({ context }: PagesDeps, pageId: string) {
   await assertStaff(context);
   invalidatePublishedCache();
-  const { error } = await context.supabase
-    .from("pages")
-    .update({ deleted_at: null, deleted_by: null, deleted_by_email: null })
-    .eq("id", pageId);
-  if (error) throw new Error(error.message);
-  await context.supabase.from("audit_logs").insert({
-    actor_id: context.userId,
-    actor_email: actorEmail(context),
-    action: "page.restore",
-    entity: "pages",
-    entity_id: pageId,
-    meta: {},
-  });
+  await publicationRpc(
+    context.supabase,
+    "cms_restore_page",
+    {
+      _page_id: pageId,
+      _actor_email: actorEmail(context),
+      _audit: {
+        description:
+          "Restored the page from the trash bin as a hidden draft. It stays off the " +
+          "public website until somebody publishes it.",
+      },
+    },
+    "Could not restore the page",
+  );
+  invalidatePublishedCache();
   return { ok: true as const };
 }
 
@@ -506,7 +928,8 @@ export function assertSingleBlock(blocks: BlockInstance[]) {
       "A global block can only contain one block. Convert it to a global section to add more.",
     );
   }
-  if (blocks.some((b) => b.type === "globalRef")) {
+  // Flattened, so a reference cannot hide inside a layout column.
+  if (flattenBlockTree(blocks).some((b) => b.type === "globalRef")) {
     throw new Error("A global block cannot contain another global block or section.");
   }
 }
@@ -743,9 +1166,38 @@ export async function getPageVersionPreviewCore(
   const blocks = blocksOf(v.blocks);
   const globals = await resolveGlobalsDeep(context.supabase, blocks);
   const meta = (v as unknown as { pages: { key: string; name: string } }).pages;
-  return { key: meta.key, name: meta.name, blocks, versionId: v.id, globals };
+  // A preview is a staff-only view of one named version, not a public window:
+  // there is nothing scheduled to revalidate against.
+  return { key: meta.key, name: meta.name, blocks, versionId: v.id, globals, revalidateAt: null };
+}
+
+/**
+ * An instant a schedule can actually be built on.
+ *
+ * The browser control offers a wall clock and a calendar, so the UI's own
+ * checks cover the editor typing into it and nothing else — not another host
+ * screen, not a script, not a replayed request. `Date.parse` accepts a good
+ * deal of nonsense and returns `NaN` for the rest, and `NaN` written into a
+ * `timestamptz` is a database error message rather than an answer anyone can
+ * act on, so the answer is worked out here first.
+ */
+function scheduleInstant(value: unknown, field: string): number {
+  const at = typeof value === "string" ? Date.parse(value) : Number.NaN;
+  if (!Number.isFinite(at)) {
+    throw new Error(`${field} is not a date and time this schedule can use.`);
+  }
+  return at;
 }
 
+/**
+ * Put a saved version on the calendar, with whatever it reveals.
+ *
+ * One database call, and therefore one transaction: the publication row, the
+ * reveals its countdowns promise and the audit trail all land together or none
+ * of them does. Scheduling used to be a bare insert that read no blocks at
+ * all, so a countdown on a version scheduled for next week scheduled nothing
+ * and the page it promised to reveal stayed hidden for good.
+ */
 export async function schedulePageVersionCore(
   { context }: PagesDeps,
   input: {
@@ -757,9 +1209,21 @@ export async function schedulePageVersionCore(
   },
 ) {
   await assertStaff(context);
+  const publishAt = scheduleInstant(input.publishAt, "The publish time");
+  const unpublishAt =
+    input.unpublishAt == null
+      ? null
+      : scheduleInstant(input.unpublishAt, "The unpublish time");
+  if (unpublishAt !== null && unpublishAt <= publishAt) {
+    throw new Error(
+      "A publication window has to end after it starts. Pick an unpublish time " +
+        "later than the publish time, or leave it empty.",
+    );
+  }
+
   const { data: v, error: vErr } = await context.supabase
     .from("page_versions")
-    .select("page_id")
+    .select("page_id, blocks")
     .eq("id", input.versionId)
     .single();
   if (vErr) throw new Error(vErr.message);
@@ -771,21 +1235,27 @@ export async function schedulePageVersionCore(
     sessionId: input.editSessionId,
   });
   invalidatePublishedCache();
-  const { data: inserted, error } = await context.supabase
-    .from("page_publications")
-    .insert({
-      page_id: v.page_id,
-      version_id: input.versionId,
-      publish_at: input.publishAt,
-      unpublish_at: input.unpublishAt ?? null,
-      is_active: true,
-      published_by: context.userId,
-      note: input.note ?? null,
-    })
-    .select("id")
-    .single();
-  if (error) throw new Error(error.message);
-  return { publicationId: inserted.id as string };
+  const scheduled = await publicationRpc(
+    context.supabase,
+    "cms_schedule_page_version",
+    {
+      _version_id: input.versionId,
+      _publish_at: new Date(publishAt).toISOString(),
+      _unpublish_at: unpublishAt === null ? null : new Date(unpublishAt).toISOString(),
+      _note: input.note ?? null,
+      // Read off the version being scheduled, not off the canvas: what goes
+      // live next week is what that version says, countdowns included.
+      _reveals: countdownReveals(blocksOf(v.blocks)),
+      _audit: {
+        description:
+          "Scheduled a version of this page to become visible on the public website.",
+      },
+      _actor_email: actorEmail(context),
+    },
+    "Could not schedule the page",
+  );
+  invalidatePublishedCache();
+  return { publicationId: String(scheduled?.publicationId ?? "") };
 }
 
 export type PagePublicationRow = {
@@ -816,6 +1286,19 @@ export async function listPagePublicationsCore(
   return (rows ?? []) as PagePublicationRow[];
 }
 
+/**
+ * Call off a publication that has not started yet.
+ *
+ * Only one that has not started. Retiring the row that is carrying the page
+ * right now takes it off the public website — and, where an earlier row is
+ * still active behind it, puts that older version back — which is not what
+ * "Cancel this scheduled publication" means to anybody. Taking a live page
+ * down is {@link setPageStatusCore}, with its own confirmation.
+ *
+ * The boundary is the database's, read inside the transaction that does the
+ * write, so a row that starts between the screen being drawn and the button
+ * being clicked is refused rather than raced.
+ */
 export async function cancelPagePublicationCore(
   { context }: PagesDeps,
   publicationId: string,
@@ -836,12 +1319,24 @@ export async function cancelPagePublicationCore(
     sessionId: editSessionId,
   });
   invalidatePublishedCache();
-  const { error } = await context.supabase
-    .from("page_publications")
-    .update({ is_active: false })
-    .eq("id", publicationId);
-  if (error) throw new Error(error.message);
-  return { ok: true as const };
+  const result = await publicationRpc(
+    context.supabase,
+    "cms_cancel_page_publication",
+    {
+      _publication_id: publicationId,
+      _audit: {
+        description: "Cancelled a publication that had not started yet.",
+      },
+      _actor_email: actorEmail(context),
+    },
+    "Could not cancel the publication",
+  );
+  invalidatePublishedCache();
+  return {
+    ok: true as const,
+    cancelled: Boolean(result?.cancelled),
+    reason: typeof result?.reason === "string" ? result.reason : null,
+  };
 }
 
 /** Where is a given global block used? */
@@ -863,8 +1358,9 @@ export async function getGlobalSectionUsageCore({ context }: PagesDeps, key: str
 
   const usedIn: { kind: "page" | "section"; key: string; name: string }[] = [];
 
+  // Flattened, so "where is this global used?" counts nested references too.
   const hasRef = (blocks: unknown) =>
-    blocksOf(blocks).some(
+    flattenBlockTree(blocksOf(blocks)).some(
       (b) =>
         b.type === "globalRef" &&
         String((b.props as { sectionKey?: string } | undefined)?.sectionKey ?? "") === key,