@michaelthielemann/kestrel 1.2.1

package/layers/media/app/composables/useMediaRelocate.ts

@@ -0,0 +1,39 @@
+import { ref } from 'vue'
+import type { OpItem, RelocationReport } from '../utils/ops'
+
+type Strategy = 'abort' | 'skip' | 'overwrite' | 'rename'
+
+export function useMediaRelocate(onChanged?: () => void) {
+  const { t } = useT()
+  const busy = ref(false)
+  const error = ref<string | null>(null)
+
+  async function preview(type: 'move' | 'copy', items: OpItem[], dest: string): Promise<RelocationReport> {
+    error.value = null
+    try {
+      return await $fetch<RelocationReport>(`/api/media/${type}`, { method: 'POST', body: { items, dest, dryRun: true } })
+    } catch (e) {
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? t('media.error.relocate')
+      throw e
+    }
+  }
+
+  async function execute(type: 'move' | 'copy', items: OpItem[], dest: string, onConflict: Strategy): Promise<void> {
+    busy.value = true
+    error.value = null
+    try {
+      await $fetch(`/api/media/${type}`, { method: 'POST', body: { items, dest, onConflict } })
+      onChanged?.()
+    } catch (e) {
+      const err = e as { statusCode?: number; statusMessage?: string }
+      error.value = err.statusCode === 409
+        ? t('media.error.relocateConflict')
+        : err.statusMessage ?? t('media.error.relocate')
+      throw e
+    } finally {
+      busy.value = false
+    }
+  }
+
+  return { busy, error, preview, execute }
+}

package/layers/media/app/composables/useMediaResolver.ts

@@ -0,0 +1,50 @@
+import { reactive, toValue } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+import type { ResolvedMedia } from '../../server/utils/resolve'
+
+// The client-facing resolved-media shape (`GET /api/media/resolve`) is the server resolver's own
+// return type — re-exported so consumers keep importing it from here, single-sourced so it can't drift.
+export type { ResolvedMedia }
+
+/**
+ * Batched, cached client resolution of media ids → `ResolvedMedia`. A reactive cache so callers can
+ * `resolve(id)` inside a computed and have it re-evaluate once `ensure()` fills the cache. Per
+ * instance (no shared module state → SSR-safe). The cache is keyed per locale, and `locale` may be
+ * a ref/getter — a locale change makes its ids "missing" again so `ensure()` re-fetches and
+ * `resolve()` returns the new-locale entry (translations differ per locale).
+ */
+export function useMediaResolver(locale?: MaybeRefOrGetter<string>) {
+  const cache = reactive(new Map<string, ResolvedMedia>())
+  // Keys that resolved to NOTHING (deleted/dangling id). Without this, a missing id is "missing" forever and
+  // re-requested on every ensure(); the negative cache stops re-fetching it. Keyed per (locale, id) like the
+  // positive cache, so a locale change still re-resolves. Only populated on a SUCCESSFUL fetch that omitted
+  // the id — a network error leaves the id retryable.
+  const absent = new Set<string>()
+  const pending = new Set<string>()
+  const loc = () => toValue(locale) || 'en'
+  const keyFor = (l: string, id: number) => `${l}:${id}`
+
+  async function ensure(ids: number[]): Promise<void> {
+    const l = loc()
+    const missing = ids.filter((id) => Number.isInteger(id) && id > 0 && !cache.has(keyFor(l, id)) && !absent.has(keyFor(l, id)) && !pending.has(keyFor(l, id)))
+    if (!missing.length) return
+    for (const id of missing) pending.add(keyFor(l, id))
+    try {
+      const { data } = await $fetch<{ data: ResolvedMedia[] }>('/api/media/resolve', { query: { ids: missing.join(','), locale: l } })
+      const returned = new Set<number>()
+      for (const m of data) { cache.set(keyFor(l, m.id), m); returned.add(m.id) }
+      // A requested id the server didn't return is gone → remember it so we don't keep asking.
+      for (const id of missing) if (!returned.has(id)) absent.add(keyFor(l, id))
+    } catch {
+      // leave unresolved (NOT absent) — a transient error stays retryable on a later attempt
+    } finally {
+      for (const id of missing) pending.delete(keyFor(l, id))
+    }
+  }
+
+  function resolve(id: number): ResolvedMedia | null {
+    return cache.get(keyFor(loc(), id)) ?? null
+  }
+
+  return { cache, ensure, resolve }
+}

