@bygghammar/cms-platform 0.1.0 → 0.2.0

package/README.md

@@ -9,6 +9,8 @@ future sites). **Code only** — no content, no data, no secrets, no theme.
 - `src/blocks/icons.ts` — the icon set blocks may reference
 - `src/blocks/block-props-context.tsx` — block prop plumbing for inline editing
 - `src/i18n/*` — the localization core (locales, types, resolver, context)
+- `src/backup/*` — archive/media safety, browser-side large-media export and
+  provider-neutral verification helpers
 - `src/theme.css` — the design-token contract + neutral starter theme
 
 ## What must never live here
@@ -17,6 +19,27 @@ future sites). **Code only** — no content, no data, no secrets, no theme.
 - page content, SEO copy, media, CMS page JSON
 - Supabase generated types, auth users, secrets, API keys
 - route files and per-site deployment config
+- site table lists, import order, database clients, authentication and RLS
+  policies; each host supplies those adapters to the shared backup core
+
+## Backup core
+
+The package owns the CMS-wide, provider-neutral parts of backup and restore:
+
+- media signature/path validation and secret sanitising
+- streaming large media files into an archive in the authenticated browser
+- archive progress and manifest contracts
+- row-count, user/role and media verification helpers
+
+The browser media exporter accepts a host storage adapter with only `list()`
+and `download()` methods plus the host's expected archive format/schema
+versions. Keep the dynamic import behind an `import.meta.env.SSR` guard in SSR
+applications so the browser-only ZIP code cannot enter the optimized server
+chunk graph.
+
+The consuming site remains responsible for its dataset groups, table import
+order, Supabase clients, superadmin authorization, HTTP routes, audit records
+and database migrations. The package never contains site data or credentials.
 
 ## Per-site wiring
 
