admin-ui-starter-kit 0.4.4 → 0.5.0

package/.agents/skills/component-library-rules/references/components/layout__layout-page.md

@@ -4,18 +4,23 @@ title: "Layout · Page"
 description: "Page shell, header partials, actions, and content regions with framework-neutral links."
 layer: layout
 family: "Shells"
-sourcePath: src/components/layout/page
+sourcePath: src/components/layout
 examples:
   - ProductionPageShell
   - ComposablePartials
+  - ResourceShells
+  - TabbedResourceDetails
+  - SettingsShellExample
 imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/cards
   - @/components/layout
   - @/components/layout/page
+  - @/components/layout/resource
+  - @/components/layout/settings
   - @/components/typography
-publicImport: admin-ui-starter-kit/layout/page
+publicImport: admin-ui-starter-kit/layout
 tags:
   - layout
   - shells
@@ -23,7 +28,6 @@ tags:
   - shell
   - header
   - partials
-  - actions
 ---
 
 # Layout · Page
@@ -31,24 +35,36 @@ tags:
 Page shell, header partials, actions, and content regions with framework-neutral links.
 
 **Layer:** `layout`
-**Source:** `src/components/layout/page`
-**Consumer import:** `admin-ui-starter-kit/layout/page`
+**Source:** `src/components/layout`
+**Consumer import:** `admin-ui-starter-kit/layout`
 
 ## Consumer import
 