package/layers/media/app/composables/useMediaUpload.ts

@@ -0,0 +1,93 @@
+import { ref, computed } from 'vue'
+import type { PendingUpload } from '../utils/dnd'
+
+export interface UploadItem {
+  id: string; file: File; filename: string; folder: string
+  status: 'queued' | 'uploading' | 'done' | 'error' | 'conflict' | 'skipped'
+  message?: string; suggestion?: string; existingId?: number
+}
+
+export interface UploadCallbacks {
+  /** Fired once a batch has fully settled (no active uploads, no unresolved conflicts). */
+  onSettled?: () => void
+  /** Fired for each item that fails (non-conflict). The component surfaces the reason (`item.message`). */
+  onError?: (item: UploadItem) => void
+}
+
+export function useMediaUpload(cb: UploadCallbacks = {}) {
+  const queue = ref<UploadItem[]>([])
+  let seq = 0
+  const conflicts = computed(() => queue.value.filter((i) => i.status === 'conflict'))
+  const active = computed(() => queue.value.some((i) => i.status === 'queued' || i.status === 'uploading'))
+  const counts = computed(() => ({
+    total: queue.value.length,
+    done: queue.value.filter((i) => i.status === 'done').length,
+    error: queue.value.filter((i) => i.status === 'error').length,
+    conflict: conflicts.value.length,
+    skipped: queue.value.filter((i) => i.status === 'skipped').length,
+  }))
+
+  async function uploadItem(item: UploadItem, opts: { overwrite?: boolean; filename?: string } = {}) {
+    item.status = 'uploading'
+    const fd = new FormData()
+    fd.append('file', item.file)
+    if (item.folder) fd.append('folder', item.folder)
+    fd.append('filename', opts.filename ?? item.filename)
+    if (opts.overwrite) fd.append('overwrite', 'true')
+    try {
+      await $fetch('/api/media', { method: 'POST', body: fd })
+      item.status = 'done'
+    } catch (e) {
+      type ConflictData = { suggestion?: string; existingId?: number }
+      const err = e as { statusCode?: number; statusMessage?: string; data?: ConflictData & { statusMessage?: string; data?: ConflictData } }
+      if (err.statusCode === 409) {
+        // $fetch wraps the thrown H3 error: the original payload is nested under data.data over HTTP.
+        const payload = err.data?.data ?? err.data
+        item.status = 'conflict'; item.suggestion = payload?.suggestion; item.existingId = payload?.existingId
+      } else if (err.statusCode === 401) {
+        // A mid-session 401 is owned by the re-auth interceptor (it redirects to login) — don't also
+        // raise a per-item toast for the same event.
+        item.status = 'error'
+      } else {
+        // Prefer the server reason from the JSON body (transport-independent) over `statusMessage`,
+        // which mirrors `response.statusText` — blank on HTTP/2 and rewritten by proxies. The component
+        // localizes a fallback when neither is present.
+        item.status = 'error'; item.message = err.data?.statusMessage ?? err.statusMessage
+        cb.onError?.(item)
+      }
+    }
+  }
+
+  function settle() { if (!active.value && !conflicts.value.length) cb.onSettled?.() }
+
+  async function run() {
+    for (const item of queue.value) if (item.status === 'queued') await uploadItem(item)
+    settle()
+  }
+
+  function enqueueUploads(uploads: PendingUpload[]) {
+    for (const u of uploads) queue.value.push({ id: `u${++seq}`, file: u.file, filename: u.file.name, folder: u.folder, status: 'queued' })
+    return run()
+  }
+
+  function enqueue(files: File[], folder: string) {
+    return enqueueUploads(files.map((file) => ({ file, folder })))
+  }
+
+  async function resolve(id: string, action: 'overwrite' | 'rename' | 'skip', name?: string) {
+    const item = queue.value.find((i) => i.id === id)
+    if (!item || item.status !== 'conflict') return
+    if (action === 'skip') item.status = 'skipped'
+    else if (action === 'overwrite') await uploadItem(item, { overwrite: true })
+    else { item.filename = name ?? item.suggestion ?? item.filename; await uploadItem(item, { filename: item.filename }) }
+    settle()
+  }
+
+  async function resolveAll(action: 'overwrite' | 'rename' | 'skip') {
+    for (const item of [...conflicts.value]) await resolve(item.id, action, action === 'rename' ? item.suggestion : undefined)
+  }
+
+  function reset() { queue.value = [] }
+
+  return { queue, conflicts, active, counts, enqueue, enqueueUploads, resolve, resolveAll, reset }
+}

