@byline/host-tanstack-start 6.2.1 → 6.4.0

package/src/admin-shell/chrome/breadcrumbs/breadcrumbs.test.tsx

@@ -0,0 +1,274 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { act, type ComponentProps, type ReactNode } from 'react'
+
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('../loose-router.js', () => ({
+  Link: ({ to, children, ...rest }: { to?: string; children?: ReactNode }) => (
+    <a href={to} {...rest}>
+      {children}
+    </a>
+  ),
+}))
+
+vi.mock('@byline/i18n/react', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}))
+
+vi.mock('@byline/ui/react', () => ({
+  EllipsisIcon: (props: ComponentProps<'span'>) => <span {...props} />,
+  Dropdown: {
+    Root: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+    Trigger: ({ children, ...rest }: ComponentProps<'button'>) => (
+      <button type="button" {...rest}>
+        {children}
+      </button>
+    ),
+    Portal: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+    Content: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+    Item: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+  },
+}))
+
+const { Breadcrumbs } = await import('./breadcrumbs.js')
+const { BreadcrumbsProvider, useBreadcrumbs } = await import('./breadcrumbs-provider.js')
+type Breadcrumb = import('./@types.js').Breadcrumb
+
+// jsdom performs no layout, so every width would read as 0 and the collapse
+// branch could never be exercised. Derive a deterministic width from rendered
+// text instead, and let each test drive the container width directly.
+const CHAR_WIDTH = 10
+const ITEM_PADDING = 20
+let containerWidth = 1000
+let resizeCallbacks: Array<() => void> = []
+
+function installLayoutStubs() {
+  Object.defineProperty(HTMLElement.prototype, 'offsetWidth', {
+    configurable: true,
+    get(this: HTMLElement) {
+      return (this.textContent?.length ?? 0) * CHAR_WIDTH + ITEM_PADDING
+    },
+  })
+  Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+    configurable: true,
+    get(this: HTMLElement) {
+      return this.tagName === 'NAV' ? containerWidth : 0
+    },
+  })
+  vi.spyOn(window, 'getComputedStyle').mockImplementation(
+    () => ({ gap: '4px' }) as unknown as CSSStyleDeclaration
+  )
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(callback: () => void) {
+        resizeCallbacks.push(callback)
+      }
+      observe() {}
+      disconnect() {}
+    }
+  )
+}
+
+let root: Root
+let container: HTMLDivElement
+
+beforeEach(() => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  containerWidth = 1000
+  resizeCallbacks = []
+  installLayoutStubs()
+  container = document.createElement('div')
+  document.body.append(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+/** Labels in the live trail, excluding the hidden measurement layer. */
+function visibleLabels(): string[] {
+  const list = container.querySelector('nav > ul')
+  if (!list) return []
+  return [...list.querySelectorAll('li')].map((li) => li.textContent?.trim() ?? '')
+}
+
+function isCollapsed(): boolean {
+  return container.querySelector('nav > ul button') != null
+}
+
+const trail = (n: number): Breadcrumb[] =>
+  Array.from({ length: n }, (_, i) => ({ label: `Section${i}`, href: `/section-${i}` }))
+
+describe('breadcrumbs provider equality', () => {
+  it('keeps the previous settings object when equivalent breadcrumbs are submitted', () => {
+    const received: unknown[] = []
+    function Consumer() {
+      const { breadCrumbSettings } = useBreadcrumbs()
+      received.push(breadCrumbSettings)
+      return null
+    }
+    let setBreadcrumbs!: ReturnType<typeof useBreadcrumbs>['setBreadcrumbs']
+    function Setter() {
+      setBreadcrumbs = useBreadcrumbs().setBreadcrumbs
+      return null
+    }
+    act(() =>
+      root.render(
+        <BreadcrumbsProvider>
+          <Setter />
+          <Consumer />
+        </BreadcrumbsProvider>
+      )
+    )
+
+    const settings = {
+      homeLabel: 'Home',
+      homePath: '/admin',
+      breadcrumbs: [{ label: 'Dashboard', href: '/admin' }],
+    }
+    act(() => setBreadcrumbs(settings))
+    const afterFirst = received.length
+
+    // A deep-equal but freshly allocated value — exactly what a route
+    // component produces on every render from an inline array literal.
+    act(() =>
+      setBreadcrumbs({
+        homeLabel: 'Home',
+        homePath: '/admin',
+        breadcrumbs: [{ label: 'Dashboard', href: '/admin' }],
+      })
+    )
+
+    expect(received.length).toBe(afterFirst)
+    expect(received.at(-1)).toBe(received[afterFirst - 1])
+  })
+
+  it('propagates a new settings object when a breadcrumb label actually changes', () => {
+    const received: unknown[] = []
+    function Consumer() {
+      received.push(useBreadcrumbs().breadCrumbSettings)
+      return null
+    }
+    let setBreadcrumbs!: ReturnType<typeof useBreadcrumbs>['setBreadcrumbs']
+    function Setter() {
+      setBreadcrumbs = useBreadcrumbs().setBreadcrumbs
+      return null
+    }
+    act(() =>
+      root.render(
+        <BreadcrumbsProvider>
+          <Setter />
+          <Consumer />
+        </BreadcrumbsProvider>
+      )
+    )
+
+    act(() => setBreadcrumbs({ breadcrumbs: [{ label: 'Dashboard', href: '/admin' }] }))
+    const afterFirst = received.length
+    act(() => setBreadcrumbs({ breadcrumbs: [{ label: 'Renamed', href: '/admin' }] }))
+
+    expect(received.length).toBeGreaterThan(afterFirst)
+  })
+
+  it('exposes a stable setter so consumer effects do not refire', () => {
+    const setters = new Set<unknown>()
+    function Consumer() {
+      setters.add(useBreadcrumbs().setBreadcrumbs)
+      return null
+    }
+    let setBreadcrumbs!: ReturnType<typeof useBreadcrumbs>['setBreadcrumbs']
+    function Setter() {
+      setBreadcrumbs = useBreadcrumbs().setBreadcrumbs
+      return null
+    }
+    act(() =>
+      root.render(
+        <BreadcrumbsProvider>
+          <Setter />
+          <Consumer />
+        </BreadcrumbsProvider>
+      )
+    )
+    act(() => setBreadcrumbs({ breadcrumbs: [{ label: 'Dashboard', href: '/admin' }] }))
+    act(() => setBreadcrumbs({ breadcrumbs: [{ label: 'Renamed', href: '/admin' }] }))
+
+    expect(setters.size).toBe(1)
+  })
+})
+
+describe('breadcrumbs measurement', () => {
+  it('re-measures when only the home label changes', () => {
+    const breadcrumbs = trail(5)
+    containerWidth = 700
+    act(() => root.render(<Breadcrumbs breadcrumbs={breadcrumbs} homeLabel="Home" />))
+    expect(isCollapsed()).toBe(false)
+
+    // Same array reference; only the home label grows. Its width feeds the
+    // same calculation, so the trail must collapse.
+    act(() =>
+      root.render(
+        <Breadcrumbs breadcrumbs={breadcrumbs} homeLabel="A considerably longer home label" />
+      )
+    )
+
+    expect(isCollapsed()).toBe(true)
+  })
+
+  it('expands a collapsed trail when it is replaced by a shorter one', () => {
+    containerWidth = 260
+    act(() => root.render(<Breadcrumbs breadcrumbs={trail(6)} homeLabel="Home" />))
+    expect(isCollapsed()).toBe(true)
+
+    act(() => root.render(<Breadcrumbs breadcrumbs={trail(2)} homeLabel="Home" />))
+
+    expect(isCollapsed()).toBe(false)
+    expect(visibleLabels()).toEqual(['Home', 'Section0', 'Section1'])
+  })
+
+  it('re-measures when labels change without changing the breadcrumb count', () => {
+    containerWidth = 600
+    act(() => root.render(<Breadcrumbs breadcrumbs={trail(4)} homeLabel="Home" />))
+    const before = isCollapsed()
+
+    const longer: Breadcrumb[] = trail(4).map((b, i) => ({
+      ...b,
+      label: `${b.label} with a much longer label ${i}`,
+    }))
+    act(() => root.render(<Breadcrumbs breadcrumbs={longer} homeLabel="Home" />))
+
+    expect(before).toBe(false)
+    expect(isCollapsed()).toBe(true)
+  })
+
+  it('collapses and expands across a resize', () => {
+    const breadcrumbs = trail(6)
+    containerWidth = 1000
+    act(() => root.render(<Breadcrumbs breadcrumbs={breadcrumbs} homeLabel="Home" />))
+    expect(isCollapsed()).toBe(false)
+
+    containerWidth = 260
+    act(() => {
+      for (const cb of resizeCallbacks) cb()
+    })
+    expect(isCollapsed()).toBe(true)
+
+    containerWidth = 1000
+    act(() => {
+      for (const cb of resizeCallbacks) cb()
+    })
+    expect(isCollapsed()).toBe(false)
+  })
+})

package/src/admin-shell/chrome/breadcrumbs/breadcrumbs.tsx

@@ -45,14 +45,11 @@ export function Breadcrumbs({
   // visibleIndices = indices into breadcrumbs[] that are shown inline.
   // Anything missing from this set is rolled into the overflow dropdown.
   // Default to "all visible" so SSR and pre-measurement paints look right.
+  // No reset effect is needed when the trail changes: the hidden measurement
+  // layer always renders every breadcrumb regardless of visibility, so the
+  // effect below recomputes the final indices from scratch before paint.
   const [visibleIndices, setVisibleIndices] = useState<number[]>(() => breadcrumbs.map((_, i) => i))
 
-  // Reset visibility when breadcrumbs change; the measurement effect below
-  // will collapse again on the next layout tick if needed.
-  useIsoLayoutEffect(() => {
-    setVisibleIndices(breadcrumbs.map((_, i) => i))
-  }, [breadcrumbs])
-
   useIsoLayoutEffect(() => {
     const nav = navRef.current
     const measure = measureRef.current
@@ -113,7 +110,10 @@ export function Breadcrumbs({
     const ro = new ResizeObserver(compute)
     ro.observe(nav)
     return () => ro.disconnect()
-  }, [breadcrumbs])
+    // `homeLabel` renders as text in the measured row, so its width feeds the
+    // same calculation. Now that the breadcrumb array is referentially stable,
+    // a home-label-only change no longer re-measures incidentally.
+  }, [breadcrumbs, homeLabel])
 
   const overflowed = useMemo(() => {
     const visible = new Set(visibleIndices)

package/src/admin-shell/collections/api.tsx

@@ -11,13 +11,28 @@ import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import { useTranslation } from '@byline/i18n/react'
 import { Container, Section } from '@byline/ui/react'
 import cx from 'clsx'
-import { allExpanded, darkStyles, JsonView } from 'react-json-view-lite'
+import { darkStyles, JsonView } from 'react-json-view-lite'
 
 import styles from './api.module.css'
 import { ViewMenu } from './view-menu.js'
 import type { ContentLocaleOption } from './view-menu.js'
 import 'react-json-view-lite/dist/index.css'
 
+/**
+ * Expand the document root and the level below it — the document's own metadata
+ * and the names of its content fields — and leave everything deeper collapsed.
+ *
+ * `react-json-view-lite` does not mount collapsed descendants, so this reduces the
+ * size of the mounted tree rather than merely hiding nodes. A document with rich
+ * text, blocks, several locales and populated relations otherwise mounts thousands
+ * of nodes that the reader has to scroll past before finding anything.
+ *
+ * Declared at module scope so its identity is stable: the viewer treats a new
+ * callback as a reason to re-derive expansion state, which would discard whatever
+ * the reader had opened.
+ */
+const expandToFirstLevel = (level: number): boolean => level < 2
+
 /**
  * JSON inspector view for a collection document.
  *
@@ -64,7 +79,7 @@ export const ApiView = ({
         <div className={cx('byline-api-viewer', styles.viewer)}>
           <JsonView
             data={initialData}
-            shouldExpandNode={allExpanded}
+            shouldExpandNode={expandToFirstLevel}
             style={{ ...darkStyles, container: 'api-json-view' }}
           />
         </div>

package/src/admin-shell/collections/edit.tsx

@@ -37,6 +37,7 @@ import {
   updateDocumentStatus,
 } from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
+import { describeMutationFailure } from '../describe-mutation-failure.js'
 import { useDocumentMutationState } from '../document-mutation-state.js'
 import { useTanStackNavigationGuard } from './tanstack-navigation-guard.js'
 import { ViewMenu } from './view-menu.js'
@@ -430,7 +431,7 @@ export const EditView = ({
       }
       console.error('Duplicate error:', err)
       const description = t('collections.edit.duplicateFailedDescription', {
-        message: t('documentConcurrency.failed'),
+        message: describeMutationFailure(err, t),
       })
       toastManager.add({
         title: t('collections.edit.duplicateTitle', { label: singular }),
@@ -526,7 +527,7 @@ export const EditView = ({
       }
       console.error('Copy to locale error:', err)
       const description = t('collections.edit.copyFailedDescription', {
-        message: t('documentConcurrency.failed'),
+        message: describeMutationFailure(err, t),
       })
       toastManager.add({
         title: t('collections.edit.copyToLocaleTitle', { label: singular }),

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -57,6 +57,18 @@ export function RestoreVersionModal({
     setError(null)
     try {
       const result = await restoreVersion()
+      // Restore is exempt from field validation, so this never blocks it. Name
+      // the fields so the editor understands why the next save is refused.
+      const issues = getRestoreValidationIssues(result)
+      if (issues.length > 0) {
+        toastManager.add({
+          title: t('collections.restore.validationIssuesToast'),
+          description: t('collections.restore.validationIssuesDescription', {
+            fields: issues.join(', '),
+          }),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
       if (hasCommittedDocumentHookFailure(result)) {
         toastManager.add({
           title: t('collections.save.hookFailedToast'),
@@ -146,6 +158,20 @@ export function RestoreVersionModal({
   )
 }
 
+/** Field paths of the restored content that today's validation rejects. */
+function getRestoreValidationIssues(result: unknown): string[] {
+  if (result == null || typeof result !== 'object') return []
+  const issues = (result as { validationIssues?: unknown }).validationIssues
+  if (!Array.isArray(issues)) return []
+  return issues
+    .map((issue) =>
+      issue != null && typeof issue === 'object' && typeof (issue as any).field === 'string'
+        ? (issue as { field: string }).field
+        : ''
+    )
+    .filter((field) => field.length > 0)
+}
+
 function getErrorCode(err: unknown): string | null {
   return typeof (err as { code?: unknown })?.code === 'string'
     ? (err as { code: string }).code

package/src/admin-shell/describe-mutation-failure.ts

@@ -0,0 +1,30 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { getDocumentFieldValidationDetails } from '@byline/core'
+import type { TranslationValues } from '@byline/i18n'
+
+/**
+ * Describe a failed document mutation for the editor.
+ *
+ * Content writes that are not restores — create, update, patch saves,
+ * duplication and locale copies — keep the field-validation gate, because each
+ * reads or authors content the editor can open and correct. Naming the
+ * offending fields is what makes that correction actionable; without it the
+ * editor sees only a generic failure.
+ */
+export function describeMutationFailure(
+  err: unknown,
+  t: (key: string, values?: TranslationValues) => string
+): string {
+  const validation = getDocumentFieldValidationDetails(err)
+  if (validation == null) return t('documentConcurrency.failed')
+  return t('collections.edit.invalidFieldsMessage', {
+    fields: validation.issues.map((issue) => issue.field || '?').join(', '),
+  })
+}

package/src/admin-shell/singletons/view.tsx

@@ -37,6 +37,7 @@ import {
 } from '../../server-fns/singletons/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { useTanStackNavigationGuard } from '../collections/tanstack-navigation-guard.js'
+import { describeMutationFailure } from '../describe-mutation-failure.js'
 import { useDocumentMutationState } from '../document-mutation-state.js'
 import { SingletonViewMenu } from './view-menu.js'
 import type { ContentLocaleOption } from '../collections/view-menu.js'
@@ -287,7 +288,7 @@ export function SingletonView({
       }
       toast(
         t('collections.edit.copyToLocaleTitle', { label }),
-        t('collections.edit.copyFailedDescription', { message: t('documentConcurrency.failed') }),
+        t('collections.edit.copyFailedDescription', { message: describeMutationFailure(err, t) }),
         'danger'
       )
       throw err

package/src/integrations/byline-field-services.test.node.ts

@@ -0,0 +1,129 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { defineAdminConfig } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import {
+  abilityFingerprint,
+  buildBylineFieldServices,
+  bylineFieldServices,
+} from './byline-field-services.js'
+
+// A deliberately non-default admin base: the create URL must come from host
+// configuration, and a hardcoded `/admin` would pass against the usual value.
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  routes: { admin: '/control-panel' },
+  collections: [
+    {
+      path: 'media',
+      labels: { singular: 'Media', plural: 'Media' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+  slugifier: (value: string) => value.toLowerCase().trim().replace(/\s+/g, '-'),
+})
+
+const viewer = (abilities: string[], isSuperAdmin = false) => ({
+  is_super_admin: isSuperAdmin,
+  abilities,
+})
+
+describe('ability fingerprint', () => {
+  /**
+   * An equivalent abilities array should not invalidate the memoised services
+   * object and notify its context consumers.
+   */
+  it('is equal for a different array holding the same abilities', () => {
+    const a = abilityFingerprint(viewer(['collections.media.create', 'collections.media.read']))
+    const b = abilityFingerprint(viewer(['collections.media.create', 'collections.media.read']))
+
+    expect(a).toBe(b)
+  })
+
+  it('changes when an ability is gained or lost', () => {
+    const before = abilityFingerprint(viewer(['collections.media.read']))
+    const after = abilityFingerprint(viewer(['collections.media.read', 'collections.media.create']))
+
+    expect(after).not.toBe(before)
+  })
+
+  it('distinguishes a super-admin from a viewer holding the same listed abilities', () => {
+    const plain = abilityFingerprint(viewer(['collections.media.create']))
+    const superAdmin = abilityFingerprint(viewer(['collections.media.create'], true))
+
+    expect(superAdmin).not.toBe(plain)
+  })
+
+  /**
+   * Ability order is not meaningful and the server does not promise one, so an
+   * order change must not invalidate the memo.
+   */
+  it('ignores the order abilities arrive in', () => {
+    const one = abilityFingerprint(viewer(['a.read', 'b.create']))
+    const other = abilityFingerprint(viewer(['b.create', 'a.read']))
+
+    expect(one).toBe(other)
+  })
+})
+
+describe('field services built for a viewer', () => {
+  it('keeps the existing services intact', () => {
+    const services = buildBylineFieldServices(viewer([]))
+
+    expect(services.getCollectionDocuments).toBe(bylineFieldServices.getCollectionDocuments)
+    expect(services.uploadField).toBe(bylineFieldServices.uploadField)
+    expect(services.placeTreeNode).toBe(bylineFieldServices.placeTreeNode)
+    expect(services.removeFromTree).toBe(bylineFieldServices.removeFromTree)
+    expect(services.getTreeAncestors).toBe(bylineFieldServices.getTreeAncestors)
+    expect(services.getTreeParent).toBe(bylineFieldServices.getTreeParent)
+  })
+
+  it('permits creation only for a collection the viewer may create in', () => {
+    const services = buildBylineFieldServices(viewer(['collections.media.create']))
+
+    expect(services.canCreateInCollection?.('media')).toBe(true)
+    expect(services.canCreateInCollection?.('pages')).toBe(false)
+  })
+
+  /**
+   * Mirrors `useAbility`, which short-circuits for super-admins rather than
+   * enumerating their abilities.
+   */
+  it('permits creation anywhere for a super-admin', () => {
+    const services = buildBylineFieldServices(viewer([], true))
+
+    expect(services.canCreateInCollection?.('media')).toBe(true)
+    expect(services.canCreateInCollection?.('anything')).toBe(true)
+  })
+
+  it('does not treat a read ability as permission to create', () => {
+    const services = buildBylineFieldServices(viewer(['collections.media.read']))
+
+    expect(services.canCreateInCollection?.('media')).toBe(false)
+  })
+
+  /**
+   * Root-relative, from the host's configured admin path. Not absolute: no
+   * origin is available during the server render, and the configured base may
+   * not be `/admin`.
+   */
+  it('builds a root-relative create url from the configured admin path', () => {
+    const services = buildBylineFieldServices(viewer([]))
+    const url = services.getCreateDocumentUrl?.('media')
+
+    expect(url).toBeTruthy()
+    expect(url?.startsWith('/')).toBe(true)
+    expect(url?.startsWith('//')).toBe(false)
+    expect(url).toBe('/control-panel/collections/media/create')
+  })
+})

package/src/integrations/byline-field-services.ts

@@ -18,7 +18,9 @@
 
 import type {
   BylineFieldServices,
+  CanCreateInCollectionFn,
   GetCollectionDocumentsFn,
+  GetCreateDocumentUrlFn,
   GetTreeAncestorsFn,
   GetTreeParentFn,
   PlaceTreeNodeFn,
@@ -26,6 +28,7 @@ import type {
   UploadFieldFn,
 } from '@byline/admin/react'
 
+import { getAdminRoutePath } from '../routes/admin-path.js'
 import { getCollectionDocuments as serverGetCollectionDocuments } from '../server-fns/collections/list.js'
 import {
   getTreeAncestors as serverGetTreeAncestors,
@@ -57,6 +60,9 @@ const getTreeAncestors: GetTreeAncestorsFn = (input) =>
 const getTreeParent: GetTreeParentFn = (input) =>
   serverGetTreeParent({ data: input }) as ReturnType<GetTreeParentFn>
 
+const getCreateDocumentUrl: GetCreateDocumentUrlFn = (collectionPath) =>
+  getAdminRoutePath('collections', collectionPath, 'create')
+
 export const bylineFieldServices: BylineFieldServices = {
   getCollectionDocuments,
   uploadField,
@@ -64,4 +70,35 @@ export const bylineFieldServices: BylineFieldServices = {
   removeFromTree,
   getTreeAncestors,
   getTreeParent,
+  getCreateDocumentUrl,
+}
+
+/** The subset of the admin session the field services need. */
+export interface FieldServicesViewer {
+  is_super_admin: boolean
+  abilities: ReadonlyArray<string>
+}
+
+/**
+ * Content-addressed memo key for the services object.
+ *
+ * Avoids notifying field-service context consumers when the host supplies an
+ * equivalent viewer object or abilities array. Existing service functions retain
+ * their module-level identity even when the containing object is rebuilt.
+ * Ability order is not meaningful, so sort a copy before building the key.
+ */
+export function abilityFingerprint(viewer: FieldServicesViewer): string {
+  if (viewer.is_super_admin) return 'super-admin'
+  return [...viewer.abilities].sort().join(' ')
+}
+
+/**
+ * Field services for one viewer. Call inside `useMemo`, keyed on
+ * `abilityFingerprint(viewer)`.
+ */
+export function buildBylineFieldServices(viewer: FieldServicesViewer): BylineFieldServices {
+  const canCreateInCollection: CanCreateInCollectionFn = (collectionPath) =>
+    viewer.is_super_admin || viewer.abilities.includes(`collections.${collectionPath}.create`)
+
+  return { ...bylineFieldServices, canCreateInCollection }
 }