@bygghammar/cms-platform 0.46.1 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.48.0
+
+- Public-site media runtime is package-owned: new `media/FocalImage` (focus-aware `<img>`, `MediaFocusProvider`, `useFocalStyle`, `useObjectPosition`), `media/MediaMetaProvider` (alt/OG metadata context) and `media/LazyVideo` (bandwidth- and mobile-safe autoplay video). Sites pass their own focus/meta query options and register nothing else.
+- New `media/use-media-upload`: `useMediaUploadWith(uploadBundle, existing)` runs the shared optimize → upload → cache-invalidate pipeline with progress; only the storage call stays site-local.
+- New `cms/page-draft-store`: `createPageDraftStore({ prefix, channel })` gives a site the localStorage + BroadcastChannel draft bridge the page builder and preview routes share.
+
+## 0.47.0
+
+- Media server logic is package-owned: new `server/media-focus-core` (focus-point map, desktop/mobile upsert, clear), `server/media-meta-core` (localized alt/title/description/credit read and write) and `server/media-replace-core` (width-matched "replace everywhere" with audit trail).
+- New `server/media-cleanup-host`: `createSupabaseCleanupHost()` assembles the bin rows, `media_meta`/`media_focus` path moves and the cleanup audit entry, so a site only supplies its privileged client, storage and reference rewriter.
+
 ## 0.46.1
 
 - Page builder host contract: `renderEditor` now also receives `initialBlocks` (the server baseline) alongside the live canvas.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.46.1",
+  "version": "0.48.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,
@@ -166,7 +166,16 @@
     "./backoffice/ResetPasswordView": "./src/backoffice/ResetPasswordView.tsx",
     "./backoffice/routes/pages": "./src/backoffice/routes/pages.tsx",
     "./config/define-site": "./src/config/define-site.ts",
-    "./server/schema-drift": "./src/server/schema-drift.ts"
+    "./server/schema-drift": "./src/server/schema-drift.ts",
+    "./server/media-focus-core": "./src/server/media-focus-core.ts",
+    "./server/media-meta-core": "./src/server/media-meta-core.ts",
+    "./server/media-replace-core": "./src/server/media-replace-core.ts",
+    "./server/media-cleanup-host": "./src/server/media-cleanup-host.ts",
+    "./media/FocalImage": "./src/media/FocalImage.tsx",
+    "./media/MediaMetaProvider": "./src/media/MediaMetaProvider.tsx",
+    "./media/LazyVideo": "./src/media/LazyVideo.tsx",
+    "./media/use-media-upload": "./src/media/use-media-upload.ts",
+    "./cms/page-draft-store": "./src/cms/page-draft-store.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -243,4 +252,4 @@
     "cms-platform-migrations": "scripts/sync-migrations.mjs",
     "create-cms-site": "./scripts/create-cms-site.mjs"
   }
-}
+}

package/src/cms/page-draft-store.ts