@@ -28,9 +51,55 @@ import { registerTranslations } from "@bygghammar/cms-platform/i18n";
 registerTranslations({ generated: TRANSLATIONS, overrides: TRANSLATION_OVERRIDES });
 ```
 
-## Consuming
+Host components must participate in a value the application actually uses.
+Do not rely only on `import "./register-host"` because an optimized build may
+remove that module when the application's `package.json` declares
+`"sideEffects": false`.
+
+```tsx
+import { initializeHostComponents, type HostComponents } from "@bygghammar/cms-platform/host";
+
+const HOST_COMPONENTS = {
+  FocalImage,
+  LazyVideo,
+  FocusPicker,
+  RichTextEditor,
+  mediaLibraryQueryOptions,
+  useMediaUpload,
+} satisfies Partial<HostComponents>;
+
+export const BLOCK_REGISTRY = initializeHostComponents(HOST_COMPONENTS, () =>
+  createBlockRegistry(),
+);
+```
+
+Keep any existing registration module in the consuming application's
+`sideEffects` allowlist as defence in depth until every entry point uses the
+explicit contract. CSS must also remain in that allowlist.
+
+## Publishing
+
+This directory is the maintained source for the public npm package. Releases
+use npm Trusted Publishing from GitHub Actions; do not publish from a laptop or
+create an npm token.
+
+1. Merge the reviewed version bump and wait for Checks to pass on `main`.
+2. Run **Actions → Publish CMS platform → Run workflow** from `main` and enter
+   the exact version from this package.
+3. Verify the new public version before updating consuming CMS lockfiles.
+
+Never place an npm token or `.npmrc` in the repository. Consumers install an
+explicit released version such as `@bygghammar/cms-platform@^0.1.1`.
+
+### Release checks and troubleshooting
+
+The workflow type-checks the package and runs
+`tests/cms-platform-host-contract.test.tsx` before requesting npm's OIDC
+publishing credential. Keep Vitest's include glob compatible with both
+`*.test.ts` and `*.test.tsx`; otherwise the release stops with “No test files
+found” before npm is contacted.
 
-Today the package is linked through the Bun workspace (`workspace:*`), so edits
-are picked up instantly with no publish step. When the workspace managed npm
-registry is enabled, the same source publishes under the `@ws-` scope and sites
-switch `workspace:*` for a version range — no code changes.
+If a release run fails, read its failed step before rerunning it. A failed run
+does not publish a partial package. After a successful run, verify the public
+registry reports the requested version, then update each consuming application
+and its frozen lockfile in a separate pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.1.0",
+  "version": "0.2.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,
@@ -13,6 +13,14 @@
     "src",
     "README.md"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/byggis79/devsba.git",
+    "directory": "packages/cms-platform"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./i18n": "./src/i18n/index.ts",
@@ -26,14 +34,23 @@
     "./ui/Lightbox": "./src/ui/Lightbox.tsx",
     "./util/scroll-lock": "./src/util/scroll-lock.ts",
     "./html/sanitize-html": "./src/html/sanitize-html.ts",
+    "./backup": "./src/backup/index.ts",
+    "./backup/safety": "./src/backup/safety.ts",
+    "./backup/browser-media": "./src/backup/browser-media.ts",
+    "./backup/verification": "./src/backup/verification.ts",
     "./backoffice/inspectors/fields": "./src/backoffice/inspectors/fields.tsx",
     "./theme.css": "./src/theme.css",
     "./backoffice/inspectors/blocks": "./src/backoffice/inspectors/blocks.tsx",
     "./blocks/registry": "./src/blocks/registry.tsx"
   },
+  "dependencies": {
+    "fflate": "^0.8.3"
+  },
   "peerDependencies": {
+    "@tanstack/react-query": ">=5",
     "lucide-react": ">=0.5.0",
     "react": ">=19",
-    "react-dom": ">=19"
+    "react-dom": ">=19",
+    "sonner": ">=2"
   }
-}
+}

package/src/backup/browser-media.ts

@@ -0,0 +1,205 @@
+import { strFromU8, strToU8, unzipSync, Zip, ZipDeflate, ZipPassThrough } from "fflate";
+
+import { hasAllowedMediaExtension, isSafeArchivePath, verifyMediaFile } from "./safety";
+
+export type BackupArchiveManifest = {
+  format: number | string;
+  schemaVersion: number | string;
+  groups: string[];
+  mediaFiles: number;
+  mediaBytes: number;
+  quarantinedMedia?: string[];
+};
+
+export type BackupStorageFile = {
+  name: string;
+  size: number;
+  contentType?: string | null;
+  updatedAt?: string | null;
+};
+
+export type BrowserBackupStorage = {
+  list(): Promise<BackupStorageFile[]>;
+  download(path: string): Promise<Uint8Array>;
+};
+
+export type MediaExportProgress = {
+  phase: "listing" | "downloading" | "finalizing";
+  completedFiles: number;
+  totalFiles: number;
+  completedBytes: number;
+  totalBytes: number;
+  currentFile?: string;
+};
+
+export type BrowserMediaExportOptions = {
+  baseArchive: Uint8Array;
+  groups: string[];
+  storage: BrowserBackupStorage;
+  expectedFormat: number | string;
+  expectedSchemaVersion: number | string;
+  onProgress?: (progress: MediaExportProgress) => void;
+};
+
+function readManifest<M extends BackupArchiveManifest>(
+  files: Record<string, Uint8Array>,
+  expectedFormat: number | string,
+  expectedSchemaVersion: number | string,
+): M {
+  const raw = files["manifest.json"];
+  if (!raw) throw new Error("The server metadata archive has no manifest.");
+
+  let manifest: M;
+  try {
+    manifest = JSON.parse(strFromU8(raw)) as M;
+  } catch {
+    throw new Error("The server metadata archive has an invalid manifest.");
+  }
+
+  if (
+    manifest.format !== expectedFormat ||
+    manifest.schemaVersion !== expectedSchemaVersion ||
+    !Array.isArray(manifest.groups)
+  ) {
+    throw new Error("The server metadata archive is not compatible with this version.");
+  }
+  return manifest;
+}
+
+function addEntry(zip: Zip, name: string, data: Uint8Array, compress: boolean): void {
+  const entry = compress ? new ZipDeflate(name, { level: 6 }) : new ZipPassThrough(name);
+  zip.add(entry);
+  entry.push(data, true);
+}
+
+function candidateMedia(files: BackupStorageFile[], quarantined: string[]): BackupStorageFile[] {
+  return files.filter((file) => {
+    if (!hasAllowedMediaExtension(file.name) || !isSafeArchivePath(file.name)) {
+      quarantined.push(file.name);
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Add large media to a small server-generated metadata archive in the
+ * authenticated browser. Objects are downloaded and verified one at a time,
+ * avoiding request timeouts and all-media-in-server-memory failures.
+ */
+export async function buildBrowserMediaArchive<M extends BackupArchiveManifest>({
+  baseArchive,
+  groups,
+  storage,
+  expectedFormat,
+  expectedSchemaVersion,
+  onProgress,
+}: BrowserMediaExportOptions): Promise<{ blob: Blob; manifest: M }> {
+  const baseFiles = unzipSync(baseArchive);
+  const baseManifest = readManifest<M>(baseFiles, expectedFormat, expectedSchemaVersion);
+  const quarantined = [...(baseManifest.quarantinedMedia ?? [])];
+
+  onProgress?.({
+    phase: "listing",
+    completedFiles: 0,
+    totalFiles: 0,
+    completedBytes: 0,
+    totalBytes: 0,
+  });
+
+  const listed = await storage.list();
+  const candidates = candidateMedia(listed, quarantined);
+  const totalBytes = candidates.reduce((sum, file) => sum + Math.max(0, file.size), 0);
+  let completedFiles = 0;
+  let completedBytes = 0;
+  let archivedFiles = 0;
+  let archivedBytes = 0;
+
+  const chunks: BlobPart[] = [];
+  let resolveZip!: () => void;
+  let rejectZip!: (error: Error) => void;
+  const zipFinished = new Promise<void>((resolve, reject) => {
+    resolveZip = resolve;
+    rejectZip = reject;
+  });
+  const zip = new Zip((error, data, final) => {
+    if (error) {
+      rejectZip(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+    if (data?.byteLength) chunks.push(data as unknown as BlobPart);
+    if (final) resolveZip();
+  });
+
+  try {
+    for (const [name, data] of Object.entries(baseFiles)) {
+      if (name === "manifest.json" || name.startsWith("media/")) continue;
+      if (!isSafeArchivePath(name)) throw new Error(`Unsafe metadata archive entry: ${name}`);
+      addEntry(zip, name, data, name.endsWith(".json"));
+    }
+
+    onProgress?.({
+      phase: "downloading",
+      completedFiles,
+      totalFiles: candidates.length,
+      completedBytes,
+      totalBytes,
+    });
+
+    for (const file of candidates) {
+      let data: Uint8Array;
+      try {
+        data = await storage.download(file.name);
+      } catch (error) {
+        throw new Error(
+          `Could not download media file “${file.name}”: ${
+            error instanceof Error ? error.message : "unknown storage error"
+          }`,
+        );
+      }
+
+      const verdict = verifyMediaFile(file.name, data);
+      if (verdict.ok) {
+        addEntry(zip, `media/${file.name}`, data, false);
+        archivedFiles += 1;
+        archivedBytes += data.byteLength;
+      } else {
+        quarantined.push(`${file.name} (${verdict.reason})`);
+      }
+
+      completedFiles += 1;
+      completedBytes += file.size > 0 ? file.size : data.byteLength;
+      onProgress?.({
+        phase: "downloading",
+        completedFiles,
+        totalFiles: candidates.length,
+        completedBytes,
+        totalBytes,
+        currentFile: file.name,
+      });
+    }
+
+    const manifest = {
+      ...baseManifest,
+      groups: [...groups],
+      mediaFiles: archivedFiles,
+      mediaBytes: archivedBytes,
+      quarantinedMedia: quarantined,
+    } as M;
+    addEntry(zip, "manifest.json", strToU8(JSON.stringify(manifest, null, 2)), true);
+    onProgress?.({
+      phase: "finalizing",
+      completedFiles,
+      totalFiles: candidates.length,
+      completedBytes,
+      totalBytes,
+    });
+    zip.end();
+    await zipFinished;
+
+    return { blob: new Blob(chunks, { type: "application/zip" }), manifest };
+  } catch (error) {
+    zip.terminate();
+    throw error;
+  }
+}

package/src/backup/index.ts

@@ -0,0 +1,3 @@
+export * from "./browser-media";
+export * from "./safety";
+export * from "./verification";

package/src/backup/safety.ts

@@ -0,0 +1,241 @@
+/**
+ * Provider-neutral backup safety helpers. Nothing in this module opens a
+ * connection or reads the filesystem, so hosts can use it in the browser,
+ * server functions and restore tools.
+ */
+
+export const ALLOWED_MEDIA_EXTENSIONS = [
+  ".webp",
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".avif",
+  ".mp4",
+  ".webm",
+  ".mov",
+  ".pdf",
+] as const;
+
+export const MAX_MEDIA_ENTRY_BYTES = 250 * 1024 * 1024;
+export const MAX_TOTAL_UNCOMPRESSED_BYTES = 8 * 1024 * 1024 * 1024;
+
+export function mediaExtension(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot < 0 ? "" : name.slice(dot).toLowerCase();
+}
+
+export function hasAllowedMediaExtension(name: string): boolean {
+  return (ALLOWED_MEDIA_EXTENSIONS as readonly string[]).includes(mediaExtension(name));
+}
+
+export const isAllowedMediaFile = hasAllowedMediaExtension;
+
+function startsWith(bytes: Uint8Array, signature: number[], offset = 0): boolean {
+  if (bytes.length < offset + signature.length) return false;
+  for (let i = 0; i < signature.length; i += 1) {
+    if (bytes[offset + i] !== signature[i]) return false;
+  }
+  return true;
+}
+
+function ascii(bytes: Uint8Array, from: number, length: number): string {
+  let out = "";
+  for (let i = from; i < Math.min(bytes.length, from + length); i += 1) {
+    out += String.fromCharCode(bytes[i]!);
+  }
+  return out;
+}
+
+export function looksLikeMarkup(bytes: Uint8Array): boolean {
+  let index = startsWith(bytes, [0xef, 0xbb, 0xbf]) ? 3 : 0;
+  while (index < bytes.length && [0x09, 0x0a, 0x0d, 0x20].includes(bytes[index]!)) index += 1;
+  const head = ascii(bytes, index, 512).toLowerCase();
+  if (!head.startsWith("<")) return false;
+  return (
+    head.startsWith("<!doctype") ||
+    head.startsWith("<html") ||
+    head.startsWith("<head") ||
+    head.startsWith("<body") ||
+    head.startsWith("<script") ||
+    head.startsWith("<svg") ||
+    head.startsWith("<?xml") ||
+    head.startsWith("<!--")
+  );
+}
+
+export function sniffMediaType(bytes: Uint8Array): string | null {
+  if (startsWith(bytes, [0xff, 0xd8, 0xff])) return "image/jpeg";
+  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return "image/png";
+  if (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a") return "image/gif";
+  if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 4) === "WEBP") return "image/webp";
+  if (ascii(bytes, 0, 4) === "%PDF") return "application/pdf";
+  if (startsWith(bytes, [0x1a, 0x45, 0xdf, 0xa3])) return "video/webm";
+  if (ascii(bytes, 4, 4) === "ftyp") {
+    const brand = ascii(bytes, 8, 4).toLowerCase();
+    if (brand.startsWith("avif") || brand.startsWith("avis")) return "image/avif";
+    if (brand.startsWith("qt")) return "video/quicktime";
+    return "video/mp4";
+  }
+  return null;
+}
+
+const TYPE_EXTENSIONS: Record<string, string[]> = {
+  "image/jpeg": [".jpg", ".jpeg"],
+  "image/png": [".png"],
+  "image/gif": [".gif"],
+  "image/webp": [".webp"],
+  "image/avif": [".avif"],
+  "application/pdf": [".pdf"],
+  "video/webm": [".webm"],
+  "video/mp4": [".mp4", ".mov", ".webm"],
+  "video/quicktime": [".mov", ".mp4"],
+};
+
+export type MediaVerdict = { ok: true; type: string } | { ok: false; reason: string };
+
+export function verifyMediaFile(name: string, bytes: Uint8Array): MediaVerdict {
+  const extension = mediaExtension(name);
+  if (!extension) return { ok: false, reason: "no file extension" };
+  if (!hasAllowedMediaExtension(name)) {
+    return { ok: false, reason: `extension ${extension} is not media` };
+  }
+  if (!bytes.byteLength) return { ok: false, reason: "empty file" };
+  if (bytes.byteLength > MAX_MEDIA_ENTRY_BYTES) return { ok: false, reason: "file too large" };
+  if (looksLikeMarkup(bytes)) return { ok: false, reason: "content is markup, not media" };
+  const type = sniffMediaType(bytes);
+  if (!type) return { ok: false, reason: "unrecognised file signature" };
+  if (!(TYPE_EXTENSIONS[type] ?? []).includes(extension)) {
+    return { ok: false, reason: `content is ${type} but named ${extension}` };
+  }
+  return { ok: true, type };
+}
+
+export function isSafeArchivePath(name: string): boolean {
+  if (!name || name.length > 1024) return false;
+  if (name.startsWith("/") || name.startsWith("\\")) return false;
+  if (/^[a-zA-Z]:[\\/]/.test(name)) return false;
+  if (name.includes("\\") || name.includes("\0")) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f]/.test(name)) return false;
+  if (name.split("/").some((segment) => segment === ".." || segment === "." || segment === "")) {
+    return false;
+  }
+  return true;
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  return prototype === Object.prototype || prototype === null;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const chunkSize = 0x8000;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+  return btoa(binary);
+}
+
+export function toJsonSafe<T>(value: T): T {
+  const walk = (input: unknown): unknown => {
+    if (input === null || input === undefined) return input;
+    if (input instanceof Date) return input.toISOString();
+    if (typeof input === "bigint") return input.toString();
+    if (Array.isArray(input)) return input.map(walk);
+    if (typeof input === "object") {
+      if (input instanceof ArrayBuffer) return bytesToBase64(new Uint8Array(input));
+      if (ArrayBuffer.isView(input)) {
+        return bytesToBase64(new Uint8Array(input.buffer, input.byteOffset, input.byteLength));
+      }
+      if (!isPlainObject(input)) {
+        const maybeJson = input as { toJSON?: () => unknown };
+        if (typeof maybeJson.toJSON === "function") return walk(maybeJson.toJSON());
+        return String(input);
+      }
+      const out: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(input)) out[key] = walk(item);
+      return out;
+    }
+    if (typeof input === "number" && !Number.isFinite(input)) return null;
+    return input;
+  };
+  return walk(value) as T;
+}
+
+export function nonJsonSafePaths(value: unknown, prefix = ""): string[] {
+  const out: string[] = [];
+  const walk = (input: unknown, path: string): void => {
+    if (input === null || input === undefined) return;
+    if (input instanceof Date || typeof input === "bigint") {
+      out.push(path || "(root)");
+      return;
+    }
+    if (Array.isArray(input)) {
+      input.forEach((item, index) => walk(item, `${path}[${index}]`));
+      return;
+    }
+    if (typeof input === "object") {
+      if (!isPlainObject(input)) {
+        out.push(path || "(root)");
+        return;
+      }
+      for (const [key, item] of Object.entries(input)) walk(item, path ? `${path}.${key}` : key);
+    }
+  };
+  walk(value, prefix);
+  return out;
+}
+
+const SECRET_KEY_RE =
+  /(password|passwd|secret|token|api[_-]?key|apikey|private[_-]?key|credential|client[_-]?secret|access[_-]?key|authorization)/i;
+const SECRET_NAME_KEY_RE = /(secret_name|secret_ref_name|_secret_ref|ref_name|key_id|_name)$/i;
+
+export function sanitizeSecrets<T>(value: T): T {
+  const walk = (input: unknown): unknown => {
+    if (input instanceof Date) return input.toISOString();
+    if (Array.isArray(input)) return input.map(walk);
+    if (input && typeof input === "object") {
+      if (!isPlainObject(input)) return toJsonSafe(input);
+      const out: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(input)) {
+        out[key] =
+          SECRET_KEY_RE.test(key) && !SECRET_NAME_KEY_RE.test(key) && item != null
+            ? null
+            : walk(item);
+      }
+      return out;
+    }
+    return toJsonSafe(input);
+  };
+  return walk(value) as T;
+}
+
+export const HOSTED_MEDIA_URL_RE =
+  /https?:\/\/[a-z0-9-]+\.supabase\.co\/storage\/v1\/object\/public\/media\//gi;
+
+export function rewriteMediaUrls<T>(value: T, base: string): T {
+  const prefix = base.endsWith("/") ? base : `${base}/`;
+  const walk = (input: unknown): unknown => {
+    if (typeof input === "string") return input.replace(HOSTED_MEDIA_URL_RE, prefix);
+    if (Array.isArray(input)) return input.map(walk);
+    if (input && typeof input === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(input as Record<string, unknown>)) {
+        out[key] = walk(item);
+      }
+      return out;
+    }
+    return input;
+  };
+  return walk(value) as T;
+}
+
+export function neutralizeInjection<T extends Record<string, unknown>>(
+  row: T,
+  keepEnabled: boolean,
+): T {
+  return keepEnabled ? row : { ...row, enabled: false };
+}

package/src/backup/verification.ts

@@ -0,0 +1,80 @@
+import { HOSTED_MEDIA_URL_RE } from "./safety";
+
+export type UserRow = { id: string; email: string | null };
+export type RoleRow = { user_id: string; role: string };
+
+export function compareCounts(
+  expected: Record<string, number>,
+  actual: Record<string, number>,
+  insertOnly: string[] = [],
+): string[] {
+  const problems: string[] = [];
+  for (const [table, wanted] of Object.entries(expected)) {
+    const found = actual[table];
+    if (found == null) problems.push(`${table}: table missing in target`);
+    else if (found !== wanted && !(insertOnly.includes(table) && found > wanted)) {
+      problems.push(`${table}: expected ${wanted} rows, found ${found}`);
+    }
+  }
+  return problems;
+}
+
+export function compareUsersAndRoles(
+  expectedUsers: UserRow[],
+  expectedRoles: RoleRow[],
+  actualUsers: UserRow[],
+  actualRoles: RoleRow[],
+): string[] {
+  const problems: string[] = [];
+  const actualById = new Map(actualUsers.map((user) => [user.id, user]));
+  for (const user of expectedUsers) {
+    const found = actualById.get(user.id);
+    if (!found) problems.push(`user ${user.id} is missing`);
+    else if ((found.email ?? null) !== (user.email ?? null)) {
+      problems.push(`user ${user.id} has a different email`);
+    }
+  }
+  const key = (role: RoleRow) => `${role.user_id}:${role.role}`;
+  const actualRoleSet = new Set(actualRoles.map(key));
+  for (const role of expectedRoles) {
+    if (!actualRoleSet.has(key(role))) {
+      problems.push(`role ${role.role} for ${role.user_id} is missing`);
+    }
+  }
+  for (const role of actualRoles.filter((item) => !actualById.has(item.user_id))) {
+    problems.push(`role ${role.role} references unknown user ${role.user_id}`);
+  }
+  return problems;
+}
+
+export function findHostedMediaUrls(rows: { table: string; json: string }[]): string[] {
+  const problems: string[] = [];
+  for (const row of rows) {
+    const expression = new RegExp(HOSTED_MEDIA_URL_RE.source, "gi");
+    const match = expression.exec(row.json);
+    if (match) problems.push(`${row.table}: still references ${match[0]}`);
+  }
+  return problems;
+}
+
+export function findMissingMedia(expected: string[], present: Set<string>): string[] {
+  return expected
+    .filter((path) => !present.has(path))
+    .map((path) => `media file missing on disk: ${path}`);
+}
+
+export type VerifyReport = { checks: { name: string; problems: string[] }[] };
+
+export function reportOk(report: VerifyReport): boolean {
+  return report.checks.every((check) => check.problems.length === 0);
+}
+
+export function formatReport(report: VerifyReport): string {
+  const lines: string[] = [];
+  for (const check of report.checks) {
+    lines.push(`[${check.problems.length === 0 ? "PASS" : "FAIL"}] ${check.name}`);
+    for (const problem of check.problems) lines.push(`        - ${problem}`);
+  }
+  lines.push(reportOk(report) ? "\nVerification passed." : "\nVerification FAILED.");
+  return lines.join("\n");
+}

package/src/host/index.tsx

@@ -89,6 +89,22 @@ export function registerHostComponents(components: Partial<HostComponents>): voi
   hosts = { ...hosts, ...components };
 }
 
+/**
+ * Register a site's host components as part of constructing a value the site
+ * actually exports or renders.
+ *
+ * Prefer this over a side-effect-only import. Applications whose package
+ * metadata declares `sideEffects: false` may otherwise lose their registration
+ * module during an optimized build even though development still works.
+ */
+export function initializeHostComponents<T>(
+  components: Partial<HostComponents>,
+  initialize: () => T,
+): T {
+  registerHostComponents(components);
+  return initialize();
+}
+
 function missing(name: keyof HostComponents): never {
   throw new Error(
     `@bygghammar/cms-platform: host "${name}" is not registered. Call registerHostComponents() during site startup.`,