@michaelthielemann/kestrel 1.2.1

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

@@ -0,0 +1,41 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import { media } from '../../collections/media'
+import { mergeTranslations, type Translations } from '../../utils/translations'
+import { emitMediaWrite } from '../../utils/media-write'
+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 body = await readBody(event)
+  const cols = getTableColumns(media) as Record<string, never>
+  const db = useDb()
+  const expectedUpdatedAt = readIfUnmodifiedSince(event)
+  const patch: Record<string, unknown> = { updatedAt: new Date() }
+  // `folder` is immutable via PATCH: relocating a file means moving its storage object and every
+  // derivative, which belongs to the media-library slice. Writing only the column would desync it
+  // from the folder baked into storageKey, which is what the public URL is built from.
+  const needsCurrent = expectedUpdatedAt !== undefined
+    || (body?.translations && typeof body.translations === 'object' && !Array.isArray(body.translations))
+  const current = needsCurrent
+    ? db.select().from(media).where(eq(cols.id, id)).get() as { translations?: Translations; updatedAt?: Date } | undefined
+    : undefined
+  // Optimistic concurrency: honor the same X-Kestrel-If-Unmodified-Since precondition the collection CRUD
+  // does, so two media-viewer tabs editing the same asset's alt text can't silently overwrite each other.
+  if (expectedUpdatedAt !== undefined && current) {
+    const cur = current.updatedAt instanceof Date ? current.updatedAt.getTime() : new Date(current.updatedAt as never).getTime()
+    if (cur !== expectedUpdatedAt) {
+      throw createError({ statusCode: 409, statusMessage: 'This media item changed since you opened it. Reload before saving.' })
+    }
+  }
+  if (body?.translations && typeof body.translations === 'object' && !Array.isArray(body.translations)) {
+    // Media keeps all locales in one JSON column. Deep-merge per locale so a partial PATCH (e.g. just
+    // `en.alt` from the media viewer) keeps the other locales AND the locale's other fields intact.
+    patch.translations = mergeTranslations(current?.translations, body.translations as Translations)
+  }
+  const row = db.update(media).set(patch).where(eq(cols.id, id)).returning().get() as Record<string, unknown> | undefined
+  if (!row) throw createError({ statusCode: 404, statusMessage: `media ${id} not found` })
+  emitMediaWrite({ id }, row) // alt/title/description changed → re-render embedding pages (fresh alt text)
+  return row
+})

package/layers/media/server/api/media/backfill.post.ts

@@ -0,0 +1,18 @@
+import { runBackfill } from '../../utils/backfill'
+import { useStorageDriver, mediaRuntimeConfig } from '../../../../core/server/utils/storage'
+import { DEFAULT_IMAGE_POLICY } from '../../../../core/server/utils/kestrel-config'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+/**
+ * Admin-triggered variant backfill/prune (the Mediathek "Regenerate/Prune" action). `{ check: true }` is a
+ * dry-run reporting the plan (rows / would-generate / would-prune) — the UI shows it before applying.
+ * Synchronous: fine for a dry-run and moderate libraries; a very large library should run the
+ * `media:backfill` task on a schedule instead (a full-original GET + sharp per row).
+ */
+export default defineEventHandler(async (event) => {
+  requireAdmin(event)
+  requireMediaCollection()
+  const body = (await readBody(event).catch(() => ({}))) as { check?: boolean }
+  const policy = mediaRuntimeConfig().imagePolicy ?? DEFAULT_IMAGE_POLICY
+  return runBackfill(useDb(), useStorageDriver(), policy, { check: !!body?.check })
+})

package/layers/media/server/api/media/copy.post.ts

@@ -0,0 +1,7 @@
+import { runRelocation } from '../../utils/relocate-ops'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  return runRelocation(event, (items, body) => ({ type: 'copy', items, dest: typeof body.dest === 'string' ? body.dest : '' }))
+})

package/layers/media/server/api/media/delete.post.ts

