@bygghammar/cms-platform 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.9.0",
+  "version": "0.11.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,
@@ -87,7 +87,10 @@
     "./backoffice/SaveGlobalDialog": "./src/backoffice/SaveGlobalDialog.tsx",
     "./backoffice/BlockPicker": "./src/backoffice/BlockPicker.tsx",
     "./backoffice/media/FocusPicker": "./src/backoffice/media/FocusPicker.tsx",
-    "./backoffice/media/MediaMetaDialog": "./src/backoffice/media/MediaMetaDialog.tsx"
+    "./backoffice/media/MediaMetaDialog": "./src/backoffice/media/MediaMetaDialog.tsx",
+    "./backoffice/SectionThumb": "./src/backoffice/SectionThumb.tsx",
+    "./backoffice/PageImagePicker": "./src/backoffice/PageImagePicker.tsx",
+    "./backoffice/seo/page-seo-form": "./src/backoffice/seo/page-seo-form.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/backoffice/PageImagePicker.tsx

@@ -0,0 +1,157 @@
+import { useState } from "react";
+import { Images, X } from "lucide-react";
+
+export type PageImageCandidate = {
+  url: string;
+  /** Where the image was found — e.g. "Hero" or "Site · gallery". */
+  source: string;
+  /** Hero-ish images float to the top of the list. */
+  hero: boolean;
+};
+
+const VIDEO_RE = /\.(mp4|webm|mov|m3u8)(\?|$)/i;
+
+export function isPickableImageUrl(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 4 &&
+    /^(https?:\/\/|\/)/.test(value) &&
+    !VIDEO_RE.test(value) &&
+    (/\.(png|jpe?g|webp|avif|gif|svg)(\?|$)/i.test(value) ||
+      value.includes("/storage/v1/object/public/"))
+  );
+}
+
+/** Recursively collect every image URL inside an arbitrary props/content tree. */
+export function collectImages(node: unknown, out: string[], depth = 0) {
+  if (node == null || depth > 8) return;
+  if (typeof node === "string") {
+    if (isPickableImageUrl(node)) out.push(node);
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) collectImages(item, out, depth + 1);
+    return;
+  }
+  if (typeof node === "object") {
+    for (const value of Object.values(node as Record<string, unknown>)) {
+      collectImages(value, out, depth + 1);
+    }
+  }
+}
+
+export function isHeroishLabel(label: string) {
+  return /hero|header|cover|banner/i.test(label);
+}
+
+export type PageImageSource = {
+  /** Page-builder blocks (already resolved, including referenced globals). */
+  blocks?: ReadonlyArray<{ type: string; name?: string | null; props?: unknown }>;
+  /** Shared site-content sections keyed by section name. */
+  siteSections?: Record<string, unknown>;
+};
+
+/**
+ * Gathers every image rendered on a page: first from the page-builder blocks,
+ * then from the shared site content sections used by coded pages.
+ *
+ * Host-agnostic: the host supplies already-fetched blocks and site sections.
+ */
+export function buildPageImageCandidates({
+  blocks,
+  siteSections,
+}: PageImageSource): PageImageCandidate[] {
+  const seen = new Set<string>();
+  const list: PageImageCandidate[] = [];
+  const push = (url: string, source: string, hero: boolean) => {
+    if (seen.has(url)) return;
+    seen.add(url);
+    list.push({ url, source, hero });
+  };
+
+  for (const block of blocks ?? []) {
+    const label = block.name || block.type;
+    const urls: string[] = [];
+    collectImages(block.props, urls);
+    for (const url of urls) push(url, label, isHeroishLabel(label));
+  }
+
+  for (const [key, value] of Object.entries(siteSections ?? {})) {
+    const urls: string[] = [];
+    collectImages(value, urls);
+    for (const url of urls) push(url, `Site · ${key}`, isHeroishLabel(key));
+  }
+
+  return list.sort((a, b) => Number(b.hero) - Number(a.hero));
+}
+
+export function PageImagePickerDialog({
+  candidates,
+  onPick,
+  onClose,
+}: {
+  candidates: PageImageCandidate[];
+  onPick: (url: string) => void;
+  onClose: () => void;
+}) {
+  const [q, setQ] = useState("");
+  const filtered = candidates.filter(
+    (c) =>
+      !q ||
+      c.url.toLowerCase().includes(q.toLowerCase()) ||
+      c.source.toLowerCase().includes(q.toLowerCase()),
+  );
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
+      onClick={onClose}
+    >
+      <div
+        className="w-full max-w-4xl max-h-[85vh] bg-white border border-ink/15 flex flex-col"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center gap-2 border-b border-ink/10 p-3">
+          <Images className="size-4 text-ink/60" />
+          <span className="text-sm font-medium text-ink">Images on this page</span>
+          <input
+            value={q}
+            onChange={(e) => setQ(e.target.value)}
+            placeholder="Search…"
+            className="ml-3 flex-1 border border-ink/15 px-2 py-1 text-sm focus:outline-none focus:border-sea"
+          />
+          <button onClick={onClose} className="text-ink/50 hover:text-ink p-1">
+            <X className="size-4" />
+          </button>
+        </div>
+        <div className="flex-1 overflow-auto p-3">
+          {filtered.length === 0 ? (
+            <div className="text-sm text-ink/60">No images found on this page yet.</div>
+          ) : (
+            <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-3">
+              {filtered.map((c) => (
+                <button
+                  key={c.url}
+                  type="button"
+                  onClick={() => {
+                    onPick(c.url);
+                    onClose();
+                  }}
+                  className="group border border-ink/10 hover:border-sea text-left"
+                >
+                  <img src={c.url} alt="" loading="lazy" className="h-28 w-full object-cover" />
+                  <div className="p-2">
+                    <div className="truncate text-xs text-ink">{c.source}</div>
+                    <div className="truncate text-[0.65rem] text-ink/45">
+                      {decodeURIComponent(c.url.split("/").pop() ?? "")}
+                    </div>
+                  </div>
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/backoffice/SectionThumb.tsx

@@ -0,0 +1,389 @@
+import { useMemo, type ComponentType } from "react";
+import { Layout } from "lucide-react";
+
+/**
+ * Static, cheap section/block thumbnail.
+ *
+ * Renders directly from the *saved* block data, so it only changes when an
+ * editor saves — no live iframe, no per-render reload. Images use the smallest
+ * responsive variant available.
+ */
+
+const THUMB_W = 128;
+const THUMB_H = 80;
+
+const VARIANT_RE = /-(480|768|1200|1920)\.webp(\?.*)?$/i;
+
+/** Prefer the tiny 480px WebP variant when the asset has one. */
+function smallestVariant(url: string): string {
+  const m = url.match(VARIANT_RE);
+  if (!m) return url;
+  return `${url.slice(0, url.length - m[0].length)}-480.webp${m[2] ?? ""}`;
+}
+
+function isImageUrl(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0) return false;
+  if (!/^(https?:\/\/|\/)/.test(value)) return false;
+  return !/\.(mp4|webm|mov)(\?|$)/i.test(value);
+}
+
+/** Image keys, in the order a block would actually render them. */
+const IMAGE_KEYS = [
+  "src",
+  "poster",
+  "posterSrc",
+  "url",
+  "image",
+  "imageSrc",
+  "thumbnail",
+  "backgroundImage",
+];
+
+/** Depth-first search for the first usable image URL inside a section blob. */
+function 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>;
+  // A block that renders video shows its poster — not an unused image prop.
+  const keys = obj["mediaType"] === "video" ? ["posterSrc", "poster", ...IMAGE_KEYS] : IMAGE_KEYS;
+  for (const key of keys) {
+    const value = obj[key];
+    if (isImageUrl(value)) return value;
+  }
+  for (const value of Object.values(obj)) {
+    const found = findImage(value, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function findText(node: unknown, depth = 0): string | null {
+  if (node == null || depth > 4) return null;
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const found = findText(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 ["title", "name", "label", "eyebrow"]) {
+    const value = obj[key];
+    if (typeof value === "string" && value.trim()) return value;
+    if (value && typeof value === "object") {
+      const sv = (value as Record<string, unknown>).sv;
+      if (typeof sv === "string" && sv.trim()) return sv;
+    }
+  }
+  return null;
+}
+
+/** Tiny schematic of a block's layout, so text-only blocks stay distinct. */
+function Wireframe({ blockType }: { blockType?: string }) {
+  const bar = (w: string, tone = "bg-ink/15") => <div className={`h-1 ${w} ${tone}`} />;
+  const box = (extra = "") => <div className={`bg-ink/10 ${extra}`} />;
+
+  switch (blockType) {
+    case "hero":
+      return (
+        <div className="flex size-full flex-col justify-end gap-1 bg-ink/70 p-2">
+          <div className="h-1 w-6 bg-sea" />
+          <div className="h-1.5 w-4/5 bg-white/80" />
+          <div className="h-1 w-3/5 bg-white/40" />
+        </div>
+      );
+    case "heroFull":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1 bg-ink/75 p-2">
+          <div className="h-1 w-8 bg-sea" />
+          <div className="h-2 w-4/5 bg-white/85" />
+          <div className="h-1 w-2/3 bg-white/45" />
+          <div className="mt-1 flex gap-1">
+            <div className="h-1.5 w-6 bg-white/80" />
+            <div className="h-1.5 w-6 border border-white/60" />
+          </div>
+        </div>
+      );
+    case "stats":
+      return (
+        <div className="grid size-full grid-cols-3 items-center gap-1 p-2">
+          {[0, 1, 2].map((i) => (
+            <div key={i} className="flex flex-col items-center gap-1">
+              <div className="h-2 w-5 bg-sea/60" />
+              <div className="h-1 w-6 bg-ink/15" />
+            </div>
+          ))}
+        </div>
+      );
+    case "features":
+      return (
+        <div className="grid size-full grid-cols-3 grid-rows-2 gap-1 p-2">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <div key={i} className="bg-ink/10" />
+          ))}
+        </div>
+      );
+    case "faq":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1.5 p-2">
+          {[0, 1, 2].map((i) => (
+            <div key={i} className="flex items-center gap-1">
+              <div className="size-1.5 bg-sea/60" />
+              {bar("flex-1")}
+            </div>
+          ))}
+        </div>
+      );
+    case "checklist":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1.5 p-2">
+          {[0, 1, 2, 3].map((i) => (
+            <div key={i} className="flex items-center gap-1">
+              <div className="size-1.5 rounded-full bg-sea/60" />
+              {bar(i % 2 ? "w-2/3" : "w-full")}
+            </div>
+          ))}
+        </div>
+      );
+    case "imageMarquee":
+      return (
+        <div className="grid size-full grid-cols-3 gap-1 p-2">
+          <div className="flex flex-col justify-center gap-1">
+            <div className="h-1 w-4/5 bg-ink/40" />
+            <div className="h-1 w-full bg-ink/15" />
+            <div className="h-1 w-3/4 bg-ink/15" />
+          </div>
+          <div className="flex flex-col gap-1">
+            <div className="h-4 bg-sea/25" />
+            <div className="h-5 bg-ink/15" />
+          </div>
+          <div className="flex flex-col justify-end gap-1">
+            <div className="h-5 bg-ink/15" />
+            <div className="h-4 bg-sea/25" />
+          </div>
+        </div>
+      );
+    case "iconGrid":
+      return (
+        <div className="grid size-full grid-cols-3 items-center gap-1 p-2">
+          {[0, 1, 2, 3, 4, 5].map((i) => (
+            <div key={i} className="flex flex-col items-center gap-1">
+              <div className="size-2 rounded-full border border-sea/70" />
+              <div className="h-1 w-5 bg-ink/15" />
+            </div>
+          ))}
+        </div>
+      );
+    case "richText":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1 p-2">
+          <div className="h-2 w-1/2 bg-ink/45" />
+          {bar("w-full")}
+          {bar("w-11/12")}
+          <div className="flex gap-1">
+            <div className="h-1 w-6 bg-sea/70" />
+            {bar("w-1/3")}
+          </div>
+          {bar("w-3/4")}
+        </div>
+      );
+    case "prose":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1 p-2">
+          <div className="h-1.5 w-2/3 bg-ink/40" />
+          {bar("w-full")}
+          {bar("w-full")}
+          {bar("w-4/5")}
+        </div>
+      );
+    case "tripList":
+    case "courseList":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1 p-2">
+          {[0, 1, 2].map((i) => (
+            <div
+              key={i}
+              className="flex items-center justify-between gap-2 border border-ink/10 px-1 py-0.5"
+            >
+              {bar("w-8")}
+              <div className="h-1 w-3 bg-sea/60" />
+            </div>
+          ))}
+        </div>
+      );
+    case "ctaBanner":
+    case "contactCta":
+      return (
+        <div className="flex size-full flex-col items-center justify-center gap-1 bg-sea/10 p-2">
+          <div className="h-1.5 w-3/5 bg-ink/35" />
+          {bar("w-2/5")}
+          <div className="mt-1 h-2 w-10 bg-sea/70" />
+        </div>
+      );
+    case "mediaSplit":
+      return (
+        <div className="grid size-full grid-cols-2 gap-1 p-2">
+          {box()}
+          <div className="flex flex-col justify-center gap-1">
+            <div className="h-1.5 w-4/5 bg-ink/30" />
+            {bar("w-full")}
+            {bar("w-3/5")}
+          </div>
+        </div>
+      );
+    case "gallery":
+      return (
+        <div className="grid size-full grid-cols-2 grid-rows-2 gap-1 p-2">
+          {box("row-span-2")}
+          {box()}
+          {box()}
+        </div>
+      );
+    case "testimonials":
+      return (
+        <div className="flex size-full items-center gap-1 p-2">
+          {[0, 1].map((i) => (
+            <div key={i} className="flex flex-1 flex-col gap-1 border border-ink/10 p-1">
+              {bar("w-full")}
+              {bar("w-3/4")}
+              <div className="mt-1 flex items-center gap-1">
+                <div className="size-2 rounded-full bg-ink/15" />
+                {bar("w-4")}
+              </div>
+            </div>
+          ))}
+        </div>
+      );
+    case "instagram":
+      return (
+        <div className="grid size-full grid-cols-4 grid-rows-2 gap-0.5 p-1.5">
+          {Array.from({ length: 8 }).map((_, i) => (
+            <div key={i} className="bg-ink/10" />
+          ))}
+        </div>
+      );
+    case "trips":
+    case "packages":
+    case "destinations":
+      return (
+        <div className="flex size-full items-stretch gap-1 p-2">
+          {[0, 1, 2].map((i) => (
+            <div key={i} className="flex flex-1 flex-col gap-1 border border-ink/10 p-1">
+              <div className="h-4 bg-ink/10" />
+              {bar("w-full")}
+            </div>
+          ))}
+        </div>
+      );
+    case "intro":
+      return (
+        <div className="flex size-full flex-col justify-center gap-1 p-2 text-center">
+          <div className="mx-auto h-1 w-4 bg-sea/60" />
+          <div className="mx-auto h-1.5 w-3/5 bg-ink/35" />
+          <div className="mx-auto h-1 w-4/5 bg-ink/15" />
+        </div>
+      );
+    case "globalRef":
+      return (
+        <div className="flex size-full flex-col items-center justify-center gap-1 border-2 border-dashed border-sea/40 p-2">
+          <Layout className="size-4 text-sea/60" />
+          <div className="h-1 w-8 bg-sea/30" />
+        </div>
+      );
+    default:
+      return (
+        <div className="flex size-full items-center justify-center">
+          <Layout className="size-5 text-ink/30" />
+        </div>
+      );
+  }
+}
+
+/**
+ * Same static thumbnail, driven by any saved data blob (e.g. the current
+ * global block list of a global block). Never renders video — only the first
+ * image / poster found in the data.
+ *
+ * Fallback order: image inside the data → `fallbackImage` (a reference image
+ * taken from a real usage of this block type) → a per-type layout wireframe.
+ */
+export type ThumbImageProps = {
+  src: string;
+  alt: string;
+  className?: string;
+  width?: number;
+  height?: number;
+  loading?: "lazy" | "eager";
+  decoding?: "async" | "sync" | "auto";
+  responsive?: boolean;
+  "aria-hidden"?: "true";
+};
+
+export function DataThumb({
+  data,
+  fallbackImage,
+  blockType,
+  Image = "img" as unknown as ComponentType<ThumbImageProps>,
+}: {
+  data: unknown;
+  fallbackImage?: string | null;
+  blockType?: string;
+  /** Host image component (e.g. a focal-point aware <img> wrapper). */
+  Image?: ComponentType<ThumbImageProps>;
+}) {
+  const { image, text } = useMemo(() => {
+    const found = findImage(data) ?? fallbackImage ?? null;
+    return {
+      image: found ? smallestVariant(found) : null,
+      text: findText(data),
+    };
+  }, [data, fallbackImage]);
+
+  const style = { width: THUMB_W, height: THUMB_H };
+
+  if (image) {
+    return (
+      <div
+        className="relative shrink-0 border border-ink/10 bg-ink/5 overflow-hidden"
+        style={style}
+      >
+        <Image
+          src={image}
+          responsive={false}
+          alt=""
+          aria-hidden="true"
+          loading="lazy"
+          decoding="async"
+          width={THUMB_W}
+          height={THUMB_H}
+          className="size-full object-cover"
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative shrink-0 border border-ink/10 bg-white overflow-hidden" style={style}>
+      {text && !blockType ? (
+        <div className="flex size-full flex-col justify-center gap-1.5 p-2">
+          <div className="h-1 w-6 bg-sea/60" />
+          <div className="text-[0.5rem] leading-tight text-ink/70 line-clamp-2 font-serif">
+            {text}
+          </div>
+          <div className="h-1 w-full bg-ink/10" />
+          <div className="h-1 w-3/4 bg-ink/10" />
+        </div>
+      ) : (
+        <Wireframe blockType={blockType} />
+      )}
+    </div>
+  );
+}

package/src/backoffice/seo/page-seo-form.ts

@@ -0,0 +1,216 @@
+/**
+ * Host-agnostic form logic for the page SEO editor.
+ *
+ * Pure functions only — no React, no data access. A host wires these to its
+ * own page registry, CMS overrides and save/reset server functions so the SEO
+ * screen behaves identically on every site.
+ */
+
+export type LocalizedField = Record<string, string>;
+
+export type PageSeoFormShape = {
+  slugs: LocalizedField;
+  seo: {
+    title: LocalizedField;
+    description: LocalizedField;
+    ogTitle: LocalizedField;
+    ogDescription: LocalizedField;
+    keywords: LocalizedField;
+    ogImageSrc: string;
+    ogImageAlt: LocalizedField;
+    robots: string;
+  };
+};
+
+/** Shape shared by a registry page definition and a CMS override row. */
+export type PageSeoSource = {
+  slug?: Partial<LocalizedField> | null;
+  seo?: {
+    title?: Partial<LocalizedField> | null;
+    description?: Partial<LocalizedField> | null;
+    ogTitle?: Partial<LocalizedField> | null;
+    ogDescription?: Partial<LocalizedField> | null;
+    keywords?: Partial<LocalizedField> | null;
+    ogImage?: { src?: string | null; alt?: Partial<LocalizedField> | null } | null;
+    robots?: string | null;
+  } | null;
+};
+
+/** Override rows store slugs under `slugs` rather than `slug`. */
+export type PageSeoOverrideSource = Omit<PageSeoSource, "slug"> & {
+  slugs?: Partial<LocalizedField> | null;
+};
+
+export type PageSeoSavePayload = {
+  pageKey: string;
+  slugs: LocalizedField;
+  seo: {
+    title?: LocalizedField;
+    description?: LocalizedField;
+    ogTitle?: LocalizedField;
+    ogDescription?: LocalizedField;
+    keywords?: LocalizedField;
+    ogImage?: { src: string; alt: LocalizedField };
+    robots?: string;
+  };
+};
+
+export function emptyLocalized(locales: readonly string[]): LocalizedField {
+  const out: LocalizedField = {};
+  for (const l of locales) out[l] = "";
+  return out;
+}
+
+/** Drop empty strings; returns undefined when nothing is left. */
+export function stripEmptyLocalized(obj: LocalizedField): LocalizedField | undefined {
+  const out: LocalizedField = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== "" && v != null) out[k] = v;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * Build the initial form state: registry defaults first, then any CMS override
+ * value that is explicitly present (including a deliberate empty string).
+ */
+export function buildPageSeoForm(args: {
+  locales: readonly string[];
+  def?: PageSeoSource | null;
+  override?: PageSeoOverrideSource | null;
+}): PageSeoFormShape {
+  const { locales, def, override } = args;
+  const form: PageSeoFormShape = {
+    slugs: emptyLocalized(locales),
+    seo: {
+      title: emptyLocalized(locales),
+      description: emptyLocalized(locales),
+      ogTitle: emptyLocalized(locales),
+      ogDescription: emptyLocalized(locales),
+      keywords: emptyLocalized(locales),
+      ogImageSrc: "",
+      ogImageAlt: emptyLocalized(locales),
+      robots: "",
+    },
+  };
+
+  if (def) {
+    for (const l of locales) {
+      form.slugs[l] = def.slug?.[l] ?? "";
+      form.seo.title[l] = def.seo?.title?.[l] ?? "";
+      form.seo.description[l] = def.seo?.description?.[l] ?? "";
+      form.seo.ogTitle[l] = def.seo?.ogTitle?.[l] ?? "";
+      form.seo.ogDescription[l] = def.seo?.ogDescription?.[l] ?? "";
+      form.seo.keywords[l] = def.seo?.keywords?.[l] ?? "";
+      form.seo.ogImageAlt[l] = def.seo?.ogImage?.alt?.[l] ?? "";
+    }
+    form.seo.ogImageSrc = def.seo?.ogImage?.src ?? "";
+    form.seo.robots = def.seo?.robots ?? "";
+  }
+
+  if (override) {
+    for (const l of locales) {
+      if (override.slugs?.[l] !== undefined) form.slugs[l] = override.slugs[l] ?? "";
+      if (override.seo?.title?.[l] !== undefined) form.seo.title[l] = override.seo.title[l] ?? "";
+      if (override.seo?.description?.[l] !== undefined)
+        form.seo.description[l] = override.seo.description[l] ?? "";
+      if (override.seo?.ogTitle?.[l] !== undefined)
+        form.seo.ogTitle[l] = override.seo.ogTitle[l] ?? "";
+      if (override.seo?.ogDescription?.[l] !== undefined)
+        form.seo.ogDescription[l] = override.seo.ogDescription[l] ?? "";
+      if (override.seo?.keywords?.[l] !== undefined)
+        form.seo.keywords[l] = override.seo.keywords[l] ?? "";
+      if (override.seo?.ogImage?.alt?.[l] !== undefined)
+        form.seo.ogImageAlt[l] = override.seo.ogImage.alt[l] ?? "";
+    }
+    if (override.seo?.ogImage?.src) form.seo.ogImageSrc = override.seo.ogImage.src;
+    if (override.seo?.robots !== undefined) form.seo.robots = override.seo.robots ?? "";
+  }
+
+  return form;
+}
+
+/** Build the save payload, omitting fields the editor left empty. */
+export function buildPageSeoSavePayload(args: {
+  pageKey: string;
+  locales: readonly string[];
+  form: PageSeoFormShape;
+}): PageSeoSavePayload {
+  const { pageKey, locales, form } = args;
+  const payload: PageSeoSavePayload = { pageKey, slugs: {}, seo: {} };
+
+  for (const l of locales) {
+    if (form.slugs[l] !== undefined) payload.slugs[l] = form.slugs[l];
+  }
+
+  const title = stripEmptyLocalized(form.seo.title);
+  const description = stripEmptyLocalized(form.seo.description);
+  const ogTitle = stripEmptyLocalized(form.seo.ogTitle);
+  const ogDescription = stripEmptyLocalized(form.seo.ogDescription);
+  const keywords = stripEmptyLocalized(form.seo.keywords);
+  const ogImageAlt = stripEmptyLocalized(form.seo.ogImageAlt);
+
+  if (title) payload.seo.title = title;
+  if (description) payload.seo.description = description;
+  if (ogTitle) payload.seo.ogTitle = ogTitle;
+  if (ogDescription) payload.seo.ogDescription = ogDescription;
+  if (keywords) payload.seo.keywords = keywords;
+  if (form.seo.robots) payload.seo.robots = form.seo.robots;
+  if (form.seo.ogImageSrc && ogImageAlt) {
+    payload.seo.ogImage = { src: form.seo.ogImageSrc, alt: ogImageAlt };
+  }
+
+  return payload;
+}
+
+/**
+ * Merge media-library metadata (alt / OG title / description) into the form.
+ * `overwrite` replaces values the editor already typed.
+ */
+export function mergeMediaMetaIntoForm(args: {
+  form: PageSeoFormShape;
+  locales: readonly string[];
+  meta: {
+    alt?: Partial<LocalizedField> | null;
+    title?: Partial<LocalizedField> | null;
+    description?: Partial<LocalizedField> | null;
+  };
+  overwrite: boolean;
+}): PageSeoFormShape {
+  const { form, locales, meta, overwrite } = args;
+  const merge = (current: LocalizedField, incoming?: Partial<LocalizedField> | null) => {
+    const next = { ...current };
+    if (!incoming) return next;
+    for (const l of locales) {
+      const value = incoming[l];
+      if (!value) continue;
+      if (overwrite || !next[l]) next[l] = value;
+    }
+    return next;
+  };
+  return {
+    ...form,
+    seo: {
+      ...form.seo,
+      ogImageAlt: merge(form.seo.ogImageAlt, meta.alt),
+      ogTitle: merge(form.seo.ogTitle, meta.title),
+      ogDescription: merge(form.seo.ogDescription, meta.description),
+    },
+  };
+}
+
+/** Locale-aware preview path: default locale has no prefix, empty slug = root. */
+export function pageSeoPreviewPath(args: {
+  slug: string;
+  locale: string;
+  defaultLocale: string;
+}): string {
+  const slug = args.slug ?? "";
+  if (args.locale === args.defaultLocale) return slug === "" ? "/" : `/${slug}`;
+  return slug === "" ? `/${args.locale}` : `/${args.locale}/${slug}`;
+}
+
+/** Absolute canonical preview URL; falls back to the path when no domain is known. */
+export function pageSeoPreviewCanonical(args: { path: string; origin?: string | null }): string {
+  return args.origin ? `https://${args.origin}${args.path}` : args.path;
+}