@michaelthielemann/kestrel 1.2.1

package/layers/media/app/components/field/Media.vue

@@ -0,0 +1,261 @@
+<script setup lang="ts">
+import { ref, computed, watch, nextTick } from 'vue'
+import type { FieldComponentProps } from '../../../../ui/app/utils/field-component'
+import type { FieldOf } from '../../../../core/server/utils/defineCollection'
+import { reorder } from '../../../../ui/app/utils/reorder'
+import { commonFolder } from '../../utils/library'
+
+interface Resolved { id: number; folder?: string; src: string; alt: string | null; mime?: string; thumbhash?: string | null; srcset?: { url: string; width: number }[] }
+
+// Honour the one shared widget contract. Narrow the media options via a computed guard, exactly as
+// Relation.vue does for its relation options.
+const props = defineProps<FieldComponentProps>()
+const model = defineModel<number | number[] | null>()
+
+const { t } = useT()
+const options = computed(() => (props.field.type === 'media' ? (props.field as FieldOf<'media'>).options : undefined))
+const required = computed(() => !!props.field.required)
+const multiple = computed(() => !!options.value?.multiple)
+const accept = computed(() => options.value?.accept ?? 'any')
+const pickerOpen = ref(false)
+
+const ids = computed<number[]>(() => {
+  const v = model.value
+  if (multiple.value) return Array.isArray(v) ? v : []
+  return typeof v === 'number' ? [v] : []
+})
+
+const { ensure, resolve } = useMediaResolver(() => props.locale)
+const resolved = computed<Resolved[]>(() => ids.value.flatMap((id) => resolve(id) ?? []))
+watch(ids, (v) => ensure(v), { immediate: true })
+
+// Seed the picker's initial folder from the common folder of the current items so it opens where the
+// selection lives (root when they diverge / nothing is selected yet).
+const initialFolder = computed(() => commonFolder(resolved.value.map((r) => r.folder ?? '')))
+
+function onConfirm(picked: number[]) {
+  if (multiple.value) {
+    // REPLACE, not merge: the picker returns the full desired set (pre-checked + toggled), so
+    // unchecking an item in the picker removes it here. Dedupe defensively.
+    model.value = [...new Set(picked)]
+  } else {
+    model.value = picked[0] ?? null
+  }
+}
+function removeId(id: number) {
+  if (multiple.value) model.value = (Array.isArray(model.value) ? model.value : []).filter((x) => x !== id)
+  else model.value = null
+}
+
+// Drag-to-reorder (multiple mode), mirroring the Combobox chip idiom. `resolved` is a SUBSEQUENCE of the
+// model ids (a dangling/deleted id drops out), so a resolved position must be mapped back to the id's
+// index in the model before reordering — a resolved index is NOT the model index.
+const itemsEl = ref<HTMLElement | null>(null)
+const liveMessage = ref('')
+// A DISTINCT accessible name per item, so the move/remove buttons don't all read "media" when the images
+// carry no alt text: alt → filename → "media #<pos>". Position keeps it unique even for same-named files.
+const nameOf = (r: Resolved, i: number) => r.alt?.trim() || filenameOf(r) || t('field.media.itemAt', { pos: i + 1 })
+function modelIndexOf(id: number) { return (Array.isArray(model.value) ? model.value : []).indexOf(id) }
+function announceMove(name: string, to: number) {
+  liveMessage.value = t('field.media.moved', { name, pos: to + 1, total: resolved.value.length })
+}
+// `resolved` is a SUBSEQUENCE of the model ids (a dangling/deleted id drops out), so commit maps the
+// resolved drag indices back to the ids' model indices before reordering — a resolved index ≠ model index.
+const { dragIndex, overIndex, onDragStart, onDragEnter, onDragLeave, onDrop, onDragEnd } = useDragReorder({
+  disabled: () => props.disabled || !multiple.value,
+  commit: (fromResolved, toResolved) => {
+    const from = modelIndexOf(resolved.value[fromResolved]!.id)
+    const to = modelIndexOf(resolved.value[toResolved]!.id)
+    if (from < 0 || to < 0) return
+    const name = nameOf(resolved.value[fromResolved]!, fromResolved)
+    model.value = reorder(Array.isArray(model.value) ? model.value : [], from, to)
+    nextTick(() => announceMove(name, toResolved))
+  },
+})
+function moveItem(i: number, dir: -1 | 1) {
+  const j = i + dir
+  if (props.disabled || !multiple.value || j < 0 || j >= resolved.value.length) return
+  const from = modelIndexOf(resolved.value[i]!.id)
+  const to = modelIndexOf(resolved.value[j]!.id)
+  if (from < 0 || to < 0) return
+  const name = nameOf(resolved.value[i]!, i)
+  model.value = reorder(Array.isArray(model.value) ? model.value : [], from, to)
+  // Keep keyboard focus on a move control at the item's new position. At a boundary the direction button
+  // is disabled, so fall back to the OPPOSITE move button (still enabled for any ≥2-item list) — never to
+  // the destructive remove button, which would turn a repeated move into an accidental delete.
+  nextTick(() => {
+    announceMove(name, j)
+    const item = itemsEl.value?.children[j] as HTMLElement | undefined
+    const btns = item?.querySelectorAll<HTMLButtonElement>('.field-media__move')
+    const dirBtn = dir < 0 ? btns?.[0] : btns?.[1]
+    const otherBtn = dir < 0 ? btns?.[1] : btns?.[0]
+    const target = dirBtn && !dirBtn.disabled ? dirBtn : otherBtn && !otherBtn.disabled ? otherBtn : item
+    target?.focus()
+  })
+}
+function srcsetOf(r: Resolved) { return r.srcset?.map((s) => `${s.url} ${s.width}w`).join(', ') }
+
+// Only image mimes get a thumbnail; everything else (pdf/doc/video/…) shows a file badge + filename so
+// it isn't a broken <img>. Filename/extension are derived from the public URL (the resolved shape
+// carries no filename); the badge falls back to the mime subtype when the URL has no extension.
+function isImage(r: Resolved) { return (r.mime ?? '').startsWith('image/') }
+function filenameOf(r: Resolved) {
+  const path = r.src.split(/[?#]/)[0]
+  return decodeURIComponent(path.slice(path.lastIndexOf('/') + 1))
+}
+function fileExt(r: Resolved) {
+  const name = filenameOf(r)
+  const dot = name.lastIndexOf('.')
+  if (dot > 0) return name.slice(dot + 1).toUpperCase()
+  return (r.mime ?? '').split('/')[1]?.toUpperCase() ?? ''
+}
+
+defineExpose({ onConfirm, removeId, onDragStart, onDrop, moveItem })
+</script>
+
+<template>
+  <UiField :id="id" :label="name" :error="error" :required="required">
+    <template #default="f">
+      <div class="field-media">
+        <ul v-if="resolved.length" ref="itemsEl" class="field-media__items" @dragleave="onDragLeave">
+          <li
+            v-for="(r, i) in resolved"
+            :key="r.id"
+            class="field-media__item"
+            :class="{
+              'field-media__item--draggable': multiple && !disabled,
+              'field-media__item--over': overIndex === i && dragIndex !== i,
+            }"
+            :draggable="multiple && !disabled"
+            @dragstart="onDragStart(i, $event)"
+            @dragenter="onDragEnter(i)"
+            @dragover.prevent="onDragEnter(i)"
+            @drop.prevent="onDrop(i)"
+            @dragend="onDragEnd"
+          >
+            <MediaThumb v-if="isImage(r)" draggable="false" class="field-media__thumb" :src="r.src" :srcset="srcsetOf(r)" sizes="80px" :alt="r.alt ?? ''" :thumbhash="r.thumbhash" />
+            <a v-else draggable="false" class="field-media__file" :href="r.src" target="_blank" rel="noopener noreferrer" :title="filenameOf(r)">
+              <span class="field-media__badge" aria-hidden="true">{{ fileExt(r) }}</span>
+              <span class="field-media__filename">{{ filenameOf(r) }}</span>
+            </a>
+            <template v-if="multiple && !disabled">
+              <button
+                type="button"
+                draggable="false"
+                class="field-media__move field-media__move--prev"
+                :aria-label="t('field.media.move_earlier', { name: nameOf(r, i) })"
+                :disabled="i === 0"
+                @click="moveItem(i, -1)"
+              ><UiIcon name="chevron-left" size="0.875rem" /></button>
+              <button
+                type="button"
+                draggable="false"
+                class="field-media__move field-media__move--next"
+                :aria-label="t('field.media.move_later', { name: nameOf(r, i) })"
+                :disabled="i === resolved.length - 1"
+                @click="moveItem(i, 1)"
+              ><UiIcon name="chevron-right" size="0.875rem" /></button>
+            </template>
+            <button v-if="!disabled" type="button" draggable="false" class="field-media__remove" :aria-label="t('field.media.remove', { name: nameOf(r, i) })" @click="removeId(r.id)"><UiIcon name="x" size="1rem" /></button>
+          </li>
+        </ul>
+        <p v-else class="field-media__empty">{{ t('field.media.empty') }}</p>
+        <UiButton
+          v-if="!disabled"
+          :id="f.id"
+          type="button"
+          variant="secondary"
+          :aria-invalid="f['aria-invalid']"
+          :aria-describedby="f['aria-describedby']"
+          @click="pickerOpen = true"
+        >
+          {{ multiple ? t('field.media.add') : (resolved.length ? t('field.media.replace') : t('field.media.select')) }}
+        </UiButton>
+        <span class="field-media__live" aria-live="polite">{{ liveMessage }}</span>
+      </div>
+      <MediaPicker v-model:open="pickerOpen" :multiple="multiple" :accept="accept" :initial-folder="initialFolder" :initial-selected="ids" @confirm="onConfirm" />
+    </template>
+  </UiField>
+</template>
+
+<style lang="scss" scoped>
+.field-media { display: flex; flex-direction: column; gap: var(--space-2); align-items: flex-start; }
+.field-media__items { display: flex; flex-wrap: wrap; gap: var(--space-2); list-style: none; margin: 0; padding: 0; }
+.field-media__item { position: relative; }
+.field-media__item--draggable { cursor: grab; }
+.field-media__item--draggable:active { cursor: grabbing; }
+/* Drop indicator — outward outline (items are gap-spaced, never overflow-clipped). */
+.field-media__item--over { outline: 2px solid var(--color-primary); outline-offset: 2px; border-radius: var(--radius-md); }
+.field-media__thumb { width: 80px; height: 80px; object-fit: cover; border-radius: var(--radius-md); background: var(--color-bg); border: 1px solid var(--color-border); }
+.field-media__file { display: flex; flex-direction: column; gap: var(--space-1); width: 80px; text-decoration: none; color: inherit; }
+.field-media__badge { display: grid; place-items: center; width: 80px; height: 80px; border-radius: var(--radius-md); background: var(--color-bg); border: 1px solid var(--color-border); color: var(--color-text-muted); font-weight: var(--weight-bold); font-size: var(--text-sm); }
+.field-media__filename { max-width: 80px; font-size: var(--text-xs); color: var(--color-text-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* Remove control — a dark translucent disc + white glyph reads on ANY image (a white surface disc was
+   invisible over pale photos); the light ring lifts it off, hover escalates to solid danger. */
+.field-media__remove {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  width: 1.75rem;
+  height: 1.75rem;
+  display: grid;
+  place-items: center;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-full);
+  background: rgba(9, 9, 11, 0.55);
+  color: #fff;
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.55), var(--shadow-sm);
+  cursor: pointer;
+  line-height: 1;
+  transition: background var(--motion-fast) var(--ease-standard),
+    transform var(--motion-fast) var(--ease-standard),
+    box-shadow var(--motion-fast) var(--ease-standard);
+}
+.field-media__remove:hover {
+  background: var(--color-danger-solid);
+  color: var(--color-on-danger);
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.7), var(--shadow-md);
+  transform: scale(1.08);
+}
+.field-media__remove:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+
+/* Keyboard reorder buttons — same disc idiom, revealed on hover/focus so idle thumbs stay clean.
+   Kept focusable when idle (opacity, not display:none) so Tab reveals them via :focus-within. */
+.field-media__move {
+  position: absolute;
+  bottom: 4px;
+  width: 1.5rem;
+  height: 1.5rem;
+  display: grid;
+  place-items: center;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-full);
+  background: rgba(9, 9, 11, 0.55);
+  color: #fff;
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.55);
+  cursor: pointer;
+  line-height: 1;
+  opacity: 0;
+  transition: opacity var(--motion-fast) var(--ease-standard);
+}
+.field-media__move--prev { left: 4px; }
+.field-media__move--next { right: 4px; }
+.field-media__move:disabled { cursor: default; } /* stays hidden at a boundary (reveal excludes :disabled) */
+.field-media__item:hover .field-media__move:not(:disabled),
+.field-media__item:focus-within .field-media__move:not(:disabled) { opacity: 1; }
+.field-media__move:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+@media (hover: none) {
+  .field-media__move:not(:disabled) { opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .field-media__remove,
+  .field-media__move { transition: none; }
+  .field-media__remove:hover { transform: none; }
+}
+
+.field-media__empty { color: var(--color-text-muted); font-size: var(--text-sm); margin: 0; }
+.field-media__live { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+</style>

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

@@ -0,0 +1,55 @@
+import { computed, ref, onMounted, watch, toValue, type MaybeRefOrGetter } from 'vue'
+import { thumbhashToDataUrl } from '../utils/thumbhash'
+
+/**
+ * Blur-up image loading state for an `<img>` painted over a thumbhash placeholder. Returns the bits a
+ * renderer binds: the element ref, the placeholder background style (shown until the raster paints), and
+ * an `onLoad` handler that drives a one-shot "sharpen-in".
+ *
+ * Degradation is deliberate: `animate`/`loaded`/`placeholder` are false/null on the server and the
+ * initial client render (so hydration matches and no-JS just shows the image — width/height reserve the
+ * box, so no layout shift). `animate` is set ONLY on a genuine async load, not for an image that was
+ * already `complete` at mount (a cached revisit), so a cached image doesn't flash a blur every time.
+ *
+ * The thumbhash placeholder is decoded CLIENT-SIDE only. `thumbHashToDataURL` inflates the ~30-byte
+ * thumbhash string (already shipped in the payload) into a ~6 KB PNG data URL; inlining that in SSR
+ * bloats the HTML by hundreds of KB on an image-dense page. Decoding after mount keeps the blur-up for
+ * JS clients while shipping a lean document (measured: −305 KB HTML on a 69-image page).
+ */
+export function useBlurUp(thumbhash: MaybeRefOrGetter<string | null | undefined>) {
+  const imgEl = ref<HTMLImageElement | null>(null)
+  const loaded = ref(false)
+  const animate = ref(false)
+  const placeholder = ref<string | null>(null) // null on SSR + first client render; decoded on mount
+
+  const placeholderStyle = computed(() => {
+    if (!placeholder.value || loaded.value) return undefined
+    return {
+      backgroundImage: `url(${placeholder.value})`,
+      backgroundSize: 'cover',
+      backgroundPosition: 'center',
+      backgroundRepeat: 'no-repeat',
+    }
+  })
+
+  function onLoad() {
+    // A real (async) decode — the only case that should animate. A cached image is caught by the
+    // `complete` check below and flips `loaded` without arming `animate`.
+    if (!loaded.value) animate.value = true
+    loaded.value = true
+  }
+  onMounted(() => {
+    // A cached image is already painted → skip the placeholder entirely (no blur flash). Otherwise
+    // decode the thumbhash now (client-only) so the blur shows until the raster arrives.
+    if (imgEl.value?.complete) loaded.value = true
+    else placeholder.value = thumbhashToDataUrl(toValue(thumbhash))
+  })
+
+  // A reactive media swap (the public BlockRenderer is reused in the admin live preview and keys blocks
+  // by id, so editing an image reuses this instance instead of remounting) must restart the blur-up for
+  // the new image — re-decode the new placeholder. Not immediate, so the server/first-client render is
+  // untouched (no hydration impact).
+  watch(() => toValue(thumbhash), (h) => { loaded.value = false; animate.value = false; placeholder.value = thumbhashToDataUrl(h) })
+
+  return { imgEl, loaded, animate, placeholderStyle, onLoad }
+}

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

@@ -0,0 +1,14 @@
+import { ref, computed } from 'vue'
+import type { OpItem } from '../utils/ops'
+
+// Module-level singleton so the clipboard survives folder navigation + remounts.
+const clipboard = ref<{ mode: 'cut' | 'copy'; items: OpItem[] } | null>(null)
+
+export function useMediaClipboard() {
+  const isEmpty = computed(() => !clipboard.value?.items.length)
+  const count = computed(() => clipboard.value?.items.length ?? 0)
+  function cut(items: OpItem[]) { clipboard.value = { mode: 'cut', items } }
+  function copy(items: OpItem[]) { clipboard.value = { mode: 'copy', items } }
+  function clear() { clipboard.value = null }
+  return { clipboard, isEmpty, count, cut, copy, clear }
+}

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

@@ -0,0 +1,56 @@
+import { ref, computed } from 'vue'
+import type { LibraryItem } from '../utils/library'
+import { resolveTargetItem, effectiveTargets, toOpItem, buildMenuItems, type MenuItemSpec, type OpItem } from '../utils/ops'
+
+export function useMediaContextMenu(opts: {
+  items: () => LibraryItem[]
+  isSelected: (i: LibraryItem) => boolean
+  select: (i: LibraryItem) => void
+  currentFolder: () => string
+  clipboardEmpty: () => boolean
+  onDelete: (items: OpItem[]) => void
+  onRename: (item: LibraryItem) => void
+  onCut: (items: OpItem[]) => void
+  onCopy: (items: OpItem[]) => void
+  onPaste: (dest: string) => void
+}) {
+  const targets = ref<LibraryItem[]>([])
+  const targetType = ref<'file' | 'folder' | null>(null)
+  const pasteDest = ref('')
+
+  // Returns label *specs* (i18n keys); the component resolves them via useT so this composable stays
+  // pure and node-testable (no Nuxt/i18n context required).
+  const menuItems = computed<MenuItemSpec[]>(() =>
+    buildMenuItems({ targetCount: targets.value.length, targetType: targetType.value, clipboardEmpty: opts.clipboardEmpty() }),
+  )
+
+  function onContextMenu(e: MouseEvent) {
+    const all = opts.items()
+    const target = resolveTargetItem(e.target as Element, all)
+    if (!target) {
+      targets.value = []
+      targetType.value = null
+      // blank space: only open a menu (Paste) when the clipboard has something; else suppress
+      // both the native menu and an empty Reka menu (capture-phase, synchronous — a reactive
+      // :disabled can't, its prop updates after Reka's handler runs).
+      if (opts.clipboardEmpty()) { e.preventDefault?.(); e.stopPropagation?.(); return }
+      pasteDest.value = opts.currentFolder()
+      return
+    }
+    targets.value = effectiveTargets(target, opts.isSelected, all.filter((i) => opts.isSelected(i)))
+    targetType.value = target.type
+    pasteDest.value = target.type === 'folder' ? target.folder.path : ''
+    if (!opts.isSelected(target)) opts.select(target)
+  }
+
+  function onSelect(value: string) {
+    const opItems = targets.value.map(toOpItem)
+    if (value === 'delete') opts.onDelete(opItems)
+    else if (value === 'rename' && targets.value.length === 1) opts.onRename(targets.value[0])
+    else if (value === 'cut') opts.onCut(opItems)
+    else if (value === 'copy') opts.onCopy(opItems)
+    else if (value === 'paste') opts.onPaste(pasteDest.value)
+  }
+
+  return { targets, menuItems, onContextMenu, onSelect }
+}

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

@@ -0,0 +1,56 @@
+import { ref } from 'vue'
+import { extractUploads, selectEmptyFolders, type PendingUpload } from '../utils/dnd'
+import type { OpItem } from '../utils/ops'
+
+const MEDIA_DRAG = 'application/x-kestrel-media'
+export interface DropResult { uploads: PendingUpload[]; folders: string[] }
+
+function hoveredFolder(e: DragEvent): string | null {
+  const el = (e.target as HTMLElement | null)?.closest?.('[data-drop-folder]') as HTMLElement | null
+  return el ? el.getAttribute('data-drop-folder') : null
+}
+function dragTypes(e: DragEvent): string[] { return e.dataTransfer ? Array.from(e.dataTransfer.types) : [] }
+function isInternal(e: DragEvent): boolean { return dragTypes(e).includes(MEDIA_DRAG) }
+function isFiles(e: DragEvent): boolean { return dragTypes(e).includes('Files') }
+
+export function useMediaDnd(opts: {
+  currentFolder: () => string
+  onDrop: (r: DropResult) => void
+  draggedItems: () => OpItem[]
+  onMove: (items: OpItem[], dest: string) => void
+}) {
+  const dragActive = ref(false)
+  const dropFolder = ref<string | null>(null)
+  let depth = 0
+
+  // Only a genuine OS file-drag raises the upload overlay. An internal item-drag may also carry 'Files'
+  // in dataTransfer.types on some platforms, so the internal marker takes precedence.
+  function onDragEnter(e: DragEvent) { e.preventDefault(); depth++; if (isFiles(e) && !isInternal(e)) dragActive.value = true }
+  function onDragOver(e: DragEvent) {
+    e.preventDefault()
+    if (e.dataTransfer) e.dataTransfer.dropEffect = isInternal(e) ? 'move' : 'copy'
+    dropFolder.value = hoveredFolder(e)
+  }
+  function onDragLeave(_e: DragEvent) {
+    depth = Math.max(0, depth - 1)
+    if (depth === 0) { dragActive.value = false; dropFolder.value = null }
+  }
+  async function onDrop(e: DragEvent) {
+    e.preventDefault()
+    depth = 0
+    dragActive.value = false
+    const dest = hoveredFolder(e)
+    dropFolder.value = null
+    if (!e.dataTransfer) return
+    if (isInternal(e)) {
+      const its = opts.draggedItems()
+      if (dest !== null && its.length && !its.some((i) => i.type === 'folder' && i.path === dest)) opts.onMove(its, dest)
+      return
+    }
+    const base = dest ?? opts.currentFolder()
+    const { uploads, dirs } = await extractUploads(e.dataTransfer, base)
+    opts.onDrop({ uploads, folders: selectEmptyFolders(uploads, dirs) })
+  }
+
+  return { dragActive, dropFolder, onDragEnter, onDragOver, onDragLeave, onDrop }
+}

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

@@ -0,0 +1,151 @@
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
+import { useRoute, useRouter } from '#imports'
+import { itemKey, computeRange, parentFolder, type LibraryFile, type LibraryFolder, type LibraryItem } from '../utils/library'
+
+interface LibraryResponse { folder: string; exists?: boolean; folders: LibraryFolder[]; files: LibraryFile[]; total: number; page: number; perPage: number }
+const PER_PAGE = 60
+const VIEW_KEY = 'kestrel-media-view'
+
+export function useMediaLibrary(opts: { urlSync?: boolean; accept?: 'image' | 'any'; initialFolder?: string } = {}) {
+  const urlSync = opts.urlSync ?? true
+  const accept = opts.accept ?? 'any'
+
+  const route = useRoute()
+  const router = useRouter()
+  const { t } = useT()
+
+  const folder = ref<string>(urlSync && typeof route.query.folder === 'string' ? route.query.folder : (opts.initialFolder ?? ''))
+  const folders = ref<LibraryFolder[]>([])
+  const files = ref<LibraryFile[]>([])
+  const total = ref(0)
+  const page = ref(1)
+  const search = ref('')
+  const sort = ref<string>('name') // `field` (asc) or `-field` (desc); matches the table headers
+  const view = ref<'grid' | 'table'>('grid')
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  const selected = ref<Set<string>>(new Set())
+  let anchorKey: string | null = null
+  let token = 0
+  let searchTimer: ReturnType<typeof setTimeout> | undefined
+
+  if (import.meta.client) {
+    const v = localStorage.getItem(VIEW_KEY)
+    if (v === 'grid' || v === 'table') view.value = v
+  }
+
+  const items = computed<LibraryItem[]>(() => [
+    ...folders.value.map((f) => ({ type: 'folder' as const, folder: f })),
+    ...files.value.map((f) => ({ type: 'file' as const, file: f })),
+  ])
+  // Parent-folder ("..") target for up-navigation: null at the root (no item rendered there). Kept out
+  // of `items`/selection so it stays pure navigation chrome, never selectable or draggable.
+  const parentPath = computed(() => parentFolder(folder.value))
+  const orderedKeys = computed(() => items.value.map(itemKey))
+  const hasMore = computed(() => files.value.length < total.value)
+  const count = computed(() => selected.value.size)
+
+  async function fetchLibrary(append = false) {
+    // A non-append fetch is a full refresh (mount / nav / sort / search / a mutation's re-list): reset to
+    // page 1 so it never re-requests a deep page and assigns ONLY that page's slice — which after a
+    // "Load more" would silently drop every earlier page from the listing. loadMore() bumps page then appends.
+    if (!append) page.value = 1
+    const my = ++token
+    loading.value = true
+    error.value = null
+    try {
+      const res = await $fetch<LibraryResponse>('/api/media/library', {
+        query: { folder: folder.value, search: search.value || undefined, sort: sort.value, page: page.value, perPage: PER_PAGE, type: accept === 'image' ? 'image' : undefined },
+      })
+      if (my !== token) return
+      // A non-root path the server doesn't know is a typo/dead link, not an empty folder: surface an
+      // error rather than a blank listing that looks like the folder exists.
+      if (folder.value !== '' && res.exists === false) {
+        folders.value = []
+        files.value = []
+        total.value = 0
+        error.value = t('media.folderNotFound')
+        return
+      }
+      folders.value = res.folders
+      files.value = append ? [...files.value, ...res.files] : res.files
+      total.value = res.total
+    } catch (e) {
+      if (my !== token) return
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? t('media.error.load')
+    } finally {
+      if (my === token) loading.value = false
+    }
+  }
+
+  function loadMore() {
+    if (!hasMore.value || loading.value) return
+    page.value += 1
+    return fetchLibrary(true)
+  }
+
+  // Returns the in-flight work so callers can await navigation: the fetch directly (urlSync:false), or
+  // the router push that the route watcher turns into a fetch (urlSync).
+  function navigate(path: string) {
+    if (path === folder.value) return
+    if (urlSync) return router.push({ query: path ? { folder: path } : {} })
+    clearTimeout(searchTimer)
+    search.value = ''
+    folder.value = path
+    page.value = 1
+    clear()
+    return fetchLibrary()
+  }
+
+  function setSearch(s: string) {
+    search.value = s
+    clearTimeout(searchTimer)
+    searchTimer = setTimeout(() => { page.value = 1; fetchLibrary() }, 250)
+  }
+
+  function setView(v: 'grid' | 'table') {
+    view.value = v
+    if (import.meta.client) localStorage.setItem(VIEW_KEY, v)
+  }
+
+  // Clicking a column re-sorts: same field flips direction, a new field starts ascending.
+  function setSort(field: string) {
+    sort.value = sort.value === field ? `-${field}` : field
+    page.value = 1
+    return fetchLibrary()
+  }
+
+  const isSelected = (item: LibraryItem) => selected.value.has(itemKey(item))
+  function select(item: LibraryItem) { const k = itemKey(item); selected.value = new Set([k]); anchorKey = k }
+  function toggle(item: LibraryItem) {
+    const k = itemKey(item); const s = new Set(selected.value)
+    s.has(k) ? s.delete(k) : s.add(k)
+    selected.value = s; anchorKey = k
+  }
+  function range(item: LibraryItem) { selected.value = computeRange(orderedKeys.value, anchorKey ?? itemKey(item), itemKey(item), selected.value) }
+  function clear() { selected.value = new Set(); anchorKey = null }
+  function selectAll() { selected.value = new Set(orderedKeys.value) }
+
+  if (urlSync) {
+    watch(() => route.query.folder, (q) => {
+      const next = typeof q === 'string' ? q : ''
+      if (next === folder.value) return
+      clearTimeout(searchTimer)
+      search.value = ''
+      folder.value = next
+      page.value = 1
+      clear()
+      fetchLibrary()
+    })
+  }
+
+  onMounted(() => fetchLibrary())
+  onUnmounted(() => clearTimeout(searchTimer))
+
+  return {
+    folder, folders, files, total, page, search, sort, view, loading, error,
+    items, parentPath, orderedKeys, hasMore, count, selected,
+    fetchLibrary, loadMore, navigate, setSearch, setView, setSort,
+    isSelected, select, toggle, range, clear, selectAll,
+  }
+}

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

@@ -0,0 +1,50 @@
+import { ref } from 'vue'
+import type { OpItem, DeleteReport } from '../utils/ops'
+
+export function useMediaOps(onChanged?: () => void) {
+  const busy = ref(false)
+  const error = ref<string | null>(null)
+
+  async function previewDelete(items: OpItem[]): Promise<DeleteReport> {
+    error.value = null
+    try {
+      return await $fetch<DeleteReport>('/api/media/delete', { method: 'POST', body: { items, dryRun: true } })
+    } catch (e) {
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? 'Could not prepare delete'
+      throw e
+    }
+  }
+
+  async function confirmDelete(items: OpItem[]): Promise<void> {
+    busy.value = true
+    error.value = null
+    try {
+      await $fetch('/api/media/delete', { method: 'POST', body: { items } })
+      onChanged?.()
+    } catch (e) {
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? 'Delete failed'
+      throw e
+    } finally {
+      busy.value = false
+    }
+  }
+
+  async function rename(item: OpItem, name: string): Promise<void> {
+    busy.value = true
+    error.value = null
+    try {
+      await $fetch('/api/media/rename', { method: 'POST', body: { items: [item], name, onConflict: 'abort' } })
+      onChanged?.()
+    } catch (e) {
+      const err = e as { statusCode?: number; statusMessage?: string }
+      error.value = err.statusCode === 409
+        ? 'A file or folder with this name already exists'
+        : err.statusMessage ?? 'Rename failed'
+      throw e
+    } finally {
+      busy.value = false
+    }
+  }
+
+  return { busy, error, previewDelete, confirmDelete, rename }
+}