@@ -0,0 +1,13 @@
+import { deleteAffected } from '../../utils/media-ops'
+import { coerceOpItems } from '../../utils/relocate-ops'
+import { useStorageDriver } from '../../../../core/server/utils/storage'
+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 body = await readBody(event)
+  const items = coerceOpItems(body?.items)
+  if (!items.length) throw createError({ statusCode: 400, statusMessage: 'No items to delete' })
+  return deleteAffected(useDb(), useStorageDriver(), items, body?.dryRun === true)
+})

package/layers/media/server/api/media/folders.post.ts

@@ -0,0 +1,18 @@
+import { ensureFolder } from '../../utils/folders'
+import { sanitizeFolder } from '../../utils/naming'
+import { useStorageDriver } from '../../../../core/server/utils/storage'
+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 body = await readBody(event)
+  const path = sanitizeFolder(typeof body?.path === 'string' ? body.path : '')
+  if (!path) throw createError({ statusCode: 400, statusMessage: 'A non-empty folder path is required' })
+  // ensureDir (mkdir, can throw ENAMETOOLONG/ENOTDIR/etc.) runs BEFORE the row commit — a folder row
+  // with no backing directory would list forever with every upload/retry into it failing the same way.
+  await useStorageDriver().ensureDir?.(path)
+  const db = useDb()
+  ensureFolder(db, path)
+  return { path }
+})

package/layers/media/server/api/media/index.get.ts

@@ -0,0 +1,15 @@
+import media from '../../collections/media'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  const query = getQuery(event)
+  return list(useDb(), media, {
+    locale: query.locale as string | undefined,
+    sort: query.sort as string | undefined,
+    page: query.page ? Number(query.page) : undefined,
+    perPage: query.perPage ? Number(query.perPage) : undefined,
+    filter: parseFilter(query as Record<string, unknown>),
+    depth: query.depth ? Number(query.depth) : 0,
+  })
+})