package/layers/media/app/composables/useMediaVariant.ts

@@ -0,0 +1,34 @@
+import { computed, toValue, type MaybeRefOrGetter } from 'vue'
+import type { ResolvedMedia } from '../../server/utils/resolve'
+import type { ResolvedVariant } from '../../../core/server/utils/kestrel-config'
+import { buildPictureModel, requestVariantSpecs, type VariantRequest, type PictureModel } from '../utils/picture-model'
+
+/**
+ * Reactive `<picture>` view-model for a resolved media + a variant request. The single render-AND-declare
+ * site: one call may declare MULTIPLE sizes + formats. During a publish/generate SSR render it also stashes
+ * the call's concrete specs on the request event, so the publish `beforeResponse` hook collects them and the
+ * end-of-publish reconcile registers exactly what was rendered (usage-driven auto-discovery). Server-guarded,
+ * so it is a no-op on the client and in non-Nuxt unit mounts.
+ */
+export function useMediaVariant(
+  media: MaybeRefOrGetter<ResolvedMedia | null | undefined>,
+  request: MaybeRefOrGetter<VariantRequest>,
+  opts?: { priority?: MaybeRefOrGetter<boolean> },
+) {
+  if (import.meta.server) {
+    const specs = requestVariantSpecs(toValue(request))
+    if (specs.length) {
+      const ev = useRequestEvent()
+      if (ev) {
+        const ctx = ev.context as { kestrelVariants?: ResolvedVariant[] }
+        ;(ctx.kestrelVariants ??= []).push(...specs)
+      }
+    }
+  }
+  const model = computed<PictureModel | null>(() => {
+    const m = toValue(media)
+    if (!m) return null
+    return buildPictureModel(m, toValue(request), { lazy: !toValue(opts?.priority ?? false) })
+  })
+  return { model }
+}

package/layers/media/app/plugins/field-media.client.ts

@@ -0,0 +1,6 @@
+// components are NOT auto-imported in a plugin's script context — pull FieldMedia from #components
+import { FieldMedia } from '#components'
+
+export default defineNuxtPlugin(() => {
+  registerFieldComponent('media', FieldMedia)
+})

package/layers/media/app/utils/dnd.ts

