@michaelthielemann/kestrel 1.2.1

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

@@ -0,0 +1,132 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { ResolvedImagePolicy, ResolvedVariant, VariantFormat } from '../../../core/server/utils/kestrel-config'
+import type { StorageDriver } from '../../../core/server/utils/storage'
+import { media } from '../collections/media'
+import { deriveImage, RASTER } from './derive'
+import { derivativeKey, type DerivativeManifest } from './record'
+import { activeVariants } from './variants'
+import { withLock, mediaLockKey } from '../../../core/server/utils/key-lock'
+import { emitMediaWrite } from './media-write'
+
+// Mirrors index.post.ts: a long-lived (non-immutable, so a replace isn't pinned) cache for originals +
+// derivatives. Backfilled objects MUST carry the same header or the CDN caches them differently.
+const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
+
+export interface BackfillPlan {
+  /** Specs, each carrying ONLY its missing formats, to derive + add. */
+  missing: ResolvedVariant[]
+  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. */
+  orphanKeys: string[]
+}
+
+/**
+ * Pure diff of a media row's derivative manifest against the active variant set: what to generate, what to
+ * prune. A proportional spec wider than the source is never "missing" (deriveImage would skip it, so it can
+ * never be satisfied). Orphans are keyed per `<name>.<format>`, so a deregistered FORMAT of a still-active
+ * name is pruned too.
+ */
+export function planBackfill(row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[]): BackfillPlan {
+  const manifest = row.derivatives ?? {}
+  const activeKeys = new Set<string>()
+  const missing: ResolvedVariant[] = []
+  for (const spec of specs) {
+    const applicable = spec.height != null || !row.width || spec.width <= row.width
+    const missingFormats: VariantFormat[] = []
+    for (const f of spec.formats) {
+      activeKeys.add(`${spec.name}.${f}`)
+      if (applicable && !(`${spec.name}.${f}` in manifest)) missingFormats.push(f)
+    }
+    if (missingFormats.length) missing.push({ ...spec, formats: missingFormats })
+  }
+  const orphanKeys: string[] = []
+  for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
+  return { missing, orphanKeys }
+}
+
+interface BackfillRow { id: number; storageKey: string; mime: string; width: number | null; derivatives: DerivativeManifest | null }
+
+/**
+ * Reconcile ONE media row to the active set: derive its missing variants from the original (put-first),
+ * write the updated manifest, then prune orphan objects LAST (a crash never dangles the manifest). The pruned
+ * objects are this row's OWN deregistered derivatives — self-owned, so no cross-row ownership guard is needed
+ * (that is Slice 9's published-media GC, a different concern).
+ */
+export async function backfillRow(
+  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy,
+): Promise<{ generated: number; pruned: number }> {
+  const plan = planBackfill(row, specs)
+  if (!plan.missing.length && !plan.orphanKeys.length) return { generated: 0, pruned: 0 }
+
+  const orphaned = new Set(plan.orphanKeys)
+  const manifest: DerivativeManifest = {}
+  for (const [k, e] of Object.entries(row.derivatives ?? {})) if (!orphaned.has(e.key)) manifest[k] = e
+
+  let generated = 0
+  if (plan.missing.length) {
+    if (typeof driver.get !== 'function') throw new Error('storage driver cannot read originals back (no get()) — backfill needs it')
+    const derived = await deriveImage(await driver.get(row.storageKey), { ...policy, variants: plan.missing })
+    for (const v of derived.variants) {
+      const key = derivativeKey(row.storageKey, v.name, v.format)
+      await driver.put(key, v.bytes, v.mime, { cacheControl: MEDIA_CACHE_CONTROL })
+      manifest[`${v.name}.${v.format}`] = { key, width: v.width, height: v.height, mime: v.mime }
+      generated++
+    }
+  }
+
+  const cols = getTableColumns(media) as Record<string, never>
+  db.update(media).set({ derivatives: manifest, updatedAt: new Date() } as never).where(eq(cols.id, row.id)).run()
+  // Published pages hold this row's srcset candidates, so a rewritten manifest — especially a pruned
+  // key, which now 404s — has to re-render them. Emitted before the prune: a delete that throws must
+  // not leave the already-written manifest un-republished.
+  emitMediaWrite({ id: row.id }, { id: row.id })
+  for (const key of plan.orphanKeys) await driver.delete(key)
+  return { generated, pruned: plan.orphanKeys.length }
+}
+
+export interface BackfillReport { rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean }
+
+/**
+ * Iterate every raster media row, reconciling each to the active variant set. Sequential (sharp CPU + a
+ * full-original GET per row) and best-effort per row — a corrupt original is logged and skipped, never
+ * aborting the whole run. `check` reports the plan (rows / would-generate / would-prune) without writing.
+ */
+export async function runBackfill(
+  db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, opts: { check?: boolean } = {},
+): Promise<BackfillReport> {
+  const specs = activeVariants(db, policy.variants, policy.presets)
+  const rows = db.select().from(media).all() as BackfillRow[]
+  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check }
+  for (const snapshot of rows) {
+    if (!RASTER.has(snapshot.mime)) continue
+    if (opts.check) {
+      // Dry-run reads only (against the snapshot) — no mutation, so no lock.
+      const plan = planBackfill(snapshot, specs)
+      const toGenerate = plan.missing.reduce((n, s) => n + s.formats.length, 0)
+      if (!toGenerate && !plan.orphanKeys.length) continue
+      report.rowsChanged++
+      report.generated += toGenerate
+      report.pruned += plan.orphanKeys.length
+      continue
+    }
+    // Serialize per storageKey with the upload path, and re-read the row FRESH inside the lock: a concurrent
+    // overwrite may have replaced the bytes/dims/manifest since the up-front snapshot, and reconciling the
+    // stale snapshot against the new object would write a manifest whose dims describe the OLD image.
+    await withLock(mediaLockKey(snapshot.storageKey), async () => {
+      const cols = getTableColumns(media) as Record<string, never>
+      const row = db.select().from(media).where(eq(cols.id, snapshot.id)).get() as BackfillRow | undefined
+      if (!row || !RASTER.has(row.mime)) return
+      const plan = planBackfill(row, specs)
+      if (!plan.missing.length && !plan.orphanKeys.length) return
+      report.rowsChanged++
+      try {
+        const r = await backfillRow(db, driver, row, specs, policy)
+        report.generated += r.generated
+        report.pruned += r.pruned
+      } catch (error) {
+        console.error(`[kestrel] backfill failed for media ${row.id} (${row.storageKey}):`, (error as Error)?.message ?? error)
+      }
+    })
+  }
+  return report
+}

