@bygghammar/cms-platform 0.3.0 → 0.4.0

package/src/i18n/translation-meta.ts

@@ -0,0 +1,207 @@
+/**
+ * Shared helpers for the translation "origin" system.
+ *
+ * Every `Localized<string>` map may carry a sibling `_meta` object:
+ *
+ *   { sv: "Boka nu", en: "Book now",
+ *     _meta: { en: { origin: "auto", svHash: "…", updatedAt: "…" } } }
+ *
+ * Rules the auto-translator enforces:
+ *  - `origin: "manual"`  → NEVER overwrite
+ *  - `origin: "auto"` + svHash matches current sv → up-to-date, skip
+ *  - `origin: "auto"` + svHash differs             → stale, refresh
+ *  - No _meta but locale value present             → treat as MANUAL
+ *    (someone typed it into the editor, so we don't clobber it)
+ *  - Locale value missing                          → fill (auto)
+ */
+
+import type { Json } from "./json";
+
+export type TranslationOrigin = "auto" | "manual";
+export type LocaleMetaEntry = {
+  origin: TranslationOrigin;
+  svHash?: string;
+  updatedAt?: string;
+};
+export type LocaleMeta = Record<string, LocaleMetaEntry>;
+
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+/** True when `v` looks like a `{ sv: string, en?: string, _meta?: … }` map. */
+export function isLocaleMap(v: unknown): v is Record<string, unknown> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const keys = Object.keys(v as Record<string, unknown>);
+  if (keys.length === 0) return false;
+  const localeKeys = keys.filter((k) => k !== "_meta");
+  if (localeKeys.length === 0) return false;
+  return localeKeys.every((k) => LOCALE_RE.test(k));
+}
+
+/** Short, deterministic hash of a string. Non-crypto, edge-safe. */
+export function svHash(s: string): string {
+  // FNV-1a 64-bit → hex; small, stable, no Web Crypto async cost.
+  let h1 = 0x811c9dc5 | 0;
+  let h2 = 0xdeadbeef | 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 ^ c, 0x85ebca6b);
+  }
+  const hex = (n: number) => (n >>> 0).toString(16).padStart(8, "0");
+  return hex(h1) + hex(h2);
+}
+
+export type FieldStatus = "missing" | "stale" | "manual" | "fresh";
+
+export function statusFor(map: Record<string, unknown>, target: string): FieldStatus {
+  const sv = map.sv;
+  if (typeof sv !== "string" || sv.trim().length === 0) return "fresh";
+  const meta = (map._meta as LocaleMeta | undefined)?.[target];
+  const value = map[target];
+  if (typeof value !== "string") return "missing";
+  if (!meta) return "manual"; // pre-existing value with no provenance = human
+  if (meta.origin === "manual") return "manual";
+  if (meta.origin === "auto" && meta.svHash === svHash(sv)) return "fresh";
+  return "stale";
+}
+
+/**
+ * Walk any JSON value and detect locale maps that need translating,
+ * based on `mode`:
+ *   - "missing" → only fill absent locale values
+ *   - "stale"   → also refresh auto entries whose svHash no longer matches
+ *   - "force"   → refresh every auto entry (still preserves manual)
+ */
+export function collectMissing(
+  value: unknown,
+  target: string,
+  mode: "missing" | "stale" | "force",
+): {
+  needs: string[];
+  skippedManual: number;
+  patch: (m: Map<string, string>) => Json;
+} {
+  const needs = new Set<string>();
+  let skippedManual = 0;
+
+  function shouldTranslate(status: FieldStatus): boolean {
+    if (status === "manual") return false;
+    if (status === "missing") return true;
+    if (status === "stale") return mode === "stale" || mode === "force";
+    // fresh
+    return mode === "force";
+  }
+
+  function scan(v: unknown): void {
+    if (Array.isArray(v)) return void v.forEach(scan);
+    if (isLocaleMap(v)) {
+      const status = statusFor(v, target);
+      if (status === "manual") skippedManual += 1;
+      const sv = v.sv;
+      if (typeof sv === "string" && sv.trim().length > 0 && shouldTranslate(status)) {
+        needs.add(sv);
+      }
+      for (const [k, leaf] of Object.entries(v)) {
+        if (k !== "_meta" && typeof leaf !== "string") scan(leaf);
+      }
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const leaf of Object.values(v as Record<string, unknown>)) scan(leaf);
+    }
+  }
+  scan(value);
+
+  function patch(m: Map<string, string>): Json {
+    const nowIso = new Date().toISOString();
+    function apply(v: unknown): unknown {
+      if (Array.isArray(v)) return v.map(apply);
+      if (isLocaleMap(v)) {
+        const out: Record<string, unknown> = { ...v };
+        const sv = v.sv;
+        const status = statusFor(v, target);
+        if (
+          typeof sv === "string" &&
+          sv.trim().length > 0 &&
+          m.has(sv) &&
+          shouldTranslate(status)
+        ) {
+          out[target] = m.get(sv);
+          const meta = { ...((out._meta as LocaleMeta | undefined) ?? {}) };
+          meta[target] = {
+            origin: "auto",
+            svHash: svHash(sv),
+            updatedAt: nowIso,
+          };
+          out._meta = meta;
+        }
+        for (const [k, leaf] of Object.entries(v)) {
+          if (k !== "_meta" && typeof leaf !== "string") out[k] = apply(leaf);
+        }
+        return out;
+      }
+      if (v && typeof v === "object") {
+        const out: Record<string, unknown> = {};
+        for (const [k, leaf] of Object.entries(v as Record<string, unknown>)) {
+          out[k] = apply(leaf);
+        }
+        return out;
+      }
+      return v;
+    }
+    return apply(value) as Json;
+  }
+
+  return { needs: [...needs], skippedManual, patch };
+}
+
+/**
+ * After a manual save, mark any locale value that changed vs `prev`
+ * as `origin: "manual"` unless the incoming payload already carries
+ * explicit `_meta` for that locale. `sv` edits leave `_meta` untouched
+ * so staleness detection keeps working.
+ */
+export function stampManualEdits(next: unknown, prev: unknown): Json {
+  function walk(n: unknown, p: unknown): unknown {
+    if (Array.isArray(n)) {
+      const pa = Array.isArray(p) ? p : [];
+      return n.map((el, i) => walk(el, pa[i]));
+    }
+    if (isLocaleMap(n)) {
+      const out: Record<string, unknown> = { ...n };
+      const prevMap = isLocaleMap(p) ? (p as Record<string, unknown>) : {};
+      const incomingMeta = (n._meta as LocaleMeta | undefined) ?? {};
+      const prevMeta = (prevMap._meta as LocaleMeta | undefined) ?? {};
+      const meta: LocaleMeta = { ...prevMeta, ...incomingMeta };
+      const nowIso = new Date().toISOString();
+      for (const [k, v] of Object.entries(n)) {
+        if (k === "_meta" || k === "sv" || typeof v !== "string") continue;
+        const prevVal = prevMap[k];
+        const changed = prevVal !== v;
+        const explicit = k in incomingMeta;
+        if (changed && !explicit) {
+          meta[k] = { origin: "manual", updatedAt: nowIso };
+        }
+      }
+      if (Object.keys(meta).length > 0) out._meta = meta;
+      for (const [k, leaf] of Object.entries(n)) {
+        if (k !== "_meta" && typeof leaf !== "string") {
+          out[k] = walk(leaf, (prevMap as Record<string, unknown>)[k]);
+        }
+      }
+      return out;
+    }
+    if (n && typeof n === "object") {
+      const out: Record<string, unknown> = {};
+      const po = (
+        p && typeof p === "object" && !Array.isArray(p) ? (p as Record<string, unknown>) : {}
+      ) as Record<string, unknown>;
+      for (const [k, leaf] of Object.entries(n as Record<string, unknown>)) {
+        out[k] = walk(leaf, po[k]);
+      }
+      return out;
+    }
+    return n;
+  }
+  return walk(next, prev) as Json;
+}