@@ -0,0 +1,69 @@
+import { joinFolder } from './library'
+
+export interface PendingUpload { file: File; folder: string }
+export interface WalkResult { uploads: PendingUpload[]; dirs: string[] }
+
+export interface DirectoryReaderLike {
+  readEntries(success: (entries: EntryLike[]) => void, error?: (e: unknown) => void): void
+}
+export interface EntryLike {
+  isFile: boolean
+  isDirectory: boolean
+  name: string
+  file?(success: (file: File) => void, error?: (e: unknown) => void): void
+  createReader?(): DirectoryReaderLike
+}
+
+/** Drain a DirectoryReader — readEntries yields in batches (Chrome caps ~100), loop until empty. */
+export function readAllEntries(reader: DirectoryReaderLike): Promise<EntryLike[]> {
+  return new Promise((resolve, reject) => {
+    const all: EntryLike[] = []
+    const next = () => reader.readEntries((batch) => { if (!batch.length) return resolve(all); all.push(...batch); next() }, reject)
+    next()
+  })
+}
+
+function entryFile(entry: EntryLike): Promise<File> {
+  return new Promise((resolve, reject) => entry.file!((f) => resolve(f), reject))
+}
+
+export async function walkEntry(entry: EntryLike, base: string, out: WalkResult): Promise<void> {
+  if (entry.isFile) {
+    out.uploads.push({ file: await entryFile(entry), folder: base })
+  } else if (entry.isDirectory && entry.createReader) {
+    const dir = joinFolder(base, entry.name)
+    out.dirs.push(dir)
+    for (const child of await readAllEntries(entry.createReader())) await walkEntry(child, dir, out)
+  }
+}
+
+interface DataTransferLike {
+  items?: ArrayLike<{ webkitGetAsEntry?(): EntryLike | null }> | null
+  files?: ArrayLike<File> | null
+}
+
+export async function extractUploads(dt: DataTransferLike, base: string): Promise<WalkResult> {
+  const out: WalkResult = { uploads: [], dirs: [] }
+  // Grab entries SYNCHRONOUSLY before any await — the DataTransferItemList dies once the handler yields.
+  const entries = (dt.items ? Array.from(dt.items) : [])
+    .map((it) => it.webkitGetAsEntry?.() ?? null)
+    .filter((e): e is EntryLike => !!e)
+  if (entries.length) {
+    for (const entry of entries) await walkEntry(entry, base, out)
+  } else {
+    for (const file of Array.from(dt.files ?? [])) out.uploads.push({ file, folder: base })
+  }
+  return out
+}
+
+/** The minimal set of folders to create explicitly: dirs no uploaded file already creates
+ *  (ensure-on-upload makes a file's whole ancestor chain), reduced to the deepest. */
+export function selectEmptyFolders(uploads: PendingUpload[], dirs: string[]): string[] {
+  const covered = new Set<string>()
+  for (const u of uploads) {
+    const segs = u.folder.split('/').filter(Boolean)
+    for (let i = 1; i <= segs.length; i++) covered.add(segs.slice(0, i).join('/'))
+  }
+  const empty = dirs.filter((d) => d && !covered.has(d))
+  return empty.filter((d) => !empty.some((o) => o !== d && o.startsWith(`${d}/`)))
+}

package/layers/media/app/utils/library.ts

