@michaelthielemann/kestrel 1.2.1

package/layers/fields/server/utils/conditional-required.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import { evaluateCondition, isEmptyValue } from '../../app/utils/condition'
+
+/**
+ * Re-enforce `required` for conditional sub-fields whose condition is met, at the object level where their
+ * sibling values are visible (a block's props, a repeater entry). The per-field validator relaxed a
+ * `required + condition` field to optional (it can't see siblings), and the collection-level applyConditions
+ * hook only walks TOP-LEVEL fields — so without this, a conditional-required prop inside a block or repeater
+ * is a silent server no-op. Adds a superRefine that checks each such field against the parsed object; a no-op
+ * (returns the schema unchanged) when the shape has no conditional-required fields.
+ */
+export function refineConditionalRequired<T extends z.ZodTypeAny>(schema: T, fields: Record<string, FieldDef>): z.ZodTypeAny {
+  const conditional = Object.entries(fields).filter(([, f]) => f.condition && f.required)
+  if (!conditional.length) return schema
+  return schema.superRefine((val, ctx) => {
+    if (!val || typeof val !== 'object') return
+    const scope = val as Record<string, unknown>
+    for (const [key, field] of conditional) {
+      if (evaluateCondition(field.condition!, scope) && isEmptyValue(scope[key])) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: 'This field is required.' })
+      }
+    }
+  })
+}

package/layers/fields/server/utils/defineBlock.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+import type { ZodObject } from 'zod'
+import type { FieldDef, Localized } from '../../../core/server/utils/defineCollection'
+import { buildFieldObjectSchema } from './buildFieldSchema'
+import { refineConditionalRequired } from './conditional-required'
+
+export interface BlockDef {
+  name: string
+  fields: Record<string, FieldDef>
+  slots?: string[]
+  label?: Localized
+  /** Optional icon name for the admin block picker (e.g. a lucide name). Set via the SFC's `defineBlock`. */
+  icon?: string
+  /** Optional preview image (URL/path, e.g. '/block-previews/hero.png') shown above the name in the picker. */
+  image?: string
+}
+
+const blocks = new Map<string, BlockDef>()
+
+export function defineBlock(def: BlockDef): BlockDef {
+  return def
+}
+export function registerBlock(def: BlockDef): void {
+  blocks.set(def.name, def)
+}
+export function getBlock(name: string): BlockDef | undefined {
+  return blocks.get(name)
+}
+export function clearBlocks(): void {
+  blocks.clear()
+}
+export function allBlocks(allowed?: string[]): BlockDef[] {
+  const all = [...blocks.values()]
+  return allowed?.length ? all.filter((b) => allowed.includes(b.name)) : all
+}
+
+const MAX_BLOCK_DEPTH = 60
+const MAX_BLOCK_NODES = 10_000
+
+// Iterative (no recursion) traversal so the guard itself can't stack-overflow.
+function withinBlockBounds(value: unknown): boolean {
+  const stack: Array<{ v: unknown; depth: number }> = [{ v: value, depth: 0 }]
+  let nodes = 0
+  while (stack.length) {
+    const top = stack.pop() as { v: unknown; depth: number }
+    const { v, depth } = top
+    if (v === null || typeof v !== 'object') continue
+    if (depth > MAX_BLOCK_DEPTH) return false
+    if (++nodes > MAX_BLOCK_NODES) return false
+    if (Array.isArray(v)) {
+      for (const item of v) stack.push({ v: item, depth: depth + 1 })
+    } else {
+      for (const key of Object.keys(v as Record<string, unknown>)) {
+        stack.push({ v: (v as Record<string, unknown>)[key], depth: depth + 1 })
+      }
+    }
+  }
+  return true
+}
+
+export function buildBlocksSchema(blockDefs: BlockDef[]): z.ZodType {
+  const node: z.ZodType = blockDefs.length
+    ? z.lazy(() =>
+        z.discriminatedUnion(
+          'type',
+          blockDefs.map((b) =>
+            z.object({
+              id: z.string().min(1),
+              type: z.literal(b.name),
+              props: refineConditionalRequired(z.object(buildFieldObjectSchema(b.fields)), b.fields),
+              slots: b.slots?.length
+                ? z.object(Object.fromEntries(b.slots.map((s) => [s, z.array(node)]))).partial().optional()
+                : z.undefined().optional(),
+            }),
+          ) as unknown as [ZodObject, ...ZodObject[]],
+        ),
+      )
+    : z.never()
+  return z.unknown()
+    .superRefine((val, ctx) => {
+      if (!withinBlockBounds(val)) {
+        ctx.addIssue({ code: 'custom', message: 'Block tree exceeds the maximum depth or size' })
+      }
+    })
+    .pipe(z.array(node))
+}