-Consumers import this surface from `admin-ui-starter-kit/layout/page`.
+Consumers import this surface from `admin-ui-starter-kit/layout`.
 The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 
 ```tsx
 import type { ReactNode } from 'react';
-import { Plus, RefreshCw, Trash2 } from 'lucide-react';
+import { Bell, Plus, RefreshCw, Shield, Trash2, User } from 'lucide-react';
 import { Badge } from '@/components/base/badge';
 import { Button } from '@/components/base/buttons';
 import { SmartCard } from '@/components/base/cards';
 import { Text } from '@/components/typography';
 import { Page, PageActions, PageContent, PageHeader, type PageAction } from '@/components/layout/page';
+import {
+	ResourceActionBar,
+	ResourceActivityCard,
+	ResourceDetailsCard,
+	ResourceDetailsSection,
+	ResourceHeader,
+	ResourceIndexShell,
+	ResourceRelatedCard,
+	ResourceShowShell,
+	TabbedResourceShell,
+} from '@/components/layout/resource';
+import { SettingsShell } from '@/components/layout/settings';
 import type { LayoutLinkRenderProps } from '@/components/layout';
 
 const actions: PageAction[] = [
@@ -163,10 +179,157 @@ export function ComposablePartials() {
 		</div>
 	);
 }
+
+export function ResourceShells() {
+	return (
+		<div className="grid gap-4">
+			<ResourceIndexShell
+				title="Bookings"
+				description="Index shells keep header, toolbar, list content, and empty state rhythm consistent."
+				actions={<Button variant="primary" icon={Plus}>New booking</Button>}
+				toolbar={
+					<ResourceActionBar
+						leading={
+							<>
+								<Badge variant="info">24 active</Badge>
+								<Badge variant="warning">8 review</Badge>
+							</>
+						}
+						trailing={<Button variant="secondary">Export</Button>}
+					/>
+				}
+			>
+				<div className="grid gap-2">
+					{queue.map((item) => (
+						<SmartCard key={item.label} padding="sm" className="shadow-sm">
+							<div className="flex items-center justify-between gap-3">
+								<div>
+									<Text weight="medium">{item.label}</Text>
+									<Text size="xs" type="secondary">{item.detail}</Text>
+								</div>
+								<Text weight="semibold">{item.value}</Text>
+							</div>
+						</SmartCard>
+					))}
+				</div>
+			</ResourceIndexShell>
+
+			<ResourceShowShell
+				slots={{
+					header: (
+						<ResourceHeader
+							title="Sarah Smitha"
+							eyebrow="Customer"
+							description="Gold-tier account with active bookings and billing history."
+							badges={<Badge variant="success">Active</Badge>}
+							actions={<Button variant="secondary">Edit profile</Button>}
+						/>
+					),
+					aside: (
+						<ResourceRelatedCard title="Related records">
+							<div className="grid gap-2">
+								<Text size="xs" type="secondary">4 bookings</Text>
+								<Text size="xs" type="secondary">2 invoices</Text>
+							</div>
+						</ResourceRelatedCard>
+					),
+				}}
+			>
+				<div className="grid gap-3 md:grid-cols-2">
+					<ResourceDetailsCard title="Account details">
+						<Text size="xs" type="secondary">Primary email, billing status, and customer metadata.</Text>
+					</ResourceDetailsCard>
+					<ResourceActivityCard title="Recent activity">
+						<Text size="xs" type="secondary">Last booking updated 12 minutes ago.</Text>
+					</ResourceActivityCard>
+				</div>
+			</ResourceShowShell>
+		</div>
+	);
+}
+
+export function TabbedResourceDetails() {
+	return (
+		<TabbedResourceShell
+			title="Sarah Smitha"
+			description="Gold-tier account with active bookings and billing history."
+			activeTab="profile"
+			tabs={[
+				{ id: 'profile', label: 'Profile', icon: User },
+				{ id: 'security', label: 'Security', icon: Shield },
+				{ id: 'notifications', label: 'Notifications', icon: Bell, badge: '3' },
+			]}
+			actions={<Button variant="secondary">Edit profile</Button>}
+			slots={{
+				aside: (
+					<ResourceRelatedCard title="Related records">
+						<div className="grid gap-2">
+							<Text size="xs" type="secondary">4 bookings</Text>
+							<Text size="xs" type="secondary">2 invoices</Text>
+						</div>
+					</ResourceRelatedCard>
+				),
+			}}
+		>
+			<div className="grid gap-3 md:grid-cols-2">
+				<ResourceDetailsSection
+					title="Account details"
+					metadata={[
+						{ label: 'Email', value: 'sarah@example.com' },
+						{ label: 'Segment', value: 'Gold' },
+						{ label: 'Created', value: 'May 14, 2026' },
+						{ label: 'Owner', value: 'Emma Garcia' },
+					]}
+					help="Consumers own field visibility, permissions, and edit workflows."
+				/>
+				<ResourceActivityCard title="Recent activity">
+					<Text size="xs" type="secondary">Last booking updated 12 minutes ago.</Text>
+				</ResourceActivityCard>
+			</div>
+		</TabbedResourceShell>
+	);
+}
+
+export function SettingsShellExample() {
+	return (
+		<SettingsShell
+			title="Workspace settings"
+			description="Aside navigation shell with router-neutral links."
+			currentId="profile"
+			renderLink={renderPreviewLink}
+			groups={[
+				{
+					id: 'workspace',
+					label: 'Workspace',
+					items: [
+						{ id: 'profile', label: 'Profile', href: '#/settings/profile', icon: User, description: 'Name, logo, and contact details' },
+						{ id: 'security', label: 'Security', href: '#/settings/security', icon: Shield, description: 'Sessions and policies' },
+						{ id: 'notifications', label: 'Notifications', href: '#/settings/notifications', icon: Bell, badge: 3 },
+					],
+				},
+			]}
+		>
+			<ResourceDetailsSection
+				title="Profile"
+				metadata={[
+					{ label: 'Workspace', value: 'Gift Come True' },
+					{ label: 'Plan', value: 'Pro' },
+				]}
+			>
+				<Text size="xs" type="secondary">
+					The app supplies forms, validation, permissions, and navigation.
+				</Text>
+			</ResourceDetailsSection>
+		</SettingsShell>
+	);
+}
 ```
 
 ## Example exports
 
 - `ProductionPageShell`
 - `ComposablePartials`
+- `ResourceShells`
+- `TabbedResourceDetails`
+- `SettingsShellExample`
 

package/CHANGELOG.md

@@ -6,7 +6,7 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-## [0.4.4] — 2026-06-20
+## [0.4.6] — 2026-06-20
 
 ### Added
 