@@ -0,0 +1,79 @@
+import type { LibraryFolder } from '../../server/utils/library'
+
+// Re-exported from the server util that produces it (`GET /api/media/library`) so the wire shape is
+// single-sourced.
+export type { LibraryFolder }
+
+export interface LibraryFile {
+  id: number; filename: string; mime: string; folder: string; size: number
+  width?: number; height?: number; thumbhash?: string; src: string; srcset?: string; alt?: string
+  createdAt?: string
+}
+export type LibraryItem =
+  | { type: 'folder'; folder: LibraryFolder }
+  | { type: 'file'; file: LibraryFile }
+
+export function itemKey(item: LibraryItem): string {
+  return item.type === 'folder' ? `folder:${item.folder.path}` : `file:${item.file.id}`
+}
+
+/** Inclusive range between the anchor and target keys (by position in `orderedKeys`), unioned
+ *  onto `current`. If the anchor is not found, selects only the target. */
+export function computeRange(orderedKeys: string[], anchorKey: string, targetKey: string, current: Set<string>): Set<string> {
+  const out = new Set(current)
+  const t = orderedKeys.indexOf(targetKey)
+  if (t < 0) return out
+  const a = orderedKeys.indexOf(anchorKey)
+  if (a < 0) { out.add(targetKey); return out }
+  for (let i = Math.min(a, t); i <= Math.max(a, t); i++) out.add(orderedKeys[i])
+  return out
+}
+
+export function humanizeSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const kb = bytes / 1024
+  if (kb < 1024) return `${kb.toFixed(1)} KB`
+  return `${(kb / 1024).toFixed(1)} MB`
+}
+
+/** The parent of an internal folder path, or `null` at the root — never above it (no path traversal).
+ *  `''` → null (root); `'a'` → `''`; `'a/b'` → `'a'`. */
+export function parentFolder(folder: string): string | null {
+  if (folder === '') return null
+  const i = folder.lastIndexOf('/')
+  return i === -1 ? '' : folder.slice(0, i)
+}
+
+/** Split a typed folder path into the existing-parent part and the trailing fragment being typed. */
+export function splitPathInput(input: string): { parent: string; fragment: string } {
+  const i = input.lastIndexOf('/')
+  return i === -1 ? { parent: '', fragment: input } : { parent: input.slice(0, i), fragment: input.slice(i + 1) }
+}
+
+/** Join folder parts into a clean relative path (drops empty segments). Also parses a typed display
+ *  path back to the internal form: `joinFolder('/test123/')` → `'test123'`, `joinFolder('/')` → `''`. */
+export function joinFolder(...parts: string[]): string {
+  return parts.flatMap((p) => p.split('/')).filter(Boolean).join('/')
+}
+
+/** Internal folder path → the slash-delimited path shown to the user, rooted at the media directory:
+ *  `''` → `'/'`, `'test123'` → `'/test123/'`, `'a/b'` → `'/a/b/'`. Tolerant of stray slashes in input. */
+export function displayFolderPath(folder: string): string {
+  const clean = joinFolder(folder)
+  return clean === '' ? '/' : `/${clean}/`
+}
+
+/** Longest common FOLDER of clean relative paths; '' (root) when they diverge at root or none given.
+ *  Keeps only equal leading segments and drops empties, so it can never emit '..' or escape root. */
+export function commonFolder(folders: string[]): string {
+  if (!folders.length) return ''
+  const split = folders.map((f) => f.split('/').filter(Boolean))
+  let prefix = split[0]!
+  for (const segs of split.slice(1)) {
+    let i = 0
+    while (i < prefix.length && prefix[i] === segs[i]) i++
+    prefix = prefix.slice(0, i)
+    if (!prefix.length) break
+  }
+  return prefix.join('/')
+}

package/layers/media/app/utils/ops.ts

@@ -0,0 +1,62 @@
+import type { LibraryItem } from './library'
+import type { OpItem, DeleteReport } from '../../server/utils/media-ops'
+import type { Conflict, RelocationReport } from '../../server/utils/relocate-ops'
+import type { MediaUsage } from '../../server/utils/usages'
+
+// Single-source the HTTP wire shapes from the server utils that own them — one definition, no drift.
+export type { OpItem, DeleteReport, Conflict, RelocationReport, MediaUsage }
+
+/** Structural shape of a UiMenu entry (UiMenu declares its own copy; kept in sync structurally). */
+export interface MenuItem { label: string; value: string; danger?: boolean; disabled?: boolean }
+
+/** A menu entry before its label is localized: carries an i18n key (+ a `count` for plural-bearing
+ *  entries) so the pure builder stays free of presentation copy; the composable resolves it via useT. */
+export interface MenuItemSpec { labelKey: string; count?: number; value: string; danger?: boolean }
+
+export function toOpItem(item: LibraryItem): OpItem {
+  return item.type === 'folder' ? { type: 'folder', path: item.folder.path } : { type: 'file', id: item.file.id }
+}
+
+/** Map a right-clicked element to its LibraryItem via the data-id attributes
+ *  (files carry data-file-id, folders carry data-drop-folder). Null if neither matches. */
+export function resolveTargetItem(el: Element | null, items: LibraryItem[]): LibraryItem | null {
+  const fileEl = el?.closest('[data-file-id]')
+  if (fileEl) {
+    const id = Number(fileEl.getAttribute('data-file-id'))
+    return items.find((i) => i.type === 'file' && i.file.id === id) ?? null
+  }
+  const folderEl = el?.closest('[data-drop-folder]')
+  if (folderEl) {
+    const path = folderEl.getAttribute('data-drop-folder')
+    return items.find((i) => i.type === 'folder' && i.folder.path === path) ?? null
+  }
+  return null
+}
+
+/** Explorer semantics: right-clicking a selected item targets the whole selection;
+ *  right-clicking elsewhere targets just that item. */
+export function effectiveTargets(clicked: LibraryItem, isSelected: (i: LibraryItem) => boolean, selected: LibraryItem[]): LibraryItem[] {
+  return isSelected(clicked) ? selected : [clicked]
+}
+
+/** Build the context-menu items for the current target + clipboard state. Blank space with an
+ *  empty clipboard returns [] (the caller suppresses the menu). */
+export function buildMenuItems(ctx: { targetCount: number; targetType: 'file' | 'folder' | null; clipboardEmpty: boolean }): MenuItemSpec[] {
+  const { targetCount, targetType, clipboardEmpty } = ctx
+  if (targetCount === 0) return clipboardEmpty ? [] : [{ labelKey: 'media.menu.paste', value: 'paste' }]
+  if (targetCount === 1) {
+    const items: MenuItemSpec[] = [
+      { labelKey: 'media.menu.cut', value: 'cut' },
+      { labelKey: 'media.menu.copy', value: 'copy' },
+      { labelKey: 'media.menu.rename', value: 'rename' },
+      { labelKey: 'media.menu.delete', value: 'delete', danger: true },
+    ]
+    if (targetType === 'folder' && !clipboardEmpty) items.push({ labelKey: 'media.menu.pasteInto', value: 'paste' })
+    return items
+  }
+  return [
+    { labelKey: 'media.menu.cut', value: 'cut' },
+    { labelKey: 'media.menu.copy', value: 'copy' },
+    { labelKey: 'media.menu.deleteN', count: targetCount, value: 'delete', danger: true },
+  ]
+}