package/layers/media/server/api/media/index.post.ts

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto'
+import { eq, inArray, getTableColumns, isNull } from 'drizzle-orm'
+import { media } from '../../collections/media'
+import { useStorageDriver, mediaRuntimeConfig } from '../../../../core/server/utils/storage'
+import { sniffMime, extForMime, resolveAllowedMimes } from '../../utils/sniff'
+import { sanitizeFolder, buildKey, suggestFreeName, withExtension } from '../../utils/naming'
+import { sanitizeSvg } from '../../utils/sanitize-svg'
+import { deriveImage, RASTER, type DerivedImage } from '../../utils/derive'
+import { DEFAULT_IMAGE_POLICY } from '../../../../core/server/utils/kestrel-config'
+import { buildMediaValues, derivativeKey, type DerivativeManifest } from '../../utils/record'
+import { persistUpload } from '../../utils/persist-upload'
+import type { Translations } from '../../utils/translations'
+import { activeVariants } from '../../utils/variants'
+import { ensureFolder } from '../../utils/folders'
+import { primaryLocale } from '../../../../core/server/utils/locale'
+import { isUniqueViolation } from '../../../../core/server/utils/crud'
+import { withLock, mediaLockKey } from '../../../../core/server/utils/key-lock'
+import { requireMediaCollection } from '../../utils/media-enabled'
+import { emitMediaWrite } from '../../utils/media-write'
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  requireMediaCollection()
+  const cfg = mediaRuntimeConfig()
+  const len = Number(getRequestHeader(event, 'content-length'))
+  // A missing/garbage Content-Length means a chunked transfer, which readMultipartFormData would
+  // buffer with no ceiling — refuse it up front. The declared length is then a cheap pre-check; the
+  // real cap is re-asserted on the parsed bytes below (a client can under-declare Content-Length).
+  if (!Number.isFinite(len) || len < 0) {
+    throw createError({ statusCode: 411, statusMessage: 'Length required' })
+  }
+  if (len > cfg.maxUploadBytes) {
+    throw createError({ statusCode: 413, statusMessage: 'Payload too large' })
+  }
+
+  const parts = await readMultipartFormData(event)
+  if (!parts) throw createError({ statusCode: 400, statusMessage: 'Expected multipart/form-data' })
+  const filePart = parts.find((p) => p.name === 'file' && p.filename)
+  if (!filePart || !filePart.data?.length) throw createError({ statusCode: 400, statusMessage: 'Missing file' })
+  if (filePart.data.length > cfg.maxUploadBytes) throw createError({ statusCode: 413, statusMessage: 'Payload too large' })
+  const text = (n: string) => parts.find((p) => p.name === n && !p.filename)?.data.toString('utf8')
+
+  let bytes = filePart.data as Buffer
+  const allowed = resolveAllowedMimes(cfg.allowedMimes)
+  const mime = await sniffMime(bytes)
+  if (!mime || !allowed.has(mime)) {
+    throw createError({ statusCode: 415, statusMessage: `Unsupported media type${mime ? `: ${mime}` : ''}` })
+  }
+  const ext = extForMime(mime)
+
+  if (mime === 'image/svg+xml') bytes = Buffer.from(sanitizeSvg(bytes.toString('utf8')))
+
+  // server-controlled key only (folder + filename are both sanitized → no path traversal)
+  const folder = sanitizeFolder(text('folder') ?? '')
+  const overwrite = text('overwrite') === 'true'
+  // The stored extension follows the sniffed type, never the client filename (content-type confusion).
+  const filename = withExtension(text('filename') ?? filePart.filename ?? 'file', ext)
+  const storageKey = buildKey(folder, filename)
+
+  const db = useDb()
+  const cols = getTableColumns(media) as Record<string, never>
+  const driver = useStorageDriver()
+
+  const checksum = createHash('sha256').update(bytes).digest('hex')
+  // Narrow generation: derive exactly the currently-registered variant set (the media_settings registry),
+  // falling back to the config policy's variants when the registry is empty (fresh project / no scan yet).
+  // Done BEFORE the per-key lock so uploads of different files derive in parallel (sharp is the hot path).
+  const policy = cfg.imagePolicy ?? DEFAULT_IMAGE_POLICY
+  // A raster that sniffs fine but is truncated/corrupt (or a misconfigured crop position slipping past
+  // validation) makes sharp reject mid-pipeline — a bare unwrapped throw here would 500 with an internal
+  // vips error string. Surface it as a real, unprocessable-upload 4xx instead.
+  let derived: DerivedImage | undefined
+  if (RASTER.has(mime)) {
+    try {
+      derived = await deriveImage(bytes, { ...policy, variants: activeVariants(db, policy.variants, policy.presets) })
+    } catch (error) {
+      throw createError({ statusCode: 422, statusMessage: 'Could not process this image', data: { reason: (error as Error)?.message } })
+    }
+  }
+
+  const alt = text('alt')
+  const title = text('title')
+  const description = text('description')
+  const translations = alt || title || description ? { [primaryLocale()]: { alt, title, description } } : {}
+
+  // Serialize the collision-check → put → insert per storageKey: two concurrent uploads to the SAME key
+  // (or a backfill re-deriving it) must not interleave, or last-writer-wins would leave the winning row
+  // describing the loser's bytes. Different keys never share a lock, so throughput is unaffected.
+  const { row, created } = await withLock(mediaLockKey(storageKey), async (): Promise<{ row: Record<string, unknown>; created: boolean }> => {
+    const existing = db.select().from(media).where(eq(cols.storageKey, storageKey)).get() as
+      | { id: number; derivatives?: DerivativeManifest; translations?: Translations }
+      | undefined
+
+    // An object on disk with no media row (another media's derivative, or an orphan) must never be
+    // clobbered — not even under overwrite, which only replaces a managed media row.
+    const blockedByDisk = !existing && (await driver.exists?.(storageKey))
+    if ((existing && !overwrite) || blockedByDisk) {
+      // One query: the filenames already taken in this folder, used to suggest a free name in memory.
+      const takenNames = new Set(
+        db.select({ f: cols.filename }).from(media)
+          .where(folder ? eq(cols.folder, folder) : isNull(cols.folder))
+          .all().map((r) => (r as { f: string }).f),
+      )
+      if (blockedByDisk) takenNames.add(filename)
+      throw createError({
+        statusCode: 409,
+        statusMessage: 'A file with this name already exists',
+        data: { storageKey, existingId: existing?.id, suggestion: suggestFreeName(filename, (n) => !takenNames.has(n)) },
+      })
+    }
+
+    // Reserve the derivative namespace: `derivativeKey` mints a syntactically valid ORIGINAL key
+    // (`<key>-<name>.<format>`), so a same-named upload elsewhere (or a coincidentally matching filename)
+    // can already own the exact key this derive is about to `driver.put` over. The create-path write below
+    // has no per-key collision check of its own, so refuse up front rather than silently overwrite another
+    // row's blob out from under it.
+    const derivKeys = (derived?.variants ?? []).map((v) => derivativeKey(storageKey, v.name, v.format))
+    if (derivKeys.length) {
+      const clash = db.select({ storageKey: cols.storageKey }).from(media).where(inArray(cols.storageKey, derivKeys)).all() as { storageKey: string }[]
+      if (clash.length) {
+        // Not a 409: the uploader reads that status as the rename/overwrite/skip name-conflict contract,
+        // and neither branch resolves this — the requested name is free, and overwriting it re-derives the
+        // very same blocked keys. The message names the file the user actually dropped, plus the existing
+        // one standing in its way, so the remedy (rename either) is visible from the upload dialog.
+        throw createError({
+          statusCode: 422,
+          statusMessage: `Cannot store "${filename}": the existing file "${clash[0]!.storageKey}" already uses a name reserved for one of its generated image sizes. Rename either file, then upload again.`,
+          data: { storageKey, clashKeys: clash.map((c) => c.storageKey) },
+        })
+      }
+    }
+
+    if (folder) ensureFolder(db, folder)
+    const values = buildMediaValues({ storageKey, folder, filename, mime, ext, size: bytes.length, checksum, derived, translations })
+    try {
+      // persistUpload writes the objects then the row; on a create-path failure it removes the freshly-written
+      // blobs so a partial upload never strands orphans that permanently 409-block the filename.
+      const saved = await persistUpload(db, driver, { storageKey, bytes, mime, derived, values, existing, overwrite })
+      return { row: saved, created: !(existing && overwrite) }
+    } catch (error) {
+      // A double-submit that slips through the check surfaces as a UNIQUE violation → 409, not a raw 500.
+      if (isUniqueViolation(error)) {
+        throw createError({ statusCode: 409, statusMessage: 'A file with this name already exists', data: { storageKey } })
+      }
+      throw error
+    }
+  })
+
+  // Only an overwrite can invalidate published output: it rewrites the bytes, dimensions, thumbhash and
+  // derivative manifest under an unchanged id, so every page embedding it holds srcset candidates that no
+  // longer exist. Gate on `created`, not the requested `overwrite` flag — an overwrite request that finds
+  // no row inserts a fresh one, which nothing published can reference yet.
+  if (!created) emitMediaWrite({ id: row.id as number }, row)
+
+  setResponseStatus(event, created ? 201 : 200)
+  return { ...row, url: driver.publicUrl(storageKey) }
+})