package/src/media/filename.ts

@@ -0,0 +1,44 @@
+/**
+ * Media filenames are SEO-relevant, so uploads keep the original, human-readable
+ * name — never a timestamp or random prefix. Collisions get a `-2`, `-3`, … suffix.
+ */
+
+export function splitExt(name: string) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return { base: name, ext: "" };
+  return { base: name.slice(0, dot), ext: name.slice(dot).toLowerCase() };
+}
+
+/** Slugify a filename while preserving its readable words and extension. */
+export function cleanFileName(name: string, fallback = "file") {
+  const { base, ext } = splitExt(name);
+  const cleaned = base
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    // Strip legacy timestamp/random prefixes such as `1785305764867-name`.
+    .replace(/^\d{10,16}-(?=[a-z0-9])/, "")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+  return `${cleaned || fallback}${ext}`;
+}
+
+/**
+ * Return `name` if free, otherwise `name-2`, `name-3`, … using `taken`
+ * (a set of existing filenames, or a predicate).
+ */
+export function uniqueFileName(
+  name: string,
+  taken: Set<string> | ((candidate: string) => boolean),
+) {
+  const isTaken = typeof taken === "function" ? taken : (c: string) => taken.has(c);
+  if (!isTaken(name)) return name;
+  const { base, ext } = splitExt(name);
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${base}-${i}${ext}`;
+    if (!isTaken(candidate)) return candidate;
+  }
+  return `${base}-${Math.floor(Math.random() * 1e6)}${ext}`;
+}

package/src/media/focus.ts

@@ -0,0 +1,101 @@
+/**
+ * Image focus points ("focal point crop").
+ *
+ * Every cropped image on the site uses `object-fit: cover`, which defaults to a
+ * centred crop. A focus point lets an editor pick which part of the image must
+ * stay visible; we translate it into `object-position`.
+ *
+ * Focus is stored per media asset (not per placement), keyed by a canonical
+ * path so all responsive variants (`-480/-768/-1200/-1920.webp`) of the same
+ * upload share one setting.
+ */
+
+export type FocalPoint = { x: number; y: number };
+
+export const DEFAULT_FOCAL: FocalPoint = { x: 50, y: 50 };
+
+/** Stored focus for one asset: desktop point plus an optional mobile override. */
+export type FocalEntry = FocalPoint & { mobile?: FocalPoint | null };
+
+export type FocusDevice = "desktop" | "mobile";
+
+export type FocusMap = Record<string, FocalEntry>;
+
+const VARIANT_RE = /-(480|768|1200|1920)\.webp$/i;
+
+/**
+ * Canonical storage key for any media URL or storage path.
+ * - Strips origin / `storage/v1/object/public/media/` prefix and query strings.
+ * - Collapses responsive variants onto a single key.
+ * - Non-library URLs (external assets) keep their full URL as the key.
+ */
+export function focusKey(input: string | undefined | null): string {
+  if (!input) return "";
+  let value = String(input).trim();
+  if (!value) return "";
+
+  // Drop query / hash.
+  value = value.split("#")[0].split("?")[0];
+
+  const marker = "/storage/v1/object/public/media/";
+  const at = value.indexOf(marker);
+  if (at >= 0) {
+    value = value.slice(at + marker.length);
+  } else if (/^https?:\/\//i.test(value)) {
+    // External URL — key on the whole thing (still collapse variants below).
+    return value.replace(VARIANT_RE, ".webp");
+  } else {
+    value = value.replace(/^\/+/, "");
+  }
+
+  try {
+    value = decodeURIComponent(value);
+  } catch {
+    /* keep raw */
+  }
+
+  return value.replace(VARIANT_RE, ".webp");
+}
+
+export function clampFocal(point: Partial<FocalPoint> | undefined): FocalPoint {
+  const clamp = (n: number | undefined, fallback: number) =>
+    Math.min(100, Math.max(0, Math.round(Number.isFinite(n as number) ? (n as number) : fallback)));
+  return { x: clamp(point?.x, 50), y: clamp(point?.y, 50) };
+}
+
+export function focalToObjectPosition(point: Partial<FocalPoint> | undefined): string {
+  const p = clampFocal(point);
+  return `${p.x}% ${p.y}%`;
+}
+
+export function lookupEntry(map: FocusMap | undefined, src: string | undefined): FocalEntry {
+  if (!map || !src) return { ...DEFAULT_FOCAL };
+  return map[focusKey(src)] ?? { ...DEFAULT_FOCAL };
+}
+
+export function lookupFocal(
+  map: FocusMap | undefined,
+  src: string | undefined,
+  device: FocusDevice = "desktop",
+): FocalPoint {
+  const entry = lookupEntry(map, src);
+  if (device === "mobile") return clampFocal(entry.mobile ?? entry);
+  return clampFocal(entry);
+}
+
+/**
+ * Inline CSS custom properties for a focus entry. Combine with the
+ * `focal-pos` class so mobile viewports pick up the mobile override.
+ */
+export function focalCssVars(entry: FocalEntry | undefined): Record<string, string> {
+  const vars: Record<string, string> = {
+    "--focal": focalToObjectPosition(entry),
+  };
+  if (entry?.mobile) vars["--focal-mobile"] = focalToObjectPosition(entry.mobile);
+  return vars;
+}
+
+export function isDefaultFocal(point: Partial<FocalPoint> | undefined): boolean {
+  const p = clampFocal(point);
+  return p.x === 50 && p.y === 50;
+}

package/src/media/internal-paths.ts

@@ -0,0 +1,30 @@
+/**
+ * Reserved, internal paths inside the media volume.
+ *
+ * Migration state (staging directories and the activation journal) lives
+ * INSIDE the persistent media volume so that:
+ *   - staging and destination share one filesystem (atomic rename works),
+ *   - the journal and staged files survive container replacement,
+ *   - `resume-media` can recover after a deployment restart.
+ *
+ * Because these files sit next to real media, every path that lists, serves,
+ * exports, cleans or scans media must skip them.
+ */
+
+/** Directory (relative to MEDIA_DIR) holding all migration state. */
+export const MIGRATION_DIR = ".migration";
+
+/** Journal file name inside MIGRATION_DIR. */
+export const MEDIA_ACTIVATION_JOURNAL = "media-activation.json";
+
+/** Any path segment starting with one of these is internal, never user media. */
+export const RESERVED_SEGMENT_PREFIXES = [".migration", ".restore-", ".staging-"] as const;
+
+/** Relative media path (POSIX style) that must never be treated as user media. */
+export function isInternalMediaPath(relPath: string): boolean {
+  const normalized = relPath.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized) return false;
+  return normalized
+    .split("/")
+    .some((seg) => RESERVED_SEGMENT_PREFIXES.some((p) => seg === p || seg.startsWith(p)));
+}

package/src/media/media-meta.ts

@@ -0,0 +1,50 @@
+/**
+ * Per-asset SEO metadata for the Media Library.
+ *
+ * Alt text, title and description are localized maps (`{ sv: "…" }`) so every
+ * language can carry its own copy — the same rule as all site content.
+ * Metadata is keyed by the same canonical path used for focus points, so all
+ * responsive variants of one upload share a single record.
+ */
+import { focusKey } from "./focus";
+
+export type LocalizedText = Record<string, string>;
+
+export type MediaMeta = {
+  alt: LocalizedText;
+  title: LocalizedText;
+  description: LocalizedText;
+  credit: string;
+};
+
+export type MediaMetaMap = Record<string, MediaMeta>;
+
+export const EMPTY_MEDIA_META: MediaMeta = {
+  alt: {},
+  title: {},
+  description: {},
+  credit: "",
+};
+
+/** Same canonical key as focus points (variant-collapsed storage path). */
+export const metaKey = focusKey;
+
+export function lookupMediaMeta(map: MediaMetaMap | undefined, src: string | undefined): MediaMeta {
+  if (!map || !src) return { ...EMPTY_MEDIA_META };
+  return map[metaKey(src)] ?? { ...EMPTY_MEDIA_META };
+}
+
+export function hasMediaMeta(meta: MediaMeta | undefined): boolean {
+  if (!meta) return false;
+  const any = (t: LocalizedText) => Object.values(t ?? {}).some((v) => v?.trim());
+  return any(meta.alt) || any(meta.title) || any(meta.description) || Boolean(meta.credit?.trim());
+}
+
+/** Strip empty strings so we never store blank locale keys. */
+export function cleanLocalized(text: LocalizedText | undefined): LocalizedText {
+  const out: LocalizedText = {};
+  for (const [k, v] of Object.entries(text ?? {})) {
+    if (typeof v === "string" && v.trim()) out[k] = v.trim();
+  }
+  return out;
+}

package/src/media/optimize.ts

@@ -0,0 +1,209 @@
+/**
+ * Client-side media optimization run at upload time in the backoffice.
+ * - Images → WebP variants, quality 0.90, max width 2560 (preserves aspect).
+ *   PNG/WebP/AVIF sources with an alpha channel keep their transparency in
+ *   every generated WebP file, and a single `-fallback.png` is produced so
+ *   older browsers still see a transparent image.
+ * - Videos → original file + a JPG poster grabbed from ~10% into the clip.
+ * - Everything else → passthrough.
+ *
+ * Runs only in the browser (uses Canvas / <video>). Do NOT import from server code.
+ */
+
+export type OptimizedFile = {
+  name: string;
+  blob: Blob;
+  contentType: string;
+};
+
+export type OptimizedBundle = {
+  primary: OptimizedFile;
+  /** Optional sibling files uploaded alongside (e.g. video poster, PNG fallback). */
+  extras: OptimizedFile[];
+};
+
+export const RESPONSIVE_WIDTHS = [480, 768, 1200, 1920, 2560] as const;
+const IMAGE_QUALITY = 0.9;
+const OPTIMIZABLE_IMAGE = /^image\/(jpeg|jpg|png|webp|avif|bmp|tiff?)$/i;
+
+function extOf(name: string): string {
+  const i = name.lastIndexOf(".");
+  return i > 0 ? name.slice(i).toLowerCase() : "";
+}
+
+function stripExt(name: string): string {
+  const i = name.lastIndexOf(".");
+  return i > 0 ? name.slice(0, i) : name;
+}
+
+export type OptimizeOptions = {
+  /** Timestamp (seconds) to grab the video poster from. Defaults to ~10% in. */
+  posterTime?: number;
+};
+
+/** True when the decoded image contains any non-opaque pixel. */
+async function hasTransparency(bmp: ImageBitmap): Promise<boolean> {
+  const canvas = document.createElement("canvas");
+  // Sample at a reduced resolution — enough to catch typical rounded corners,
+  // logos and cut-out subjects without reading millions of pixels.
+  const w = Math.min(bmp.width, 128);
+  const h = Math.min(bmp.height, 128);
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext("2d", { alpha: true });
+  if (!ctx) return false;
+  ctx.drawImage(bmp, 0, 0, w, h);
+  const data = ctx.getImageData(0, 0, w, h).data;
+  for (let i = 3; i < data.length; i += 4) {
+    if (data[i] < 255) return true;
+  }
+  return false;
+}
+
+export async function optimizeForUpload(
+  file: File,
+  slug: string,
+  options: OptimizeOptions = {},
+): Promise<OptimizedBundle> {
+  // Images: transcode to WebP at 5 widths for srcset (480 / 768 / 1200 / 1920 / 2560).
+  if (OPTIMIZABLE_IMAGE.test(file.type)) {
+    try {
+      const base = stripExt(slug);
+      const bmp = await createImageBitmap(file);
+      try {
+        const transparent = await hasTransparency(bmp);
+        const files: OptimizedFile[] = [];
+        let largestW = 1;
+        let largestH = 1;
+        for (const targetW of RESPONSIVE_WIDTHS) {
+          // Every width is always written, even for small sources: the image is
+          // never upscaled (the file just repeats the capped size), but the full
+          // set of variant URLs is guaranteed to exist, so a responsive srcSet
+          // can never point at a file that was skipped at upload time.
+          const scale = Math.min(1, targetW / bmp.width);
+          const w = Math.max(1, Math.round(bmp.width * scale));
+          const h = Math.max(1, Math.round(bmp.height * scale));
+          largestW = w;
+          largestH = h;
+          // The fresh canvas starts fully transparent, so drawing an image with
+          // alpha preserves its transparency rather than compositing onto a
+          // solid background. WebP encoding keeps the alpha channel.
+          const blob = await encodeWebpAt(bmp, w, h);
+          files.push({ name: `${base}-${targetW}.webp`, blob, contentType: "image/webp" });
+        }
+
+        // Primary = largest variant so its URL can derive the srcset via `-2560.webp` suffix.
+        const primary = files.find((f) => f.name.endsWith("-2560.webp")) ?? files[files.length - 1];
+        const extras = files.filter((f) => f !== primary);
+
+        // Transparent sources also get a single PNG fallback at the largest
+        // width. It is stored as an extra so the primary WebP URL stays stable
+        // and every existing page reference remains valid.
+        if (transparent) {
+          const fallback = await encodePngAt(bmp, largestW, largestH);
+          extras.push({ name: `${base}-fallback.png`, blob: fallback, contentType: "image/png" });
+        }
+
+        return { primary, extras };
+      } finally {
+        bmp.close?.();
+      }
+    } catch {
+      // Fallback: upload original untouched.
+      return {
+        primary: { name: `${slug}${extOf(file.name)}`, blob: file, contentType: file.type },
+        extras: [],
+      };
+    }
+  }
+  // Videos: keep original, generate poster.
+  if (file.type.startsWith("video/")) {
+    const primary: OptimizedFile = {
+      name: `${slug}${extOf(file.name)}`,
+      blob: file,
+      contentType: file.type,
+    };
+    const poster = await extractVideoPoster(file, options.posterTime).catch(() => null);
+    return {
+      primary,
+      extras: poster
+        ? [{ name: `${stripExt(slug)}-poster.jpg`, blob: poster, contentType: "image/jpeg" }]
+        : [],
+    };
+  }
+
+  // Everything else: passthrough.
+  return {
+    primary: {
+      name: `${slug}${extOf(file.name)}`,
+      blob: file,
+      contentType: file.type || "application/octet-stream",
+    },
+    extras: [],
+  };
+}
+async function encodeWebpAt(bmp: ImageBitmap, w: number, h: number): Promise<Blob> {
+  const canvas = document.createElement("canvas");
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("2d ctx unavailable");
+  ctx.drawImage(bmp, 0, 0, w, h);
+  return await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (b) => (b ? resolve(b) : reject(new Error("webp encode failed"))),
+      "image/webp",
+      IMAGE_QUALITY,
+    );
+  });
+}
+
+async function encodePngAt(bmp: ImageBitmap, w: number, h: number): Promise<Blob> {
+  const canvas = document.createElement("canvas");
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext("2d", { alpha: true });
+  if (!ctx) throw new Error("2d ctx unavailable");
+  ctx.drawImage(bmp, 0, 0, w, h);
+  return await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("png encode failed"))), "image/png");
+  });
+}
+
+export async function extractVideoPoster(file: File, atSeconds?: number): Promise<Blob | null> {
+  const url = URL.createObjectURL(file);
+  try {
+    const video = document.createElement("video");
+    video.src = url;
+    video.muted = true;
+    video.playsInline = true;
+    video.preload = "auto";
+    await new Promise<void>((resolve, reject) => {
+      video.onloadedmetadata = () => resolve();
+      video.onerror = () => reject(new Error("video metadata failed"));
+    });
+    const duration = video.duration || 1;
+    const target =
+      typeof atSeconds === "number" && Number.isFinite(atSeconds)
+        ? Math.max(0, Math.min(atSeconds, Math.max(0, duration - 0.05)))
+        : Math.min(1, duration * 0.1);
+    await new Promise<void>((resolve, reject) => {
+      video.onseeked = () => resolve();
+      video.onerror = () => reject(new Error("seek failed"));
+      video.currentTime = target;
+    });
+    const w = video.videoWidth || 1280;
+    const h = video.videoHeight || 720;
+    const canvas = document.createElement("canvas");
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+    ctx.drawImage(video, 0, 0, w, h);
+    return await new Promise<Blob | null>((resolve) =>
+      canvas.toBlob((b) => resolve(b), "image/jpeg", 0.82),
+    );
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}