package/layers/media/app/utils/picture-model.ts

@@ -0,0 +1,125 @@
+import type { ResolvedMedia } from '../../server/utils/resolve'
+import type { VariantFit, VariantFormat, ResolvedVariant } from '../../../core/server/utils/kestrel-config'
+import { variantName } from './variant-name'
+
+/** What a `KestrelImg` / `useMediaVariant` call declares it needs. One call may declare MULTIPLE sizes and
+ *  formats: `widths` (proportional responsive set) and/or a fixed-box `crop`, plus named config `preset`s,
+ *  crossed with `formats` (preference order, most-modern first). */
+export interface VariantRequest {
+  widths?: number[]
+  crop?: { width: number; height: number; fit?: VariantFit }
+  preset?: string | string[]
+  formats?: VariantFormat[]
+  /** The `<img sizes>` attribute; `auto` (or `auto, <fallback>`) is honoured on lazy images (see resolveSizes). */
+  sizes?: string
+}
+
+export interface PictureSource { type: string; srcset: string }
+export interface PictureModel {
+  sources: PictureSource[]
+  src: string
+  width: number | null
+  height: number | null
+  alt: string
+  sizes?: string
+}
+
+const MIME: Record<string, string> = { webp: 'image/webp', jpeg: 'image/jpeg', jpg: 'image/jpeg', png: 'image/png', avif: 'image/avif', gif: 'image/gif' }
+
+/**
+ * `sizes=auto` lets the browser pick the srcset candidate from the image's rendered width, but ONLY on
+ * lazy-loaded images — on eager ones it is inert. Non-supporting browsers ignore the `auto` keyword and use
+ * the fallback after it, so `auto, 100vw` degrades to `100vw`. Hence: keep `auto` only when lazy (with any
+ * fallback), and on an eager image drop the keyword, leaving just the fallback.
+ */
+export function resolveSizes(sizes: string | undefined, lazy: boolean): string | undefined {
+  if (!sizes) return undefined
+  const t = sizes.trim()
+  if (/^auto\b/i.test(t)) {
+    const fallback = t.slice(4).replace(/^\s*,\s*/, '').trim()
+    if (!lazy) return fallback || undefined
+    return fallback ? `auto, ${fallback}` : 'auto'
+  }
+  return t
+}
+
+/**
+ * The concrete, registrable specs a request declares (for the prerender scan): each `width` → a
+ * proportional `w<width>` spec, a `crop` → a fixed-box spec, both crossed with the request's formats.
+ * Named `preset`s are NOT expanded — they are already config-resolved (referenced by name, not discovered).
+ */
+export function requestVariantSpecs(req: VariantRequest): ResolvedVariant[] {
+  const formats: VariantFormat[] = req.formats?.length ? req.formats : ['webp']
+  const out: ResolvedVariant[] = []
+  // props may bind strings; drop any non-positive-integer dim so a bad spec is never registered (would crash sharp later)
+  for (const raw of req.widths ?? []) {
+    const w = posInt(raw)
+    if (w != null) out.push({ name: variantName({ width: w }), width: w, height: null, fit: 'cover', position: 'centre', formats: [...formats] })
+  }
+  if (req.crop) {
+    const w = posInt(req.crop.width)
+    const h = posInt(req.crop.height)
+    if (w != null && h != null) out.push({ name: variantName({ width: w, height: h, fit: req.crop.fit }), width: w, height: h, fit: req.crop.fit ?? 'cover', position: 'centre', formats: [...formats] })
+  }
+  return out
+}
+
+function posInt(value: unknown): number | null {
+  const n = Math.floor(Number(value))
+  return Number.isFinite(n) && n >= 1 ? n : null
+}
+
+/** The variant names a request targets: derived names for widths/crop + any explicit preset names.
+ *  Applies the SAME posInt sanitisation as requestVariantSpecs so the render-lookup name matches the
+ *  registered/derived name — otherwise a fractional width registers `w640` but looks up `w640.5`, and the
+ *  derivative is never used. */
+export function requestedNames(req: VariantRequest): string[] {
+  const names: string[] = []
+  for (const raw of req.widths ?? []) {
+    const w = posInt(raw)
+    if (w != null) names.push(variantName({ width: w }))
+  }
+  if (req.crop) {
+    const w = posInt(req.crop.width)
+    const h = posInt(req.crop.height)
+    if (w != null && h != null) names.push(variantName({ width: w, height: h, fit: req.crop.fit }))
+  }
+  const presets = req.preset ? (Array.isArray(req.preset) ? req.preset : [req.preset]) : []
+  names.push(...presets)
+  return [...new Set(names)]
+}
+
+/**
+ * Build the `<picture>` view-model for a resolved media + a variant request: one `<source>` per requested
+ * format (in the request's preference order) whose srcset is the matching derivatives, and an `<img>`
+ * fallback = the largest derivative of the LAST (most-compatible) format, or the original when none exist.
+ * Pure — the load-bearing render logic, unit-tested without a DOM.
+ */
+export function buildPictureModel(media: ResolvedMedia, req: VariantRequest, opts: { lazy: boolean }): PictureModel {
+  const names = new Set(requestedNames(req))
+  const formats = (req.formats?.length ? req.formats : ['webp']) as string[]
+  const pool = media.variants.filter((v) => names.has(v.name))
+
+  const sources: PictureSource[] = []
+  for (const fmt of formats) {
+    const entries = pool.filter((v) => v.format === fmt).sort((a, b) => a.width - b.width)
+    if (!entries.length) continue
+    sources.push({ type: MIME[fmt] ?? `image/${fmt}`, srcset: entries.map((v) => `${v.url} ${v.width}w`).join(', ') })
+  }
+
+  // <img> fallback: the largest derivative of the last (most-compatible) requested format; else the original
+  // (which may be a large PNG/AVIF, but is always a valid last resort).
+  const lastFmt = formats[formats.length - 1]
+  const lastEntries = pool.filter((v) => v.format === lastFmt).sort((a, b) => a.width - b.width)
+  const fallback = lastEntries[lastEntries.length - 1]
+
+  return {
+    sources,
+    src: fallback?.url ?? media.src,
+    width: fallback?.width ?? media.width,
+    height: fallback?.height ?? media.height,
+    alt: media.alt ?? '',
+    // Lazy images with no explicit sizes default to `auto, 100vw` — a strict upgrade over the 100vw default.
+    sizes: resolveSizes(req.sizes ?? (opts.lazy ? 'auto, 100vw' : undefined), opts.lazy),
+  }
+}

