@byline/host-tanstack-start 3.13.3 → 3.15.0

package/dist/admin-shell/collections/list.d.ts

@@ -5,14 +5,15 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { ColumnDefinition, WorkflowStatus } from '@byline/core';
+import type React from 'react';
+import type { ColumnDefinition, ListActionComponentProps, WorkflowStatus } from '@byline/core';
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas';
 type ReorderFn = (params: {
     documentId: string;
     beforeDocumentId: string | null;
     afterDocumentId: string | null;
 }) => Promise<unknown>;
-export declare const ListView: ({ data, columns, workflowStatuses, useAsTitle, orderable, onReorder, }: {
+export declare const ListView: ({ data, columns, workflowStatuses, useAsTitle, orderable, onReorder, listActions, }: {
     data: AnyCollectionSchemaTypes["ListType"];
     columns: ColumnDefinition[];
     workflowStatuses?: WorkflowStatus[];
@@ -21,5 +22,7 @@ export declare const ListView: ({ data, columns, workflowStatuses, useAsTitle, o
     orderable?: boolean;
     /** Persists a single-row reorder via the host's reorder server fn. */
     onReorder?: ReorderFn;
-}) => import("react").JSX.Element;
+    /** Header action components (`CollectionAdminConfig.listActions`). */
+    listActions?: Array<(props: ListActionComponentProps) => React.ReactNode>;
+}) => React.JSX.Element;
 export {};

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

@@ -70,7 +70,7 @@ function SortableTableRow({ id, disabled, t, children }) {
         ]
     });
 }