package/layers/media/server/utils/derive.ts

@@ -0,0 +1,59 @@
+import sharp from 'sharp'
+import { rgbaToThumbHash } from 'thumbhash'
+import type { ResolvedImagePolicy } from '../../../core/server/utils/kestrel-config'
+
+// The derivation policy is resolved once from kestrel config (KESTREL_MEDIA_IMAGE_* env → config → default)
+// and threaded in by the upload handler. `DEFAULT_IMAGE_POLICY` is auto-imported from kestrel-config
+// (the single export site); re-exporting it here would register a duplicate auto-import.
+export type ImagePolicy = ResolvedImagePolicy
+
+// Raster mimes that receive a derivative ladder. GIF is intentionally excluded: deriving WebP flattens it
+// to a static first frame. Shared by the upload handler and the backfill task so they never disagree.
+export const RASTER = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/avif'])
+
+export interface DerivedImage {
+  width: number
+  height: number
+  thumbhash: string
+  variants: { name: string; width: number; height: number; format: 'webp' | 'jpeg'; mime: string; bytes: Buffer }[]
+}
+
+export async function deriveImage(input: Buffer, policy: ImagePolicy): Promise<DerivedImage> {
+  const meta = await sharp(input, { limitInputPixels: 268402689 }).metadata()
+  // sharp's metadata reports the stored (pre-EXIF-rotation) dimensions; .rotate() only affects
+  // the pixel pipeline. For EXIF orientation 5-8 (90°/270°, e.g. phone portrait photos) the
+  // displayed image — and every variant below, which applies .rotate() — has width/height swapped.
+  const swap = (meta.orientation ?? 0) >= 5
+  const width = (swap ? meta.height : meta.width) ?? 0
+  const height = (swap ? meta.width : meta.height) ?? 0
+
+  const small = await sharp(input).rotate().resize(100, 100, { fit: 'inside' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  const thumbhash = Buffer.from(rgbaToThumbHash(small.info.width, small.info.height, small.data)).toString('base64')
+
+  // Derive exactly the active variant set (name × format). A proportional spec wider than the source is
+  // skipped (never upscale); a crop clamps via withoutEnlargement. The stored width/height are the REAL
+  // pipeline-output dims (correct for crops and for clamped proportionals — not an aspect-ratio guess).
+  const variants: DerivedImage['variants'] = []
+  for (const spec of policy.variants) {
+    // sharp throws on a non-positive-integer dimension — coerce so a malformed spec (e.g. a stale
+    // `height: ''`) degrades to a proportional resize instead of 500ing the upload.
+    const specWidth = toPosInt(spec.width)
+    if (specWidth == null) continue
+    const cropHeight = toPosInt(spec.height)
+    if (cropHeight == null && width > 0 && specWidth > width) continue
+    for (const format of spec.formats) {
+      const resized = cropHeight == null
+        ? sharp(input).rotate().resize({ width: specWidth, withoutEnlargement: true })
+        : sharp(input).rotate().resize(specWidth, cropHeight, { fit: spec.fit, position: spec.position, withoutEnlargement: true })
+      const encoded = format === 'jpeg' ? resized.jpeg({ quality: policy.jpegQuality }) : resized.webp({ quality: policy.webpQuality })
+      const { data, info } = await encoded.toBuffer({ resolveWithObject: true })
+      variants.push({ name: spec.name, width: info.width, height: info.height, format, mime: format === 'jpeg' ? 'image/jpeg' : 'image/webp', bytes: data })
+    }
+  }
+  return { width, height, thumbhash, variants }
+}
+
+function toPosInt(value: unknown): number | null {
+  const n = Math.floor(Number(value))
+  return Number.isFinite(n) && n >= 1 ? n : null
+}

package/layers/media/server/utils/folder-paths.ts

@@ -0,0 +1,42 @@
+/** Parent folder path; '' for a top-level folder; null for the root itself. */
+export function parentOf(path: string): string | null {
+  if (path === '') return null
+  const i = path.lastIndexOf('/')
+  return i === -1 ? '' : path.slice(0, i)
+}
+
+/** Every ancestor folder (excluding the path itself and the root ''), root-first. */
+export function ancestorsOf(path: string): string[] {
+  const out: string[] = []
+  const segs = path.split('/').filter(Boolean)
+  for (let i = 1; i < segs.length; i++) out.push(segs.slice(0, i).join('/'))
+  return out
+}
+
+/** The path plus all its ancestors (excluding root ''), root-first. */
+export function selfAndAncestors(path: string): string[] {
+  return path === '' ? [] : [...ancestorsOf(path), path]
+}
+
+/** True when `path` is exactly one level below `parent`. */
+export function isImmediateChild(parent: string, path: string): boolean {
+  return parentOf(path) === parent
+}
+
+/** Last path segment. */
+export function childName(path: string): string {
+  const i = path.lastIndexOf('/')
+  return i === -1 ? path : path.slice(i + 1)
+}
+
+/** True when `path` is `prefix` itself or a descendant of it (anchored on a '/' boundary). */
+export function isUnder(prefix: string, path: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`)
+}
+
+/** Re-base `path` from the `from` subtree onto `to` (path unchanged if not under `from`). */
+export function rewritePrefix(path: string, from: string, to: string): string {
+  if (path === from) return to
+  if (path.startsWith(`${from}/`)) return to + path.slice(from.length)
+  return path
+}

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

@@ -0,0 +1,12 @@
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import { folders } from '../database/folders'
+import { sanitizeFolder } from './naming'
+import { selfAndAncestors } from './folder-paths'
+
+/** Ensure a folder row exists for `path` and every ancestor (after sanitizing). Idempotent. */
+export function ensureFolder(db: BetterSQLite3Database, path: string): void {
+  const clean = sanitizeFolder(path)
+  for (const p of selfAndAncestors(clean)) {
+    db.insert(folders).values({ path: p }).onConflictDoNothing().run()
+  }
+}

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

@@ -0,0 +1,90 @@
+import { and, eq, like, count, getTableColumns, sql, isNull, or, asc, desc } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import { media } from '../collections/media'
+import { folders as foldersTable } from '../database/folders'
+import { resolveMedia } from './resolve'
+import { childName, isImmediateChild } from './folder-paths'
+import { primaryLocale } from '../../../core/server/utils/locale'
+import { escapeLike } from '../../../core/server/utils/sql'
+
+export interface LibraryQuery { folder?: string; search?: string; type?: 'image' | 'all'; page?: number; perPage?: number; sort?: string }
+export interface LibraryFolder { path: string; name: string; size: number }
+
+// Sortable table columns → media column. `sort` is `field` (asc) or `-field` (desc); unknown → name.
+const SORT_FIELDS = ['name', 'size', 'type'] as const
+function parseSort(sort: string | undefined): { field: (typeof SORT_FIELDS)[number]; desc: boolean } {
+  const isDesc = (sort ?? '').startsWith('-')
+  const field = (sort ?? '').replace(/^-/, '') as (typeof SORT_FIELDS)[number]
+  return { field: SORT_FIELDS.includes(field) ? field : 'name', desc: isDesc }
+}
+
+export function listLibrary(db: BetterSQLite3Database, q: LibraryQuery, publicUrl: (key: string) => string) {
+  const folder = q.folder ?? ''
+  const cols = getTableColumns(media) as Record<string, never>
+  const t = media as AnySQLiteTable
+
+  // root files are stored with folder NULL (the uploader maps '' → null), so match both at root
+  const conds = [folder === '' ? or(isNull(cols.folder), eq(cols.folder, '')) : eq(cols.folder, folder)]
+  if (q.search) conds.push(sql`${cols.filename} like ${`%${escapeLike(q.search)}%`} escape '\\'`)
+  if (q.type === 'image') conds.push(like(cols.mime, 'image/%'))
+  const where = and(...conds)
+
+  // `?? default` catches only null/undefined, NOT NaN (`?perPage=abc` → Number('abc') === NaN), and
+  // .limit(NaN) binds LIMIT NULL / 500s in SQLite — guard with Number.isFinite (mirrors crud.list).
+  const num = (v: number | undefined, fallback: number) => (Number.isFinite(v) ? (v as number) : fallback)
+  const page = Math.max(1, Math.floor(num(q.page, 1)))
+  const perPage = Math.min(200, Math.max(1, Math.floor(num(q.perPage, 60))))
+
+  // Files are paginated, so sorting must happen in SQL. Tie-break by filename for a stable order.
+  const sort = parseSort(q.sort)
+  const sortCol = sort.field === 'size' ? cols.size : sort.field === 'type' ? cols.mime : cols.filename
+  const dir = sort.desc ? desc : asc
+  const rows = db.select().from(t).where(where).orderBy(dir(sortCol), asc(cols.filename))
+    .limit(perPage).offset((page - 1) * perPage).all() as Record<string, unknown>[]
+  const totalRow = db.select({ value: count() }).from(t).where(where).get() as { value: number } | undefined
+
+  // Resolve in the configured PRIMARY locale — the same locale the viewer edits alt in (and the locale
+  // resolveMedia itself falls back to), so an alt edit round-trips into the list for any primary, not
+  // just 'en'. A literal 'en' here would let an 'en' translation mask a non-en primary's alt.
+  const locale = primaryLocale()
+  const files = rows.map((r) => {
+    const m = resolveMedia(r as never, locale, publicUrl)
+    // serialize the webp ladder to an <img srcset> string; non-derivable files (pdf/svg) → undefined
+    // so the grid renders its ext badge instead of a broken <img> (an empty array is truthy)
+    const srcset = m.srcset.length ? m.srcset.map((s) => `${s.url} ${s.width}w`).join(', ') : undefined
+    return {
+      id: m.id, filename: r.filename as string, mime: m.mime, folder: r.folder as string,
+      size: r.size as number, width: m.width, height: m.height, thumbhash: m.thumbhash,
+      src: m.src, srcset, alt: m.alt, createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
+    }
+  })
+
+  const allFolders = db.select({ path: foldersTable.path }).from(foldersTable).all()
+
+  // Recursive folder sizes: one grouped query sums bytes per exact folder across the current subtree,
+  // then each immediate child's whole subtree is rolled up in JS (cheap: one row per distinct folder).
+  const sizeBase = db.select({ folder: cols.folder, total: sql<number>`coalesce(sum(${cols.size}), 0)` }).from(t).groupBy(cols.folder)
+  const sizeRows = (folder === ''
+    ? sizeBase
+    : sizeBase.where(or(eq(cols.folder, folder), sql`${cols.folder} like ${`${escapeLike(folder)}/%`} escape '\\'`))
+  ).all() as { folder: string | null; total: number }[]
+  const sizeOf = (prefix: string): number =>
+    sizeRows.reduce((sum, r) => (((r.folder ?? '') === prefix || (r.folder ?? '').startsWith(`${prefix}/`)) ? sum + Number(r.total ?? 0) : sum), 0)
+
+  // Folders always render before files; within the group they follow the same sort (by name, or by
+  // recursive size; type is uniform for folders so it falls back to name).
+  const folderList: LibraryFolder[] = allFolders
+    .filter((f) => isImmediateChild(folder, f.path))
+    .map((f) => ({ path: f.path, name: childName(f.path), size: sizeOf(f.path) }))
+    .sort((a, b) => {
+      const c = sort.field === 'size' ? a.size - b.size : a.name.localeCompare(b.name)
+      return sort.desc ? -c : c
+    })
+
+  // The root always exists; any other folder must have a row in the registry. Lets the client tell a
+  // genuinely-empty folder apart from a path that does not exist (→ error instead of a blank listing).
+  const exists = folder === '' || allFolders.some((f) => f.path === folder)
+
+  return { folder, exists, folders: folderList, files, total: Number(totalRow?.value ?? 0), page, perPage }
+}

package/layers/media/server/utils/media-cleanup.ts

@@ -0,0 +1,27 @@
+import type { WriteEvent } from '../../../core/server/utils/write-events'
+import type { DerivativeManifest } from './record'
+
+/** Every storage key a media row owns — the original plus each generated derivative (the webp ladder). */
+export function mediaStorageKeys(row: Record<string, unknown>): string[] {
+  const keys: string[] = []
+  if (typeof row.storageKey === 'string' && row.storageKey) keys.push(row.storageKey)
+  const derivatives = row.derivatives as DerivativeManifest | null | undefined
+  if (derivatives && typeof derivatives === 'object') {
+    for (const d of Object.values(derivatives)) {
+      if (d && typeof d.key === 'string' && d.key) keys.push(d.key)
+    }
+  }
+  return keys
+}
+
+/**
+ * Storage keys to delete when a write event is a media-record DELETE — the original + ALL derivatives;
+ * `[]` for anything else. This makes deleting a media record remove its files on EVERY delete path:
+ * the generic CRUD `remove()` emits a delete event handled here, complementing the media library's own
+ * `deleteAffected` (which deletes storage inline). So a media record can never be removed while leaving
+ * orphaned objects in storage — principle 4 (output ≡ DB) for media. Pure → unit-testable.
+ */
+export function planMediaDeletion(event: WriteEvent): string[] {
+  if (event.def.name !== 'media' || event.after !== null || !event.before) return []
+  return mediaStorageKeys(event.before)
+}

package/layers/media/server/utils/media-enabled.ts

@@ -0,0 +1,23 @@
+import { createError } from 'h3'
+import { collectionEnabled } from '../../../core/server/schema/bootstrap'
+import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
+import mediaCollection from '../collections/media'
+
+/**
+ * Whether the `media` built-in is active for this consumer. The media routes are static files rather than
+ * registry-driven, so they have to ask the SAME predicate the registry plugin and the schema engine use.
+ * Without it a consumer who turned the built-in off keeps serving endpoints that query a table the schema
+ * engine deliberately never created.
+ */
+export function mediaCollectionEnabled(): boolean {
+  const toggles = (serverRuntimeConfig()?.kestrel?.collections ?? resolveServerKestrel().collections) as
+    | Record<string, boolean>
+    | undefined
+  return collectionEnabled(mediaCollection.def, toggles)
+}
+
+/** Route guard: with the built-in disabled the endpoint genuinely does not exist, so 404 — not a 500 from
+ *  the missing table. */
+export function requireMediaCollection(): void {
+  if (!mediaCollectionEnabled()) throw createError({ statusCode: 404, statusMessage: 'Media collection is disabled' })
+}

package/layers/media/server/utils/media-ops.ts

@@ -0,0 +1,118 @@
+import { eq, inArray, or, getTableColumns, sql } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import { findMediaUsagesForMany, type MediaUsage } from './usages'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import { media } from '../collections/media'
+import { folders } from '../database/folders'
+import { isUnder } from './folder-paths'
+import type { DerivativeManifest } from './record'
+import { emitMediaWrite } from './media-write'
+import type { StorageDriver } from '../../../core/server/utils/storage'
+import { escapeLike } from '../../../core/server/utils/sql'
+
+export type OpItem = { type: 'file'; id: number } | { type: 'folder'; path: string }
+
+export interface AffectedMedia {
+  id: number; storageKey: string; folder: string | null; filename: string
+  size: number; derivatives: DerivativeManifest | null
+}
+export interface AffectedSet { media: AffectedMedia[]; folders: string[] }
+
+/** Resolve op items into the concrete affected media rows + folder paths. A `folder` item
+ *  expands to itself + every descendant (media + folder rows). Folders are returned deepest-first
+ *  (so a delete removes children before parents); media is deduped by id. */
+export function collectAffected(db: BetterSQLite3Database, items: OpItem[]): AffectedSet {
+  const cols = getTableColumns(media) as Record<string, never>
+  const t = media as AnySQLiteTable
+  const mediaById = new Map<number, AffectedMedia>()
+  const folderSet = new Set<string>()
+  // Only a folder item ever consults the full folder list (to find its descendants) — an all-file list
+  // never touches it, so skip the read rather than materialize every row for nothing.
+  const allFolders = items.some((i) => i.type === 'folder')
+    ? db.select({ path: folders.path }).from(folders).all().map((f) => f.path)
+    : []
+
+  const add = (rows: Record<string, unknown>[]) => {
+    for (const r of rows) mediaById.set(r.id as number, {
+      id: r.id as number, storageKey: r.storageKey as string, folder: (r.folder as string | null) ?? null,
+      filename: r.filename as string, size: r.size as number, derivatives: (r.derivatives as DerivativeManifest | null) ?? null,
+    })
+  }
+
+  for (const item of items) {
+    if (item.type === 'file') {
+      const row = db.select().from(t).where(eq(cols.id, item.id)).get() as Record<string, unknown> | undefined
+      if (row) add([row])
+    } else {
+      for (const fp of allFolders) if (isUnder(item.path, fp)) folderSet.add(fp)
+      folderSet.add(item.path)
+      const rows = db.select().from(t).where(
+        or(eq(cols.folder, item.path), sql`${cols.folder} like ${`${escapeLike(item.path)}/%`} escape '\\'`),
+      ).all() as Record<string, unknown>[]
+      add(rows)
+    }
+  }
+
+  const folderList = [...folderSet].sort((a, b) => b.split('/').length - a.split('/').length)
+  return { media: [...mediaById.values()], folders: folderList }
+}
+
+/** Reverse-usage lookup for many media ids at once: id -> the records referencing it. */
+export function bulkUsages(db: BetterSQLite3Database, ids: number[]): Record<number, MediaUsage[]> {
+  return findMediaUsagesForMany(db, ids)
+}
+
+export interface DeleteReport {
+  summary: { files: number; folders: number; totalBytes: number }
+  usages?: Record<number, MediaUsage[]>
+  /** storageKeys whose blob delete failed — the row is already gone (rows commit before storage), so a
+   *  failure here is an orphaned object, not a retryable half-delete; surfaced for the caller to log/alert. */
+  failedKeys?: string[]
+}
+
+/** Two-wave delete. dryRun → report impact + per-media usages, no mutation. Otherwise → delete
+ *  all affected media rows + folder rows in one transaction, then delete the storage objects
+ *  (original + derivatives). Folder cascade included. */
+export async function deleteAffected(
+  db: BetterSQLite3Database, driver: StorageDriver, items: OpItem[], dryRun: boolean,
+): Promise<DeleteReport> {
+  const affected = collectAffected(db, items)
+  const summary = {
+    files: affected.media.length,
+    folders: affected.folders.length,
+    totalBytes: affected.media.reduce((n, m) => n + (m.size || 0), 0),
+  }
+  if (dryRun) return { summary, usages: bulkUsages(db, affected.media.map((m) => m.id)) }
+
+  const cols = getTableColumns(media) as Record<string, never>
+  const mediaIds = affected.media.map((m) => m.id)
+  db.transaction((tx) => {
+    if (mediaIds.length) tx.delete(media).where(inArray(cols.id, mediaIds)).run()
+    if (affected.folders.length) tx.delete(folders).where(inArray(folders.path, affected.folders)).run()
+  })
+
+  // Best-effort per item: the rows are already committed gone, so a storage error here means an orphan
+  // object, not a rollback candidate — one bad key (a throttled/5xx S3 call) must not abort the loop and
+  // leave every LATER item's blobs undeleted too with no row left to find them again.
+  const failedKeys: string[] = []
+  for (const m of affected.media) {
+    try {
+      await driver.delete(m.storageKey)
+      for (const d of Object.values(m.derivatives ?? {})) await driver.delete(d.key)
+    } catch (error) {
+      console.error(`[kestrel] media storage delete failed for ${m.storageKey}:`, (error as Error)?.message ?? error)
+      failedKeys.push(m.storageKey)
+    }
+    emitMediaWrite({ id: m.id }, null) // deleted media → re-render listings that query it
+  }
+  // Clean up the folder dir ONLY when nothing unmanaged remains under it. removeDir is a recursive subtree
+  // wipe, so a blind call would destroy any non-media object living under the same path — e.g. an extension's
+  // encrypted blob namespace, or any consumer blob written via useStorageDriver — which no media row (and no
+  // dryRun count) accounts for. If anything is still there, leave the whole path alone.
+  for (const it of items) {
+    if (it.type !== 'folder') continue
+    const remaining = driver.listPrefix ? await driver.listPrefix(it.path) : ['guard']
+    if (remaining.length === 0) await driver.removeDir?.(it.path)
+  }
+  return failedKeys.length ? { summary, failedKeys } : { summary }
+}

package/layers/media/server/utils/media-write.ts

@@ -0,0 +1,13 @@
+import { emitWrite } from '../../../core/server/utils/write-events'
+import mediaCollection from '../collections/media'
+
+/**
+ * Notify the publish runtime that a media row changed. The media-library write paths (relocate / duplicate
+ * / delete / alt-edit) bypass core CRUD, so — unlike a normal content write — they emit no write event on
+ * their own. Without this, a page that embeds the media (dep-tagged `media:<id>`) is never re-rendered, so
+ * the static output keeps the old (now 404) URL or stale alt text. `before`/`after` need only carry `id`
+ * for the media classification (non-pageLike, no status column).
+ */
+export function emitMediaWrite(before: Record<string, unknown> | null, after: Record<string, unknown> | null): void {
+  emitWrite(mediaCollection.def, before, after)
+}

package/layers/media/server/utils/naming.ts

@@ -0,0 +1,52 @@
+export function sanitizeFilename(name: string): string {
+  const base = name.split(/[/\\]/).pop() ?? ''
+  const cleaned = base.replace(/ /g, '_').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/_+/g, '_').slice(0, 120)
+  if (cleaned === '' || cleaned === '.' || cleaned === '..') return 'file'
+  return cleaned
+}
+
+/** The last extension of a filename (no leading dot), or '' when there is none. */
+export function extensionOf(name: string): string {
+  const dot = name.lastIndexOf('.')
+  return dot > 0 ? name.slice(dot + 1) : ''
+}
+
+/** Sanitize `name` and force its extension to `ext` (drops any client-supplied extension).
+ *  The stored extension must follow the authenticated content type, never the upload filename. */
+export function withExtension(name: string, ext: string): string {
+  const cleaned = sanitizeFilename(name)
+  const dot = cleaned.lastIndexOf('.')
+  const stem = dot > 0 ? cleaned.slice(0, dot) : cleaned
+  return ext ? `${stem}.${ext}` : stem
+}
+
+/** Safe relative folder: drops `.`/`..` segments (no traversal) and cleans each segment.
+ *  Deliberately NOT length-capped: truncating would silently map two distinct folders onto one
+ *  storage path. An unusable path is caught where it is created — folders.post.ts runs `ensureDir`
+ *  before committing the row, so an over-long name fails there instead of stranding a row. */
+export function sanitizeFolder(folder: string): string {
+  return folder
+    .split(/[/\\]+/)
+    .map((seg) => seg.trim())
+    .filter((seg) => seg && seg !== '.' && seg !== '..')
+    .map((seg) => seg.replace(/ /g, '_').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/_+/g, '_'))
+    .filter((seg) => seg.length > 0)
+    .join('/')
+}
+
+export function buildKey(folder: string, filename: string): string {
+  const f = sanitizeFolder(folder)
+  return f ? `${f}/${filename}` : filename
+}
+
+export function suggestFreeName(filename: string, isFree: (name: string) => boolean): string {
+  if (isFree(filename)) return filename
+  const dot = filename.lastIndexOf('.')
+  const stem = dot > 0 ? filename.slice(0, dot) : filename
+  const ext = dot > 0 ? filename.slice(dot) : ''
+  for (let i = 2; i < 10000; i++) {
+    const candidate = `${stem}-${i}${ext}`
+    if (isFree(candidate)) return candidate
+  }
+  throw new Error('no free filename found')
+}

package/layers/media/server/utils/ondemand.ts

@@ -0,0 +1,69 @@
+import { inArray, getTableColumns } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { ResolvedImagePolicy, VariantFit } from '../../../core/server/utils/kestrel-config'
+import type { StorageDriver } from '../../../core/server/utils/storage'
+import { media } from '../collections/media'
+import { deriveImage, RASTER } from './derive'
+
+const FITS = new Set<VariantFit>(['cover', 'contain', 'inside', 'outside', 'fill'])
+
+/** The storage key a request addresses, or null when the request is not for media at all: outside the
+ *  configured base URL, bare, or carrying a malformed %-escape (which must degrade to a static 404, never
+ *  a 500). `baseUrl` is the media base as resolved config holds it — its default is the same `/uploads`. */
+export function variantKeyFromPath(path: string, baseUrl: string | undefined): string | null {
+  const base = (baseUrl || '/uploads').replace(/\/+$/, '')
+  const clean = path.split('?')[0]!
+  if (!clean.startsWith(`${base}/`)) return null
+  try {
+    return decodeURIComponent(clean.slice(base.length + 1)) || null
+  } catch {
+    return null
+  }
+}
+
+/** Inverse of variantName: `w<width>` | `c<w>x<h>[-<fit>]` → the shape to derive, or null for anything else. */
+export function parseVariantName(name: string): { width: number; height: number | null; fit: VariantFit } | null {
+  const w = /^w(\d+)$/.exec(name)
+  if (w) return { width: +w[1], height: null, fit: 'cover' }
+  const c = /^c(\d+)x(\d+)(?:-([a-z]+))?$/.exec(name)
+  if (c) {
+    const fit = (c[3] ?? 'cover') as VariantFit
+    return FITS.has(fit) ? { width: +c[1], height: +c[2], fit } : null
+  }
+  return null
+}
+
+export interface VariantRequest { storageKey: string; mime: string; name: string; format: string }
+
+// requestedKey is `<storageKey>-<name>.<format>`; storageKey contains dots and a name may contain '-', so
+// resolve the original by trying every '-' split and matching a real media row (longest storageKey wins).
+export function resolveVariantRequest(db: BetterSQLite3Database, requestedKey: string): VariantRequest | null {
+  const dot = requestedKey.lastIndexOf('.')
+  if (dot < 0) return null
+  const format = requestedKey.slice(dot + 1)
+  const stem = requestedKey.slice(0, dot)
+  const candidates: string[] = []
+  for (let i = 1; i < stem.length; i++) if (stem[i] === '-') candidates.push(stem.slice(0, i))
+  if (!candidates.length) return null
+  const cols = getTableColumns(media) as Record<string, never>
+  const rows = db.select({ storageKey: cols.storageKey, mime: cols.mime }).from(media).where(inArray(cols.storageKey, candidates)).all() as { storageKey: string; mime: string }[]
+  const match = rows.map((r) => ({ ...r, name: stem.slice(r.storageKey.length + 1), format })).sort((a, b) => b.storageKey.length - a.storageKey.length)[0]
+  return match ?? null
+}
+
+const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
+
+// DEV-only: derive one missing variant from the stored original and cache it. Registry-INDEPENDENT (parses
+// the name), so a size/format a KestrelImg declares but the scan hasn't registered yet still shows in the
+// editor preview without a full publish.
+export async function deriveOnDemand(db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, requestedKey: string): Promise<{ bytes: Buffer; mime: string } | null> {
+  const req = resolveVariantRequest(db, requestedKey)
+  if (!req || !RASTER.has(req.mime) || (req.format !== 'webp' && req.format !== 'jpeg')) return null
+  const shape = parseVariantName(req.name)
+  if (!shape || typeof driver.get !== 'function') return null
+  const spec = { name: req.name, width: shape.width, height: shape.height, fit: shape.fit, position: 'centre', formats: [req.format] as ('webp' | 'jpeg')[] }
+  const v = (await deriveImage(await driver.get(req.storageKey), { ...policy, variants: [spec] })).variants[0]
+  if (!v) return null
+  await driver.put(requestedKey, v.bytes, v.mime, { cacheControl: MEDIA_CACHE_CONTROL })
+  return { bytes: v.bytes, mime: v.mime }
+}