package/layers/fields/server/utils/defineFieldType.ts

@@ -0,0 +1,33 @@
+import type { FieldTypeDescriptor } from '../field-registry/types'
+import { registerFieldType } from '../field-registry'
+
+export type { FieldTypeDescriptor }
+// Re-export the descriptor helpers so a consumer's field-type file can build the Drizzle column + Zod with
+// the SAME optionality/constraint logic the built-ins use — all auto-imported in a `server/field-types/` file.
+export { constrain, opt, optArr, isHardRequired, getFieldType, registerFieldType } from '../field-registry'
+
+/**
+ * A consumer-defined field type: a `name` plus the server contract — a Drizzle `column` and a Zod
+ * `validator`. Drop a file in `server/field-types/` that default-exports `defineFieldType({...})`; it is
+ * auto-discovered and registered BEFORE any table is built. Pair it with a client editor widget via
+ * `registerFieldComponent('<name>', Component)` in an `app/plugins/*.client.ts`.
+ *
+ * @example
+ * // server/field-types/color.ts
+ * import { text } from 'drizzle-orm/sqlite-core'
+ * import { z } from 'zod'
+ * export default defineFieldType({
+ *   name: 'color',
+ *   column: (n, f) => constrain(text(n), f),
+ *   validator: (f) => opt(z.string().regex(/^#[0-9a-f]{6}$/i), f),
+ * })
+ */
+export interface FieldTypeDef extends FieldTypeDescriptor {
+  name: string
+}
+
+export function defineFieldType(def: FieldTypeDef): FieldTypeDescriptor {
+  const { name, ...descriptor } = def // keep column, validator AND transform — don't drop a consumer's transform
+  registerFieldType(name, descriptor)
+  return descriptor
+}

package/layers/fields/server/utils/extract-refs.ts