package/layers/media/app/utils/thumbhash.ts

@@ -0,0 +1,19 @@
+import { thumbHashToDataURL } from 'thumbhash'
+
+/**
+ * Decode a base64 thumbhash (as stored by the media pipeline, `derive.ts`) to a tiny PNG data URL — or
+ * null when absent/malformed. Pure + deterministic. Decoded CLIENT-SIDE only (see `useBlurUp`): the
+ * ~6 KB PNG data URL must not be inlined in SSR HTML — the ~30-byte thumbhash string ships in the
+ * payload and is inflated here after mount. Never throws — bad input degrades to null (no placeholder).
+ */
+export function thumbhashToDataUrl(thumbhash: string | null | undefined): string | null {
+  if (!thumbhash) return null
+  try {
+    const bin = atob(thumbhash)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return thumbHashToDataURL(bytes)
+  } catch {
+    return null
+  }
+}

package/layers/media/app/utils/variant-name.ts

@@ -0,0 +1,20 @@
+import type { VariantFit } from '../../../core/server/utils/kestrel-config'
+
+export interface VariantShape {
+  width: number
+  /** A fixed-box height (crop). null/undefined ⇒ proportional (width-only). */
+  height?: number | null
+  fit?: VariantFit
+}
+
+/**
+ * Canonical stable name for a variant shape — the manifest/object-key stem. This ONE function is shared by
+ * the render lookup (`KestrelImg` / `useMediaVariant`), the prerender scan that registers a discovered spec,
+ * and (via the registry) `deriveImage`, so all three agree on the name. Names stay `[A-Za-z0-9_-]` so the
+ * `<name>.<format>` manifest key and the relocate parser split cleanly on the last dot.
+ */
+export function variantName(shape: VariantShape): string {
+  if (shape.height == null) return `w${shape.width}`
+  const fit = shape.fit ?? 'cover'
+  return fit === 'cover' ? `c${shape.width}x${shape.height}` : `c${shape.width}x${shape.height}-${fit}`
+}

