@bygghammar/cms-platform 0.32.2 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -141,7 +141,9 @@
     "./server/audit-core": "./src/server/audit-core.ts",
     "./server/review-image-validate": "./src/server/review-image-validate.ts",
     "./server/media-library-core": "./src/server/media-library-core.ts",
-    "./server/admin-core": "./src/server/admin-core.ts"
+    "./server/admin-core": "./src/server/admin-core.ts",
+    "./server/pages-core": "./src/server/pages-core.ts",
+    "./server/resolve-globals": "./src/server/resolve-globals.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/server/pages-core.ts

@@ -0,0 +1,799 @@
+/**
+ * Host-agnostic page-builder server logic.
+ *
+ * Owns pages, page versions, publications (including scheduling), the page
+ * trash bin, global blocks/sections and the two library scans the backoffice
+ * uses. Hosts keep only input validation and their own auth middleware; every
+ * read and write here runs through the client the host passes, so row-level
+ * security still applies as the signed-in user.
+ */
+import type { BlockInstance } from "../blocks/types";
+import { diffBlocks, summarizeChanges } from "../cms/version-diff";
+import type { VersionChange } from "../cms/version-diff";
+import { actorEmail, assertStaff, assertSuperadmin } from "./guards";
+import type { PlatformAuthContext } from "./guards";
+import { resolveGlobalsDeep } from "./resolve-globals";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Authenticated request context a host must provide. */
+export type PagesContext = PlatformAuthContext & { supabase: any };
+
+/** What the page cores need from the host. */
+export type PagesDeps = {
+  context: PagesContext;
+  /** Privileged client; only used to resolve legacy version authors. */
+  admin?: () => Promise<any>;
+};
+
+export type ResolvedPage = {
+  key: string;
+  name: string;
+  blocks: BlockInstance[];
+  versionId: string | null;
+  globals: Record<string, BlockInstance[]>;
+};
+
+const blocksOf = (value: unknown): BlockInstance[] =>
+  (value as unknown as BlockInstance[] | null) ?? [];
+
+/**
+ * Public rendering path: the currently-live blocks for a page plus any global
+ * blocks they reference. Needs a trusted client because CMS tables are not
+ * readable by anonymous callers.
+ */
+export async function getPublishedPageCore(
+  client: any,
+  key: string,
+): Promise<ResolvedPage | null> {
+  const { data: page } = await client
+    .from("pages")
+    .select("id,key,name,current_version_id")
+    .eq("key", key)
+    .is("deleted_at", null)
+    .maybeSingle();
+  if (!page) return 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 versionId = pub?.version_id ?? page.current_version_id;
+  if (!versionId) return null;
+  const { data: version } = await client
+    .from("page_versions")
+    .select("id, blocks")
+    .eq("id", versionId)
+    .maybeSingle();
+  const blocks = blocksOf(version?.blocks);
+  const globals = await resolveGlobalsDeep(client, blocks);
+  return { key: page.key, name: page.name, blocks, versionId: version?.id ?? null, globals };
+}
+
+export type PageListRow = {
+  id: string;
+  key: string;
+  name: string;
+  is_system: boolean;
+  status: string;
+  updated_at: string;
+  current_version_id: string | null;
+};
+
+export async function listPagesCore({ context }: PagesDeps): Promise<PageListRow[]> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("pages")
+    .select("id,key,name,is_system,status,updated_at,current_version_id")
+    .is("deleted_at", null)
+    .order("is_system", { ascending: false })
+    .order("name");
+  if (error) throw new Error(error.message);
+  return (data ?? []) as PageListRow[];
+}
+
+export async function getPageForEditCore({ context }: PagesDeps, key: string) {
+  await assertStaff(context);
+  const { data: page, error } = await context.supabase
+    .from("pages")
+    .select("id,key,name,is_system,status,current_version_id")
+    .eq("key", key)
+    .is("deleted_at", null)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  if (!page) throw new Error("Page not found");
+  let blocks: BlockInstance[] = [];
+  if (page.current_version_id) {
+    const { data: v } = await context.supabase
+      .from("page_versions")
+      .select("blocks")
+      .eq("id", page.current_version_id)
+      .maybeSingle();
+    blocks = blocksOf(v?.blocks);
+  }
+  return { page, blocks };
+}
+
+export async function savePageVersionCore(
+  { context }: PagesDeps,
+  input: { pageId: string; blocks: BlockInstance[]; publish?: boolean; note?: string },
+) {
+  await assertStaff(context);
+  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);
+
+  await context.supabase
+    .from("pages")
+    .update({ current_version_id: inserted.id })
+    .eq("id", input.pageId);
+
+  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);
+  }
+  return { versionId: inserted.id as string, versionNo: nextNo };
+}
+
+export async function listPageVersionsCore(deps: PagesDeps, pageId: string) {
+  const { context, admin } = deps;
+  await assertStaff(context);
+  const { data: rows, error } = await context.supabase
+    .from("page_versions")
+    .select("id, version_no, note, created_at, created_by, created_by_email, blocks")
+    .eq("page_id", pageId)
+    .order("version_no", { ascending: false })
+    .limit(50);
+  if (error) throw new Error(error.message);
+  const list = (rows ?? []) as any[];
+
+  // Resolve display names for authors that predate created_by_email.
+  const missing = Array.from(
+    new Set(list.filter((r) => !r.created_by_email && r.created_by).map((r) => r.created_by as string)),
+  );
+  const emailById = new Map<string, string>();
+  if (missing.length > 0 && admin) {
+    try {
+      const client = await admin();
+      for (const id of missing) {
+        const { data: u } = await client.auth.admin.getUserById(id);
+        if (u?.user?.email) emailById.set(id, u.user.email);
+      }
+    } catch {
+      // best effort only
+    }
+  }
+
+  return list.map((row, index) => {
+    const current = blocksOf(row.blocks);
+    const older = list[index + 1];
+    const previous = older ? blocksOf(older.blocks) : [];
+    const changes: VersionChange[] = older
+      ? diffBlocks(previous, current)
+      : current.map((b) => ({ kind: "added" as const, blockType: b.type }));
+    return {
+      id: row.id as string,
+      version_no: row.version_no as number,
+      note: row.note as string | null,
+      created_at: row.created_at as string,
+      created_by: row.created_by as string | null,
+      author:
+        ((row.created_by_email as string | null) ??
+          (row.created_by ? (emailById.get(row.created_by) ?? null) : null)) ||
+        "Unknown user",
+      block_count: current.length,
+      changes,
+      summary: summarizeChanges(changes),
+    };
+  });
+}
+
+export async function restorePageVersionCore(deps: PagesDeps, versionId: string) {
+  await assertStaff(deps.context);
+  const { data: v, error } = await deps.context.supabase
+    .from("page_versions")
+    .select("page_id, blocks")
+    .eq("id", versionId)
+    .single();
+  if (error) throw new Error(error.message);
+  return savePageVersionCore(deps, {
+    pageId: v.page_id,
+    blocks: blocksOf(v.blocks),
+    publish: true,
+    note: "Restored from earlier version",
+  });
+}
+
+export async function createPageCore({ context }: PagesDeps, input: { key: string; name: string }) {
+  await assertStaff(context);
+  const { data: page, error } = await context.supabase
+    .from("pages")
+    .insert({ key: input.key, name: input.name, is_system: false, status: "draft" })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+  const { data: v } = await context.supabase
+    .from("page_versions")
+    .insert({ page_id: page.id, version_no: 1, blocks: [], note: "Empty" })
+    .select("id")
+    .single();
+  if (v) {
+    await context.supabase.from("pages").update({ current_version_id: v.id }).eq("id", page.id);
+  }
+  return { id: page.id as string };
+}
+
+export async function renamePageCore(
+  { context }: PagesDeps,
+  input: { pageId: string; name: string },
+) {
+  await assertStaff(context);
+  const { error } = await context.supabase
+    .from("pages")
+    .update({ name: input.name })
+    .eq("id", input.pageId);
+  if (error) throw new Error(error.message);
+  await context.supabase.from("audit_logs").insert({
+    actor_id: context.userId,
+    action: "page.rename",
+    entity: "pages",
+    entity_id: input.pageId,
+    meta: { name: input.name },
+  });
+  return { ok: true as const };
+}
+
+/** Soft delete: moves the page to the trash bin. Never destroys data. */
+export async function deletePageCore({ context }: PagesDeps, pageId: string) {
+  await assertStaff(context);
+  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 },
+  });
+  return { ok: true as const };
+}
+
+export type DeletedPageRow = {
+  id: string;
+  key: string;
+  name: string;
+  status: string;
+  updated_at: string;
+  deleted_at: string;
+  deleted_by: string | null;
+  deleted_by_email: string | null;
+};
+
+export async function listDeletedPagesCore({
+  context,
+}: PagesDeps): Promise<{ rows: DeletedPageRow[]; canPurge: boolean }> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("pages")
+    .select("id,key,name,status,updated_at,deleted_at,deleted_by,deleted_by_email")
+    .not("deleted_at", "is", null)
+    .order("deleted_at", { ascending: false });
+  if (error) throw new Error(error.message);
+  const { data: isSuper } = await context.supabase.rpc("has_role", {
+    _user_id: context.userId,
+    _role: "superadmin",
+  });
+  return { rows: (data ?? []) as DeletedPageRow[], canPurge: !!isSuper };
+}
+
+export async function restorePageCore({ context }: PagesDeps, pageId: string) {
+  await assertStaff(context);
+  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: {},
+  });
+  return { ok: true as const };
+}
+
+/** Permanent delete from the trash bin — superadmin only. */
+export async function purgePageCore({ context }: PagesDeps, pageId: string) {
+  await assertStaff(context);
+  await assertSuperadmin(context);
+  const { data: page } = await context.supabase
+    .from("pages")
+    .select("key,name,deleted_at")
+    .eq("id", pageId)
+    .maybeSingle();
+  if (!page?.deleted_at) throw new Error("Move the page to the trash bin first");
+  const { error } = await context.supabase.from("pages").delete().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.purge",
+    entity: "pages",
+    entity_id: pageId,
+    meta: { key: page.key, name: page.name },
+  });
+  return { ok: true as const };
+}
+
+/* ---------- Global blocks ---------- */
+
+/** A global block holds exactly one block and may not reference other globals. */
+export function assertSingleBlock(blocks: BlockInstance[]) {
+  if (blocks.length > 1) {
+    throw new Error(
+      "A global block can only contain one block. Convert it to a global section to add more.",
+    );
+  }
+  if (blocks.some((b) => b.type === "globalRef")) {
+    throw new Error("A global block cannot contain another global block or section.");
+  }
+}
+
+export type GlobalSectionRow = {
+  id: string;
+  key: string;
+  name: string;
+  kind: "block" | "section";
+  updated_at: string;
+  current_version_id: string | null;
+};
+
+export async function listGlobalSectionsCore({
+  context,
+}: PagesDeps): Promise<(GlobalSectionRow & { blocks: BlockInstance[] })[]> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("global_sections")
+    .select("id,key,name,kind,updated_at,current_version_id")
+    .order("name");
+  if (error) throw new Error(error.message);
+  const rows = (data ?? []) as any[];
+  const versionIds = rows.map((r) => r.current_version_id).filter((x): x is string => !!x);
+  const blocksByVersion = new Map<string, BlockInstance[]>();
+  if (versionIds.length > 0) {
+    const { data: versions } = await context.supabase
+      .from("global_section_versions")
+      .select("id,blocks")
+      .in("id", versionIds);
+    for (const v of (versions ?? []) as any[]) blocksByVersion.set(v.id, blocksOf(v.blocks));
+  }
+  return (rows as GlobalSectionRow[]).map((r) => ({
+    ...r,
+    blocks: blocksByVersion.get(r.current_version_id ?? "") ?? [],
+  }));
+}
+
+export async function getGlobalSectionForEditCore({ context }: PagesDeps, key: string) {
+  await assertStaff(context);
+  const { data: gs, error } = await context.supabase
+    .from("global_sections")
+    .select("id,key,name,kind,current_version_id")
+    .eq("key", key)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  if (!gs) throw new Error("Global block not found");
+  let blocks: BlockInstance[] = [];
+  if (gs.current_version_id) {
+    const { data: v } = await context.supabase
+      .from("global_section_versions")
+      .select("blocks")
+      .eq("id", gs.current_version_id)
+      .maybeSingle();
+    blocks = blocksOf(v?.blocks);
+  }
+  return { section: gs, blocks };
+}
+
+export async function createGlobalSectionCore(
+  { context }: PagesDeps,
+  input: { key: string; name: string; blocks?: BlockInstance[]; kind?: "block" | "section" },
+) {
+  await assertStaff(context);
+  const kind = input.kind ?? "section";
+  if (kind === "block") assertSingleBlock(input.blocks ?? []);
+  const { data: gs, error } = await context.supabase
+    .from("global_sections")
+    .insert({ key: input.key, name: input.name, kind })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+  const { data: v } = await context.supabase
+    .from("global_section_versions")
+    .insert({
+      section_id: gs.id,
+      version_no: 1,
+      blocks: (input.blocks ?? []) as unknown as any,
+      note: "Initial",
+    })
+    .select("id")
+    .single();
+  if (v) {
+    await context.supabase
+      .from("global_sections")
+      .update({ current_version_id: v.id })
+      .eq("id", gs.id);
+  }
+  return { id: gs.id as string };
+}
+
+export async function setGlobalSectionKindCore(
+  { context }: PagesDeps,
+  input: { sectionId: string; kind: "block" | "section" },
+) {
+  await assertStaff(context);
+  if (input.kind === "block") {
+    const { data: gs } = await context.supabase
+      .from("global_sections")
+      .select("current_version_id")
+      .eq("id", input.sectionId)
+      .maybeSingle();
+    if (gs?.current_version_id) {
+      const { data: v } = await context.supabase
+        .from("global_section_versions")
+        .select("blocks")
+        .eq("id", gs.current_version_id)
+        .maybeSingle();
+      assertSingleBlock(blocksOf(v?.blocks));
+    }
+  }
+  const { error } = await context.supabase
+    .from("global_sections")
+    .update({ kind: input.kind })
+    .eq("id", input.sectionId);
+  if (error) throw new Error(error.message);
+  return { ok: true as const };
+}
+
+export async function saveGlobalSectionVersionCore(
+  { context }: PagesDeps,
+  input: { sectionId: string; blocks: BlockInstance[]; note?: string },
+) {
+  await assertStaff(context);
+  const { data: meta } = await context.supabase
+    .from("global_sections")
+    .select("kind")
+    .eq("id", input.sectionId)
+    .maybeSingle();
+  if ((meta?.kind ?? "section") === "block") assertSingleBlock(input.blocks);
+  const { data: last } = await context.supabase
+    .from("global_section_versions")
+    .select("version_no")
+    .eq("section_id", input.sectionId)
+    .order("version_no", { ascending: false })
+    .limit(1)
+    .maybeSingle();
+  const nextNo = (last?.version_no ?? 0) + 1;
+  const { data: inserted, error } = await context.supabase
+    .from("global_section_versions")
+    .insert({
+      section_id: input.sectionId,
+      version_no: nextNo,
+      blocks: input.blocks as unknown as any,
+      note: input.note ?? null,
+      created_by: context.userId,
+    })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+  await context.supabase
+    .from("global_sections")
+    .update({ current_version_id: inserted.id })
+    .eq("id", input.sectionId);
+  return { versionId: inserted.id as string, versionNo: nextNo };
+}
+
+export async function renameGlobalSectionCore(
+  { context }: PagesDeps,
+  input: { sectionId: string; name: string },
+) {
+  await assertStaff(context);
+  const { error } = await context.supabase
+    .from("global_sections")
+    .update({ name: input.name })
+    .eq("id", input.sectionId);
+  if (error) throw new Error(error.message);
+  return { ok: true as const };
+}
+
+export async function deleteGlobalSectionCore({ context }: PagesDeps, sectionId: string) {
+  await assertStaff(context);
+  const { error } = await context.supabase
+    .from("global_sections")
+    .delete()
+    .eq("id", sectionId);
+  if (error) throw new Error(error.message);
+  return { ok: true as const };
+}
+
+/* ---------- Scheduling / drafts ---------- */
+
+/** A specific version's blocks, for previewing drafts. */
+export async function getPageVersionPreviewCore(
+  { context }: PagesDeps,
+  versionId: string,
+): Promise<ResolvedPage | null> {
+  await assertStaff(context);
+  const { data: v, error } = await context.supabase
+    .from("page_versions")
+    .select("id, page_id, blocks, pages!inner(key,name)")
+    .eq("id", versionId)
+    .single();
+  if (error) throw new Error(error.message);
+  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 };
+}
+
+export async function schedulePageVersionCore(
+  { context }: PagesDeps,
+  input: { versionId: string; publishAt: string; unpublishAt?: string | null; note?: string },
+) {
+  await assertStaff(context);
+  const { data: v, error: vErr } = await context.supabase
+    .from("page_versions")
+    .select("page_id")
+    .eq("id", input.versionId)
+    .single();
+  if (vErr) throw new Error(vErr.message);
+  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 };
+}
+
+export type PagePublicationRow = {
+  id: string;
+  version_id: string;
+  publish_at: string;
+  unpublish_at: string | null;
+  is_active: boolean;
+  note: string | null;
+  published_at: string | null;
+  page_versions: { version_no: number } | null;
+};
+
+export async function listPagePublicationsCore(
+  { context }: PagesDeps,
+  pageId: string,
+): Promise<PagePublicationRow[]> {
+  await assertStaff(context);
+  const { data: rows, error } = await context.supabase
+    .from("page_publications")
+    .select(
+      "id, version_id, publish_at, unpublish_at, is_active, note, published_at, page_versions(version_no)",
+    )
+    .eq("page_id", pageId)
+    .order("publish_at", { ascending: false })
+    .limit(50);
+  if (error) throw new Error(error.message);
+  return (rows ?? []) as PagePublicationRow[];
+}
+
+export async function cancelPagePublicationCore({ context }: PagesDeps, publicationId: string) {
+  await assertStaff(context);
+  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 };
+}
+
+/** Where is a given global block used? */
+export async function getGlobalSectionUsageCore({ context }: PagesDeps, key: string) {
+  await assertStaff(context);
+  const { data: pages } = await context.supabase
+    .from("pages")
+    .select("key,name,current_version_id");
+  const { data: sections } = await context.supabase
+    .from("global_sections")
+    .select("key,name,current_version_id");
+
+  const pageVersionIds = ((pages ?? []) as any[])
+    .map((p) => p.current_version_id)
+    .filter((x): x is string => !!x);
+  const gsVersionIds = ((sections ?? []) as any[])
+    .map((g) => g.current_version_id)
+    .filter((x): x is string => !!x);
+
+  const usedIn: { kind: "page" | "section"; key: string; name: string }[] = [];
+
+  const hasRef = (blocks: unknown) =>
+    blocksOf(blocks).some(
+      (b) =>
+        b.type === "globalRef" &&
+        String((b.props as { sectionKey?: string } | undefined)?.sectionKey ?? "") === key,
+    );
+
+  if (pageVersionIds.length > 0) {
+    const { data: pv } = await context.supabase
+      .from("page_versions")
+      .select("id,blocks")
+      .in("id", pageVersionIds);
+    const byId = new Map(((pv ?? []) as any[]).map((v) => [v.id, v.blocks]));
+    for (const p of (pages ?? []) as any[]) {
+      if (p.current_version_id && hasRef(byId.get(p.current_version_id))) {
+        usedIn.push({ kind: "page", key: p.key, name: p.name });
+      }
+    }
+  }
+  if (gsVersionIds.length > 0) {
+    const { data: gv } = await context.supabase
+      .from("global_section_versions")
+      .select("id,blocks")
+      .in("id", gsVersionIds);
+    const byId = new Map(((gv ?? []) as any[]).map((v) => [v.id, v.blocks]));
+    for (const g of (sections ?? []) as any[]) {
+      if (g.key === key) continue;
+      if (g.current_version_id && hasRef(byId.get(g.current_version_id))) {
+        usedIn.push({ kind: "section", key: g.key, name: g.name });
+      }
+    }
+  }
+  return usedIn;
+}
+
+/**
+ * Reference thumbnails per block type.
+ *
+ * Scans the current version of every page and global block plus the saved block
+ * templates, and returns the first usable image URL found inside a real
+ * instance of each block type. The Blocks library uses this so every block type
+ * shows a real reference image even when its defaults contain no media.
+ */
+export async function listBlockTypeImagesCore({
+  context,
+}: PagesDeps): Promise<Record<string, string>> {
+  await assertStaff(context);
+
+  const [{ data: pages }, { data: sections }, { data: templates }] = await Promise.all([
+    context.supabase.from("pages").select("current_version_id"),
+    context.supabase.from("global_sections").select("current_version_id"),
+    context.supabase.from("block_templates").select("block_type,block"),
+  ]);
+
+  const pageVersionIds = ((pages ?? []) as any[])
+    .map((p) => p.current_version_id)
+    .filter((x): x is string => !!x);
+  const gsVersionIds = ((sections ?? []) as any[])
+    .map((g) => g.current_version_id)
+    .filter((x): x is string => !!x);
+
+  const blockLists: unknown[] = [];
+  if (pageVersionIds.length > 0) {
+    const { data } = await context.supabase
+      .from("page_versions")
+      .select("blocks")
+      .in("id", pageVersionIds);
+    for (const v of (data ?? []) as any[]) blockLists.push(v.blocks);
+  }
+  if (gsVersionIds.length > 0) {
+    const { data } = await context.supabase
+      .from("global_section_versions")
+      .select("blocks")
+      .in("id", gsVersionIds);
+    for (const v of (data ?? []) as any[]) blockLists.push(v.blocks);
+  }
+
+  const isImage = (value: unknown): value is string =>
+    typeof value === "string" &&
+    value.length > 0 &&
+    /^(https?:\/\/|\/)/.test(value) &&
+    !/\.(mp4|webm|mov)(\?|$)/i.test(value);
+
+  const findImage = (node: unknown, depth = 0): string | null => {
+    if (node == null || depth > 6) return null;
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const found = findImage(item, depth + 1);
+        if (found) return found;
+      }
+      return null;
+    }
+    if (typeof node !== "object") return null;
+    const obj = node as Record<string, unknown>;
+    for (const key of ["src", "poster", "url", "image", "thumbnail"]) {
+      if (isImage(obj[key])) return obj[key] as string;
+    }
+    for (const value of Object.values(obj)) {
+      const found = findImage(value, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  };
+
+  const out: Record<string, string> = {};
+  const consider = (block: unknown) => {
+    if (!block || typeof block !== "object") return;
+    const b = block as { type?: unknown; props?: unknown };
+    if (typeof b.type !== "string" || out[b.type]) return;
+    const image = findImage(b.props);
+    if (image) out[b.type] = image;
+  };
+
+  for (const list of blockLists) {
+    if (!Array.isArray(list)) continue;
+    for (const block of list) consider(block);
+  }
+  for (const t of (templates ?? []) as any[]) consider(t.block);
+
+  return out;
+}