@@ -0,0 +1,121 @@
+/**
+ * Per-page draft store shared by every site.
+ *
+ * The page builder writes an unsaved snapshot to `localStorage` and broadcasts
+ * it so the preview route can render it live. Only the storage prefix and the
+ * broadcast channel name differ per site, so both are parameters.
+ */
+
+export type PageDraftSnapshot<TBlock = unknown> = {
+  blocks: TBlock[];
+  globals: Record<string, TBlock[]>;
+  locale?: string;
+  updatedAt: number;
+};
+
+export type PageDraftStoreOptions = {
+  /** localStorage key prefix, e.g. `"voyara:draft:"`. */
+  prefix: string;
+  /** BroadcastChannel name, e.g. `"voyara-page-draft"`. */
+  channel: string;
+};
+
+export type PageDraftStore<TBlock = unknown> = {
+  draftKey: (pageKey: string) => string;
+  writeDraft: (pageKey: string, snap: Omit<PageDraftSnapshot<TBlock>, "updatedAt">) => void;
+  readDraft: (pageKey: string) => PageDraftSnapshot<TBlock> | null;
+  clearDraft: (pageKey: string) => void;
+  subscribeDraft: (pageKey: string, cb: (snap: PageDraftSnapshot<TBlock>) => void) => () => void;
+};
+
+export function createPageDraftStore<TBlock = unknown>(
+  options: PageDraftStoreOptions,
+): PageDraftStore<TBlock> {
+  const draftKey = (pageKey: string) => `${options.prefix}${pageKey}`;
+
+  const openChannel = (): BroadcastChannel | null => {
+    if (typeof window === "undefined" || typeof BroadcastChannel === "undefined") return null;
+    try {
+      return new BroadcastChannel(options.channel);
+    } catch {
+      return null;
+    }
+  };
+
+  const isSnapshot = (value: unknown): value is PageDraftSnapshot<TBlock> =>
+    !!value && Array.isArray((value as PageDraftSnapshot<TBlock>).blocks);
+
+  return {
+    draftKey,
+
+    writeDraft(pageKey, snap) {
+      if (typeof window === "undefined") return;
+      const payload: PageDraftSnapshot<TBlock> = { ...snap, updatedAt: Date.now() };
+      try {
+        window.localStorage.setItem(draftKey(pageKey), JSON.stringify(payload));
+      } catch {
+        /* quota or disabled storage — preview falls back to published */
+      }
+      const bc = openChannel();
+      if (bc) {
+        try {
+          bc.postMessage({ pageKey, snapshot: payload });
+        } finally {
+          bc.close();
+        }
+      }
+    },
+
+    readDraft(pageKey) {
+      if (typeof window === "undefined") return null;
+      try {
+        const raw = window.localStorage.getItem(draftKey(pageKey));
+        if (!raw) return null;
+        const parsed = JSON.parse(raw) as unknown;
+        return isSnapshot(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+
+    clearDraft(pageKey) {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.removeItem(draftKey(pageKey));
+      } catch {
+        /* ignore */
+      }
+    },
+
+    subscribeDraft(pageKey, cb) {
+      if (typeof window === "undefined") return () => {};
+
+      const onStorage = (e: StorageEvent) => {
+        if (e.key !== draftKey(pageKey) || !e.newValue) return;
+        try {
+          const parsed = JSON.parse(e.newValue) as unknown;
+          if (isSnapshot(parsed)) cb(parsed);
+        } catch {
+          /* ignore */
+        }
+      };
+      window.addEventListener("storage", onStorage);
+
+      const bc = openChannel();
+      const onMsg = (ev: MessageEvent) => {
+        const d = ev.data as { pageKey?: string; snapshot?: unknown } | undefined;
+        if (!d || d.pageKey !== pageKey) return;
+        if (isSnapshot(d.snapshot)) cb(d.snapshot);
+      };
+      bc?.addEventListener("message", onMsg);
+
+      return () => {
+        window.removeEventListener("storage", onStorage);
+        if (bc) {
+          bc.removeEventListener("message", onMsg);
+          bc.close();
+        }
+      };
+    },
+  };
+}

package/src/media/FocalImage.tsx

@@ -0,0 +1,152 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type CSSProperties,
+  type ImgHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { useQuery } from "@tanstack/react-query";
+
+import {
+  focalCssVars,
+  focalToObjectPosition,
+  lookupEntry,
+  lookupFocal,
+  type FocusMap,
+} from "./focus";
+import { responsiveImage } from "./srcset";
+
+const FocusContext = createContext<FocusMap>({});
+
+/** Structural shape of a site's `queryOptions(...)` for its focus map. */
+export type FocusQueryOptions = {
+  queryKey: readonly unknown[];
+  queryFn: () => Promise<FocusMap>;
+  staleTime?: number;
+};
+
+/**
+ * Provides the site's saved focus points to every `FocalImage` below it.
+ * The query itself is site infrastructure and is passed in.
+ */
+export function MediaFocusProvider({
+  queryOptions,
+  children,
+}: {
+  queryOptions: FocusQueryOptions;
+  children: ReactNode;
+}) {
+  const { data } = useQuery({ ...queryOptions, placeholderData: {} as FocusMap });
+  return <FocusContext.Provider value={data ?? {}}>{children}</FocusContext.Provider>;
+}
+
+export function useFocusMap(): FocusMap {
+  return useContext(FocusContext);
+}
+
+/** `object-position` for a given image URL, honouring its saved focus point. */
+export function useObjectPosition(src: string | undefined): string {
+  const map = useFocusMap();
+  return focalToObjectPosition(lookupFocal(map, src));
+}
+
+/**
+ * Class + inline CSS vars that apply the desktop focus point and, when set,
+ * a separate mobile focus point (below 768px).
+ */
+export function useFocalStyle(src: string | undefined): {
+  className: string;
+  style: CSSProperties;
+} {
+  const map = useFocusMap();
+  return {
+    className: "focal-pos",
+    style: focalCssVars(lookupEntry(map, src)) as CSSProperties,
+  };
+}
+
+export type FocalImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> & {
+  src: string | undefined;
+  /** When set, builds a responsive srcSet from the media library variants. */
+  sizes?: string;
+  responsive?: boolean;
+};
+
+/**
+ * `<img>` that always crops around the image's editor-chosen focus point.
+ * Falls back to a centred crop when no focus point is stored.
+ *
+ * When the source is a responsive WebP variant with a `-fallback.png` sibling,
+ * renders a `<picture>` so browsers that do not support WebP (or need explicit
+ * alpha handling) still receive a transparent PNG.
+ */
+export function FocalImage({
+  src,
+  sizes,
+  responsive = true,
+  style,
+  onError,
+  ...rest
+}: FocalImageProps) {
+  const focal = useFocalStyle(src);
+  // Uploads of small source images skip the intermediate widths, so a candidate
+  // in the srcSet can be missing. If the browser picks one of those, fall back
+  // to the stored URL on its own — never leave a blank space on the page.
+  const [srcSetFailed, setSrcSetFailed] = useState(false);
+  useEffect(() => setSrcSetFailed(false), [src]);
+
+  const img = responsive && !srcSetFailed ? responsiveImage(src, sizes) : { src: src ?? "" };
+  const merged: CSSProperties = { ...focal.style, ...style };
+  const className = [focal.className, rest.className].filter(Boolean).join(" ");
+
+  // Only wrap in <picture> when a fallback PNG is advertised. The fallback URL
+  // is always derived, but it only exists for transparent uploads; using it for
+  // every image would cause unnecessary 404s on opaque assets.
+  const hasFallback =
+    "fallbackSrc" in img &&
+    img.fallbackSrc &&
+    // A missing fallback is indistinguishable from an opaque asset, so we only
+    // render the <source> when the primary URL is definitely a responsive WebP.
+    img.type === "image/webp" &&
+    img.srcSet;
+
+  if (hasFallback && "fallbackSrc" in img) {
+    // The <picture> is only a source selector: it must not take the layout or
+    // focus classes, or the inner <img> loses `object-position` and the crop
+    // ignores the editor-chosen focus point.
+    return (
+      <picture style={{ display: "contents" }}>
+        <source srcSet={img.srcSet} sizes={img.sizes} type="image/webp" />
+        <img
+          {...rest}
+          className={className}
+          src={img.fallbackSrc}
+          alt={rest.alt}
+          style={merged}
+          onError={(event) => {
+            if (!srcSetFailed) setSrcSetFailed(true);
+            onError?.(event);
+          }}
+        />
+      </picture>
+    );
+  }
+
+  return (
+    <img
+      {...rest}
+      className={className}
+      src={img.src}
+      srcSet={"srcSet" in img ? img.srcSet : undefined}
+      sizes={"sizes" in img ? img.sizes : undefined}
+      alt={rest.alt}
+      style={merged}
+      onError={(event) => {
+        if (!srcSetFailed) setSrcSetFailed(true);
+        onError?.(event);
+      }}
+    />
+  );
+}

package/src/media/LazyVideo.tsx

@@ -0,0 +1,202 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useT } from "../i18n/context";
+import { resolveMediaSrc } from "./urls";
+
+/**
+ * Bandwidth-safe, mobile-safe <video> wrapper.
+ *
+ * Mobile browsers (iOS Safari in particular) only start an inline autoplaying
+ * video when `muted`, `playsinline` and `autoplay` are present as real
+ * attributes on the element that owns the media, and when at least one source
+ * is present when the element is parsed. Sources are therefore always
+ * rendered — the download itself stays cheap because `preload` is `none`
+ * until the element is near the viewport.
+ *
+ *  - the poster paints first (cheap image, correct visual design),
+ *  - `preload` is upgraded to the caller's hint once near the viewport,
+ *  - a timeout fallback guarantees the video is never left permanently
+ *    unloaded when IntersectionObserver never fires,
+ *  - `play()` is called explicitly and its promise is always caught: a refused
+ *    autoplay never crashes the page, it reveals an accessible tap-to-play
+ *    button over the poster,
+ *  - reduced motion keeps the poster and the tap-to-play button instead of
+ *    removing the media.
+ */
+export type LazyVideoProps = {
+  src?: string;
+  /** Optional alternative sources (e.g. WebM) tried before `src`. */
+  sources?: Array<{ src: string; type: string }>;
+  poster?: string;
+  className?: string;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  /** Preload hint used once the element is near the viewport. */
+  preload?: "none" | "metadata" | "auto";
+  ariaLabel?: string;
+  /** Localized accessible label for the tap-to-play fallback control. */
+  playLabel?: { sv: string } & Record<string, string>;
+};
+
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * Order the sources so the broadly compatible MP4/H.264 rendition is always
+ * offered. Safari picks the first source it claims to support, and some iOS
+ * versions claim WebM support they cannot actually decode, so MP4 goes first.
+ */
+export function orderedSources(
+  rawSrc: string | undefined,
+  rawSources: Array<{ src: string; type: string }> | undefined,
+): Array<{ src: string; type: string }> {
+  const src = resolveMediaSrc(rawSrc);
+  const sources = rawSources?.map((s) => ({ ...s, src: resolveMediaSrc(s.src) }));
+  const list =
+    sources && sources.length ? [...sources] : src ? [{ src, type: guessType(src) }] : [];
+  const seen = new Set<string>();
+  const unique = list.filter((s) => {
+    if (!s.src || seen.has(s.src)) return false;
+    seen.add(s.src);
+    return true;
+  });
+  if (src && !seen.has(src)) unique.push({ src, type: guessType(src) });
+  const rank = (type: string) => (/mp4/i.test(type) ? 0 : /webm/i.test(type) ? 1 : 2);
+  return unique.sort((a, b) => rank(a.type) - rank(b.type));
+}
+
+function guessType(url: string): string {
+  const clean = url.split("?")[0]!.toLowerCase();
+  if (clean.endsWith(".webm")) return "video/webm";
+  if (clean.endsWith(".mov")) return "video/quicktime";
+  return "video/mp4";
+}
+
+export function LazyVideo({
+  src,
+  sources,
+  poster,
+  className,
+  autoPlay = true,
+  loop = true,
+  muted = true,
+  controls = false,
+  preload = "metadata",
+  ariaLabel,
+  playLabel,
+}: LazyVideoProps) {
+  const { t } = useT();
+  const ref = useRef<HTMLVideoElement>(null);
+  const [active, setActive] = useState(false);
+  const [reduced, setReduced] = useState(false);
+  const [blocked, setBlocked] = useState(false);
+
+  const list = orderedSources(src, sources);
+
+  useEffect(() => {
+    setReduced(prefersReducedMotion());
+  }, []);
+
+  useEffect(() => {
+    if (active) return;
+    const el = ref.current;
+    if (!el) return;
+    if (typeof IntersectionObserver === "undefined") {
+      setActive(true);
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          setActive(true);
+          io.disconnect();
+        }
+      },
+      { rootMargin: "200px" },
+    );
+    io.observe(el);
+    // Never leave the video permanently unloaded (mobile browsers can skip
+    // observer callbacks for elements inside transformed/animated ancestors).
+    const timer = setTimeout(() => setActive(true), 3000);
+    return () => {
+      io.disconnect();
+      clearTimeout(timer);
+    };
+  }, [active]);
+
+  // Explicit playback attempt: a refused promise must never propagate.
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !active) return;
+    if (!autoPlay || reduced) return;
+    let cancelled = false;
+    el.muted = muted;
+    const attempt = el.play();
+    if (attempt && typeof attempt.catch === "function") {
+      attempt
+        .then(() => {
+          if (!cancelled) setBlocked(false);
+        })
+        .catch(() => {
+          if (!cancelled) setBlocked(true);
+        });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [active, autoPlay, muted, reduced]);
+
+  const play = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    setActive(true);
+    el.muted = muted;
+    const attempt = el.play();
+    if (attempt && typeof attempt.catch === "function") {
+      attempt.then(() => setBlocked(false)).catch(() => setBlocked(true));
+    }
+  }, [muted]);
+
+  const showPlayButton = !controls && (blocked || (reduced && autoPlay));
+
+  return (
+    <>
+      <video
+        ref={ref}
+        className={className}
+        poster={resolveMediaSrc(poster) || undefined}
+        preload={active ? preload : "none"}
+        autoPlay={autoPlay && !reduced}
+        loop={loop}
+        muted={muted}
+        controls={controls}
+        playsInline
+        aria-label={ariaLabel}
+      >
+        {list.map((s) => (
+          <source key={s.src} src={s.src} type={s.type} />
+        ))}
+      </video>
+      {showPlayButton ? (
+        <button
+          type="button"
+          onClick={play}
+          aria-label={t(
+            playLabel ?? { sv: ariaLabel ? `Spela upp ${ariaLabel}` : "Spela upp video" },
+          )}
+          className="absolute inset-0 z-10 grid place-items-center bg-transparent"
+        >
+          <span className="grid size-14 place-items-center rounded-full bg-white/85 text-black shadow-lg">
+            <svg viewBox="0 0 24 24" width="22" height="22" fill="currentColor" aria-hidden="true">
+              <path d="M8 5v14l11-7z" />
+            </svg>
+          </span>
+        </button>
+      ) : null}
+    </>
+  );
+}