package/layers/media/nuxt.config.ts

@@ -0,0 +1,3 @@
+// Marks `media` as a Nuxt layer (so its components/server code are auto-registered). The media config
+// + the `kestrel` module that resolves it now live in the core layer (single non-auth config source).
+export default defineNuxtConfig({})

package/layers/media/server/api/media/[id]/usages.get.ts

@@ -0,0 +1,8 @@
+import { findMediaUsages } from '../../../utils/usages'
+import { requireMediaCollection } from '../../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  const id = requireId(event)
+  return { id, usages: findMediaUsages(useDb(), id) }
+})

package/layers/media/server/api/media/[id].delete.ts

@@ -0,0 +1,18 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import { media } from '../../collections/media'
+import { useStorageDriver } from '../../../../core/server/utils/storage'
+import { deleteAffected } from '../../utils/media-ops'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  requireMediaCollection()
+  const id = requireId(event)
+  const cols = getTableColumns(media) as Record<string, never>
+  const db = useDb()
+  // deleteAffected silently no-ops on a missing row, so keep an explicit 404 guard.
+  const row = db.select({ id: cols.id }).from(media).where(eq(cols.id, id)).get() as { id: number } | undefined
+  if (!row) throw createError({ statusCode: 404, statusMessage: `media ${id} not found` })
+  await deleteAffected(db, useStorageDriver(), [{ type: 'file', id }], false)
+  return { deleted: true, id }
+})

package/layers/media/server/api/media/[id].get.ts

@@ -0,0 +1,10 @@
+import media from '../../collections/media'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  const query = getQuery(event)
+  const depth = Number(query.depth ?? 0)
+  const locale = query.locale as string | undefined
+  return getOne(useDb(), media, requireId(event), depth, locale)
+})