@@ -16,6 +16,20 @@ this project adheres to [Semantic Versioning](https://semver.org/).
   now supports alert messages, custom footer composition, hidden headers,
   focus refs, escape/backdrop behavior, content classes, confirm style, icon /
   emphasis controls, and drawer footer visibility.
+- **Action migration APIs** — added `useLocalAction` for incremental
+  page-owned action migration, provider-level guards, provider/action error
+  parsing, request runner support, overlay/running state callbacks, typed action
+  factories, and surface mapping helpers.
+- **Dependency-free action adapters** — added HTTP, Inertia-like, and React
+  Query-like helpers that accept router/query-client objects without importing
+  framework packages into the library.
+- **Neutral action runtime glue** — added `ActionRuntimeGlue` and neutral
+  `ActionRequestTarget` request definitions. `ActionProvider` now accepts
+  `runtime` while keeping direct props as overriding compatibility props.
+- **Admin pattern primitives** — added header tool primitives, admin shell
+  aliases, resource page shells/cards, form workflow chrome, and data-view
+  toolbar/pagination/saved-view primitives so consumers can reuse package
+  patterns instead of rebuilding page glue.
 
 ### Fixed
 
@@ -29,6 +43,19 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 - Documented the recommended modality pattern: use
   `services/actions` + `ActionOverlayOutlet` for reusable modal workflows, and
   reserve `features/overlays` for one-off local state.
+- Expanded package-facing action docs across `README.md`, `INTEGRATION.md`,
+  the service README, and the consumer migration skill with provider contracts,
+  request runners, guards, error parsing, local actions, and migration choice
+  points.
+- Added neutral consumer glue recipes for routing, transport, cache
+  invalidation, toasts, permissions, backend error parsing, polling pause, and
+  busy state. Framework-named action helpers remain available in `0.4.x` but
+  are deprecated in favor of consumer-owned `ActionRuntimeGlue`.
+
+### Maintenance
+
+- Strengthened `lint:architecture` so package source cannot import framework
+  runtimes and new framework-named action exports are rejected.
 
 ## [0.1.3] — 2026-05-22
 
@@ -122,7 +149,7 @@ Initial public release.
 - **What this is not:** a marketing-site UI kit. Built for admin panels
   and SaaS dashboards.
 
-[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.4.4...HEAD
-[0.4.4]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.4
+[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.4.6...HEAD
+[0.4.6]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.6
 [0.1.3]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.0...v0.1.3
 [0.1.0]: https://github.com/nicolasvlachos/admin-ui-starter-kit/releases/tag/v0.1.0

package/COMPONENT_SELECTION.md

@@ -20,19 +20,23 @@ or documented here, treat it as private.
 | Recharts primitives with themed tooltip/legend | chart display family | `admin-ui-starter-kit/base/display/chart` |
 | Form label/control/error row | `FormField`, `ControlledFormField` | `admin-ui-starter-kit/base/forms` |
 | Inputs, password reveal, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
+| Form sections, dirty/error/submit state | `FormSection`, `FormActionsBar`, `ErrorSummary`, `DirtyStateBanner`, `SubmitStateButton` | `admin-ui-starter-kit/base/forms` |
 | Backend/schema-driven settings forms | `SchemaForm`, `useSchemaForm` | `admin-ui-starter-kit/features/schema-form` |
-| Searchable select | `EnhancedCombobox`, `EnhancedComboboxMultiple` | `admin-ui-starter-kit/base/combobox` |
+| Searchable select / async resource picker | `EnhancedCombobox`, `EnhancedComboboxMultiple`, `AsyncResourceCombobox` | `admin-ui-starter-kit/base/combobox` |
 | Popover menu or command menu | `PopoverMenu`, `Command` | `admin-ui-starter-kit/base/popover-menu`, `admin-ui-starter-kit/base/command` |
 | Embla-backed carousel controls | `Carousel` family | `admin-ui-starter-kit/base/carousel` |
 | Dropdown navigation menus | navigation family | `admin-ui-starter-kit/base/navigation` |
-| Data table | `DataTable` | `admin-ui-starter-kit/base/table` |
+| Data table / index table cells | `DataTable`, `ResourceCell`, `StatusClusterCell`, `DateMetaCell` | `admin-ui-starter-kit/base/table` |
+| Data view toolbar/pagination/saved views | `DataViewShell`, `DataViewToolbar`, `DataViewPagination`, `SavedViewTabs` | `admin-ui-starter-kit/base/data-view` |
 | Date picker or date range picker | date picker family | `admin-ui-starter-kit/base/date-pickers` |
 | Map or place autocomplete | map family | `admin-ui-starter-kit/base/map` |
 | KPI cards and chart cards | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
+| Selected resource card | `ResourceSelectorCard` | `admin-ui-starter-kit/composed/data-display` |
+| Settings/security action rows and token manager | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` | `admin-ui-starter-kit/composed/admin` |
 | Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
 | Timeline | timeline surfaces | `admin-ui-starter-kit/composed/timelines` |
 | Comments panel | `Comments` | `admin-ui-starter-kit/features/comments` |
-| Filter bar/facets | filters feature | `admin-ui-starter-kit/features/filters` |
+| Filter bar/facets/query helpers | filters feature, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` | `admin-ui-starter-kit/features/filters` |
 | Dialog, drawer, alert dialog | overlays feature | `admin-ui-starter-kit/features/overlays` |
 | Global search shell | global search feature | `admin-ui-starter-kit/features/global-search` |
 | Media picker, asset library, product gallery field | `MediaLibrary`, `MediaLibraryDialog`, `useMediaLibrary` | `admin-ui-starter-kit/features/media-library` |
@@ -40,6 +44,8 @@ or documented here, treat it as private.
 | Rich text editor | TipTap-backed editor | `admin-ui-starter-kit/features/rich-text-editor` |
 | Auth card or split-page chrome | `AuthShell`, `AuthCard`, `AuthSplitPanel`, social/policy/language slots | `admin-ui-starter-kit/layout/auth` |
 | Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
+| Resource index/show page chrome | resource layout | `admin-ui-starter-kit/layout/resource` |
+| Settings/aside navigation page chrome | `SettingsShell`, `AsideNavShell` | `admin-ui-starter-kit/layout/settings` |
 | Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
 | Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
 | Shared action lifecycle across page/table/card/command/overlay surfaces | actions service | `admin-ui-starter-kit/services/actions` |
@@ -112,6 +118,27 @@ uploading, metadata updates, routing, and storage through props such as
 `fetcher`, `onUpload`, `onItemUpdate`, `onItemDelete`, `value`, and
 `onValueChange`.
 
+Use `AsyncResourceCombobox` when a selector fetches remote resources by search
+query. The package owns debounce, loading, empty, error, abort, clear, and
+keyboard behavior; the app supplies `fetcher`, accessors, translations, and
+error telemetry.
+
+Use `ResourceSelectorCard` for a selected resource inside forms, dialogs, or
+show pages. The app owns the picker overlay and routing; the card only renders
+the selected resource through accessors and calls `onSelect` / `onRemove`.
+
+Use `DataTable` selection toolbar props plus `ResourceCell`,
+`StatusClusterCell`, and `DateMetaCell` for dense index pages. Keep URL state,
+sorting persistence, row navigation, and data fetching in the app.
+
+Use `parseFiltersFromQuery`, `serializeFiltersToQuery`, and `mergeFilterQuery`
+to bridge filters with URL search params. They return plain query records and
+never navigate.
+
+Use `SettingsShell` / `AsideNavShell` for settings pages with a left nav and
+content slot. Pass `renderLink` for framework-native links; keep permissions
+and route generation in the app.
+
 Typography is not optional glue. Use `Text`, `Heading`, `Label`, and `TextLink`
 from `admin-ui-starter-kit/typography` instead of raw font-size, weight, or
 muted-color utility classes.

package/INTEGRATION.md

@@ -37,18 +37,24 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Carousel } from 'admin-ui-starter-kit/base/carousel';
-import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { AsyncResourceCombobox, EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { DataTable, ResourceCell } from 'admin-ui-starter-kit/base/table';
 import { ControlledFormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
 import { Frame } from 'admin-ui-starter-kit/base/frame';
 import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/base/item';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
 import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
+import { ActionList, ApiTokenManager } from 'admin-ui-starter-kit/composed/admin';
+import { ResourceSelectorCard } from 'admin-ui-starter-kit/composed/data-display';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { mergeFilterQuery, parseFiltersFromQuery, serializeFiltersToQuery } from 'admin-ui-starter-kit/features/filters';
 import { MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library';
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
 import { PageHeader } from 'admin-ui-starter-kit/layout/page';
+import { ResourceIndexShell, ResourceShowShell } from 'admin-ui-starter-kit/layout/resource';
+import { SettingsShell } from 'admin-ui-starter-kit/layout/settings';
 import { ActionProvider, ActionOverlayOutlet } from 'admin-ui-starter-kit/services/actions';
 ```
 
@@ -85,6 +91,23 @@ Common primitive choices:
 - Use `EnhancedCombobox` / `EnhancedComboboxMultiple` for searchable selects;
   wrap them in `ControlledFormField` inside forms and pass `invalid={invalid}`
   from the render-prop.
+- Use `AsyncResourceCombobox` for remote resource selectors. The component owns
+  debounce, abort, loading, empty, clear, keyboard, and error-display state;
+  the app supplies `fetcher`, accessors, strings, and `onError`.
+- Use `DataTable` with `ResourceCell`, `StatusClusterCell`, and `DateMetaCell`
+  for index pages. The package owns table ergonomics and selected-row chrome;
+  the app owns sorting/query persistence, data fetching, row routing, and
+  backend state.
+- Use `parseFiltersFromQuery`, `serializeFiltersToQuery`, and
+  `mergeFilterQuery` to synchronize filters with URL search params. They
+  return plain records; the consuming app decides how to navigate.
+- Use `ResourceIndexShell`, `ResourceShowShell`, `TabbedResourceShell`, and
+  `SettingsShell` for page chrome. Pass `renderLink` for framework-native
+  links and keep route generation/permissions in the app.
+- Use `ResourceSelectorCard`, `ActionList`, `SensitiveActionCard`, and
+  `ApiTokenManager` for selected-resource, settings, security, and token
+  management surfaces. Persistence and confirmation behavior stay callback
+  driven.
 - Use `SchemaForm` from `admin-ui-starter-kit/features/schema-form` when the
   app already has backend-provided field definitions, tenant settings, or
   integration configuration that should render as a cohesive form or section
@@ -157,7 +180,7 @@ components from a client component file (`'use client'`). The package is
 framework-neutral, but interactive UI still runs on the client.
 
 For shared actions, keep the registry framework-neutral and put framework
-calls inside callbacks:
+calls inside callbacks or provider adapters:
 
 ```tsx
 import {
@@ -165,6 +188,8 @@ import {
 	ActionProvider,
 	ActionScope,
 	type ActionDefinition,
+	type ActionRequestRunner,
+	type ActionRuntimeGlue,
 } from 'admin-ui-starter-kit/services/actions';
 
 const customerActions: ActionDefinition<Customer>[] = [
@@ -180,9 +205,71 @@ const customerActions: ActionDefinition<Customer>[] = [
 		run: ({ payload }) => router.delete(`/customers/${payload?.id}`),
 		successMessage: ({ payload }) => `${payload?.name} deleted`,
 	},
+	{
+		id: 'customer.archive',
+		label: 'Archive customer',
+		permission: 'customers.archive',
+		roles: ['admin', 'ops'],
+		modality: {
+			type: 'alert',
+			tone: 'warning',
+			title: ({ payload }) => `Archive ${payload?.name}?`,
+			confirmLabel: 'Archive',
+		},
+		request: {
+			method: 'post',
+			target: ({ payload }) => ({
+				type: 'named',
+				name: 'customers.archive',
+				params: payload?.id,
+			}),
+			options: { preserveScroll: true },
+		},
+		successMessage: ({ payload }) => `${payload?.name} archived`,
+	},
 ];
 
-<ActionProvider feedback={{ onSuccess: (event) => event.message && toast.success(event.message) }}>
+const requestRunner: ActionRequestRunner = async (request) => {
+	if (request.target?.type === 'named') {
+		return appVisit(appRoute(request.target.name, request.target.params), {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	if (request.target?.type === 'url') {
+		return appHttp(request.target.url, {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	throw new Error('Action request target is missing.');
+};
+
+const actionRuntime: ActionRuntimeGlue = {
+	requestRunner,
+	feedback: {
+		onSuccess: (event) => {
+			if (event.message) toast.success(event.message);
+			queryClient.invalidateQueries({ queryKey: [event.actionId] });
+		},
+		onError: (event) => event.message && toast.error(event.message),
+	},
+	guards: {
+		can: (permission) => auth.can(permission),
+		hasAnyRole: (roles) => auth.hasAnyRole(roles),
+	},
+	parseErrors: (error) => parseBackendActionError(error),
+	onOverlayOpenChange: (open) => polling.setPaused(open),
+	onRunningChange: (running) => activity.setBusy(running),
+};
+
+<ActionProvider runtime={actionRuntime}>
 	<ActionScope scope={`customer:${customer.id}`} actions={customerActions}>
 		<CustomerPage />
 	</ActionScope>
@@ -190,6 +277,14 @@ const customerActions: ActionDefinition<Customer>[] = [
 </ActionProvider>;
 ```
 
+Use `useLocalAction(definition, options)` for one page-owned action during an
+incremental migration. Use `<ActionScope>` and `useActionSurface(...)` once the
+same definition needs to appear in page actions, table row menus, command
+palette entries, cards, or action-owned overlays. `ActionOverlayOutlet` renders
+action modality through the package `features/overlays`, so reusable modal
+workflows keep the same focus, backdrop, loading, submit, and error behavior as
+direct overlay usage.
+
 For form actions, set `modality.formId` and render a form through the modality
 render prop. The context exposes `getFormProps(...)`, `submit(values)`,
 `errors`, and loading/status flags. Keep `react-hook-form`, validation schemas,

package/README.md

@@ -186,25 +186,108 @@ loading/error/overlay lifecycle. Keep one-off dialogs local with
 import {
   ActionOverlayOutlet,
   ActionProvider,
+  useLocalAction,
+  type ActionRequestRunner,
+  type ActionRuntimeGlue,
 } from 'admin-ui-starter-kit/services/actions';
 
-<ActionProvider
-  feedback={{
-    onSuccess: (event) => event.message && toast.success(event.message),
-    onError: (event) => event.message && toast.error(event.message),
-  }}
->
+const requestRunner: ActionRequestRunner = async (request) => {
+  const method = request.method;
+  const target = request.target;
+
+  if (target?.type === 'named') {
+    return appVisit(appRoute(target.name, target.params), {
+      ...request.options,
+      method,
+      data: request.data,
+      headers: request.headers,
+    });
+  }
+
+  if (target?.type === 'url') {
+    return appHttp(target.url, {
+      ...request.options,
+      method,
+      data: request.data,
+      headers: request.headers,
+    });
+  }
+
+  throw new Error('Action request target is missing.');
+};
+
+const actionRuntime: ActionRuntimeGlue = {
+  requestRunner,
+  feedback: {
+      onSuccess: (event) => event.message && toast.success(event.message),
+      onError: (event) => event.message && toast.error(event.message),
+  },
+  guards: {
+    can: (permission) => auth.can(permission),
+    hasAnyRole: (roles) => auth.hasAnyRole(roles),
+  },
+  parseErrors: (error) => {
+    const response = error as {
+      errors?: Record<string, string | string[]>;
+      message?: string;
+    };
+
+    return {
+      fieldErrors: response.errors,
+      message: response.message ?? 'Action failed.',
+    };
+  },
+  onOverlayOpenChange: (open) => polling.setPaused(open),
+  onRunningChange: (running) => activity.setBusy(running),
+};
+
+<ActionProvider runtime={actionRuntime}>
   <App />
   <ActionOverlayOutlet />
 </ActionProvider>
 ```
 
+Actions can be callback-driven with `run`, or data-driven through `request`
+plus a provider/action `requestRunner`. Provider `guards` keep permission and
+role checks app-owned, while `parseErrors` normalizes backend validation
+payloads into `action.errors` and failed lifecycle messages. Use
+`useLocalAction` for incremental page-owned migrations, and use
+`<ActionScope>` + `useActionSurface` when one definition needs to power page,
+table, card, command, or overlay surfaces.
+
+```tsx
+const confirmBooking = useLocalAction<Booking, { note: string }, Booking>({
+  id: 'booking.confirm',
+  label: 'Confirm booking',
+  permission: 'bookings.confirm',
+  modality: {
+    type: 'dialog',
+    title: ({ payload }) => `Confirm ${payload?.reference}`,
+    formId: 'confirm-booking-form',
+    render: ({ getFormProps, isRunning }) => (
+      <form {...getFormProps()} id="confirm-booking-form">
+        <textarea name="note" disabled={isRunning} />
+      </form>
+    ),
+  },
+  request: {
+    method: 'post',
+    target: ({ payload }) => ({
+      type: 'named',
+      name: 'bookings.confirm',
+      params: payload?.id,
+    }),
+    data: ({ values }) => values,
+  }}
+}, { payload: booking });
+```
+
 Pages register contextual actions with `useRegisterActions` or
 `<ActionScope>`. Routing, permissions, translations, cache invalidation, and
-toasts stay in the consuming app through callbacks. Resolved actions expose
-`status`, `isRunning`, `isSuccess`, `isError`, `errors`, `result`, and
-timestamps; overlay form actions can use `modality.formId` with
-`getFormProps(...)` in the render context.
+toasts stay in the consuming app through callbacks, provider adapters, and
+lifecycle hooks. Resolved actions expose `status`, `isRunning`, `isSuccess`,
+`isError`, `errors`, `message`, `result`, and timestamps; overlay form actions
+can use `modality.formId` with `getFormProps(...)` in the render context.
 
 ### 7. Install the AI agent skills (optional)
 
@@ -356,17 +439,25 @@ import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Frame, FramePanel } from 'admin-ui-starter-kit/base/frame';
 import { Item, ItemGroup, ItemMedia, ItemContent, ItemTitle } from 'admin-ui-starter-kit/base/item';
-import { ControlledFormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
-import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { ControlledFormField, FormSection, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
+import { DataViewShell, DataViewToolbar } from 'admin-ui-starter-kit/base/data-view';
+import { AsyncResourceCombobox, EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { DataTable, ResourceCell, StatusClusterCell } from 'admin-ui-starter-kit/base/table';
 import { Badge } from 'admin-ui-starter-kit/base/badge';
 import { Alert } from 'admin-ui-starter-kit/base/display';
 import { Carousel, CarouselContent, CarouselItem } from 'admin-ui-starter-kit/base/carousel';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
+import { ActionList, ApiTokenManager } from 'admin-ui-starter-kit/composed/admin';
 import { ContactCard } from 'admin-ui-starter-kit/composed/cards';
+import { ResourceSelectorCard } from 'admin-ui-starter-kit/composed/data-display';
 import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { parseFiltersFromQuery, serializeFiltersToQuery } from 'admin-ui-starter-kit/features/filters';
 import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
+import { HeaderToolButton, HeaderToolPopover } from 'admin-ui-starter-kit/layout/header';
+import { ResourceIndexShell, ResourceShowShell, TabbedResourceShell } from 'admin-ui-starter-kit/layout/resource';
+import { SettingsShell } from 'admin-ui-starter-kit/layout/settings';
 import { ActionProvider, ActionOverlayOutlet } from 'admin-ui-starter-kit/services/actions';
 import { useStrings } from 'admin-ui-starter-kit/lib/strings';
 ```
@@ -386,11 +477,14 @@ Safe public entrypoint shapes:
 - `admin-ui-starter-kit/ui-provider`
 - `admin-ui-starter-kit/typography`
 - `admin-ui-starter-kit/base/buttons`, `admin-ui-starter-kit/base/item`, etc.
+- `admin-ui-starter-kit/base/data-view`
+- `admin-ui-starter-kit/base/table`
+- `admin-ui-starter-kit/base/combobox`
 - `admin-ui-starter-kit/base/display/metadata`
 - `admin-ui-starter-kit/base/display/chart`
-- `admin-ui-starter-kit/composed/cards`, `admin-ui-starter-kit/composed/analytics`, etc.
+- `admin-ui-starter-kit/composed/cards`, `admin-ui-starter-kit/composed/analytics`, `admin-ui-starter-kit/composed/admin`, etc.
 - `admin-ui-starter-kit/features/comments`, `admin-ui-starter-kit/features/filters`, `admin-ui-starter-kit/features/schema-form`, etc.
-- `admin-ui-starter-kit/layout` and exact layout families such as `admin-ui-starter-kit/layout/page`
+- `admin-ui-starter-kit/layout` and exact layout families such as `admin-ui-starter-kit/layout/page`, `admin-ui-starter-kit/layout/resource`, `admin-ui-starter-kit/layout/settings`
 - `admin-ui-starter-kit/services/actions`
 - `admin-ui-starter-kit/lib/strings`
 - `admin-ui-starter-kit/lib/utils`