package/layers/media/server/api/media/library.get.ts

@@ -0,0 +1,17 @@
+import { listLibrary } from '../../utils/library'
+import { useStorageDriver } from '../../../../core/server/utils/storage'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  const query = getQuery(event)
+  const driver = useStorageDriver()
+  return listLibrary(useDb(), {
+    folder: typeof query.folder === 'string' ? query.folder : '',
+    search: typeof query.search === 'string' ? query.search : undefined,
+    type: query.type === 'image' ? 'image' : 'all',
+    page: query.page ? Number(query.page) : undefined,
+    perPage: query.perPage ? Number(query.perPage) : undefined,
+    sort: typeof query.sort === 'string' ? query.sort : undefined,
+  }, (key) => driver.publicUrl(key))
+})

package/layers/media/server/api/media/move.post.ts

@@ -0,0 +1,7 @@
+import { runRelocation } from '../../utils/relocate-ops'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  return runRelocation(event, (items, body) => ({ type: 'move', items, dest: typeof body.dest === 'string' ? body.dest : '' }))
+})

package/layers/media/server/api/media/rename.post.ts

@@ -0,0 +1,7 @@
+import { runRelocation } from '../../utils/relocate-ops'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  return runRelocation(event, (items, body) => ({ type: 'rename', items, name: typeof body.name === 'string' ? body.name : '' }))
+})