package/src/media/MediaMetaProvider.tsx

@@ -0,0 +1,33 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+
+import { lookupMediaMeta, type MediaMeta, type MediaMetaMap } from "./media-meta";
+
+const MediaMetaContext = createContext<MediaMetaMap>({});
+
+/** Structural shape of a site's `queryOptions(...)` for its media metadata. */
+export type MediaMetaQueryOptions = {
+  queryKey: readonly unknown[];
+  queryFn: () => Promise<MediaMetaMap>;
+  staleTime?: number;
+};
+
+export function MediaMetaProvider({
+  queryOptions,
+  children,
+}: {
+  queryOptions: MediaMetaQueryOptions;
+  children: ReactNode;
+}) {
+  const { data } = useQuery({ ...queryOptions, placeholderData: {} as MediaMetaMap });
+  return <MediaMetaContext.Provider value={data ?? {}}>{children}</MediaMetaContext.Provider>;
+}
+
+export function useMediaMetaMap(): MediaMetaMap {
+  return useContext(MediaMetaContext);
+}
+
+/** Saved metadata (alt / OG title / description / credit) for one image URL. */
+export function useMediaMeta(src: string | undefined): MediaMeta {
+  return lookupMediaMeta(useMediaMetaMap(), src);
+}

package/src/media/use-media-upload.ts