-const ListView = ({ data, columns, workflowStatuses, useAsTitle, orderable = false, onReorder })=>{
+const ListView = ({ data, columns, workflowStatuses, useAsTitle, orderable = false, onReorder, listActions })=>{
     const navigate = useNavigate();
     const router = useRouter();
     const toastManager = useToastManager();
@@ -215,6 +215,9 @@ const ListView = ({ data, columns, workflowStatuses, useAsTitle, orderable = fal
                         /*#__PURE__*/ jsx(Stats, {
                             total: data?.meta.total
                         }),
+                        listActions?.map((Action, i)=>/*#__PURE__*/ jsx(Action, {
+                                collectionPath: data.included.collection.path
+                            }, i)),
                         /*#__PURE__*/ jsx(IconButton, {
                             "aria-label": t('collections.list.createAriaLabel'),
                             render: /*#__PURE__*/ jsx(Link, {

package/dist/admin-shell/collections/reindex-button.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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
+ */
+/**
+ * A `CollectionAdminConfig.listActions` component that rebuilds a collection's
+ * search index. Register it on a searchable collection's admin config:
+ *
+ * ```ts
+ * import { ReindexButton } from '@byline/host-tanstack-start/admin-shell/collections/reindex-button'
+ * // CollectionAdminConfig:
+ * listActions: [ReindexButton],
+ * ```
+ *
+ * Permission-gated both ends: hidden unless the actor holds
+ * `collections.<path>.reindex` (the same ability the server fn re-asserts).
+ * Synchronous — fine for small/medium collections; a large corpus wants a
+ * backgrounded job (see docs/05-reading-and-delivery/07-search.md).
+ */
+import type React from 'react';
+import type { ListActionComponentProps } from '@byline/core';
+export declare function ReindexButton({ collectionPath, }: ListActionComponentProps): React.JSX.Element | null;

package/dist/admin-shell/collections/reindex-button.js

@@ -0,0 +1,55 @@
+import { jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { useTranslation } from "@byline/i18n/react";
+import { Button, useToastManager } from "@byline/ui/react";
+import { useAbility } from "../../integrations/abilities.js";
+import { reindexCollection } from "../../server-fns/collections/reindex.js";
+function ReindexButton({ collectionPath }) {
+    const { t } = useTranslation('byline-admin');
+    const toastManager = useToastManager();
+    const canReindex = useAbility(`collections.${collectionPath}.reindex`);
+    const [pending, setPending] = useState(false);
+    if (!canReindex) return null;
+    const onClick = async ()=>{
+        setPending(true);
+        try {
+            const report = await reindexCollection({
+                data: {
+                    collection: collectionPath
+                }
+            });
+            toastManager.add({
+                title: t('collections.list.reindexDoneTitle'),
+                description: t("collections.list.reindexDoneDescription", {
+                    count: report.documents
+                }),
+                data: {
+                    intent: 'success',
+                    iconType: 'success',
+                    icon: true,
+                    close: true
+                }
+            });
+        } catch  {
+            toastManager.add({
+                title: t('collections.list.reindexFailedTitle'),
+                data: {
+                    intent: 'danger',
+                    iconType: 'danger',
+                    icon: true,
+                    close: true
+                }
+            });
+        } finally{
+            setPending(false);
+        }
+    };
+    return /*#__PURE__*/ jsx(Button, {
+        size: "sm",
+        variant: "outlined",
+        disabled: pending,
+        onClick: onClick,
+        children: pending ? t('collections.list.reindexPending') : t('collections.list.reindexLabel')
+    });
+}
+export { ReindexButton };

package/dist/admin-shell/collections/tree-list.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type React from 'react';
-import type { ColumnDefinition, WorkflowStatus } from '@byline/core';
+import type { ColumnDefinition, ListActionComponentProps, WorkflowStatus } from '@byline/core';
 import type { CollectionTreeRow } from '../../server-fns/collections/tree.js';
 export type TreeMoveFn = (params: {
     documentId: string;
@@ -14,7 +14,7 @@ export type TreeMoveFn = (params: {
     beforeDocumentId: string | null;
     afterDocumentId: string | null;
 }) => Promise<unknown>;
-export declare const TreeListView: ({ rows, columns, workflowStatuses, useAsTitle, collection, collectionLabels, onMove, }: {
+export declare const TreeListView: ({ rows, columns, workflowStatuses, useAsTitle, collection, collectionLabels, onMove, listActions, }: {
     rows: CollectionTreeRow[];
     columns: ColumnDefinition[];
     workflowStatuses?: WorkflowStatus[];
@@ -26,4 +26,6 @@ export declare const TreeListView: ({ rows, columns, workflowStatuses, useAsTitl
     };
     /** When provided, the placed tree becomes drag-to-reorder / re-parent. */
     onMove?: TreeMoveFn;
+    /** Header action components (`CollectionAdminConfig.listActions`). */
+    listActions?: Array<(props: ListActionComponentProps) => React.ReactNode>;
 }) => React.JSX.Element;

package/dist/admin-shell/collections/tree-list.js

@@ -50,7 +50,7 @@ function SortableTreeRow({ id, depth, dragging, dragHandleLabel, children }) {
         ]
     });
 }
-const TreeListView = ({ rows, columns, workflowStatuses, useAsTitle, collection, collectionLabels, onMove })=>{
+const TreeListView = ({ rows, columns, workflowStatuses, useAsTitle, collection, collectionLabels, onMove, listActions })=>{
     const { t } = useTranslation('byline-admin');
     const router = useRouter();
     const toastManager = useToastManager();
@@ -177,6 +177,9 @@ const TreeListView = ({ rows, columns, workflowStatuses, useAsTitle, collection,
                             className: classnames('byline-coll-list-stats', tree_list_module.stats),
                             children: formatNumber(rows.length, 0)
                         }),
+                        listActions?.map((Action, i)=>/*#__PURE__*/ jsx(Action, {
+                                collectionPath: collection
+                            }, i)),
                         /*#__PURE__*/ jsx(IconButton, {
                             "aria-label": t('collections.list.createAriaLabel'),
                             render: /*#__PURE__*/ jsx(Link, {

package/dist/integrations/byline-client.d.ts

@@ -5,17 +5,20 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { type BylineClient } from '@byline/client';
+export declare function getAdminBylineClient(): BylineClient;
 /**
- * The admin webapp's `BylineClient` singleton.
+ * A `BylineClient` bound to an explicit super-admin context — for
+ * **system / background** work that is not scoped to an HTTP request:
+ * lifecycle-hook search indexing, maintenance scripts, seeds, migrations.
  *
- * Configured with a `requestContext` factory that resolves the
- * authenticated admin actor per call via `getAdminRequestContext`. Every
- * admin server fn that reads documents goes through this client, so the
- * full read pipeline (`beforeRead` → `findDocuments` → `populate` →
- * `afterRead`) is uniform between admin and any future external
- * client. The collection runtime, db adapter, and storage provider are
- * sourced from the shared `getServerConfig()` so we don't duplicate
- * adapter wiring.
+ * Unlike {@link getAdminBylineClient}, this does **not** read session
+ * cookies, so it works outside the TanStack Start server runtime (a bare
+ * `tsx` script, a seed, a test). Reaching for the request-scoped client in
+ * a lifecycle hook couples that hook to the live server and throws
+ * `No StartEvent found in AsyncLocalStorage` from any out-of-band write
+ * path. Indexing is maintenance, not a user action — it reads the published
+ * view and bypasses `beforeRead` — so the super-admin context is both
+ * correct and runtime-agnostic. The context is auditable by its stable id.
  */
-import { type BylineClient } from '@byline/client';
-export declare function getAdminBylineClient(): BylineClient;
+export declare function getSystemBylineClient(): BylineClient;

package/dist/integrations/byline-client.js

@@ -1,3 +1,4 @@
+import { createSuperAdminContext } from "@byline/auth";
 import { createBylineClient } from "@byline/client";
 import { getServerConfig } from "@byline/core";
 import { getAdminRequestContext } from "../auth/auth-context.js";
@@ -10,4 +11,15 @@ function getAdminBylineClient() {
     });
     return cachedClient;
 }
-export { getAdminBylineClient };
+let cachedSystemClient;
+function getSystemBylineClient() {
+    if (cachedSystemClient) return cachedSystemClient;
+    cachedSystemClient = createBylineClient({
+        config: getServerConfig(),
+        requestContext: createSuperAdminContext({
+            id: 'byline-system-client'
+        })
+    });
+    return cachedSystemClient;
+}
+export { getAdminBylineClient, getSystemBylineClient };

package/dist/routes/create-collection-list-route.js

@@ -1,6 +1,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { createFileRoute, notFound } from "@tanstack/react-router";
+import { applyRelationColumnFormatters } from "@byline/admin/react";
 import { getCollectionAdminConfig, getCollectionDefinition, getWorkflowStatuses } from "@byline/core";
 import { useTranslation } from "@byline/i18n/react";
 import { useToastManager } from "@byline/ui/react";
@@ -71,7 +72,7 @@ function createCollectionListRoute(path) {
             const navigate = useNavigate();
             const collectionDef = getCollectionDefinition(collection);
             const adminConfig = getCollectionAdminConfig(collection);
-            const columns = adminConfig?.columns || [];
+            const columns = applyRelationColumnFormatters(adminConfig?.columns || [], collectionDef);
             const workflowStatuses = getWorkflowStatuses(collectionDef);
             const createdToastFiredRef = useRef(false);
             useEffect(()=>{
@@ -132,6 +133,7 @@ function createCollectionListRoute(path) {
                         useAsTitle: collectionDef.useAsTitle,
                         collection: collection,
                         collectionLabels: data.included.collection.labels,
+                        listActions: adminConfig?.listActions,
                         onMove: async ({ documentId, parentDocumentId, beforeDocumentId, afterDocumentId })=>{
                             await placeTreeNode({
                                 data: {
@@ -152,6 +154,7 @@ function createCollectionListRoute(path) {
                         workflowStatuses: workflowStatuses,
                         useAsTitle: collectionDef.useAsTitle,
                         orderable: true === collectionDef.orderable,
+                        listActions: adminConfig?.listActions,
                         onReorder: async ({ documentId, beforeDocumentId, afterDocumentId })=>{
                             await reorderCollectionDocument({
                                 data: {

package/dist/server-fns/collections/index.d.ts

@@ -13,6 +13,7 @@ export * from './duplicate';
 export * from './get';
 export * from './history';
 export * from './list';
+export * from './reindex';
 export * from './reorder';
 export * from './restore-version';
 export * from './stats';

package/dist/server-fns/collections/index.js

@@ -7,6 +7,7 @@ export * from "./duplicate.js";
 export * from "./get.js";
 export * from "./history.js";
 export * from "./list.js";
+export * from "./reindex.js";
 export * from "./reorder.js";
 export * from "./restore-version.js";
 export * from "./stats.js";

package/dist/server-fns/collections/list.js

@@ -1,5 +1,5 @@
 import { createServerFn } from "@tanstack/react-start";
-import { ERR_NOT_FOUND, getCollectionSchemasForPath, getLogger, getServerConfig } from "@byline/core";
+import { ERR_NOT_FOUND, buildRelationSummaryPopulateMap, getCollectionAdminConfig, getCollectionDefinition, getCollectionSchemasForPath, getLogger, getServerConfig } from "@byline/core";
 import { ensureCollection } from "../../integrations/api-utils.js";
 import { getAdminBylineClient } from "../../integrations/byline-client.js";
 import { serialise } from "./utils.js";
@@ -26,6 +26,12 @@ const getCollectionDocuments = createServerFn({
     const sortSpec = params.order ? {
         [params.order]: false === params.desc ? 'asc' : 'desc'
     } : defaultSort;
+    const populateMap = buildRelationSummaryPopulateMap(config.definition.fields, (targetPath)=>({
+            def: getCollectionDefinition(targetPath),
+            admin: getCollectionAdminConfig(targetPath)
+        }));
+    const hasRelations = Object.keys(populateMap).length > 0;
+    const populate = hasRelations ? populateMap : void 0;
     const result = await handle.find({
         where: Object.keys(where).length > 0 ? where : void 0,
         sort: sortSpec,
@@ -33,6 +39,8 @@ const getCollectionDocuments = createServerFn({
         page: params.page,
         pageSize,
         select: params.fields,
+        populate,
+        depth: hasRelations ? 1 : void 0,
         status: 'any',
         onMissingLocale: 'empty'
     });
@@ -65,6 +73,7 @@ const getCollectionDocuments = createServerFn({
     };
     const serialised = serialise(response);
     const { list } = getCollectionSchemasForPath(path);
+    if (hasRelations) return serialised;
     return list.parse(serialised);
 });
 export { getCollectionDocuments };

package/dist/server-fns/collections/reindex.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type { ReindexResult } from '@byline/client';
+export type { ReindexResult };
+export declare const reindexCollection: import("@tanstack/react-start").RequiredFetcher<undefined, (input: {
+    collection: string;
+}) => {
+    collection: string;
+}, Promise<ReindexResult>>;

package/dist/server-fns/collections/reindex.js

@@ -0,0 +1,18 @@
+import { createServerFn } from "@tanstack/react-start";
+import { ERR_NOT_FOUND, getLogger } from "@byline/core";
+import { ensureCollection } from "../../integrations/api-utils.js";
+import { getAdminBylineClient } from "../../integrations/byline-client.js";
+const reindexCollection = createServerFn({
+    method: 'POST'
+}).validator((input)=>input).handler(async ({ data })=>{
+    const { collection } = data;
+    const config = await ensureCollection(collection);
+    if (!config) throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: {
+            collectionPath: collection
+        }
+    }).log(getLogger());
+    return getAdminBylineClient().collection(collection).reindex();
+});
+export { reindexCollection };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "3.13.3",
+  "version": "3.15.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -119,13 +119,13 @@
     "react-swipeable": "^7.0.2",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/i18n": "3.13.3",
-    "@byline/ai": "3.13.3",
-    "@byline/admin": "3.13.3",
-    "@byline/client": "3.13.3",
-    "@byline/auth": "3.13.3",
-    "@byline/ui": "3.13.3",
-    "@byline/core": "3.13.3"
+    "@byline/admin": "3.15.0",
+    "@byline/auth": "3.15.0",
+    "@byline/ai": "3.15.0",
+    "@byline/i18n": "3.15.0",
+    "@byline/client": "3.15.0",
+    "@byline/core": "3.15.0",
+    "@byline/ui": "3.15.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

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

@@ -6,11 +6,12 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import type React from 'react'
 import { useEffect, useMemo, useState } from 'react'
 import { useRouter, useRouterState } from '@tanstack/react-router'
 
 import { renderFormatted, StatusBadge } from '@byline/admin/react'
-import type { ColumnDefinition, WorkflowStatus } from '@byline/core'
+import type { ColumnDefinition, ListActionComponentProps, WorkflowStatus } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import type { UseTranslationReturn } from '@byline/i18n/react'
 import { useTranslation } from '@byline/i18n/react'
@@ -158,6 +159,7 @@ export const ListView = ({
   useAsTitle,
   orderable = false,
   onReorder,
+  listActions,
 }: {
   data: AnyCollectionSchemaTypes['ListType']
   columns: ColumnDefinition[]
@@ -167,6 +169,8 @@ export const ListView = ({
   orderable?: boolean
   /** Persists a single-row reorder via the host's reorder server fn. */
   onReorder?: ReorderFn
+  /** Header action components (`CollectionAdminConfig.listActions`). */
+  listActions?: Array<(props: ListActionComponentProps) => React.ReactNode>
 }) => {
   const navigate = useNavigate()
   const router = useRouter()
@@ -316,6 +320,10 @@ export const ListView = ({
             {data.included.collection.labels.plural as string}
           </h1>
           <Stats total={data?.meta.total} />
+          {listActions?.map((Action, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: static config order
+            <Action key={i} collectionPath={data.included.collection.path as string} />
+          ))}
           <IconButton
             aria-label={t('collections.list.createAriaLabel')}
             render={

package/src/admin-shell/collections/reindex-button.tsx

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+
+/**
+ * A `CollectionAdminConfig.listActions` component that rebuilds a collection's
+ * search index. Register it on a searchable collection's admin config:
+ *
+ * ```ts
+ * import { ReindexButton } from '@byline/host-tanstack-start/admin-shell/collections/reindex-button'
+ * // CollectionAdminConfig:
+ * listActions: [ReindexButton],
+ * ```
+ *
+ * Permission-gated both ends: hidden unless the actor holds
+ * `collections.<path>.reindex` (the same ability the server fn re-asserts).
+ * Synchronous — fine for small/medium collections; a large corpus wants a
+ * backgrounded job (see docs/05-reading-and-delivery/07-search.md).
+ */
+
+import type React from 'react'
+import { useState } from 'react'
+
+import type { ListActionComponentProps } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Button, useToastManager } from '@byline/ui/react'
+
+import { useAbility } from '../../integrations/abilities.js'
+import { reindexCollection } from '../../server-fns/collections/reindex.js'
+
+export function ReindexButton({
+  collectionPath,
+}: ListActionComponentProps): React.JSX.Element | null {
+  const { t } = useTranslation('byline-admin')
+  const toastManager = useToastManager()
+  const canReindex = useAbility(`collections.${collectionPath}.reindex`)
+  const [pending, setPending] = useState(false)
+
+  if (!canReindex) return null
+
+  const onClick = async (): Promise<void> => {
+    setPending(true)
+    try {
+      const report = await reindexCollection({ data: { collection: collectionPath } })
+      toastManager.add({
+        title: t('collections.list.reindexDoneTitle'),
+        description: t('collections.list.reindexDoneDescription', { count: report.documents }),
+        data: { intent: 'success', iconType: 'success', icon: true, close: true },
+      })
+    } catch {
+      toastManager.add({
+        title: t('collections.list.reindexFailedTitle'),
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    } finally {
+      setPending(false)
+    }
+  }
+
+  return (
+    <Button size="sm" variant="outlined" disabled={pending} onClick={onClick}>
+      {pending ? t('collections.list.reindexPending') : t('collections.list.reindexLabel')}
+    </Button>
+  )
+}

package/src/admin-shell/collections/tree-list.tsx

@@ -11,7 +11,7 @@ import { useEffect, useMemo, useState } from 'react'
 import { useRouter } from '@tanstack/react-router'
 
 import { renderFormatted, StatusBadge } from '@byline/admin/react'
-import type { ColumnDefinition, WorkflowStatus } from '@byline/core'
+import type { ColumnDefinition, ListActionComponentProps, WorkflowStatus } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import {
   Container,
@@ -124,6 +124,7 @@ export const TreeListView = ({
   collection,
   collectionLabels,
   onMove,
+  listActions,
 }: {
   rows: CollectionTreeRow[]
   columns: ColumnDefinition[]
@@ -133,6 +134,8 @@ export const TreeListView = ({
   collectionLabels: { singular: string; plural: string }
   /** When provided, the placed tree becomes drag-to-reorder / re-parent. */
   onMove?: TreeMoveFn
+  /** Header action components (`CollectionAdminConfig.listActions`). */
+  listActions?: Array<(props: ListActionComponentProps) => React.ReactNode>
 }) => {
   const { t } = useTranslation('byline-admin')
   const router = useRouter()
@@ -267,6 +270,10 @@ export const TreeListView = ({
           <span className={cx('byline-coll-list-stats', styles.stats)}>
             {formatNumber(rows.length, 0)}
           </span>
+          {listActions?.map((Action, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: static config order
+            <Action key={i} collectionPath={collection} />
+          ))}
           <IconButton
             aria-label={t('collections.list.createAriaLabel')}
             render={

package/src/integrations/byline-client.ts

@@ -19,6 +19,7 @@
  * adapter wiring.
  */
 
+import { createSuperAdminContext } from '@byline/auth'
 import { type BylineClient, createBylineClient } from '@byline/client'
 import { getServerConfig } from '@byline/core'
 
@@ -38,3 +39,28 @@ export function getAdminBylineClient(): BylineClient {
   })
   return cachedClient
 }
+
+let cachedSystemClient: BylineClient | undefined
+
+/**
+ * A `BylineClient` bound to an explicit super-admin context — for
+ * **system / background** work that is not scoped to an HTTP request:
+ * lifecycle-hook search indexing, maintenance scripts, seeds, migrations.
+ *
+ * Unlike {@link getAdminBylineClient}, this does **not** read session
+ * cookies, so it works outside the TanStack Start server runtime (a bare
+ * `tsx` script, a seed, a test). Reaching for the request-scoped client in
+ * a lifecycle hook couples that hook to the live server and throws
+ * `No StartEvent found in AsyncLocalStorage` from any out-of-band write
+ * path. Indexing is maintenance, not a user action — it reads the published
+ * view and bypasses `beforeRead` — so the super-admin context is both
+ * correct and runtime-agnostic. The context is auditable by its stable id.
+ */
+export function getSystemBylineClient(): BylineClient {
+  if (cachedSystemClient) return cachedSystemClient
+  cachedSystemClient = createBylineClient({
+    config: getServerConfig(),
+    requestContext: createSuperAdminContext({ id: 'byline-system-client' }),
+  })
+  return cachedSystemClient
+}

package/src/routes/create-collection-edit-route.tsx

@@ -54,7 +54,7 @@ export function createCollectionEditRoute(path: string, opts: CollectionEditOpts
       // Auto-populate direct relation fields (depth 1) so the edit form's
       // relation-summary tiles render with target data (category name, media
       // thumbnail, etc.) on first paint. Projection is derived from each
-      // target's `CollectionAdminConfig.picker` columns.
+      // target's `CollectionAdminConfig.itemView` columns.
       const data = await getCollectionDocument(
         params.collection,
         params.id,

package/src/routes/create-collection-list-route.tsx

@@ -9,6 +9,7 @@
 import { useEffect, useRef } from 'react'
 import { createFileRoute, notFound } from '@tanstack/react-router'
 
+import { applyRelationColumnFormatters } from '@byline/admin/react'
 import type { CollectionDefinition } from '@byline/core'
 import {
   getCollectionAdminConfig,
@@ -118,7 +119,10 @@ export function createCollectionListRoute(path: string) {
       const navigate = useNavigate()
       const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
       const adminConfig = getCollectionAdminConfig(collection)
-      const columns = adminConfig?.columns || []
+      // Apply the built-in relation formatter to any relation column without an
+      // explicit one, so relation cells render the target's title (the list
+      // read populates relation columns to depth 1).
+      const columns = applyRelationColumnFormatters(adminConfig?.columns || [], collectionDef)
       const workflowStatuses = getWorkflowStatuses(collectionDef)
 
       // Ref-guarded so the post-create toast fires exactly once per arrival with
@@ -178,6 +182,7 @@ export function createCollectionListRoute(path: string) {
               useAsTitle={collectionDef.useAsTitle}
               collection={collection}
               collectionLabels={data.included.collection.labels}
+              listActions={adminConfig?.listActions}
               onMove={async ({
                 documentId,
                 parentDocumentId,
@@ -204,6 +209,7 @@ export function createCollectionListRoute(path: string) {
               workflowStatuses={workflowStatuses}
               useAsTitle={collectionDef.useAsTitle}
               orderable={collectionDef.orderable === true}
+              listActions={adminConfig?.listActions}
               onReorder={async ({ documentId, beforeDocumentId, afterDocumentId }) => {
                 await reorderCollectionDocument({
                   data: {

package/src/server-fns/collections/index.ts

@@ -14,6 +14,7 @@ export * from './duplicate'
 export * from './get'
 export * from './history'
 export * from './list'
+export * from './reindex'
 export * from './reorder'
 export * from './restore-version'
 export * from './stats'

package/src/server-fns/collections/list.ts

@@ -9,10 +9,14 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import {
+  buildRelationSummaryPopulateMap,
   ERR_NOT_FOUND,
+  getCollectionAdminConfig,
+  getCollectionDefinition,
   getCollectionSchemasForPath,
   getLogger,
   getServerConfig,
+  type PopulateSpec,
   type QueryPredicate,
 } from '@byline/core'
 
@@ -74,6 +78,19 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
       ? { [params.order]: params.desc === false ? 'asc' : 'desc' }
       : defaultSort
 
+    // Auto-populate relation columns (depth 1) so the list renders each
+    // target's title (via `relationColumnFormatter`) rather than a raw
+    // document id. Projection follows each target's `itemView` columns +
+    // `useAsTitle` — the same map the edit view uses. Populate only fires for
+    // relation fields actually loaded (i.e. selected as columns), so building
+    // the full map is harmless for collections whose relations aren't shown.
+    const populateMap = buildRelationSummaryPopulateMap(config.definition.fields, (targetPath) => ({
+      def: getCollectionDefinition(targetPath),
+      admin: getCollectionAdminConfig(targetPath),
+    }))
+    const hasRelations = Object.keys(populateMap).length > 0
+    const populate: PopulateSpec | undefined = hasRelations ? populateMap : undefined
+
     const result = await handle.find({
       where: Object.keys(where).length > 0 ? where : undefined,
       sort: sortSpec,
@@ -81,6 +98,8 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
       page: params.page,
       pageSize,
       select: params.fields,
+      populate,
+      depth: hasRelations ? 1 : undefined,
       status: 'any',
       // Admin list: show the raw per-locale state (untranslated docs render
       // empty in the active locale's columns) rather than falling back to the
@@ -131,5 +150,15 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
 
     // Validate with schema for runtime type safety and field normalisation.
     const { list } = getCollectionSchemasForPath(path)
+
+    // Skip the per-locale Zod parse when relations were populated — the tree
+    // then carries nested populated documents that don't match the raw
+    // relation-ref shape the list schema expects, and a strict parse would
+    // strip the `_resolved` / `document` envelope keys the relation formatter
+    // reads. Mirrors the edit-route (`get.ts`) populated-tree handling.
+    if (hasRelations) {
+      return serialised as unknown as ReturnType<typeof list.parse>
+    }
+
     return list.parse(serialised)
   })

package/src/server-fns/collections/reindex.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+
+/**
+ * Admin server fn: rebuild a collection's search index. Thin boundary over
+ * `CollectionHandle.reindex()` — which clears the index slice and re-indexes
+ * every published document. Routes through `getAdminBylineClient()` so the
+ * request's admin actor is used; `reindex()` asserts the
+ * `collections.<path>.reindex` ability, so authorization is enforced here even
+ * though the button is also permission-gated in the UI.
+ *
+ * Synchronous today (fine for small/medium collections). A large corpus wants
+ * this backgrounded with progress — see docs/05-reading-and-delivery/07-search.md
+ * ("reindex cost").
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import type { ReindexResult } from '@byline/client'
+import { ERR_NOT_FOUND, getLogger } from '@byline/core'
+
+import { ensureCollection } from '../../integrations/api-utils.js'
+import { getAdminBylineClient } from '../../integrations/byline-client.js'
+
+export type { ReindexResult }
+
+export const reindexCollection = createServerFn({ method: 'POST' })
+  .validator((input: { collection: string }) => input)
+  .handler(async ({ data }): Promise<ReindexResult> => {
+    const { collection } = data
+    const config = await ensureCollection(collection)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: collection },
+      }).log(getLogger())
+    }
+
+    // `reindex()` asserts `collections.<collection>.reindex` against the
+    // request's admin actor before doing any work.
+    return getAdminBylineClient().collection(collection).reindex()
+  })