@byline/host-tanstack-start 6.2.0 → 6.3.0

package/dist/admin-shell/chrome/breadcrumbs/breadcrumbs-provider.js

@@ -1,16 +1,27 @@
 import { jsx } from "react/jsx-runtime";
-import { createContext, useContext, useState } from "react";
+import { createContext, useCallback, useContext, useState } from "react";
 const BreadcrumbsContext = /*#__PURE__*/ createContext(void 0);
+function sameBreadcrumbs(a, b) {
+    if (a === b) return true;
+    if (a.length !== b.length) return false;
+    return a.every((crumb, index)=>crumb.label === b[index].label && crumb.href === b[index].href && crumb.active === b[index].active);
+}
+function sameSettings(a, b) {
+    return a.homeLabel === b.homeLabel && a.homePath === b.homePath && sameBreadcrumbs(a.breadcrumbs, b.breadcrumbs);
+}
 function BreadcrumbsProvider({ children }) {
     const [breadcrumbSettings, setBreadcrumbSettings] = useState({
         homeLabel: 'Home',
         homePath: '/',
         breadcrumbs: []
     });
+    const setBreadcrumbs = useCallback((settings)=>{
+        setBreadcrumbSettings((previous)=>sameSettings(previous, settings) ? previous : settings);
+    }, []);
     return /*#__PURE__*/ jsx(BreadcrumbsContext, {
         value: {
             breadCrumbSettings: breadcrumbSettings,
-            setBreadcrumbs: setBreadcrumbSettings
+            setBreadcrumbs
         },
         children: children
     });

package/dist/admin-shell/chrome/breadcrumbs/breadcrumbs.js

@@ -18,11 +18,6 @@ function Breadcrumbs({ breadcrumbs, className, homeLabel = 'Home', homePath = '/
     const navRef = useRef(null);
     const measureRef = useRef(null);
     const [visibleIndices, setVisibleIndices] = useState(()=>breadcrumbs.map((_, i)=>i));
-    useIsoLayoutEffect(()=>{
-        setVisibleIndices(breadcrumbs.map((_, i)=>i));
-    }, [
-        breadcrumbs
-    ]);
     useIsoLayoutEffect(()=>{
         const nav = navRef.current;
         const measure = measureRef.current;
@@ -71,7 +66,8 @@ function Breadcrumbs({ breadcrumbs, className, homeLabel = 'Home', homePath = '/
         ro.observe(nav);
         return ()=>ro.disconnect();
     }, [
-        breadcrumbs
+        breadcrumbs,
+        homeLabel
     ]);
     const overflowed = useMemo(()=>{
         const visible = new Set(visibleIndices);

package/dist/admin-shell/chrome/breadcrumbs/breadcrumbs.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/admin-shell/collections/api.js

@@ -2,10 +2,11 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useTranslation } from "@byline/i18n/react";
 import { Container, Section } from "@byline/ui/react";
 import clsx from "clsx";
-import { JsonView, allExpanded, darkStyles } from "react-json-view-lite";
+import { JsonView, darkStyles } from "react-json-view-lite";
 import api_module from "./api.module.js";
 import { ViewMenu } from "./view-menu.js";
 import "react-json-view-lite/dist/index.css";
+const expandToFirstLevel = (level)=>level < 2;
 const ApiView = ({ collectionDefinition, initialData, locale, depth, contentLocales, defaultContentLocale })=>{
     const { labels, path } = collectionDefinition;
     const { t } = useTranslation('byline-admin');
@@ -38,7 +39,7 @@ const ApiView = ({ collectionDefinition, initialData, locale, depth, contentLoca
                     className: clsx('byline-api-viewer', api_module.viewer),
                     children: /*#__PURE__*/ jsx(JsonView, {
                         data: initialData,
-                        shouldExpandNode: allExpanded,
+                        shouldExpandNode: expandToFirstLevel,
                         style: {
                             ...darkStyles,
                             container: 'api-json-view'

package/dist/integrations/byline-field-services.d.ts

@@ -16,3 +16,22 @@
  */
 import type { BylineFieldServices } from '@byline/admin/react';
 export declare const bylineFieldServices: BylineFieldServices;
+/** 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 declare function abilityFingerprint(viewer: FieldServicesViewer): string;
+/**
+ * Field services for one viewer. Call inside `useMemo`, keyed on
+ * `abilityFingerprint(viewer)`.
+ */
+export declare function buildBylineFieldServices(viewer: FieldServicesViewer): BylineFieldServices;

package/dist/integrations/byline-field-services.js

@@ -1,3 +1,4 @@
+import { getAdminRoutePath } from "../routes/admin-path.js";
 import { getCollectionDocuments } from "../server-fns/collections/list.js";
 import { getTreeAncestors, getTreeParent, placeTreeNode, removeFromTree } from "../server-fns/collections/tree.js";
 import { uploadField } from "../server-fns/collections/upload.js";
@@ -20,12 +21,27 @@ const byline_field_services_getTreeAncestors = (input)=>getTreeAncestors({
 const byline_field_services_getTreeParent = (input)=>getTreeParent({
         data: input
     });
+const getCreateDocumentUrl = (collectionPath)=>getAdminRoutePath('collections', collectionPath, 'create');
 const bylineFieldServices = {
     getCollectionDocuments: byline_field_services_getCollectionDocuments,
     uploadField: byline_field_services_uploadField,
     placeTreeNode: byline_field_services_placeTreeNode,
     removeFromTree: byline_field_services_removeFromTree,
     getTreeAncestors: byline_field_services_getTreeAncestors,
-    getTreeParent: byline_field_services_getTreeParent
+    getTreeParent: byline_field_services_getTreeParent,
+    getCreateDocumentUrl: getCreateDocumentUrl
 };
-export { bylineFieldServices };
+function abilityFingerprint(viewer) {
+    if (viewer.is_super_admin) return 'super-admin';
+    return [
+        ...viewer.abilities
+    ].sort().join(' ');
+}
+function buildBylineFieldServices(viewer) {
+    const canCreateInCollection = (collectionPath)=>viewer.is_super_admin || viewer.abilities.includes(`collections.${collectionPath}.create`);
+    return {
+        ...bylineFieldServices,
+        canCreateInCollection
+    };
+}
+export { abilityFingerprint, buildBylineFieldServices, bylineFieldServices };

package/dist/routes/create-admin-layout-route.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
 import { Outlet, createFileRoute } from "@tanstack/react-router";
 import { applyStoredTheme } from "@byline/admin/admin-account/components/theme";
 import { BylineFieldServicesProvider } from "@byline/admin/react";
@@ -18,7 +18,7 @@ import { SessionChangeBoundary } from "../admin-shell/chrome/session-change-boun
 import { buildLocaleDefinitions } from "../i18n/locale-definitions.js";
 import { bylineAdminServices } from "../integrations/byline-admin-services.js";
 import { BylineAiAdminProvider } from "../integrations/byline-ai.js";
-import { bylineFieldServices } from "../integrations/byline-field-services.js";
+import { abilityFingerprint, buildBylineFieldServices } from "../integrations/byline-field-services.js";
 import { observeSession, sessionIsChanged } from "../integrations/session-coordination.js";
 import { renewExpectedSession } from "../integrations/session-renewal.js";
 import { getAnalyticsRuntime } from "../server-fns/analytics/index.js";
@@ -58,6 +58,9 @@ function createAdminLayoutRoute(path) {
             useEffect(()=>{
                 applyStoredTheme();
             }, []);
+            const fieldServices = useMemo(()=>buildBylineFieldServices(user), [
+                abilityFingerprint(user)
+            ]);
             const handleSetLocale = async (next)=>{
                 await setAdminLocaleFn({
                     data: {
@@ -77,7 +80,7 @@ function createAdminLayoutRoute(path) {
                     children: /*#__PURE__*/ jsx(BylineAdminServicesProvider, {
                         services: bylineAdminServices,
                         children: /*#__PURE__*/ jsx(BylineFieldServicesProvider, {
-                            services: bylineFieldServices,
+                            services: fieldServices,
                             children: /*#__PURE__*/ jsx(BylineAiAdminProvider, {
                                 children: /*#__PURE__*/ jsxs(AdminMenuProvider, {
                                     children: [

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -125,15 +125,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.6.2",
-    "@byline/admin": "6.2.0",
-    "@byline/analytics": "6.2.0",
-    "@byline/auth": "6.2.0",
-    "@byline/ai": "6.2.0",
-    "@byline/client": "6.2.0",
-    "@byline/core": "6.2.0",
-    "@byline/analytics-agent": "6.2.0",
-    "@byline/i18n": "6.2.0",
-    "@byline/ui": "6.2.0"
+    "@byline/admin": "6.3.0",
+    "@byline/analytics": "6.3.0",
+    "@byline/analytics-agent": "6.3.0",
+    "@byline/ai": "6.3.0",
+    "@byline/client": "6.3.0",
+    "@byline/auth": "6.3.0",
+    "@byline/i18n": "6.3.0",
+    "@byline/ui": "6.3.0",
+    "@byline/core": "6.3.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

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

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import { createContext, type ReactNode, useContext, useState } from 'react'
+import { createContext, type ReactNode, useCallback, useContext, useState } from 'react'
 
 import type { Breadcrumb } from './@types.js'
 
@@ -23,6 +23,32 @@ interface BreadcrumbsContextType {
 
 const BreadcrumbsContext = createContext<BreadcrumbsContextType | undefined>(undefined)
 
+/**
+ * Route components build their breadcrumb trail from an inline array literal,
+ * so every render submits a new array that is almost always value-identical to
+ * the last one. Comparing by value lets the provider hand back the previous
+ * state, which keeps the array reference — and therefore the measurement
+ * effect in `Breadcrumbs` — stable across unrelated renders.
+ */
+function sameBreadcrumbs(a: Breadcrumb[], b: Breadcrumb[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  return a.every(
+    (crumb, index) =>
+      crumb.label === b[index].label &&
+      crumb.href === b[index].href &&
+      crumb.active === b[index].active
+  )
+}
+
+function sameSettings(a: BreadcrumbsSettings, b: BreadcrumbsSettings): boolean {
+  return (
+    a.homeLabel === b.homeLabel &&
+    a.homePath === b.homePath &&
+    sameBreadcrumbs(a.breadcrumbs, b.breadcrumbs)
+  )
+}
+
 export function BreadcrumbsProvider({ children }: { children: ReactNode }) {
   const [breadcrumbSettings, setBreadcrumbSettings] = useState<BreadcrumbsSettings>({
     homeLabel: 'Home',
@@ -30,10 +56,14 @@ export function BreadcrumbsProvider({ children }: { children: ReactNode }) {
     breadcrumbs: [],
   })
 
+  // `BreadcrumbsClient` lists this setter in its effect dependencies, so it
+  // has to stay referentially stable or the effect refires on every render.
+  const setBreadcrumbs = useCallback((settings: BreadcrumbsSettings) => {
+    setBreadcrumbSettings((previous) => (sameSettings(previous, settings) ? previous : settings))
+  }, [])
+
   return (
-    <BreadcrumbsContext
-      value={{ breadCrumbSettings: breadcrumbSettings, setBreadcrumbs: setBreadcrumbSettings }}
-    >
+    <BreadcrumbsContext value={{ breadCrumbSettings: breadcrumbSettings, setBreadcrumbs }}>
       {children}
     </BreadcrumbsContext>
   )

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/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 }
 }

package/src/routes/create-admin-layout-route.tsx

@@ -21,7 +21,7 @@
  * route (and the `AdminAppBar`) can read it without an extra fetch.
  */
 
-import { useEffect } from 'react'
+import { useEffect, useMemo } from 'react'
 import { createFileRoute, Outlet } from '@tanstack/react-router'
 
 import { applyStoredTheme } from '@byline/admin/admin-account/components/theme'
@@ -43,7 +43,10 @@ import { SessionChangeBoundary } from '../admin-shell/chrome/session-change-boun
 import { buildLocaleDefinitions } from '../i18n/locale-definitions.js'
 import { bylineAdminServices } from '../integrations/byline-admin-services.js'
 import { BylineAiAdminProvider } from '../integrations/byline-ai.js'
-import { bylineFieldServices } from '../integrations/byline-field-services.js'
+import {
+  abilityFingerprint,
+  buildBylineFieldServices,
+} from '../integrations/byline-field-services.js'
 import { observeSession, sessionIsChanged } from '../integrations/session-coordination.js'
 import { renewExpectedSession } from '../integrations/session-renewal.js'
 import { getAnalyticsRuntime } from '../server-fns/analytics/index.js'
@@ -99,9 +102,17 @@ export function createAdminLayoutRoute(path: string) {
       useEffect(() => {
         applyStoredTheme()
       }, [])
-      // Cookie + DB write happen in setAdminLocaleFn; full reload
-      // re-runs beforeLoad so the provider re-renders with the new
-      // bundle/locale (no in-place bundle swap needed for PR 1's scope).
+      // Composed here rather than imported as a constant because the create
+      // affordance depends on the viewer's abilities, which only exist in route
+      // context. Keying on ability content avoids notifying context consumers
+      // when route context supplies an equivalent user object or abilities array.
+      // biome-ignore lint/correctness/useExhaustiveDependencies: see above
+      const fieldServices = useMemo(
+        () => buildBylineFieldServices(user),
+        [abilityFingerprint(user)]
+      )
+
+      // The full reload re-runs beforeLoad with the saved locale and its bundle.
       const handleSetLocale = async (next: LocaleCode) => {
         await setAdminLocaleFn({ data: { locale: next } })
         window.location.reload()
@@ -116,7 +127,7 @@ export function createAdminLayoutRoute(path: string) {
             setLocale={handleSetLocale}
           >
             <BylineAdminServicesProvider services={bylineAdminServices}>
-              <BylineFieldServicesProvider services={bylineFieldServices}>
+              <BylineFieldServicesProvider services={fieldServices}>
                 <BylineAiAdminProvider>
                   <AdminMenuProvider>
                     <RouteProgressBar />