package/layers/media/server/api/media/resolve.get.ts

@@ -0,0 +1,13 @@
+import { resolveManyByIds } from '../../utils/resolve'
+import { useStorageDriver } from '../../../../core/server/utils/storage'
+import { primaryLocale } from '../../../../core/server/utils/locale'
+import { requireMediaCollection } from '../../utils/media-enabled'
+
+export default defineEventHandler((event) => {
+  requireMediaCollection()
+  const q = getQuery(event)
+  const ids = String(q.ids ?? '').split(',').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n > 0)
+  const locale = typeof q.locale === 'string' ? q.locale : primaryLocale()
+  const driver = useStorageDriver()
+  return { data: resolveManyByIds(useDb(), ids, locale, (k) => driver.publicUrl(k)) }
+})

package/layers/media/server/collections/media-settings.ts

@@ -0,0 +1,25 @@
+import { buildCollection } from '../../../fields/server/utils/buildCollection'
+import { defineCollection } from '../../../core/server/utils/defineCollection'
+
+// The usage-driven variant REGISTRY: a single-row store of the active image-variant set (name × size ×
+// format presets) that the upload path derives and the generate-time scan reconciles. A singleton so it
+// reuses the schema engine + (later) the singleton editor, but `nav: false` — it is a system/config store,
+// not content, and must not appear as a flat top-level rail item beside the media library. It is surfaced
+// (if at all) through a Media sub-menu once the rail supports nested navigation.
+const built = buildCollection(defineCollection({
+  name: 'media_settings',
+  mode: 'single',
+  translatable: false,
+  builtin: true,
+  nav: false,
+  label: { singular: 'Media settings', plural: 'Media settings' },
+  icon: 'sliders',
+  fields: {
+    // The resolved variant set (`StoredVariant[]`): each entry carries its provenance (`source`/`pinned`)
+    // so the scan reconcile can replace discovered entries while preserving hand-authored ones.
+    variants: { type: 'json' },
+  },
+}))
+
+export const mediaSettings = built.table
+export default built

package/layers/media/server/collections/media.ts

@@ -0,0 +1,29 @@
+import { buildCollection } from '../../../fields/server/utils/buildCollection'
+import { defineCollection } from '../../../core/server/utils/defineCollection'
+
+const built = buildCollection(defineCollection({
+  name: 'media',
+  mode: 'multi',
+  translatable: false,
+  builtin: true,
+  label: { singular: 'Media', plural: 'Media' },
+  icon: 'image',
+  fields: {
+    storageKey: { type: 'text', required: true, unique: true },
+    // Indexed: the library lists/filters/rolls-up recursive sizes by folder on every request.
+    folder: { type: 'text', index: true },
+    filename: { type: 'text', required: true },
+    mime: { type: 'text', required: true },
+    ext: { type: 'text', required: true },
+    size: { type: 'number', required: true },
+    width: { type: 'number' },
+    height: { type: 'number' },
+    checksum: { type: 'text' },
+    thumbhash: { type: 'text' },
+    derivatives: { type: 'json' },
+    translations: { type: 'json' },
+  },
+}))
+
+export const media = built.table
+export default built

package/layers/media/server/database/folders.ts