@@ -0,0 +1,152 @@
+import type { CollectionDef, FieldDef } from '../../../core/server/utils/defineCollection'
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import type { KeyMode } from '../../../core/server/utils/populate'
+import { seoPopulateFields } from '../../../core/server/utils/seo'
+import { getBlock } from './defineBlock'
+import { collectRichtextRefs } from '../../app/utils/richtext-links'
+
+/**
+ * Static reference extraction over a record's fields — the pure core of the `record_refs` durable index
+ * and the derived stale-reference warnings. Walks every reference-bearing field type (relation, media,
+ * internal link, richtext internal-link markers, repeater) plus the block tree, and yields the
+ * `(collection, id)` targets it points at. PURE (no DB / no Nuxt) so it unit-tests hard.
+ */
+export interface FieldRef {
+  collection: string
+  id: number
+}
+
+/** A ref tagged with WHERE it lives, for the editor's per-field / per-block dead-reference notes. */
+export interface LocatedRef extends FieldRef {
+  /** The top-level field key (a repeater attributes all its entries' refs to the repeater key). */
+  field: string
+  /** The id of the block node the ref lives in, or undefined at the record root. */
+  blockId?: string
+}
+
+// `KeyMode` (columns vs props storage asymmetry) is owned by core's populate seam and imported above —
+// the same asymmetry the field-tree populator walks, so both share one definition.
+
+/** The internal-link guard, reimplemented locally to keep this `core`/`fields`-side extractor from
+ *  importing the `public` layer's private `isInternal` (which would invert the layer dependency). */
+function internalLinkRef(value: unknown): FieldRef | null {
+  if (!value || typeof value !== 'object') return null
+  const v = value as Record<string, unknown>
+  if (v.type === 'internal' && typeof v.collection === 'string' && typeof v.id === 'number') {
+    return { collection: v.collection, id: v.id }
+  }
+  return null
+}
+
+/** Located refs inside one flat value bag (top-level row | block props | a repeater entry). */
+function bagRefs(fields: Record<string, FieldDef>, bag: Record<string, unknown>, keyMode: KeyMode): LocatedRef[] {
+  const out: LocatedRef[] = []
+  for (const [key, field] of Object.entries(fields)) {
+    // `if (fieldIs(...))` not `switch (field.type)`: the open consumer arm makes `type` a non-discriminant,
+    // so a switch wouldn't narrow `field` to its arm. (text / number / boolean / datetime / choice / json
+    // carry no typed references, so they're not handled here.)
+    if (fieldIs(field, 'relation')) {
+      const coll = field.relation.collection
+      if (field.relation.many) {
+        const ids = bag[key]
+        if (Array.isArray(ids)) for (const id of ids) if (typeof id === 'number') out.push({ field: key, collection: coll, id })
+      } else {
+        const value = bag[keyMode === 'columns' ? `${key}Id` : key]
+        if (typeof value === 'number') out.push({ field: key, collection: coll, id: value })
+      }
+    } else if (fieldIs(field, 'media')) {
+      if (field.options?.multiple) {
+        const ids = bag[key]
+        if (Array.isArray(ids)) for (const id of ids) if (typeof id === 'number') out.push({ field: key, collection: 'media', id })
+      } else {
+        const value = bag[keyMode === 'columns' ? `${key}Id` : key]
+        if (typeof value === 'number') out.push({ field: key, collection: 'media', id: value })
+      }
+    } else if (field.type === 'link') {
+      const ref = internalLinkRef(bag[key])
+      if (ref) out.push({ field: key, collection: ref.collection, id: ref.id })
+    } else if (field.type === 'richtext') {
+      const value = bag[key]
+      if (typeof value === 'string') for (const r of collectRichtextRefs(value)) out.push({ field: key, collection: r.collection, id: r.id })
+    } else if (fieldIs(field, 'repeater')) {
+      const entries = bag[key]
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          if (entry && typeof entry === 'object') {
+            // A repeater entry is keyed bare (props mode); attribute its refs to the repeater field.
+            for (const r of bagRefs(field.options.fields, entry as Record<string, unknown>, 'props')) {
+              out.push({ field: key, collection: r.collection, id: r.id })
+            }
+          }
+        }
+      }
+    }
+  }
+  return out
+}
+
+/** Located refs inside a block `content` array, recursing slots; each ref carries the innermost block id. */
+function blockRefs(content: unknown): LocatedRef[] {
+  const out: LocatedRef[] = []
+  const walk = (nodes: unknown): void => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue
+      const n = node as { id?: string; type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
+      const def = n.type ? getBlock(n.type) : undefined
+      if (def && n.props && typeof n.props === 'object') {
+        for (const r of bagRefs(def.fields, n.props, 'props')) out.push({ field: r.field, blockId: n.id, collection: r.collection, id: r.id })
+      }
+      if (n.slots && typeof n.slots === 'object') {
+        for (const slotNodes of Object.values(n.slots)) walk(slotNodes)
+      }
+    }
+  }
+  walk(content)
+  return out
+}
+
+function dedupe(refs: FieldRef[]): FieldRef[] {
+  const seen = new Set<string>()
+  const out: FieldRef[] = []
+  for (const r of refs) {
+    const k = `${r.collection}:${r.id}`
+    if (!seen.has(k)) { seen.add(k); out.push({ collection: r.collection, id: r.id }) }
+  }
+  return out
+}
+
+function dedupeLocated(refs: LocatedRef[]): LocatedRef[] {
+  const seen = new Set<string>()
+  const out: LocatedRef[] = []
+  for (const r of refs) {
+    const k = `${r.blockId ?? ''} ${r.field} ${r.collection}:${r.id}`
+    if (!seen.has(k)) { seen.add(k); out.push(r) }
+  }
+  return out
+}
+
+/** Deduped `(collection,id)` refs in a single flat value bag (one field set), honouring the key-mode. */
+export function extractFieldRefs(fields: Record<string, FieldDef>, bag: Record<string, unknown>, keyMode: KeyMode): FieldRef[] {
+  return dedupe(bagRefs(fields, bag, keyMode))
+}
+
+/** Every distinct `(collection,id)` a record points at — its top-level columns plus, if blocks are
+ *  enabled, its whole block tree. The forward edges stored in `record_refs`. */
+export function extractRecordRefs(def: CollectionDef, row: Record<string, unknown>): FieldRef[] {
+  return dedupe(extractLocatedRecordRefs(def, row))
+}
+
+/** Like `extractRecordRefs` but each ref carries its field + block-node location (for editor warnings). */
+export function extractLocatedRecordRefs(def: CollectionDef, row: Record<string, unknown>): LocatedRef[] {
+  const refs = bagRefs(def.fields, row, 'columns')
+  // The `seo` system column carries a media ref (the social image) — track it like any media field so
+  // dead-link warnings and the published-media GC see a record whose ONLY use of an image is og:image.
+  if (def.seo && row.seo && typeof row.seo === 'object') {
+    for (const r of bagRefs(seoPopulateFields, row.seo as Record<string, unknown>, 'props')) {
+      refs.push({ ...r, field: `seo.${r.field}` })
+    }
+  }
+  if (def.blocks?.enabled) refs.push(...blockRefs(row.content))
+  return dedupeLocated(refs)
+}

