@happyvertical/smrt-content 0.44.0 → 0.45.0

package/dist/svelte/components/ContentList.svelte

@@ -45,6 +45,16 @@ import { Button, Pagination } from '@happyvertical/smrt-ui/ui';
 import type { Snippet } from 'svelte';
 import { untrack } from 'svelte';
 import type { ContentData } from '../../mock-smrt-client.js';
+import type { ContentListLifecycleBinding } from '../content-list-lifecycle.js';
+import {
+  readContentListLifecycleSummary,
+  reconcileContentListLifecycleSelection,
+} from '../content-list-lifecycle.js';
+import {
+  registerContentListDataSurface,
+  type ContentListSurfaceContext,
+  type ContentListSurfaceHandle,
+} from '../content-list-data-surface.js';
 import {
   applyContentListFilter,
   buildContentListColumns,
@@ -123,10 +133,109 @@ import {
   readContentListViewStateFromSearchParams,
 } from '../content-list-url-state.js';
 import { M } from '../i18n.contribution.js';
+import ContentListLifecyclePanel from './ContentListLifecyclePanel.svelte';
 import ImageThumbnail from './ImageThumbnail.svelte';
 
 const { t } = useI18n();
 
+const DEFAULT_CONTENT_LIST_SURFACE_IDENTITY: DataSurfaceIdentity = {
+  surfaceId: 'content-list',
+  kind: 'table',
+};
+
+function sameSurfaceIdentity(
+  left: DataSurfaceIdentity,
+  right: DataSurfaceIdentity,
+): boolean {
+  return (
+    left.kind === right.kind &&
+    left.surfaceId === right.surfaceId &&
+    left.subject?.type === right.subject?.type &&
+    left.subject?.id === right.subject?.id
+  );
+}
+
+function resolveSurfaceAuthority(
+  lifecycle: ContentListLifecycleBinding | undefined,
+  workflows: ContentListWorkflowBinding | undefined,
+): {
+  identity?: DataSurfaceIdentity;
+  maxSelectionSize?: number;
+  lifecycle?: ContentListLifecycleBinding;
+  workflows?: ContentListWorkflowBinding;
+} {
+  const lifecycleIdentity = lifecycle
+    ? (lifecycle.identity ?? DEFAULT_CONTENT_LIST_SURFACE_IDENTITY)
+    : undefined;
+  const workflowIdentity = workflows
+    ? (workflows.identity ?? DEFAULT_CONTENT_LIST_SURFACE_IDENTITY)
+    : undefined;
+  if (
+    lifecycleIdentity &&
+    workflowIdentity &&
+    !sameSurfaceIdentity(lifecycleIdentity, workflowIdentity)
+  ) {
+    throw new Error(
+      'ContentList lifecycle and workflow bindings must use the same data surface identity',
+    );
+  }
+  const bindings = [lifecycle, workflows].filter(
+    (binding): binding is ContentListLifecycleBinding | ContentListWorkflowBinding =>
+      binding !== undefined,
+  );
+  const maxSelectionSize =
+    bindings.length > 0
+      ? Math.min(...bindings.map((binding) => binding.maxSelectionSize ?? 200))
+      : undefined;
+  return {
+    ...(lifecycleIdentity ?? workflowIdentity
+      ? { identity: lifecycleIdentity ?? workflowIdentity }
+      : {}),
+    ...(maxSelectionSize === undefined ? {} : { maxSelectionSize }),
+    ...(lifecycle && lifecycleIdentity
+      ? {
+          lifecycle: {
+            ...lifecycle,
+            identity: lifecycleIdentity,
+            ...(maxSelectionSize === undefined ? {} : { maxSelectionSize }),
+          },
+        }
+      : {}),
+    ...(workflows && workflowIdentity
+      ? {
+          workflows: {
+            ...workflows,
+            identity: workflowIdentity,
+            ...(maxSelectionSize === undefined ? {} : { maxSelectionSize }),
+          },
+        }
+      : {}),
+  };
+}
+
+function reconcileSurfaceDescriptor(
+  descriptor: import('@happyvertical/smrt-ui/data').DataSurfaceDescriptor,
+  authority: ReturnType<typeof resolveSurfaceAuthority>,
+): import('@happyvertical/smrt-ui/data').DataSurfaceDescriptor {
+  if (
+    authority.identity &&
+    !sameSurfaceIdentity(descriptor.identity, authority.identity)
+  ) {
+    throw new Error(
+      'ContentList custom data surface descriptor must use the lifecycle and workflow identity',
+    );
+  }
+  if (
+    authority.maxSelectionSize !== undefined &&
+    descriptor.limits.maxSelectionSize !== authority.maxSelectionSize
+  ) {
+    throw new Error(
+      'ContentList custom data surface descriptor must use the lifecycle and workflow selection limit',
+    );
+  }
+  return descriptor;
+}
+
 const WORKFLOW_LABEL_MESSAGES: Record<
   ContentListWorkflowId,
   keyof typeof M
@@ -318,7 +427,7 @@ interface Props {
   error?: string | null;
   /** Retry affordance rendered with an error. */
   onRetry?: () => void;
-  /** Opt-in agent addressability. Non-table presentations land with #2456. */
+  /** Opt-in agent addressability shared by every list presentation. */
   dataSurface?: ContentListDataSurface;
   /**
    * Opt-in server-backed rows (#2452). `bind()` is called exactly once, during
@@ -335,6 +444,10 @@ interface Props {
   jobs?: ContentListJobBinding;
   /** Opt-in, authenticated preview/apply client for bulk workflows (#2453). */
   workflows?: ContentListWorkflowBinding;
+  /** Opt-in, server-authoritative trash/restore/permanent-delete lifecycle. */
+  lifecycle?: ContentListLifecycleBinding;
+  /** Locks the status query to deleted content and exposes trash actions. */
+  lifecycleMode?: 'active' | 'trash';
 }
 
 let {
@@ -356,8 +469,14 @@ let {
   savedViews = undefined,
   jobs = undefined,
   workflows = undefined,
+  lifecycle = undefined,
+  lifecycleMode = 'active',
 }: Props = $props();
 
+const surfaceAuthority = $derived(
+  resolveSurfaceAuthority(lifecycle, workflows),
+);
+
 const initialQuery = untrack(() => query);
 
 // One controller owns search, filters, sorting, paging, and selection for
@@ -425,6 +544,7 @@ const urlStateOptions: ContentListUrlStateOptions = {
 
 const controller = createContentListController({
   type: untrack(() => type),
+  ...(untrack(() => lifecycleMode) === 'trash' ? { status: 'deleted' } : {}),
   // Local mode keeps the historical unpaginated list.
   ...(serverPageSize === null ? {} : { pageSize: serverPageSize }),
 });
@@ -454,6 +574,18 @@ let resultNotices = $state<ContentListQueryNotices>({
  * its own total ever arrived.
  */
 let settledSignature = $state<string | undefined>(undefined);
+let settledLifecycleQuery = $state<ContentListDataQueryRequest | undefined>(
+  undefined,
+);
+let settledLifecycleFingerprint = $state<string | undefined>(undefined);
+let settledSurfaceMetadata = $state<
+  | {
+      signature: string;
+      queryFingerprint: string | null;
+      totalRows: number | null;
+    }
+  | undefined
+>(undefined);
 
 function toSearchParams(
   input: URLSearchParams | string | null | undefined,
@@ -480,22 +612,34 @@ if (initialUrlState?.params !== undefined && initialUrlState?.params !== null) {
   // the same link just restored. Folding the lock into the restored patch keeps
   // it to one `replaceState`, and leaves the effect's first run a no-op.
   const initialLockedType = normalizeContentListTypeLock(untrack(() => type));
-  const patch =
-    initialLockedType === null
-      ? reading.state
-      : {
-          ...reading.state,
-          filters: [
-            ...(reading.state.filters ?? []).filter(
-              (filter) => filter.columnId !== CONTENT_LIST_TYPE_FILTER_ID,
-            ),
-            {
-              columnId: CONTENT_LIST_TYPE_FILTER_ID,
-              operator: 'equals' as const,
-              value: initialLockedType,
-            },
-          ],
-        };
+  const initialTrashMode = untrack(() => lifecycleMode) === 'trash';
+  const lockedFilters = [...(reading.state.filters ?? [])].filter(
+    (filter) =>
+      (initialLockedType === null ||
+        filter.columnId !== CONTENT_LIST_TYPE_FILTER_ID) &&
+      (!initialTrashMode ||
+        filter.columnId !== CONTENT_LIST_STATUS_FILTER_ID),
+  );
+  if (initialLockedType !== null) {
+    lockedFilters.push({
+      columnId: CONTENT_LIST_TYPE_FILTER_ID,
+      operator: 'equals',
+      value: initialLockedType,
+    });
+  }
+  if (initialTrashMode) {
+    lockedFilters.push({
+      columnId: CONTENT_LIST_STATUS_FILTER_ID,
+      operator: 'equals',
+      value: 'deleted',
+    });
+  }
+  const patch = {
+    ...reading.state,
+    ...(initialLockedType !== null || initialTrashMode
+      ? { filters: lockedFilters }
+      : {}),
+  };
   applyContentListViewState(controller, patch, restoreOptions);
   restoreDrops = reading.dropped;
 }
@@ -515,6 +659,7 @@ const queryRequestOptions: ContentListQueryRequestOptions | undefined =
       }
     : undefined;
 const serverBacked = queryBinding !== undefined;
+let locallyRemovedLifecycleIds = $state<Set<string>>(new Set());
 
 let snapshot = $state(controller.snapshot());
 let viewMode: ContentListViewMode = $state(untrack(() => defaultViewMode));
@@ -532,6 +677,11 @@ const MAX_DEFERRED_JOB_COMPLETIONS = 50;
 let completedJobs = $state<ContentListJob[]>([]);
 let completedJobsOverflowed = $state(false);
 let activeQueryKey = $state<string | undefined>(undefined);
+let lifecycleRefreshPending = $state(false);
+let surfaceRoot: HTMLDivElement | undefined;
+let surfaceHighlighted = $state(false);
+let surfaceHighlightTimeout: ReturnType<typeof setTimeout> | undefined;
+let surfaceHandle: ContentListSurfaceHandle | undefined;
 
 // Job state is subscribed once so hosts can use a framework-free controller.
 // Only transitions observed after the initial snapshot are completion events;
@@ -697,8 +847,20 @@ const columnLabels = $derived({
 
 const queryColumns = $derived(buildContentListColumns(columnLabels));
 const sourceContents = $derived(
-  queryBinding ? contentListQueryRowsToContents(queryBinding.rows) : contents,
+  (queryBinding
+    ? contentListQueryRowsToContents(queryBinding.rows)
+    : contents
+  ).filter((content) => !locallyRemovedLifecycleIds.has(String(content.id))),
 );
+
+$effect(() => {
+  if (!queryBinding || refreshing || isLoading) return;
+  const removed = locallyRemovedLifecycleIds;
+  if (removed.size === 0) return;
+  const visible = new Set(queryBinding.rows.map((row) => String(row.id)));
+  const retained = new Set([...removed].filter((id) => visible.has(id)));
+  if (retained.size !== removed.size) locallyRemovedLifecycleIds = retained;
+});
 const rows = $derived(toContentListRows(sourceContents));
 const visibleRowIds = $derived(
   new Set(rows.filter((row) => row.identified).map((row) => String(row.id))),
@@ -843,21 +1005,58 @@ function refreshQuery(): void {
   void queryBinding
     .refresh()
     .then((result) => {
-      if (result !== undefined && activeQueryKey === key)
-        resultNotices = readContentListQueryNotices(result);
+      if (result !== undefined && activeQueryKey === key) {
+        if (executedWorkflowQuery) {
+          settleWorkflowQueryResult(
+            result,
+            executedWorkflowQuery,
+            querySignature,
+          );
+        } else {
+          resultNotices = readContentListQueryNotices(result);
+        }
+        settleLifecycleResult(result, lifecycleQueryRequest, querySignature);
+      }
     })
     .catch(() => undefined);
 }
 
+function requestLifecycleRefresh(): void {
+  if (!queryBinding?.refresh) return;
+  if (refreshing || isLoading) {
+    lifecycleRefreshPending = true;
+    return;
+  }
+  lifecycleRefreshPending = false;
+  refreshQuery();
+}
+
+$effect(() => {
+  if (!lifecycleRefreshPending || refreshing || isLoading) return;
+  lifecycleRefreshPending = false;
+  refreshQuery();
+});
+
 function settleWorkflowQueryResult(
   result: unknown,
   request: ContentListDataQueryRequest,
   signature: string,
 ): void {
   settledSignature = signature;
+  const envelope =
+    result !== null && typeof result === 'object' && !Array.isArray(result)
+      ? (result as Record<string, unknown>)
+      : undefined;
+  settledSurfaceMetadata = {
+    signature,
+    queryFingerprint:
+      typeof envelope?.queryFingerprint === 'string'
+        ? envelope.queryFingerprint
+        : null,
+    totalRows: surfaceMetadataTotalRows(envelope?.total),
+  };
   resultNotices = readContentListQueryNotices(result);
-  if (result !== null && typeof result === 'object' && !Array.isArray(result)) {
-    const envelope = result as Record<string, unknown>;
+  if (envelope) {
     settledWorkflowQuery = request;
     settledWorkflowFingerprint =
       typeof envelope.queryFingerprint === 'string'
@@ -878,6 +1077,38 @@ function settleWorkflowQueryResult(
   settledWorkflowRevision = null;
 }
 
+function surfaceMetadataTotalRows(total: unknown): number | null {
+  if (!total || typeof total !== 'object' || Array.isArray(total)) return null;
+  const record = total as Record<string, unknown>;
+  return (record.kind === 'exact' || record.kind === 'estimated') &&
+    typeof record.value === 'number' &&
+    Number.isSafeInteger(record.value) &&
+    record.value >= 0
+    ? record.value
+    : null;
+}
+
+function settleLifecycleResult(
+  result: unknown,
+  request: ContentListDataQueryRequest | undefined,
+  signature: string,
+): void {
+  if (
+    !request ||
+    result === null ||
+    typeof result !== 'object' ||
+    Array.isArray(result)
+  ) {
+    settledLifecycleQuery = undefined;
+    settledLifecycleFingerprint = undefined;
+    return;
+  }
+  const fingerprint = (result as Record<string, unknown>).queryFingerprint;
+  settledLifecycleQuery = request;
+  settledLifecycleFingerprint =
+    typeof fingerprint === 'string' ? fingerprint : undefined;
+  settledSignature = signature;
+}
 /**
  * A retry re-reads the same query, so its answer replaces the rendered rows —
  * and therefore has to replace the completeness flags that describe them too.
@@ -903,6 +1134,7 @@ function retryQuery(): void {
       )
         return;
       settleWorkflowQueryResult(result, request, signature);
+      settleLifecycleResult(result, lifecycleQueryRequest, signature);
     })
     .catch(() => undefined);
 }
@@ -930,6 +1162,7 @@ const querySignature = $derived(
 let executedSignature: string | undefined;
 let executedWorkflowQuery: ContentListDataQueryRequest | null = null;
 let publishedUrlSignature: string | undefined;
+let lifecycleQueryRequest: ContentListDataQueryRequest | undefined;
 
 $effect(() => {
   const signature = querySignature;
@@ -976,6 +1209,7 @@ $effect(() => {
       // flags, which the binding itself does not expose.
       activeQueryKey = contentListQueryRequestKey(translated.request);
       executedWorkflowQuery = translated.request;
+      lifecycleQueryRequest = translated.request;
       void queryBinding
         .execute(translated.request)
         .then((result) => {
@@ -985,6 +1219,7 @@ $effect(() => {
           // may be clamped against them and workflows may bind to the exact
           // settled request.
           settleWorkflowQueryResult(result, translated.request, signature);
+          settleLifecycleResult(result, translated.request, signature);
         })
         .catch(() => undefined);
     }
@@ -1111,7 +1346,7 @@ const canSelectAllMatching = $derived(
       settledWorkflowRevision &&
       exactMatchingCount !== undefined &&
       exactMatchingCount > 0 &&
-      exactMatchingCount <= (workflows?.maxSelectionSize ?? 200),
+      exactMatchingCount <= (surfaceAuthority.maxSelectionSize ?? 200),
   ),
 );
 const workflowPayloadValid = $derived(
@@ -1124,6 +1359,23 @@ const workflowQueuedJob = $derived(
   workflowQueuedJobs.find((job) => job.intent === workflowIntentSignature()) ??
     workflowQueuedJobs[0],
 );
+const lifecycleViewKey = $derived(
+  JSON.stringify([
+    lifecycleMode,
+    querySignature,
+    [...tableState.selectedRowIds].map(String).sort(),
+  ]),
+);
+const lifecycleQuery = $derived(
+  serverBacked && settledSignature === querySignature
+    ? settledLifecycleQuery
+    : undefined,
+);
+const lifecycleExactMatchingCount = $derived(
+  serverBacked && settledSignature === querySignature
+    ? contentListQueryExactTotal(queryBinding?.total)
+    : queryRows.length,
+);
 
 /** Synthetic ids the adapter minted for rows that carry no durable identity. */
 const unidentifiedRowKeys = $derived(
@@ -1153,6 +1405,23 @@ $effect(() => {
   );
 });
 
+// Trash is a view, not an editable select value. Keep its status predicate
+// locked against URL restores and agent-driven filter commands.
+$effect(() => {
+  if (lifecycleMode !== 'trash') return;
+  if (
+    isContentListFilterExactly(
+      tableState,
+      CONTENT_LIST_STATUS_FILTER_ID,
+      'deleted',
+    )
+  )
+    return;
+  untrack(() =>
+    applyContentListFilter(controller, CONTENT_LIST_STATUS_FILTER_ID, 'deleted'),
+  );
+});
+
 /**
  * What each toolbar select may display, and whether it can display the live
  * predicate at all.
@@ -1257,20 +1526,30 @@ const surfaceOptions = $derived(
     ? {
         registry: dataSurface.registry,
         descriptor:
-          dataSurface.descriptor ??
+          dataSurface.descriptor
+            ? reconcileSurfaceDescriptor(
+                dataSurface.descriptor,
+                surfaceAuthority,
+              )
+            :
           (() => {
             const descriptor = buildContentListSurfaceDescriptor({
               columnLabels,
+              serverBacked: initialQuery !== undefined,
+              lifecycle: lifecycle !== undefined,
+              lifecycleMode,
               includeWorkflows: workflows !== undefined,
+              refresh: queryBinding?.refresh !== undefined,
+              retry: retryHandler !== undefined,
             });
             return {
               ...descriptor,
-              identity: workflows?.identity ?? descriptor.identity,
+              identity: surfaceAuthority.identity ?? descriptor.identity,
               limits: {
                 ...descriptor.limits,
-                ...(workflows?.maxSelectionSize === undefined
+                ...(surfaceAuthority.maxSelectionSize === undefined
                   ? {}
-                  : { maxSelectionSize: workflows.maxSelectionSize }),
+                  : { maxSelectionSize: surfaceAuthority.maxSelectionSize }),
               },
             };
           })(),
@@ -1312,6 +1591,164 @@ const queryWarnings = $derived<ReadonlyArray<string>>(
     boundResultNotices?.warnings ??
     resultNotices.warnings,
 );
+
+function surfaceLastUpdated(value: unknown): string | null {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return null;
+}
+
+const matchingSurfaceMetadata = $derived(
+  serverBacked && settledSurfaceMetadata?.signature === querySignature
+    ? settledSurfaceMetadata
+    : undefined,
+);
+
+const surfaceContext = $derived<ContentListSurfaceContext>({
+  viewMode,
+  queryFingerprint: serverBacked
+    ? (matchingSurfaceMetadata?.queryFingerprint ?? null)
+    : null,
+  totalRows: serverBacked
+    ? (matchingSurfaceMetadata?.totalRows ?? null)
+    : Number.isSafeInteger(totalRowCount)
+      ? totalRowCount
+      : null,
+  freshness: {
+    stale,
+    refreshing,
+    offline,
+    lastUpdated: surfaceLastUpdated(lastUpdated),
+    truncated: queryTruncated,
+    warnings: queryWarnings,
+  },
+});
+
+function focusSurface(): void {
+  if (!surfaceRoot) return;
+  surfaceRoot.tabIndex = -1;
+  surfaceRoot.focus();
+}
+
+// ContentList owns the registration so grid, detailed, compact, empty, and
+// loading presentations all expose one stable identity and revision stream.
+// This ref is deliberately non-reactive: registration input changes must
+// advance a stable identity revision, but normal command acknowledgements must
+// not themselves cause a registration teardown/replay window.
+const surfaceRevision = { value: undefined as number | undefined };
+
+function acceptsSurfaceTableCommand(
+  command: import('@happyvertical/smrt-ui/data').DataTableCommand,
+): boolean {
+  if (command.type === 'setPageSize' && serverPageSize !== null) {
+    if (command.pageSize === null || command.pageSize > maxPageSize) return false;
+  }
+  if (command.type === 'setPage') {
+    if (command.page > maxReachablePage) return false;
+    if (
+      tableState.pageSize !== null &&
+      clampableRowCount !== undefined &&
+      // A server binding retains the previous query's exact total until its
+      // replacement settles. That count cannot bound a command for the new
+      // query: it may be smaller, and would reject a valid page before the
+      // new query gets a chance to report its own total.
+      (!serverBacked || settledSignature === querySignature) &&
+      command.page > Math.max(1, Math.ceil(clampableRowCount / tableState.pageSize))
+    )
+      return false;
+  }
+  if (command.type === 'setFilters') {
+    if (
+      lockedType !== null &&
+      !isContentListFilterExactly(
+        { ...tableState, filters: command.filters },
+        CONTENT_LIST_TYPE_FILTER_ID,
+        lockedType,
+      )
+    )
+      return false;
+    if (
+      lifecycleMode === 'trash' &&
+      !isContentListFilterExactly(
+        { ...tableState, filters: command.filters },
+        CONTENT_LIST_STATUS_FILTER_ID,
+        'deleted',
+      )
+    )
+      return false;
+  }
+  return command.type !== 'reset' || (lockedType === null && lifecycleMode !== 'trash');
+}
+
+$effect(() => {
+  const surface = surfaceOptions;
+  if (!surface) {
+    surfaceHandle = undefined;
+    return;
+  }
+  const handle = registerContentListDataSurface({
+    ...surface,
+    controller,
+    context: untrack(() => surfaceContext),
+    initialRevision:
+      surfaceRevision.value === undefined ? 0 : surfaceRevision.value + 1,
+    onRevision: (revision) => {
+      surfaceRevision.value = revision;
+    },
+    acceptsTableCommand: acceptsSurfaceTableCommand,
+    setViewMode: (next) => {
+      viewMode = next;
+    },
+    ...(queryBinding?.refresh
+      ? {
+          refresh: async () => {
+            await refreshQuery();
+            return true;
+          },
+        }
+      : {}),
+    ...(retryHandler
+      ? {
+          retry: async () => {
+            await retryHandler();
+            return true;
+          },
+        }
+      : {}),
+    focus: focusSurface,
+    reveal: () => surfaceRoot?.scrollIntoView({ block: 'nearest' }),
+    highlight: () => {
+      if (surfaceHighlightTimeout !== undefined) {
+        clearTimeout(surfaceHighlightTimeout);
+      }
+      surfaceHighlighted = true;
+      const timeout = setTimeout(() => {
+        if (surfaceHandle === handle) surfaceHighlighted = false;
+        if (surfaceHighlightTimeout === timeout) {
+          surfaceHighlightTimeout = undefined;
+        }
+      }, 1_000);
+      surfaceHighlightTimeout = timeout;
+    },
+  });
+  surfaceHandle = handle;
+  return () => {
+    if (surfaceHandle === handle) surfaceHandle = undefined;
+    if (surfaceHighlightTimeout !== undefined) {
+      clearTimeout(surfaceHighlightTimeout);
+      surfaceHighlightTimeout = undefined;
+    }
+    surfaceHighlighted = false;
+    handle.destroy();
+  };
+});
+
+$effect(() => {
+  surfaceHandle?.update(surfaceContext);
+});
 /** Identity of the current set of refusals, so a dismissal is not permanent. */
 const dropNoticeKey = $derived(
   dropNotices.length > 0 || queryTruncated || queryWarnings.length > 0
@@ -1606,6 +2043,16 @@ function workflowSelection(): ContentListWorkflowRequest['selection'] | null {
   return { scope: 'explicit-ids', rowIds: effectiveRowIds };
 }
 
+function workflowSelectionCount(
+  selection: ContentListWorkflowRequest['selection'],
+): number {
+  if (selection.scope === 'explicit-ids') return selection.rowIds.length;
+  if (selection.scope === 'current-page') return selectablePageRowIds.length;
+  return tableState.selection.scope === 'allMatching'
+    ? tableState.selection.expectedCount
+    : 0;
+}
+
 function workflowJobTarget(
   request: ContentListWorkflowRequest,
 ): ContentListJobTarget {
@@ -1646,6 +2093,8 @@ function createWorkflowRequest(
 ): ContentListWorkflowRequest | null {
   const selection = workflowSelection();
   if (!selection) return null;
+  const selectionCount = workflowSelectionCount(selection);
+  if (selectionCount > (surfaceAuthority.maxSelectionSize ?? 200)) return null;
   const queryRequired = selection.scope !== 'explicit-ids';
   if (
     queryRequired &&
@@ -1658,7 +2107,8 @@ function createWorkflowRequest(
   return {
     version: 1,
     requestId: globalThis.crypto?.randomUUID?.() ?? `content-workflow-${Date.now()}`,
-    identity: workflows?.identity ?? { surfaceId: 'content-list', kind: 'table' },
+    identity:
+      surfaceAuthority.identity ?? DEFAULT_CONTENT_LIST_SURFACE_IDENTITY,
     actionId: selectedWorkflow,
     phase,
     selection,
@@ -1668,10 +2118,7 @@ function createWorkflowRequest(
       ...(queryRequired && settledWorkflowQuery
         ? { query: settledWorkflowQuery }
         : {}),
-      expectedCount:
-        selection.scope === 'explicit-ids'
-          ? selection.rowIds.length
-          : selectedCount,
+      expectedCount: selectionCount,
     },
   };
 }
@@ -2052,7 +2499,29 @@ function handleFilter(columnId: string, value: string) {
 }
 
 function rowActions(row: ContentListRow) {
-  return contentListRowActions(row, { getViewHref });
+  return contentListRowActions(row, {
+    getViewHref,
+    canEdit: lifecycleMode !== 'trash',
+    canDelete: lifecycleMode !== 'trash' && lifecycle === undefined,
+  });
+}
+
+function handleLifecycleComplete(
+  result: import('@happyvertical/smrt-ui/data').DataSurfaceActionResult,
+) {
+  const removed = new Set(locallyRemovedLifecycleIds);
+  for (const outcome of readContentListLifecycleSummary(result).outcomes) {
+    if (outcome.status === 'accepted') removed.add(String(outcome.rowId));
+  }
+  locallyRemovedLifecycleIds = removed;
+  controller.dispatch({
+    type: 'setSelectedRows',
+    rowIds: reconcileContentListLifecycleSelection(
+      tableState.selectedRowIds,
+      result,
+    ),
+  });
+  requestLifecycleRefresh();
 }
 
 function viewHref(row: ContentListRow): string | null {
@@ -2127,7 +2596,11 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
 </script>
 
 {#snippet tableEmptyState()}
-  <p class="table-empty-state">{t(M['content.content_list.empty'])}</p>
+  <p class="table-empty-state">
+    {lifecycleMode === 'trash'
+      ? t(M['content.content_list.trash_empty'])
+      : t(M['content.content_list.empty'])}
+  </p>
 {/snippet}
 
 {#snippet selectHeader()}
@@ -2226,7 +2699,11 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
   </div>
 {/snippet}
 
-<div class="content-list-wrapper">
+<div
+  class="content-list-wrapper"
+  class:data-surface-highlighted={surfaceHighlighted}
+  bind:this={surfaceRoot}
+>
 
   <div class="content-controls">
     <div class="search-filters">
@@ -2267,6 +2744,7 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
         </Select>
       {/if}
 
+      {#if lifecycleMode !== 'trash'}
       <Select
         aria-label={t(M['content.content_list.filter_status'])}
         value={selectedStatus}
@@ -2289,6 +2767,7 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
           </option>
         {/if}
       </Select>
+      {/if}
 
       {#if savedViews}
         <div class="saved-views" role="group" aria-label={t(M['content.content_list.saved_views'])}>
@@ -2568,6 +3047,19 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
       </div>
     {/if}
 
+    {#if lifecycle}
+      <ContentListLifecyclePanel
+        binding={surfaceAuthority.lifecycle ?? lifecycle}
+        mode={lifecycleMode}
+        selectedRowIds={tableState.selectedRowIds}
+        query={lifecycleQuery}
+        queryFingerprint={settledLifecycleFingerprint}
+        exactMatchingCount={lifecycleExactMatchingCount}
+        viewKey={lifecycleViewKey}
+        oncomplete={handleLifecycleComplete}
+      />
+    {/if}
+
     {#if workflows && (selectedCount > 0 || workflowError || workflowResult)}
       <section class="content-workflows" aria-label={t(M['content.content_list.bulk_workflows'])}>
         <Select
@@ -2686,9 +3178,9 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
 
     {#if viewMode === 'compact'}
       <!--
-        The compact table stays mounted for empty and loading results: it owns
-        the mounted data surface, so unmounting it on a zero-row query would
-        unregister the surface and leave an agent unable to undo its own search.
+        The compact table stays mounted for empty and loading results so its
+        table semantics and operator affordances remain stable across queries.
+        ContentList itself owns the agent-addressable surface in every view.
       -->
       <div class="content-table-wrapper">
         <DataTable
@@ -2701,7 +3193,6 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
           loading={isLoading}
           caption={t(M['content.content_list.table_caption'])}
           rowLabel={(row: ContentListRow) => row.title}
-          dataSurface={surfaceOptions}
           empty={tableEmptyState}
         />
       </div>
@@ -2711,7 +3202,9 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
       </div>
     {:else if pageRows.length === 0}
       <div class="state-panel empty-state">
-        {t(M['content.content_list.empty'])}
+        {lifecycleMode === 'trash'
+          ? t(M['content.content_list.trash_empty'])
+          : t(M['content.content_list.empty'])}
       </div>
     {:else if viewMode === 'detailed'}
       <div class="content-detailed">
@@ -2937,6 +3430,11 @@ const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
     width: 100%;
   }
 
+  .content-list-wrapper.data-surface-highlighted {
+    outline: 2px solid var(--smrt-color-primary);
+    outline-offset: 0.25rem;
+  }
+
   .content-controls {
     display: flex;
     justify-content: space-between;