@prenta/admin 0.93.0 → 0.95.0

package/src/components/CanvasEditTip.tsx

@@ -26,9 +26,9 @@ export function CanvasEditTip() {
       <p className="min-w-0 flex-1 leading-[1.5]">
         <span className="text-foreground font-medium">Editing tip</span>
         {' — '}
-        Hover sections for a light outline, then click to select. Edit copy and images in the
-        inspector. Use <span className="text-foreground font-medium">Site preview</span> to click
-        text and images in place.
+        Click a section on the canvas, or in the list, to open its copy and images in the section
+        list. Use <span className="text-foreground font-medium">Site preview</span> to click text
+        and images in place.
       </p>
       <button
         type="button"

package/src/components/EditorRail.tsx

@@ -96,7 +96,7 @@ export function EditorRail({ collapsedLabel, children }: EditorRailProps) {
   if (!open) {
     return (
       <div
-        className="bg-card border-border flex shrink-0 flex-col items-center gap-3 border-r py-3"
+        className="prenta-editor-rail-collapsed bg-card border-border flex shrink-0 flex-col items-center gap-3 border-r py-3"
         style={{ width: RAIL_COLLAPSED_WIDTH }}
       >
         <button
@@ -104,14 +104,14 @@ export function EditorRail({ collapsedLabel, children }: EditorRailProps) {
           onClick={() => setOpen(true)}
           aria-label={`Expand ${collapsedLabel} panel`}
           title={`Expand ${collapsedLabel} panel`}
-          className="text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-6.5 w-6.5 items-center justify-center rounded-md transition-colors"
+          className="prenta-touch-target text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-6.5 w-6.5 items-center justify-center rounded-md transition-colors"
         >
           <PanelLeftOpen className="h-4 w-4" aria-hidden />
         </button>
         {/* Vertical label so the strip still says which panel is hidden. The
             button's accessible name already carries it, hence aria-hidden. */}
         <span
-          className="text-muted-foreground text-[10px] font-bold tracking-[0.8px] whitespace-nowrap uppercase [writing-mode:vertical-rl]"
+          className="prenta-rail-label text-muted-foreground text-[10px] font-bold tracking-[0.8px] whitespace-nowrap uppercase [writing-mode:vertical-rl]"
           aria-hidden
         >
           {collapsedLabel}
@@ -123,7 +123,7 @@ export function EditorRail({ collapsedLabel, children }: EditorRailProps) {
   return (
     <div
       ref={railRef}
-      className={`bg-card border-border relative flex shrink-0 flex-col border-r ${
+      className={`prenta-editor-rail bg-card border-border relative flex shrink-0 flex-col border-r ${
         // A width transition during a drag fights the pointer: the panel
         // chases the cursor a frame behind and the resize feels broken.
         dragging ? '' : 'motion-safe:transition-[width] motion-safe:duration-(--mo-slow)'
@@ -209,7 +209,7 @@ export function RailHeader({
           onClick={onCollapse}
           aria-label={`Collapse ${title} panel`}
           title={`Collapse ${title} panel`}
-          className="text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-6.5 w-6.5 items-center justify-center rounded-md transition-colors"
+          className="prenta-touch-target text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-6.5 w-6.5 items-center justify-center rounded-md transition-colors"
         >
           <PanelLeftClose className="h-4 w-4" aria-hidden />
         </button>

package/src/components/page-tab/DirectiveSwitch.tsx

@@ -74,7 +74,10 @@ export function DirectiveSwitch({
           onCheckedChange={onChange}
           disabled={disabled}
           aria-label={`${label} — currently ${token}`}
-          className={`focus-visible:ring-ring relative h-[19px] w-[34px] shrink-0 rounded-full transition-colors duration-(--mo-base) focus-visible:ring-2 focus-visible:outline-none disabled:opacity-50 ${
+          // `prenta-touch-hit`, not `prenta-touch-target`: growing the track to
+          // 44px would strand the thumb, which is positioned against it. The
+          // hit area grows; the switch keeps its measured 34×19.
+          className={`prenta-touch-hit focus-visible:ring-ring relative h-[19px] w-[34px] shrink-0 rounded-full transition-colors duration-(--mo-base) focus-visible:ring-2 focus-visible:outline-none disabled:opacity-50 ${
             checked ? 'bg-success' : 'bg-destructive/55'
           }`}
         >

package/src/layout/primitives/AdminShell.tsx

@@ -71,6 +71,16 @@ export function AdminShell({
           : { display: 'block', position: 'relative' }
       }
     >
+      {/*
+       * First focusable thing in the admin, so a keyboard user's very first
+       * Tab offers a jump past the sidebar's ~20 nav items. Off-screen until
+       * focused; styling lives in `responsive.css` because it has to survive
+       * a consumer whose Tailwind build does not scan this file.
+       */}
+      <a className="prenta-skip-link" href="#prenta-main">
+        Skip to content
+      </a>
+
       {!isDesktop && mobileSidebarOpen && (
         <div
           aria-hidden
@@ -111,7 +121,9 @@ export function AdminShell({
       >
         {header}
         {breadcrumbs}
-        <main className="min-h-0 flex-1 overflow-y-auto">{children}</main>
+        <main id="prenta-main" className="min-h-0 flex-1 overflow-y-auto">
+          {children}
+        </main>
       </div>
     </div>
   )

package/src/lib/version-diff.ts

@@ -0,0 +1,376 @@
+/**
+ * Field-level diff between two page snapshots.
+ *
+ * One of the three parts of the page-builder handoff specified as real logic
+ * rather than mockup ("the version diff — field-level, computed from full
+ * snapshots, and its output drives the changed-section outlines on the
+ * canvas"). Nothing here is display-only: the same result feeds the history
+ * panel's per-field list AND the set of sections the canvas outlines while
+ * reviewing, so the two can never disagree about what changed.
+ *
+ * Pure over `PageSection[]`, with no React and no fetching, because the diff
+ * is asked for in three different places (panel rows, canvas outlines, the
+ * review bar's count) and recomputing it from the same inputs has to be free
+ * of side effects.
+ */
+import {
+  getSectionType,
+  resolveRepeaterField,
+  type SectionFieldDef,
+} from '../views/page-editor/section-types.js'
+import type { PageSection } from './page-editor-service.js'
+
+/** One changed field on one section. */
+export interface FieldChange {
+  sectionId: string
+  /** Editor-facing section name, captured so the panel needn't re-look it up. */
+  sectionName: string
+  /** Human label for the field ("Heading"), from the section registry. */
+  field: string
+  /** Formatted previous value; `—` when absent. */
+  from: string
+  /** Formatted new value; `—` when absent. */
+  to: string
+}
+
+/** Changes for one section, in the order the sections appear on the page. */
+export interface SectionChangeGroup {
+  sectionId: string
+  sectionName: string
+  changes: FieldChange[]
+}
+
+/**
+ * Labels for the keys that are not content fields and so have no entry in the
+ * section registry. Visibility earns its place here: hiding a section is the
+ * one structural change a design-owned CMS lets an editor make, so a history
+ * that silently dropped it would be missing the only structural edit there is.
+ */
+const META_LABELS: Record<string, string> = {
+  visible: 'Visibility',
+  name: 'Section name',
+}
+
+const SETTING_LABELS: Record<string, string> = {
+  backgroundType: 'Background type',
+  backgroundColor: 'Background colour',
+  paddingY: 'Vertical padding',
+  anchorId: 'Anchor id',
+  cssClass: 'CSS class',
+}
+
+const EMPTY = '—'
+
+/**
+ * Label a content key through the section registry — the same definitions the
+ * inspector renders from, so the diff reads in the words the editor typed
+ * under. Falls back to the raw key for content on a custom or unmanaged type
+ * the registry does not describe: a key is uglier than a label but it is true,
+ * whereas omitting the row would hide a real change.
+ */
+function contentFieldLabel(sectionType: string, key: string): string {
+  const def = getSectionType(sectionType)
+  const field = def?.fields.find((f: SectionFieldDef) => f.key === key)
+  return field?.label ?? key
+}
+
+/**
+ * The repeater shape behind a content key, or null when the field is not one.
+ *
+ * Goes through `resolveRepeaterField` rather than reading `field.fields`
+ * directly: `stats` and `gallery` are shorthand presets whose sub-fields are
+ * supplied by the registry, not spelled out on the definition, so reading the
+ * raw property finds nothing and the diff falls back to raw keys ("value"
+ * instead of "Value") on the two repeaters that ship by default.
+ */
+function repeaterFor(sectionType: string, key: string) {
+  const def = getSectionType(sectionType)
+  const field = def?.fields.find((f: SectionFieldDef) => f.key === key)
+  return field ? resolveRepeaterField(field) : null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Values that all render as `—` and must therefore compare as equal.
+ *
+ * Without this, tightening the comparison from formatted strings to structure
+ * would start reporting `'' → undefined` as a change, emitting rows that read
+ * "— → —". Blank is blank however it is spelled.
+ */
+function isBlank(value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'string') return value.trim() === ''
+  if (Array.isArray(value)) return value.length === 0
+  if (isPlainObject(value)) return Object.keys(value).length === 0
+  return false
+}
+
+/**
+ * Structural equality, which is what decides whether a field changed.
+ *
+ * This deliberately does NOT go through {@link formatValue}. Comparing the
+ * display strings is the obvious shortcut and it silently loses real edits:
+ * `formatValue` collapses an array to "N items", so retyping a stats row while
+ * keeping the row count formats identically on both sides and the field reports
+ * no change — no row in the panel, and no outline on the canvas. That is
+ * precisely the edit the reviewer is looking for.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (isBlank(a) && isBlank(b)) return true
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]))
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+    for (const key of keys) if (!deepEqual(a[key], b[key])) return false
+    return true
+  }
+  return false
+}
+
+/**
+ * Render a value as the one line the diff shows.
+ *
+ * Lossy on purpose — a repeater row expanded in full would bury the change it
+ * is reporting. It is used for DISPLAY ONLY; {@link deepEqual} decides whether
+ * a field changed, and repeater rows are descended into by
+ * {@link compareRepeater} so a collapsed summary never has to stand in for a
+ * change it cannot show.
+ */
+export function formatValue(value: unknown): string {
+  if (value === null || value === undefined) return EMPTY
+  if (typeof value === 'string') return value.trim() === '' ? EMPTY : value
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No'
+  if (typeof value === 'number') return String(value)
+  if (Array.isArray(value)) {
+    if (value.length === 0) return EMPTY
+    return `${value.length} item${value.length === 1 ? '' : 's'}`
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    for (const key of ['name', 'title', 'label', 'url', 'alt']) {
+      const candidate = record[key]
+      if (typeof candidate === 'string' && candidate.trim() !== '') return candidate
+    }
+    const count = Object.keys(record).length
+    return count === 0 ? EMPTY : `${count} field${count === 1 ? '' : 's'}`
+  }
+  return String(value)
+}
+
+/** Visibility reads as a state, not a boolean — "No" is not a useful diff. */
+function formatVisible(value: unknown): string {
+  return value === false ? 'Hidden' : 'Shown'
+}
+
+function push(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  field: string,
+  from: string,
+  to: string,
+): void {
+  out.push({ sectionId: section.id, sectionName: section.name, field, from, to })
+}
+
+function compare(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  field: string,
+  before: unknown,
+  after: unknown,
+  format: (v: unknown) => string = formatValue,
+): void {
+  if (deepEqual(before, after)) return
+  push(out, section, field, format(before), format(after))
+}
+
+/**
+ * Diff a repeater (stats rows, gallery images, FAQ entries) row by row.
+ *
+ * A single "2 items → 2 items" row would be worse than useless: it is the one
+ * case where the summary cannot express the change, and the reviewer's next
+ * question — *which* row — has no answer. Descending gives
+ * "Stats · Row 2 · Value" and a real before/after.
+ */
+function compareRepeater(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  sectionType: string,
+  key: string,
+  label: string,
+  before: readonly unknown[],
+  after: readonly unknown[],
+): void {
+  const repeater = repeaterFor(sectionType, key)
+  // The registry's own noun for a row ("Stat", "Image") when it has one.
+  const rowNoun = repeater?.rowLabel ?? 'Row'
+  const subLabel = (subKey: string) =>
+    repeater?.fields.find((f: SectionFieldDef) => f.key === subKey)?.label ?? subKey
+
+  for (let i = 0; i < Math.max(before.length, after.length); i++) {
+    const rowLabel = `${label} · ${rowNoun} ${i + 1}`
+    const prev = before[i]
+    const next = after[i]
+
+    if (prev === undefined) {
+      push(out, section, rowLabel, EMPTY, 'Added')
+      continue
+    }
+    if (next === undefined) {
+      push(out, section, rowLabel, 'Present', 'Removed')
+      continue
+    }
+    if (deepEqual(prev, next)) continue
+
+    // Rows are normally objects of sub-fields; anything else (a bare string in
+    // a legacy gallery, say) still gets a row rather than being skipped.
+    if (!isPlainObject(prev) || !isPlainObject(next)) {
+      push(out, section, rowLabel, formatValue(prev), formatValue(next))
+      continue
+    }
+
+    for (const subKey of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+      compare(out, section, `${rowLabel} · ${subLabel(subKey)}`, prev[subKey], next[subKey])
+    }
+  }
+}
+
+/** One content field: descends into repeaters, otherwise a plain comparison. */
+function compareContentField(
+  out: FieldChange[],
+  section: Pick<PageSection, 'id' | 'name'>,
+  sectionType: string,
+  key: string,
+  before: unknown,
+  after: unknown,
+): void {
+  if (deepEqual(before, after)) return
+
+  const label = contentFieldLabel(sectionType, key)
+  const beforeRows = Array.isArray(before) ? before : null
+  const afterRows = Array.isArray(after) ? after : null
+
+  if (beforeRows && afterRows) {
+    compareRepeater(out, section, sectionType, key, label, beforeRows, afterRows)
+    return
+  }
+
+  push(out, section, label, formatValue(before), formatValue(after))
+}
+
+/**
+ * Compute what changed going FROM `older` TO `newer`.
+ *
+ * Diffing version *i* against version *i+1* therefore yields what changed *in*
+ * version *i* — the framing the history panel needs, where each row answers
+ * "what did this save do?" rather than "how does this differ from now?".
+ *
+ * `older` is optional because the earliest version in a list has nothing
+ * before it. That case is no changes, not "everything was added": the oldest
+ * snapshot we happen to hold is not the moment the page came into existence,
+ * and reporting every field as new would say it was.
+ */
+export function diffVersions(
+  newer: readonly PageSection[],
+  older: readonly PageSection[] | null | undefined,
+): FieldChange[] {
+  if (!older) return []
+
+  const out: FieldChange[] = []
+  const olderById = new Map(older.map((s) => [s.id, s]))
+
+  for (const next of newer) {
+    const prev = olderById.get(next.id)
+
+    if (!prev) {
+      out.push({
+        sectionId: next.id,
+        sectionName: next.name,
+        field: 'Section',
+        from: EMPTY,
+        to: 'Added',
+      })
+      continue
+    }
+
+    if (next.name !== prev.name) {
+      compare(out, next, META_LABELS.name!, prev.name, next.name)
+    }
+    compare(out, next, META_LABELS.visible!, prev.visible, next.visible, formatVisible)
+
+    // Union of both key sets: a field cleared to undefined only appears in the
+    // older snapshot, and clearing a heading is exactly the kind of edit a
+    // history is consulted about.
+    const contentKeys = new Set([
+      ...Object.keys(prev.content ?? {}),
+      ...Object.keys(next.content ?? {}),
+    ])
+    for (const key of contentKeys) {
+      compareContentField(
+        out,
+        next,
+        next.sectionType,
+        key,
+        prev.content?.[key],
+        next.content?.[key],
+      )
+    }
+
+    const settingKeys = new Set([
+      ...Object.keys(prev.settings ?? {}),
+      ...Object.keys(next.settings ?? {}),
+    ])
+    for (const key of settingKeys) {
+      compare(
+        out,
+        next,
+        SETTING_LABELS[key] ?? key,
+        (prev.settings as Record<string, unknown>)?.[key],
+        (next.settings as Record<string, unknown>)?.[key],
+      )
+    }
+  }
+
+  // Sections present before and gone after. Reported against the OLD section's
+  // name because the new snapshot has nothing to name it with.
+  const newerIds = new Set(newer.map((s) => s.id))
+  for (const gone of older) {
+    if (newerIds.has(gone.id)) continue
+    out.push({
+      sectionId: gone.id,
+      sectionName: gone.name,
+      field: 'Section',
+      from: 'Present',
+      to: 'Removed',
+    })
+  }
+
+  return out
+}
+
+/**
+ * Group changes by section, preserving first-seen order so the panel lists
+ * them top-to-bottom in the order they appear on the page.
+ */
+export function groupChangesBySection(changes: readonly FieldChange[]): SectionChangeGroup[] {
+  const groups = new Map<string, SectionChangeGroup>()
+  for (const change of changes) {
+    let group = groups.get(change.sectionId)
+    if (!group) {
+      group = { sectionId: change.sectionId, sectionName: change.sectionName, changes: [] }
+      groups.set(change.sectionId, group)
+    }
+    group.changes.push(change)
+  }
+  return [...groups.values()]
+}
+
+/** The ids the canvas outlines while reviewing a version. */
+export function changedSectionIds(changes: readonly FieldChange[]): Set<string> {
+  return new Set(changes.map((c) => c.sectionId))
+}

package/src/lib/version-history.ts

@@ -0,0 +1,192 @@
+/**
+ * Version history data layer for the page editor.
+ *
+ * History in this editor is a **mode, not a popup**: selecting a version
+ * renders it on the canvas, so the panel needs the full section snapshot of
+ * every entry, not just its metadata. `GET /collections/:slug/:id/versions`
+ * already returns each version's whole `data` blob — the same blob the restore
+ * endpoint writes back — so the snapshots are read straight off the list
+ * response and no second request per row is needed.
+ */
+import { cmsApi } from './api.js'
+import { coerceSections, type PageSection } from '@prenta/core/page-sections'
+
+/**
+ * Mirrors the `ChangeType` enum in the Prisma schema.
+ *
+ * `PUBLISH` and `RESTORE` were declared there from the beginning and nothing
+ * ever wrote them; `cms-core` now does. Rows written before that read `UPDATE`
+ * whatever they actually were, which is why {@link versionKind} labels
+ * `UPDATE` as "Saved" rather than "Draft" — the neutral reading is the only
+ * one that is true for both old and new rows.
+ */
+export type VersionChangeType = 'CREATE' | 'UPDATE' | 'PUBLISH' | 'RESTORE' | 'DELETE'
+
+export interface VersionAuthor {
+  id: string
+  /** Display name, falling back to email and then to a non-blank placeholder. */
+  name: string
+}
+
+export interface PageVersion {
+  id: string
+  changeType: VersionChangeType
+  createdAt: string
+  author: VersionAuthor
+  /** Full page content as of this version — what the canvas renders. */
+  sections: PageSection[]
+}
+
+/** Versions sharing a calendar day, newest day first. */
+export interface VersionDayGroup {
+  /** `Today` / `Yesterday` / `Jul 27` — the sticky header text. */
+  label: string
+  versions: PageVersion[]
+}
+
+/** How one change type presents as a pill. */
+export interface VersionKind {
+  label: string
+  /** Semantic tone; the panel maps these onto token classes. */
+  tone: 'live' | 'draft' | 'neutral' | 'danger'
+}
+
+const KINDS: Record<VersionChangeType, VersionKind> = {
+  // "Published" is the one distinction that matters in a version list: which
+  // of these could a visitor have seen?
+  PUBLISH: { label: 'Published', tone: 'live' },
+  CREATE: { label: 'Created', tone: 'neutral' },
+  // NOT "Draft". Every version written before cms-core started recording
+  // PUBLISH is an UPDATE regardless of whether it went live, so calling this
+  // "Draft" would state something false about historical rows. "Saved" is true
+  // of all of them.
+  UPDATE: { label: 'Saved', tone: 'draft' },
+  RESTORE: { label: 'Restored', tone: 'neutral' },
+  DELETE: { label: 'Deleted', tone: 'danger' },
+}
+
+export function versionKind(changeType: string): VersionKind {
+  return KINDS[changeType as VersionChangeType] ?? { label: 'Saved', tone: 'draft' }
+}
+
+interface VersionApiRow {
+  id: string
+  changeType: string
+  createdAt: string
+  data: Record<string, unknown> | null
+  changedBy?: { id: string; name?: string | null; email?: string | null } | null
+}
+
+function toAuthor(row: VersionApiRow): VersionAuthor {
+  const by = row.changedBy
+  return {
+    id: by?.id ?? '',
+    // An avatar built from an empty string renders a blank circle, so the
+    // fallback has to be a real word rather than ''.
+    name: by?.name?.trim() || by?.email?.trim() || 'Unknown',
+  }
+}
+
+export function toPageVersion(row: VersionApiRow): PageVersion {
+  const data = row.data ?? {}
+  return {
+    id: row.id,
+    changeType: (row.changeType as VersionChangeType) ?? 'UPDATE',
+    createdAt: row.createdAt,
+    author: toAuthor(row),
+    // `preserve` matches how the editor reads the live document. Coercing a
+    // snapshot more strictly than the current page would make an unmanaged
+    // section look like it was deleted in every version that contains one.
+    sections: coerceSections(data.sections, { onUnknown: 'preserve' }),
+  }
+}
+
+/** Newest first, matching the API's own ordering. */
+export async function fetchPageVersions(
+  collectionSlug: string,
+  documentId: string,
+): Promise<PageVersion[]> {
+  const res = await cmsApi<{ versions: VersionApiRow[]; total: number }>(
+    `/collections/${collectionSlug}/${documentId}/versions?pageSize=50`,
+  )
+  if (res.error) throw new Error(res.error)
+  const rows = res.data?.versions ?? []
+  return rows.map(toPageVersion)
+}
+
+export async function restorePageVersion(
+  collectionSlug: string,
+  documentId: string,
+  versionId: string,
+): Promise<void> {
+  const res = await cmsApi(
+    `/collections/${collectionSlug}/${documentId}/versions/${versionId}/restore`,
+    { method: 'POST' },
+  )
+  if (res.error) throw new Error(res.error)
+}
+
+// ─── Presentation helpers ────────────────────────────────────────────
+
+function startOfDay(date: Date): number {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()
+}
+
+/**
+ * `Today` / `Yesterday` / a short date.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the label is
+ * testable — "relative to today" is untestable when today is whatever the
+ * suite happens to run on.
+ */
+export function dayLabel(iso: string, now: Date = new Date()): string {
+  const date = new Date(iso)
+  if (Number.isNaN(date.getTime())) return 'Unknown date'
+
+  const days = Math.round((startOfDay(now) - startOfDay(date)) / 86_400_000)
+  if (days === 0) return 'Today'
+  if (days === 1) return 'Yesterday'
+
+  return date.toLocaleDateString(undefined, {
+    month: 'short',
+    day: 'numeric',
+    // Drop the year within the current one — "Jul 27, 2026" in a list where
+    // every entry is 2026 is four characters of noise per row.
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: 'numeric' }),
+  })
+}
+
+export function timeLabel(iso: string): string {
+  const date = new Date(iso)
+  if (Number.isNaN(date.getTime())) return ''
+  return date.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })
+}
+
+/**
+ * Group an already-ordered list into consecutive runs sharing a day label.
+ *
+ * Consecutive runs, not a keyed bucket: the list arrives newest-first and must
+ * stay that way, and a `Map` keyed on the label would silently merge two runs
+ * that are not adjacent if the API ever returned an unsorted page.
+ */
+export function groupVersionsByDay(
+  versions: readonly PageVersion[],
+  now: Date = new Date(),
+): VersionDayGroup[] {
+  const groups: VersionDayGroup[] = []
+  for (const version of versions) {
+    const label = dayLabel(version.createdAt, now)
+    const last = groups[groups.length - 1]
+    if (last && last.label === label) last.versions.push(version)
+    else groups.push({ label, versions: [version] })
+  }
+  return groups
+}
+
+/** Two-letter monogram for the row avatar. */
+export function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return '?'
+  if (parts.length === 1) return parts[0]!.slice(0, 2).toUpperCase()
+  return (parts[0]![0]! + parts[parts.length - 1]![0]!).toUpperCase()
+}