@@ -0,0 +1,10 @@
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+// Path-based folder registry: persists folders (incl. empty ones) and is the authoritative
+// tree for media navigation. `path` is the normalized folder path (root '' is never a row).
+export const folders = sqliteTable('folders', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  path: text('path').notNull().unique(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().$defaultFn(() => new Date()),
+})

package/layers/media/server/middleware/ondemand-variants.ts

@@ -0,0 +1,37 @@
+import type { H3Event } from 'h3'
+import { deriveOnDemand, variantKeyFromPath } from '../utils/ondemand'
+import { useStorageDriver, mediaRuntimeConfig } from '../../../core/server/utils/storage'
+import { DEFAULT_IMAGE_POLICY } from '../../../core/server/utils/kestrel-config'
+
+/**
+ * Whether the IP allow-list would deny this request, checked directly rather than relied on by ordering:
+ * Nitro sorts middleware by layer scan dir first, and media's precedes access's, so the real
+ * access/00.ip-allowlist gate has NOT run yet when this middleware short-circuits with a derived response.
+ */
+export function deniedByAllowlist(event: H3Event): boolean {
+  const mode = allowlistMode(process.env.KESTREL_IP_ALLOWLIST_MODE, process.env.KESTREL_IP_ALLOWLIST)
+  if (mode !== 'enforce') return false
+  return !ipAllowed(clientIp(event), parseAllowlist(process.env.KESTREL_IP_ALLOWLIST))
+}
+
+// Dev only: a GET for a not-yet-generated variant under the media baseUrl derives it from the original and
+// serves it, so a newly-declared size/format shows in the editor preview without a full publish. On a hit
+// this is a no-op — the static /uploads handler serves the cached file.
+export default defineEventHandler(async (event) => {
+  if (!import.meta.dev || event.method !== 'GET') return
+  if (deniedByAllowlist(event)) return
+  const cfg = mediaRuntimeConfig()
+  const key = variantKeyFromPath(event.path, cfg.local.baseUrl)
+  if (key == null) return
+  const driver = useStorageDriver()
+  if (await driver.exists?.(key)) return
+  // Dev is the diagnosis environment, so surface a real derive failure (missing original, sharp reject)
+  // instead of silently 404ing — a broken preview <img> with no log violates the fail-loud convention.
+  const result = await deriveOnDemand(useDb(), driver, cfg.imagePolicy ?? DEFAULT_IMAGE_POLICY, key).catch((error) => {
+    console.warn(`[kestrel] on-demand variant derive failed for ${key}:`, (error as Error)?.message ?? error)
+    return null
+  })
+  if (!result) return
+  setResponseHeader(event, 'content-type', result.mime)
+  return result.bytes
+})

package/layers/media/server/plugins/02.register-media.ts

@@ -0,0 +1,19 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import { media as mediaTable } from '../collections/media'
+import { registerFieldPopulator } from '../../../core/server/utils/populate'
+import { buildMediaFieldPopulator } from '../utils/populate'
+import { resolveMedia } from '../utils/resolve'
+import { useStorageDriver } from '../../../core/server/utils/storage'
+import { mediaCollectionEnabled } from '../utils/media-enabled'
+
+export default defineNitroPlugin(() => {
+  // A consumer who turned the built-in off has no `media` table, so a row that still carries a media id
+  // must stay unpopulated rather than blow up the read path.
+  if (!mediaCollectionEnabled()) return
+  const cols = getTableColumns(mediaTable) as Record<string, never>
+  registerFieldPopulator('media', buildMediaFieldPopulator((id, locale) => {
+    const driver = useStorageDriver()
+    const row = useDb().select().from(mediaTable).where(eq(cols.id, id)).get()
+    return row ? resolveMedia(row as never, locale, (k) => driver.publicUrl(k)) : null
+  }))
+})

package/layers/media/server/plugins/03.media-cleanup.ts