@@ -0,0 +1,90 @@
+import { useCallback, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+import { optimizeForUpload } from "./optimize";
+import { pickVideoPoster } from "./pick-video-poster";
+import { cleanFileName, splitExt, uniqueFileName } from "./filename";
+
+export type UploadProgress = { label: string; percent: number } | null;
+
+/** One file in a site's media library, as far as uploading is concerned. */
+export type UploadExistingItem = { name: string };
+
+/** The site's server call that stores an already-optimized bundle. */
+export type UploadBundleFn = (input: {
+  data: {
+    files: Array<{ name: string; contentType: string; bytes: number[] }>;
+  };
+}) => Promise<{ urls: string[] }>;
+
+/**
+ * Shared browser-side media upload (optimize → storage → cache invalidate)
+ * with a coarse percentage so callers can render a progress bar.
+ *
+ * The storage call itself is site infrastructure and is injected.
+ */
+export function useMediaUploadWith(
+  uploadBundle: UploadBundleFn,
+  existing: UploadExistingItem[] = [],
+) {
+  const queryClient = useQueryClient();
+  const [progress, setProgress] = useState<UploadProgress>(null);
+  const [uploading, setUploading] = useState(false);
+
+  const upload = useCallback(
+    async (files: FileList | File[] | null): Promise<string[]> => {
+      const arr = files ? Array.from(files as ArrayLike<File>) : [];
+      if (!arr.length) return [];
+      setUploading(true);
+      const urls: string[] = [];
+      const taken = new Set<string>(
+        existing.flatMap((i) => {
+          const { base } = splitExt(i.name);
+          return [i.name, base, base.replace(/-(?:480|768|1200|1920)$/, "")];
+        }),
+      );
+      try {
+        for (let idx = 0; idx < arr.length; idx++) {
+          const file = arr[idx]!;
+          const step = (frac: number, label: string) =>
+            setProgress({
+              label: `${label} ${idx + 1}/${arr.length}: ${file.name}`,
+              percent: Math.round(((idx + frac) / arr.length) * 100),
+            });
+
+          // Videos: let the editor pick the poster frame before we transcode.
+          const posterTime = file.type.startsWith("video/") ? await pickVideoPoster(file) : null;
+
+          step(0.05, "Optimizing");
+          const { base } = splitExt(cleanFileName(file.name));
+          const baseSlug = uniqueFileName(base, taken);
+          taken.add(baseSlug);
+          const bundle = await optimizeForUpload(file, baseSlug, {
+            posterTime: posterTime ?? undefined,
+          });
+
+          step(0.4, "Uploading");
+          const all = [bundle.primary, ...bundle.extras];
+          const payload = await Promise.all(
+            all.map(async (part) => ({
+              name: part.name,
+              contentType: part.contentType,
+              bytes: Array.from(new Uint8Array(await part.blob.arrayBuffer())),
+            })),
+          );
+          const { urls: uploaded } = await uploadBundle({ data: { files: payload } });
+          urls.push(uploaded[0]!);
+          step(1, "Uploading");
+        }
+        await queryClient.invalidateQueries({ queryKey: ["media-library"] });
+        return urls;
+      } finally {
+        setUploading(false);
+        setProgress(null);
+      }
+    },
+    [existing, queryClient, uploadBundle],
+  );
+
+  return { upload, uploading, progress };
+}

package/src/server/media-cleanup-host.ts

@@ -0,0 +1,79 @@
+/**
+ * Supabase-backed `CleanupHost` for the media cleanup core.
+ *
+ * Every site stores media bookkeeping in the same three tables (`media_trash`,
+ * `media_meta`, `media_focus`) and the same `audit_logs` table, so the database
+ * side effects the cleanup core needs are platform logic, not site logic. A host
+ * supplies its privileged client, its storage provider and its reference
+ * rewriter; this factory assembles the rest.
+ */
+import { actorEmail, type PlatformAuthContext } from "./guards";
+import type { CleanupHost, CleanupStorage, MediaCleanupResult } from "./media-cleanup-core";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+const PATH_TABLES = ["media_meta", "media_focus"] as const;
+
+export type CleanupHostDeps = {
+  context: PlatformAuthContext;
+  /** Privileged client used for the bin rows, path moves and the audit entry. */
+  admin: any;
+  /** Storage bound to the privileged client (usually `getMediaStorage(admin)`). */
+  storage: CleanupStorage;
+  /** Repoint stored references from any of `oldUrls` to `newUrl`; returns hits. */
+  rewriteReferences: (oldUrls: string[], newUrl: string) => Promise<number>;
+};
+
+export function createSupabaseCleanupHost(deps: CleanupHostDeps): CleanupHost {
+  const { admin, context } = deps;
+
+  return {
+    storage: deps.storage,
+    rewriteReferences: deps.rewriteReferences,
+
+    trashDuplicate: async ({ trashId, path, trashPrefix, size, mergedInto }) => {
+      await admin.from("media_trash").insert({
+        id: trashId,
+        original_path: path,
+        paths: [path],
+        trash_prefix: trashPrefix,
+        size_bytes: size,
+        content_type: null,
+        deleted_by: context.userId,
+        deleted_by_email: actorEmail(context),
+        usage_snapshot: { mergedInto },
+      });
+      for (const table of PATH_TABLES) {
+        await admin.from(table).delete().eq("path", path);
+      }
+    },
+
+    movePathRows: async (from: string, to: string) => {
+      for (const table of PATH_TABLES) {
+        // A row already sitting on the destination path wins; drop the stale one
+        // instead of violating the unique path constraint.
+        const { data: existing } = await admin
+          .from(table)
+          .select("path")
+          .eq("path", to)
+          .maybeSingle();
+        if (existing) {
+          await admin.from(table).delete().eq("path", from);
+          continue;
+        }
+        await admin.from(table).update({ path: to }).eq("path", from);
+      }
+    },
+
+    logCleanup: async (result: MediaCleanupResult) => {
+      await admin.from("audit_logs").insert({
+        actor_id: context.userId,
+        actor_email: actorEmail(context),
+        action: "media.cleanup",
+        entity: "media",
+        entity_id: "bulk",
+        meta: result,
+      });
+    },
+  };
+}

package/src/server/media-focus-core.ts

@@ -0,0 +1,136 @@
+/**
+ * Host-agnostic focus-point (focal crop) server logic.
+ *
+ * Owns the whole `media_focus` lifecycle: the public read of every stored
+ * point, the desktop/mobile upsert and the clear. Hosts supply a privileged
+ * client for the public read (the table is staff-only through row-level
+ * security, but the coordinates themselves are needed to render the site) and
+ * their authenticated request context for the writes, so RLS applies as the
+ * signed-in user.
+ */
+import { assertStaff, type PlatformAuthContext } from "./guards";
+import { clampFocal, focusKey, type FocusDevice, type FocusMap } from "../media/focus";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Privileged-client factory the public read needs. */
+export type FocusAdmin = () => Promise<any>;
+
+/** Authenticated request context the writes run under. */
+export type FocusContext = PlatformAuthContext & { supabase: any };
+
+export type SetFocusInput = { src: string; x: number; y: number; device?: FocusDevice };
+export type ClearFocusInput = { src: string; device?: FocusDevice };
+
+export type FocusWriteResult = {
+  ok: true;
+  path?: string;
+  device?: FocusDevice;
+  x?: number;
+  y?: number;
+};
+
+/**
+ * Every stored focus point, keyed by canonical media path. Returns an empty map
+ * rather than throwing so a failed read never breaks page rendering.
+ */
+export async function getMediaFocusMapCore(admin: FocusAdmin): Promise<FocusMap> {
+  const db = await admin();
+  const { data, error } = await db
+    .from("media_focus")
+    .select("path, focal_x, focal_y, mobile_x, mobile_y");
+  if (error) return {};
+
+  const map: FocusMap = {};
+  for (const row of (data ?? []) as {
+    path: string;
+    focal_x: number;
+    focal_y: number;
+    mobile_x: number | null;
+    mobile_y: number | null;
+  }[]) {
+    map[row.path] = {
+      x: row.focal_x,
+      y: row.focal_y,
+      mobile:
+        row.mobile_x !== null && row.mobile_y !== null
+          ? { x: row.mobile_x, y: row.mobile_y }
+          : null,
+    };
+  }
+  return map;
+}
+
+/**
+ * Store a focus point. A mobile point is an override: the existing desktop
+ * coordinates are preserved (defaulting to dead centre) so switching device
+ * never silently recentres the other breakpoint.
+ */
+export async function setMediaFocusCore(
+  context: FocusContext,
+  data: SetFocusInput,
+): Promise<FocusWriteResult> {
+  await assertStaff(context);
+
+  const path = focusKey(data.src);
+  if (!path) throw new Error("Missing image path");
+  const point = clampFocal({ x: data.x, y: data.y });
+  const device: FocusDevice = data.device === "mobile" ? "mobile" : "desktop";
+
+  if (device === "mobile") {
+    const { data: existing } = await context.supabase
+      .from("media_focus")
+      .select("focal_x, focal_y")
+      .eq("path", path)
+      .maybeSingle();
+    const { error } = await context.supabase.from("media_focus").upsert(
+      {
+        path,
+        focal_x: existing?.focal_x ?? 50,
+        focal_y: existing?.focal_y ?? 50,
+        mobile_x: point.x,
+        mobile_y: point.y,
+        updated_by: context.userId,
+      },
+      { onConflict: "path" },
+    );
+    if (error) throw new Error(error.message);
+    return { ok: true, path, device, ...point };
+  }
+
+  const { error } = await context.supabase
+    .from("media_focus")
+    .upsert(
+      { path, focal_x: point.x, focal_y: point.y, updated_by: context.userId },
+      { onConflict: "path" },
+    );
+  if (error) throw new Error(error.message);
+  return { ok: true, path, device, ...point };
+}
+
+/**
+ * Drop a focus point. Clearing mobile only nulls the override; clearing desktop
+ * removes the row so the image falls back to a centred crop.
+ */
+export async function clearMediaFocusCore(
+  context: FocusContext,
+  data: ClearFocusInput,
+): Promise<FocusWriteResult> {
+  await assertStaff(context);
+
+  const path = focusKey(data.src);
+  if (!path) return { ok: true };
+
+  if (data.device === "mobile") {
+    const { error } = await context.supabase
+      .from("media_focus")
+      .update({ mobile_x: null, mobile_y: null, updated_by: context.userId })
+      .eq("path", path);
+    if (error) throw new Error(error.message);
+    return { ok: true };
+  }
+
+  const { error } = await context.supabase.from("media_focus").delete().eq("path", path);
+  if (error) throw new Error(error.message);
+  return { ok: true };
+}

package/src/server/media-meta-core.ts

@@ -0,0 +1,95 @@
+/**
+ * Host-agnostic media metadata server logic (alt / title / description /
+ * credit).
+ *
+ * Alt text, title and description are localized maps so every language carries
+ * its own copy; metadata is keyed by the same canonical, variant-collapsed path
+ * as focus points. The public read uses a privileged client because the table is
+ * staff-only through row-level security while the text itself is rendered on the
+ * public site; writes run under the host's authenticated context.
+ */
+import { assertStaff, type PlatformAuthContext } from "./guards";
+import {
+  cleanLocalized,
+  metaKey,
+  type LocalizedText,
+  type MediaMetaMap,
+} from "../media/media-meta";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export type MediaMetaAdmin = () => Promise<any>;
+export type MediaMetaContext = PlatformAuthContext & { supabase: any };
+
+export type SaveMediaMetaInput = {
+  src: string;
+  alt?: LocalizedText;
+  title?: LocalizedText;
+  description?: LocalizedText;
+  credit?: string;
+};
+
+/** All stored metadata, keyed by canonical path. Never throws. */
+export async function getMediaMetaMapCore(admin: MediaMetaAdmin): Promise<MediaMetaMap> {
+  const db = await admin();
+  const { data, error } = await db
+    .from("media_meta")
+    .select("path, alt, title, description, credit");
+  if (error) return {};
+
+  const map: MediaMetaMap = {};
+  for (const row of (data ?? []) as {
+    path: string;
+    alt: LocalizedText | null;
+    title: LocalizedText | null;
+    description: LocalizedText | null;
+    credit: string | null;
+  }[]) {
+    map[row.path] = {
+      alt: row.alt ?? {},
+      title: row.title ?? {},
+      description: row.description ?? {},
+      credit: row.credit ?? "",
+    };
+  }
+  return map;
+}
+
+/** Upsert metadata for one asset; empty locales are stripped before storing. */
+export async function setMediaMetaCore(
+  context: MediaMetaContext,
+  data: SaveMediaMetaInput,
+): Promise<{ ok: true; path: string }> {
+  await assertStaff(context);
+
+  const path = metaKey(data.src);
+  if (!path) throw new Error("Missing image path");
+
+  const { error } = await context.supabase.from("media_meta").upsert(
+    {
+      path,
+      alt: cleanLocalized(data.alt),
+      title: cleanLocalized(data.title),
+      description: cleanLocalized(data.description),
+      credit: (data.credit ?? "").trim(),
+      updated_by: context.userId,
+    },
+    { onConflict: "path" },
+  );
+  if (error) throw new Error(error.message);
+  return { ok: true, path };
+}
+
+/** Remove all metadata for one asset. */
+export async function clearMediaMetaCore(
+  context: MediaMetaContext,
+  data: { src: string },
+): Promise<{ ok: true }> {
+  await assertStaff(context);
+
+  const path = metaKey(data.src);
+  if (!path) return { ok: true };
+  const { error } = await context.supabase.from("media_meta").delete().eq("path", path);
+  if (error) throw new Error(error.message);
+  return { ok: true };
+}

package/src/server/media-replace-core.ts

@@ -0,0 +1,102 @@
+/**
+ * Host-agnostic "replace this file everywhere" logic.
+ *
+ * Swaps one library asset for another across every stored CMS reference.
+ * Responsive variants are matched width-for-width so srcSets stay consistent;
+ * anything without a matching width falls back to the new primary file.
+ *
+ * Nothing is deleted — the old asset stays in the library, so a wrong replace is
+ * reversed by replacing back.
+ */
+import { assertStaff, actorEmail, type PlatformAuthContext } from "./guards";
+import { RESPONSIVE_WIDTHS, variantSiblings } from "../media/srcset";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+const VARIANT_RE = /-(480|768|1200|1920|2560)\.webp$/i;
+
+function variantBase(path: string): string | null {
+  const m = path.match(VARIANT_RE);
+  return m ? path.slice(0, path.length - m[0].length) : null;
+}
+
+/** Every storage path belonging to one asset (primary + responsive siblings). */
+function family(path: string): string[] {
+  return [path, ...variantSiblings(path)];
+}
+
+/** Storage surface the replace needs — satisfied by `getMediaStorage()`. */
+export type ReplaceStorage = {
+  list: () => Promise<{ name: string }[]>;
+  publicUrl: (path: string) => string;
+};
+
+export type ReplaceDeps = {
+  context: PlatformAuthContext & { supabase: any };
+  /** Privileged client used for the reference rewrite and the audit row. */
+  admin: () => Promise<any>;
+  /** Storage bound to the privileged client. */
+  storage: (admin: any) => ReplaceStorage;
+  /** Repoint stored references from any of `oldUrls` to `newUrl`; returns hits. */
+  rewriteReferences: (admin: any, oldUrls: string[], newUrl: string) => Promise<number>;
+};
+
+export type ReplaceResult = { rewritten: number; widths: number };
+
+export async function replaceMediaEverywhereCore(
+  deps: ReplaceDeps,
+  data: { fromPath: string; toPath: string },
+): Promise<ReplaceResult> {
+  await assertStaff(deps.context);
+  if (!data.fromPath || !data.toPath) throw new Error("Both files are required");
+  if (data.fromPath === data.toPath) throw new Error("Pick two different files");
+
+  const admin = await deps.admin();
+  const storage = deps.storage(admin);
+
+  const existing = new Set((await storage.list()).map((f) => f.name));
+  if (!existing.has(data.fromPath)) throw new Error("Source file not found");
+  if (!existing.has(data.toPath)) throw new Error("Replacement file not found");
+
+  const newBase = variantBase(data.toPath);
+  const newPrimaryUrl = storage.publicUrl(data.toPath);
+
+  // Most specific first: width-matched variants, then the primary path.
+  const pairs: { oldPath: string; newUrl: string }[] = [];
+  for (const oldPath of family(data.fromPath)) {
+    if (!existing.has(oldPath) && oldPath !== data.fromPath) continue;
+    const width = oldPath.match(VARIANT_RE)?.[1];
+    let target = newPrimaryUrl;
+    if (width && newBase) {
+      const candidate = `${newBase}-${width}.webp`;
+      if (existing.has(candidate)) target = storage.publicUrl(candidate);
+    }
+    pairs.push({ oldPath, newUrl: target });
+  }
+  pairs.sort((a, b) => b.oldPath.length - a.oldPath.length);
+
+  let rewritten = 0;
+  for (const pair of pairs) {
+    const url = storage.publicUrl(pair.oldPath);
+    if (!url || url === pair.newUrl) continue;
+    const candidates = Array.from(
+      new Set([url, encodeURI(url), decodeURI(url), `/${pair.oldPath}`]),
+    );
+    rewritten += await deps.rewriteReferences(admin, candidates, pair.newUrl);
+  }
+
+  try {
+    await admin.from("audit_logs").insert({
+      actor_id: deps.context.userId,
+      actor_email: actorEmail(deps.context),
+      action: "media.replace_everywhere",
+      entity: "media",
+      entity_id: data.fromPath,
+      meta: { to: data.toPath, rewritten },
+    });
+  } catch (e) {
+    console.warn("audit failed", e);
+  }
+
+  return { rewritten, widths: RESPONSIVE_WIDTHS.length };
+}