package/src/server/resolve-globals.ts

@@ -0,0 +1,71 @@
+/**
+ * Host-agnostic resolution of global block references.
+ *
+ * Reads only two CMS tables through whatever Supabase-shaped client the caller
+ * passes, so it works with an authenticated client in the backoffice and with a
+ * privileged client during public rendering.
+ */
+import type { BlockInstance, BlockProps } from "../blocks/types";
+
+/** Minimal read surface this helper needs from a Supabase-style client. */
+export type GlobalsReadClient = {
+  from: (table: string) => {
+    select: (columns: string) => {
+      in: (column: string, values: string[]) => PromiseLike<{ data: unknown }>;
+    };
+  };
+};
+
+function refKeysOf(blocks: BlockInstance[]): string[] {
+  return blocks
+    .filter((b) => b.type === "globalRef")
+    .map((b) => String((b.props as BlockProps | undefined)?.sectionKey ?? ""))
+    .filter(Boolean);
+}
+
+/**
+ * Resolve every global block referenced by `blocks`, following references
+ * nested inside other global blocks. Cycles are stopped by the visited set.
+ */
+export async function resolveGlobalsDeep(
+  client: GlobalsReadClient,
+  blocks: BlockInstance[],
+): Promise<Record<string, BlockInstance[]>> {
+  const globals: Record<string, BlockInstance[]> = {};
+  let pending = Array.from(new Set(refKeysOf(blocks)));
+  let guard = 0;
+
+  while (pending.length > 0 && guard < 10) {
+    guard += 1;
+    const { data: gs } = await client
+      .from("global_sections")
+      .select("key, current_version_id")
+      .in("key", pending);
+    const rows = (gs ?? []) as { key: string; current_version_id: string | null }[];
+    const versionIds = rows.map((g) => g.current_version_id).filter((x): x is string => !!x);
+    const byId = new Map<string, BlockInstance[]>();
+    if (versionIds.length > 0) {
+      const { data: gvs } = await client
+        .from("global_section_versions")
+        .select("id, blocks")
+        .in("id", versionIds);
+      for (const v of (gvs ?? []) as { id: string; blocks: unknown }[]) {
+        byId.set(v.id, (v.blocks as unknown as BlockInstance[] | null) ?? []);
+      }
+    }
+
+    const next: string[] = [];
+    for (const key of pending) {
+      if (key in globals) continue;
+      const row = rows.find((r) => r.key === key);
+      const inner = row?.current_version_id ? (byId.get(row.current_version_id) ?? []) : [];
+      globals[key] = inner;
+      for (const k of refKeysOf(inner)) {
+        if (!(k in globals)) next.push(k);
+      }
+    }
+    pending = Array.from(new Set(next));
+  }
+
+  return globals;
+}