@@ -0,0 +1,20 @@
+import { registerWriteListener } from '../../../core/server/utils/write-events'
+import { planMediaDeletion } from '../utils/media-cleanup'
+import { useStorageDriver } from '../../../core/server/utils/storage'
+
+/**
+ * Storage GC for media-record deletes. The media library's own `deleteAffected` deletes storage inline
+ * (and bypasses the write bus); this covers EVERY OTHER delete path — the generic CRUD `remove()`, which
+ * emits a delete event — by removing the row's original + all derivatives from storage. So a media record
+ * is never removed while leaving orphaned files: principle 4 (output ≡ DB) for media, on every path.
+ * Fire-and-forget (best-effort, like the publisher); the driver's delete is idempotent, errors are logged.
+ */
+export default defineNitroPlugin(() => {
+  registerWriteListener((event) => {
+    const keys = planMediaDeletion(event)
+    if (!keys.length) return
+    const driver = useStorageDriver()
+    void Promise.all(keys.map((key) => driver.delete(key)))
+      .catch((error) => console.error('[kestrel] media storage cleanup failed:', error))
+  })
+})

package/layers/media/server/plugins/04.variant-capture.ts

@@ -0,0 +1,23 @@
+import { recordVariants, saveDiscoveredVariants } from '../utils/variant-capture'
+
+/**
+ * Auto-discovery capture. `KestrelImg`/`useMediaVariant` stash their concrete specs on the render's
+ * `event.context.kestrelVariants` during SSR. Renders count when they are either a PUBLISH render (the
+ * incremental publisher marks them with the `x-kestrel-publish` header, see publisher.ts `renderRoute`) OR
+ * a build-time PRERENDER render (the classic `nuxt generate` topology) — so live preview / stray runtime
+ * renders never pollute the scan. For a publish, `publishFull` reconciles the drained accumulator once at
+ * the end; the generate topology has no such orchestrator, so each prerendered route reconciles inline
+ * WITHOUT draining and the growing accumulator converges to the full used set by the last route.
+ *
+ * NOTE: relies on `beforeResponse` firing for the publisher's `localFetch` renders / the prerenderer, and on
+ * the app→server `event.context` bridge — verified by a real publish/generate, not the headless unit suite.
+ */
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('beforeResponse', (event) => {
+    const isPrerender = import.meta.prerender === true
+    if (getRequestHeader(event, 'x-kestrel-publish') !== '1' && !isPrerender) return
+    const specs = (event.context as { kestrelVariants?: unknown[] }).kestrelVariants
+    if (Array.isArray(specs) && specs.length) recordVariants(specs as never)
+    if (isPrerender) saveDiscoveredVariants(useDb(), { clear: false })
+  })
+})

package/layers/media/server/schema-tables/folders.ts

@@ -0,0 +1,4 @@
+import { folders } from '../database/folders'
+
+// Registers the standalone folders table with the schema engine (the `#kestrel/schema-tables` virtual).
+export default folders

package/layers/media/server/tasks/media/backfill.ts

@@ -0,0 +1,18 @@
+import { runBackfill } from '../../utils/backfill'
+import { useStorageDriver, mediaRuntimeConfig } from '../../../../core/server/utils/storage'
+import { DEFAULT_IMAGE_POLICY } from '../../../../core/server/utils/kestrel-config'
+
+/**
+ * Reconcile every media row's derivatives to the active variant registry: generate the missing sizes/formats
+ * (from the stored original) and prune the deregistered ones. `{check:true}` is a dry-run (report only).
+ * Trigger (like `db:migrate` — no `nuxi task run`): dev `GET /_nitro/tasks/media:backfill`; prod `runTask(
+ * 'media:backfill', { payload })` from the admin endpoint (`POST /api/media/backfill`) or a cron scheduledTask.
+ */
+export default defineTask({
+  meta: { name: 'media:backfill', description: 'Generate missing image variants + prune deregistered ones; {check:true}=dry-run' },
+  async run({ payload }) {
+    const policy = mediaRuntimeConfig().imagePolicy ?? DEFAULT_IMAGE_POLICY
+    const result = await runBackfill(useDb(), useStorageDriver(), policy, { check: !!(payload as { check?: boolean })?.check })
+    return { result }
+  },
+})