package/layers/fields/server/utils/field-populate.ts

@@ -0,0 +1,68 @@
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import { seoPopulateFields } from '../../../core/server/utils/seo'
+import type { Populator, PopulateCtx, KeyMode, FieldPopulator } from '../../../core/server/utils/populate'
+import { getFieldPopulator } from '../../../core/server/utils/populate'
+import { buildBlockPopulator } from './block-populate'
+
+/** How the walker finds the populator for a field type — the global registry by default, or an explicit
+ *  map (used by tests + the media/link whole-row compatibility builders to run one populator in isolation). */
+export type PopulatorLookup = (type: string) => FieldPopulator | undefined
+
+/**
+ * Apply the registered per-field-type populators over ONE flat value bag (top-level row | block props | a
+ * repeater entry). For each field: dispatch to its type's populator (which reads by `keyMode` and mutates
+ * `bag`), then — for a repeater — clone its entries and recurse in PROPS mode. Cloning the array + entries
+ * keeps the ORIGINAL row untouched (population is non-destructive). Mutates `bag` in place. This is the
+ * `bagRefs` recursion (see `extract-refs.ts`), generalised from "collect refs" to "run a visitor".
+ */
+export function applyFieldPopulators(
+  bag: Record<string, unknown>,
+  fields: Record<string, FieldDef>,
+  keyMode: KeyMode,
+  ctx: PopulateCtx,
+  lookup: PopulatorLookup,
+): void {
+  for (const [key, field] of Object.entries(fields)) {
+    // A per-instance `field.populate` (Pruvious `additional.population`) wins over the type's default.
+    const fn = field.populate ?? lookup(field.type)
+    if (fn) fn(bag, key, field, ctx, keyMode)
+    if (fieldIs(field, 'repeater')) {
+      const entries = bag[key]
+      if (Array.isArray(entries)) {
+        const cloned = entries.map((e) => (e && typeof e === 'object' ? { ...(e as Record<string, unknown>) } : e))
+        bag[key] = cloned
+        for (const entry of cloned) {
+          if (entry && typeof entry === 'object') {
+            applyFieldPopulators(entry as Record<string, unknown>, field.options.fields, 'props', ctx, lookup)
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * The single global row populator: walks a row's top-level fields (COLUMNS mode) and, when blocks are
+ * enabled, its block tree (each node's props in PROPS mode + every slot), dispatching each field to its
+ * registered per-type populator and recursing repeaters. Non-destructive (returns a fresh row; block
+ * nodes/props are cloned by `buildBlockPopulator`, repeater entries by `applyFieldPopulators`).
+ */
+export function buildFieldTreePopulator(lookup: PopulatorLookup = getFieldPopulator): Populator {
+  return (row, ctx) => {
+    const out: Record<string, unknown> = { ...row }
+    applyFieldPopulators(out, ctx.def.fields, 'columns', ctx, lookup)
+    // The `seo` system column carries a media reference (the social image) — walk it like a props bag
+    // so the id resolves under `seo.$media.image` with the same read-capture as any media field.
+    if (ctx.def.seo && out.seo && typeof out.seo === 'object') {
+      const seoBag = { ...(out.seo as Record<string, unknown>) }
+      applyFieldPopulators(seoBag, seoPopulateFields, 'props', ctx, lookup)
+      out.seo = seoBag
+    }
+    if (ctx.def.blocks?.enabled && Array.isArray(out.content)) {
+      const walk = buildBlockPopulator((props, fields) => applyFieldPopulators(props, fields, 'props', ctx, lookup))
+      out.content = walk(out.content)
+    }
+    return out
+  }
+}

package/layers/media/app/components/KestrelImg.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { useBlurUp } from '../composables/useBlurUp'
+import { useMediaVariant } from '../composables/useMediaVariant'
+import type { ResolvedMedia } from '../../server/utils/resolve'
+import type { VariantFit, VariantFormat } from '../../../core/server/utils/kestrel-config'
+
+// The engine's responsive-image component: it renders a <picture> from the media's generated derivatives
+// AND its usage declares (to the generate-time scan) which sizes/formats are actually needed — "not in the
+// code ⇒ not generated". One usage may declare MULTIPLE `widths` (proportional) and/or a fixed `crop`, plus
+// named config `preset`s, crossed with `formats`. `priority` marks the LCP image (eager + high fetchpriority;
+// no `sizes=auto`, which only applies to lazy images). `sizes="auto"` degrades gracefully (see resolveSizes).
+const props = defineProps<{
+  media: ResolvedMedia | null | undefined
+  widths?: number[]
+  crop?: { width: number; height: number; fit?: VariantFit }
+  preset?: string | string[]
+  formats?: VariantFormat[]
+  sizes?: string
+  priority?: boolean
+}>()
+
+const { model } = useMediaVariant(
+  () => props.media,
+  () => ({ widths: props.widths, crop: props.crop, preset: props.preset, formats: props.formats, sizes: props.sizes }),
+  { priority: () => props.priority ?? false },
+)
+const { imgEl, animate, placeholderStyle, onLoad } = useBlurUp(() => props.media?.thumbhash)
+</script>
+
+<template>
+  <picture v-if="model">
+    <source v-for="s in model.sources" :key="s.type" :type="s.type" :srcset="s.srcset" :sizes="model.sizes">
+    <img
+      ref="imgEl"
+      :src="model.src"
+      :sizes="model.sizes"
+      :width="model.width ?? undefined"
+      :height="model.height ?? undefined"
+      :alt="model.alt"
+      :class="{ 'kestrel-img--in': animate }"
+      :style="placeholderStyle"
+      :loading="priority ? 'eager' : 'lazy'"
+      :fetchpriority="priority ? 'high' : undefined"
+      decoding="async"
+      @load="onLoad"
+    >
+  </picture>
+</template>
+
+<style scoped>
+/* Sharpen-in: one-shot blur→crisp on a genuine async load (JS-driven, so SSR / no-JS / cached just show
+   the image). Same treatment as the demo MediaImage. */
+@keyframes kestrel-img-sharpen {
+  from { filter: blur(8px); }
+  to { filter: blur(0); }
+}
+.kestrel-img--in {
+  animation: kestrel-img-sharpen 0.5s ease-out;
+}
+@media (prefers-reduced-motion: reduce) {
+  .kestrel-img--in {
+    animation: none;
+  }
+}
+</style>

package/layers/media/app/components/MediaConflictDialog.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { Conflict } from '../utils/ops'
+
+const props = defineProps<{ open: boolean; conflicts: Conflict[]; type: 'move' | 'copy'; dest: string; busy?: boolean; error?: string | null }>()
+const emit = defineEmits<{ resolve: ['skip' | 'overwrite' | 'rename']; 'update:open': [boolean] }>()
+
+const { t } = useT()
+const title = computed(() => props.type === 'move' ? t('media.conflictTitleMove') : t('media.conflictTitleCopy'))
+</script>
+
+<template>
+  <UiDialog :open="open" :title="title" @update:open="(v) => emit('update:open', v)">
+    <p>{{ t('media.conflictItems', { count: conflicts.length, dest: dest || t('media.rootFolder') }) }}</p>
+    <ul class="media-conflict__list">
+      <li v-for="c in conflicts" :key="c.targetPath">{{ c.targetPath }} — {{ c.type === 'folder-exists' ? t('media.conflictFolderExists') : t('media.conflictFileExists') }}</li>
+    </ul>
+    <UiAlert v-if="error" variant="error">{{ error }}</UiAlert>
+    <template #footer>
+      <UiButton :disabled="busy" @click="emit('update:open', false)">{{ t('common.cancel') }}</UiButton>
+      <UiButton :disabled="busy" @click="emit('resolve', 'skip')">{{ t('media.skip') }}</UiButton>
+      <UiButton :disabled="busy" @click="emit('resolve', 'overwrite')">{{ t('media.replace') }}</UiButton>
+      <UiButton variant="primary" :disabled="busy" @click="emit('resolve', 'rename')">{{ t('media.keepBoth') }}</UiButton>
+    </template>
+  </UiDialog>
+</template>
+
+<style lang="scss" scoped>
+.media-conflict__list {
+  margin: var(--space-2) 0 0;
+  padding-left: var(--space-4);
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+}
+</style>

package/layers/media/app/components/MediaDeleteDialog.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { humanizeSize } from '../utils/library'
+import type { DeleteReport } from '../utils/ops'
+
+const props = defineProps<{ open: boolean; report: DeleteReport | null; names: Record<number, string>; busy?: boolean; error?: string | null }>()
+const emit = defineEmits<{ confirm: []; 'update:open': [boolean] }>()
+
+const { t } = useT()
+
+const usageLines = computed(() => {
+  const out: { file: string; refs: string }[] = []
+  for (const [id, refs] of Object.entries(props.report?.usages ?? {})) {
+    if (refs.length) out.push({ file: props.names[Number(id)] ?? `#${id}`, refs: refs.map((u) => `${u.collection} #${u.recordId} (${u.field})`).join(', ') })
+  }
+  return out
+})
+</script>
+
+<template>
+  <UiDialog :open="open" :title="t('common.delete')" @update:open="(v) => emit('update:open', v)">
+    <p v-if="report">
+      {{ t('media.deleteSummary', {
+        files: report.summary.files,
+        filesUnit: report.summary.files === 1 ? t('media.file') : t('media.files'),
+        folders: report.summary.folders,
+        foldersUnit: report.summary.folders === 1 ? t('media.folder') : t('media.folders'),
+        size: humanizeSize(report.summary.totalBytes)
+      }) }}
+    </p>
+    <div v-if="usageLines.length" class="media-delete__usages">
+      <p>{{ t('media.usageWarning') }}</p>
+      <ul>
+        <li v-for="u in usageLines" :key="u.file">{{ u.file }} → {{ u.refs }}</li>
+      </ul>
+    </div>
+    <UiAlert v-if="error" variant="error">{{ error }}</UiAlert>
+    <template #footer>
+      <UiButton variant="ghost" :disabled="busy" @click="emit('update:open', false)">{{ t('common.cancel') }}</UiButton>
+      <UiButton variant="danger" :disabled="busy" @click="emit('confirm')">{{ t('common.delete') }}</UiButton>
+    </template>
+  </UiDialog>
+</template>
+
+<style lang="scss" scoped>
+.media-delete__usages {
+  margin-top: var(--space-3);
+  color: var(--color-danger);
+  font-size: var(--text-sm);
+  ul { margin: var(--space-1) 0 0; padding-left: var(--space-4); }
+}
+</style>

package/layers/media/app/components/MediaGrid.vue

@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { itemKey, humanizeSize, type LibraryFile, type LibraryItem } from '../utils/library'
+defineProps<{ items: LibraryItem[]; isSelected: (item: LibraryItem) => boolean; dropTargetPath?: string | null; parentPath?: string | null; upLabel?: string }>()
+const emit = defineEmits<{ navigate: [string]; select: [LibraryItem, { toggle: boolean; range: boolean }]; open: [LibraryItem]; dragstart: [LibraryItem, DragEvent]; dragend: [] }>()
+const mods = (e: MouseEvent) => ({ toggle: e.ctrlKey || e.metaKey, range: e.shiftKey })
+// Plain click opens the folder; modifier-click selects it so folders can join the selection.
+function onFolder(item: LibraryItem, path: string, e: MouseEvent) {
+  if (e.ctrlKey || e.metaKey || e.shiftKey) emit('select', item, mods(e))
+  else emit('navigate', path)
+}
+function onFile(item: LibraryItem, e: MouseEvent) { emit('select', item, mods(e)) }
+const ext = (filename: string) => (filename.split('.').pop() ?? '').toUpperCase()
+// Hover meta: dimensions (when known) · size — the same facts the table view shows in its columns.
+function fileMeta(f: LibraryFile): string {
+  const parts: string[] = []
+  if (f.width && f.height) parts.push(`${f.width}×${f.height}`)
+  parts.push(humanizeSize(f.size))
+  return parts.join(' · ')
+}
+</script>
+
+<template>
+  <ul class="media-grid">
+    <li v-if="parentPath != null" class="media-grid__cell">
+      <!-- Pure up-navigation; not selectable/draggable (kept out of `items`). -->
+      <button type="button" class="media-grid__tile media-grid__tile--folder" data-test="folder-up"
+        :aria-label="upLabel" @click="emit('navigate', parentPath)">
+        <span class="media-grid__thumb-wrap">
+          <span class="media-grid__thumb media-grid__thumb--folder" aria-hidden="true"><UiIcon name="folder" :size="40" /></span>
+        </span>
+        <span class="media-grid__name">..</span>
+      </button>
+    </li>
+    <li v-for="item in items" :key="itemKey(item)" class="media-grid__cell">
+      <button v-if="item.type === 'folder'" type="button" class="media-grid__tile media-grid__tile--folder"
+        :data-test="`folder-${item.folder.path}`" :aria-pressed="isSelected(item)"
+        :data-drop-folder="item.folder.path"
+        :class="{ 'is-selected': isSelected(item), 'is-drop-target': item.folder.path === dropTargetPath }"
+        draggable="true"
+        @click="onFolder(item, item.folder.path, $event)"
+        @keydown.space.prevent="emit('select', item, { toggle: true, range: false })"
+        @dragstart="(e) => emit('dragstart', item, e)"
+        @dragend="emit('dragend')">
+        <span class="media-grid__thumb-wrap">
+          <span class="media-grid__thumb media-grid__thumb--folder" aria-hidden="true"><UiIcon name="folder" :size="40" /></span>
+          <span v-if="item.folder.size != null" class="media-grid__meta" aria-hidden="true">{{ humanizeSize(item.folder.size) }}</span>
+        </span>
+        <span class="media-grid__name">{{ item.folder.name }}</span>
+      </button>
+      <button v-else type="button" class="media-grid__tile media-grid__tile--file"
+        :data-test="`file-${item.file.id}`" :aria-pressed="isSelected(item)"
+        :data-file-id="item.file.id"
+        :class="{ 'is-selected': isSelected(item) }"
+        draggable="true"
+        @click="onFile(item, $event)"
+        @dblclick="emit('open', item)"
+        @keydown.enter.prevent="emit('open', item)"
+        @dragstart="(e) => emit('dragstart', item, e)"
+        @dragend="emit('dragend')">
+        <span class="media-grid__thumb-wrap">
+          <!-- Show a thumbnail for any image WITH a source: media files carry `srcset` (responsive derivatives),
+               while a consumer feeding object-URLs (e.g. the secure gallery) has only `src`. Non-images → badge. -->
+          <MediaThumb v-if="item.file.mime?.startsWith('image/') && (item.file.srcset || item.file.src)" class="media-grid__thumb"
+            :src="item.file.src" :srcset="item.file.srcset" sizes="160px" :alt="item.file.alt ?? item.file.filename" :thumbhash="item.file.thumbhash" />
+          <span v-else class="media-grid__badge" aria-hidden="true">{{ ext(item.file.filename) }}</span>
+          <span class="media-grid__meta" aria-hidden="true">{{ fileMeta(item.file) }}</span>
+          <!-- Optional per-file overlay (e.g. proofing colour flags). Empty by default → nothing rendered. -->
+          <span class="media-grid__overlay"><slot name="file-overlay" :file="item.file" /></span>
+        </span>
+        <span class="media-grid__name">{{ item.file.filename }}</span>
+      </button>
+    </li>
+  </ul>
+</template>
+
+<style lang="scss" scoped>
+.media-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(8rem, 1fr)); gap: var(--space-3); list-style: none; padding: 0; margin: 0; }
+.media-grid__tile { display: flex; flex-direction: column; gap: var(--space-2); width: 100%; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-md); padding: var(--space-2); cursor: pointer; text-align: left; }
+.media-grid__tile:hover { border-color: var(--color-border-strong); }
+// Selection/drop/focus rings are INSET (border-color + inset shadow, or a negative outline-offset) so a
+// scrolling ancestor never clips them — matches MediaTable. An outset outline (positive offset) on an
+// edge tile is sliced off by the library's overflow.
+.media-grid__tile.is-selected { border-color: var(--color-primary); box-shadow: inset 0 0 0 1px var(--color-primary); }
+.media-grid__tile.is-drop-target { outline: 2px dashed var(--color-primary); outline-offset: -2px; background: var(--color-surface); }
+.media-grid__tile:focus-visible { outline: 2px solid var(--color-focus); outline-offset: -2px; }
+.media-grid__thumb-wrap { position: relative; width: 100%; }
+.media-grid__overlay { position: absolute; top: var(--space-1); left: var(--space-1); display: flex; gap: 2px; pointer-events: none; }
+.media-grid__thumb { aspect-ratio: 1; width: 100%; object-fit: cover; border-radius: var(--radius-sm); background: var(--color-bg); display: block; }
+.media-grid__thumb--folder { display: grid; place-items: center; color: var(--color-text-subtle); }
+.media-grid__badge { display: grid; place-items: center; aspect-ratio: 1; width: 100%; border-radius: var(--radius-sm); background: var(--color-bg); color: var(--color-text-muted); font-weight: var(--weight-bold); }
+// Hover/focus reveal of the dimensions · size caption, overlaid on the lower edge of the thumb.
+.media-grid__meta {
+  position: absolute;
+  inset-inline: 0;
+  bottom: 0;
+  padding: 2px var(--space-1);
+  font-size: var(--text-xs);
+  line-height: 1.35;
+  text-align: center;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--color-on-primary);
+  background: linear-gradient(transparent, var(--color-scrim));
+  border-radius: 0 0 var(--radius-sm) var(--radius-sm);
+  opacity: 0;
+  transition: opacity var(--motion-fast) var(--ease-standard);
+  pointer-events: none;
+}
+.media-grid__tile:hover .media-grid__meta,
+.media-grid__tile:focus-visible .media-grid__meta { opacity: 1; }
+.media-grid__name { font-size: var(--text-sm); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+</style>