@nocobase/app-template-default 1.0.0-beta.87 → 1.0.0-beta.89

package/.agents/rules/components.md

@@ -15,7 +15,7 @@ yes n | pnpm exec shadcn add card
 pnpm exec prettier --write client/components/ui/card.tsx
 ```
 
-Build your own components by composing these primitives, and put them in `client/components/`. A page below another one — a covering child page, a record's own page — leaves by the header's breadcrumb when its route declares `breadcrumb` or the page declares its trail with `usePageBreadcrumb`, and otherwise by `BackButton` (`client/components/back-button.tsx`) above its heading; never both.
+Build your own components by composing these primitives, and put them in `client/components/`. A covering child page, independent detail or edit declares its complete navigation with `breadcrumb` or `usePageBreadcrumb`; the shell renders desktop breadcrumbs and the mobile parent arrow. Declare dynamic/logic parents before loading succeeds and keep them on failure. Use `BackButton` only without that shell navigation, with route/access context for target validation; never show duplicate return entries.
 
 **Look components up in the shadcn skill.** The development Skill carries the shadcn/ui skill, unchanged from shadcn 4.21.0, in `.agents/skills/nocobase-app-development/references/frontend/shadcn/`. Read [the shadcn guide](../skills/nocobase-app-development/references/frontend/references/shadcn.md) first: it routes to the skill's rules and states where this application departs from them, among others `pnpm exec shadcn` instead of `npx shadcn@latest`, no `shadcn apply` or `--preset`, and create, edit and detail as `RouteDialog` or `RouteDrawer` child routes rather than a `Sheet`. `pnpm exec shadcn docs <name>` gives one primitive's documentation and examples for the Base UI version. For a whole page, start from the worked example that [the example index](../skills/nocobase-app-development/references/frontend/references/example.md) indexes.
 
@@ -31,6 +31,8 @@ Style with the semantic Tailwind tokens — `bg-background`, `text-foreground`,
 
 The default brand palette and density live in `client/theme/themes/*.css`; shared hover/cursor and Badge geometry live in `client/styles.css`, outside generated shadcn primitives. For semantic status labels, use `StatusBadge` from `client/components/status-badge.tsx` with `neutral`, `info`, `warning`, or `success`; choose the tone by meaning and keep the visible status text. A badge beside a title or on a dense card is the small one, `size='sm'` on `StatusBadge` or `data-size='sm'` on `Badge`. Reuse these shared components and tokens in new pages so template upgrades can carry the design consistently.
 
+Dialog and AlertDialog footer actions use the shared semantic-slot sizing rule in `client/styles.css`, including linked Buttons and RouteOverlay's composed DialogFooter. Keep route links and pending guards; avoid page height/padding patches. The [footer contract](../skills/nocobase-app-development/references/frontend/references/overlay.md#footer-ownership) explains precedence, wrapping and the source upgrade path for existing applications.
+
 **Follow the UI guidelines.** [The UI guidelines](../skills/nocobase-app-development/references/frontend/ui-guidelines.md) set the conventions every page follows, among them the page header and the single placement of the primary action, empty states, row actions behind one "…" menu, dates picked from a `Calendar` in a `Popover` rather than a native date input, and medium-width drawers; the frontend workflow says how much of it to read for a change.
 
 ## Standard process management

package/.agents/rules/notification-templates.md

@@ -0,0 +1,5 @@
+# Notification template administration
+
+When notification business is used, register the real scenarios alongside their shared sending renderers and deliver the read-only template directory with synthetic preview. Read the installed Notification Skill’s `references/template-directory.md` for registration, safety and coverage requirements. The app-owned `NotificationManagementProvider` projects only `client.notificationTemplates.invitationConfigured` from the same channel selector used by Users sending and the directory. Default's runtime route factory calls `includeNotificationTemplateRoutes` with that bootstrap flag; a configured invitation mailer (including a configured but disabled legacy channel) is real business use. No transport configuration enters the browser. Restart after changing server mailer configuration. The helper reuses `notificationManagement` and preserves existing log children, paths and grants; when integrating a richer settings module container, insert `notificationTemplateRoute` into its template view once. Preserve the host's settings navigation container. The template page permission and API permission are both `page:notification.templates/access`; grant it only to intended administrators. Default does not register unused business settings. Examples registers task assignment/update and Users invitation scenarios.
+
+For an existing application, follow the installed upgrade Skill’s version-selected workflow and `references/notification-template-upgrade.md`. Reconcile source, dependency ranges and Skills; retain custom templates, workflows, grants and data. Updating packages alone does not insert or update application pages.

package/.agents/rules/shell.md

@@ -4,6 +4,8 @@ Read this before changing the layouts, header, sidebar, breadcrumbs, account men
 
 ## Breadcrumbs and layouts
 
+Both automatic and explicit parents pass through `client/routing/navigation-destination.ts`, using the shell's existing route/access context. Keep permission loading fail-closed, check every target ancestor, and remove denied parent names. Desktop breadcrumbs and the mobile parent arrow use the same resolved levels; mobile keeps the current title and omits the duplicate brand. Follow the [detail/edit generation contract](../skills/nocobase-app-development/references/frontend/references/navigation.md), including stable parents during record failures, source-tab state and direct-entry defaults. Do not add a second page BackButton under the shell.
+
 Layouts own breadcrumb route context and render the current page's trail in the header after the sidebar toggle (`client/components/breadcrumbs.tsx`): the route trail by default, or the trail a page declares with `usePageBreadcrumb` from `@nocobase/app-client` when it names records. Pages do not render breadcrumbs themselves. `AppRouter` selects routes and layouts. See [pages and routes](../skills/nocobase-app-development/references/frontend/references/page.md) for each layout's scope.
 
 The route-tree provider remembers each visited ancestor's query while its descendants are open. Default breadcrumbs and back links restore that query, including an empty one, instead of applying detail-only parameters to the list. Keep this provider mounted above page navigation. Explicit breadcrumb/back destinations remain application-owned. See the linked pages-and-routes reference for deep-link and reload fallbacks.
@@ -12,7 +14,7 @@ The route-tree provider remembers each visited ancestor's query while its descen
 
 `client/layouts/components/layout-header.tsx` is a presentation container accepting children. The sidebar is shadcn's Sidebar: `components/app-sidebar.tsx` wraps its provider, desktop icon mode and phone sheet, and `components/navigation-menu.tsx` draws the permission-filtered route tree with `SidebarMenu*`: a top-level group with no page of its own is a section, its entries always shown under a `SidebarGroupLabel` heading, while clickable parents and nested groups are controlled `Collapsible` sub-menus, and an item `client/lib/navigation-transform.ts` marks `section` deeper in the tree is a heading over its direct links inside that menu; a count beside an entry, such as unread items, is passed by the App layout in `NavigationMenu`'s `badges`, keyed by route name. Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it except for removing its unused origin-wide `sidebar_state` cookie write; persistence belongs to the application-scoped preference. Customize from outside: widths go through the provider's `style` in spacing units, the phone sheet is rendered in `app-sidebar.tsx` with a translated title, and the provider's Ctrl/Cmd+B shortcut is stopped at `document`. The App layout owns menus, branding, permissions and redirects. Desktop icon mode hides top-level section headings and keeps their entries' icons, shows leaf labels as zero-delay tooltips and opens groups in hover and keyboard-focus popovers, preserving filtered navigation, parent-page links, nested groups and the selected group's highlight. Keep this behavior aligned across layouts. Desktop collapse state is shared through `useSidebarPreference` at `nocobase:sidebar:collapsed:app:<basename>` across layouts and tabs of the same application. `createApp(runtime)` provides a stable store using `runtime.basename`, with only empty/root and boundary slashes normalized; paths and case remain intact. Missing new keys default to expanded without migrating the old shared preference; whether the phone sheet is open stays local to each layout.
 
-The header carries no Settings or Inbox entry. An application has no separate settings area: a page that configures something is an ordinary route in `client/routes.ts` with `navigation`, placed in the sidebar like any other page, for example under a Settings navigation group. The `/inbox` page declares no navigation; give it an entry where the application wants one.
+The header carries no Settings or Inbox entry, and there is no separate settings layout. A page that configures something is an ordinary route in `client/routes.ts` registered into System settings: the `settings` group (`client/pages/settings/shell-routes.ts`) with its `settingsHome` page and category groups. `client/lib/navigation-transform.ts` folds that group into one sidebar entry opening the home, which stays selected on every page below it; the home (`client/pages/settings/settings-home.tsx`) shows the modules a viewer may open as cards by category, and `SettingsModulePage` turns the pages of a module group into URL-backed tabs. Both read the shell's single page permission check through `RouteTreeProvider`'s `access`. See [System settings navigation](../skills/nocobase-app-development/references/settings-navigation.md). The `/inbox` page declares no navigation; give it an entry where the application wants one.
 
 `client/lib/navigation-transform.ts` is the application-owned hook for customizing the permission-filtered navigation tree. The shared sidebar supports static section labels with direct links as well as collapsible groups.
 
@@ -24,13 +26,13 @@ Theme lives in the account menu as a submenu beside Language, rather than a sepa
 
 The account menu checks Better Auth sign-out results before refreshing the session and shows a localized error toast for API or network failures. Preserve this behavior when upgrading the shell; navigation alone does not revoke a session.
 
-The authorization provider clears the permission snapshot before rendering a new session. Route navigation and page guards subscribe to the authorization revision; preserve these checks when customizing the shell so account changes and permission updates take effect without a reload. Pending checks hide protected content, and failed checks deny access.
+The authorization provider clears the permission snapshot before rendering a new session. Route navigation and page guards subscribe to the authorization revision; preserve these checks when customizing the shell so account changes and permission updates take effect without a reload. Keep `RouteLeaveBoundary` in `AppLayout`, outside all page Activities including nested routes, so `useSettingsLeave` navigation guards, confirmation UI and `beforeunload` survive permission checks. Clear retained guards on denial and session changes. Restored Activity Effects re-run existing data requests. Keep each resolved route module for the same loader and retry attempt when Activity reconnects; namespace-wrapping loaders may return a new component type on every invocation and discard form state if invoked again. Pending checks hide protected content with React Activity while retaining drafts; failed checks unmount it and deny access. Body portals must detach in an Effect cleanup so they also disappear while the page is hidden; use `BodyPortal` from `#components/body-portal` for application-owned content mounted on `document.body`.
 
 The account menu language control in `client/layouts/components/language-switcher.tsx` uses a shadcn submenu with radio items. Render it inside `DropdownMenuContent` to preserve menu keyboard navigation and selection semantics.
 
 ## Branded loading
 
-Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapter to `BrandSpinner`) for inline pending actions, uploads, and refresh indicators. Both share the stable NocoBase mark and orbit animation; do not introduce independent Lucide spinners for application loading. Keep skeletons for content placeholders and progress bars for determinate progress. `index.html` has the matching pre-JavaScript mark and must stay visually consistent. All animations respect reduced motion.
+Follow [pending feedback](../skills/nocobase-app-development/references/pending-feedback.md) for shared 300ms display and 10s long-wait guidance. Use `PendingButton` with real `submitting` for native form actions; preserve the shared submission lock. Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapter to `BrandSpinner`) for inline pending actions, uploads, and refresh indicators. Both share the stable NocoBase mark and orbit animation; do not introduce independent Lucide spinners for application loading. Keep skeletons for content placeholders and progress bars for determinate progress. `index.html` has the matching pre-JavaScript mark and must stay visually consistent. All animations respect reduced motion.
 
 The shared list of shell behaviors to keep when customizing is in [customizing the shell](../skills/nocobase-app-development/references/frontend/references/shell.md).
 
@@ -39,3 +41,7 @@ The signed-in region waits in `client/routing/session-preparation.tsx` before mo
 ## List context
 
 Keep the identity-keyed `SessionPreparation` boundary: mounted private list conditions and ancestor query memory must be discarded when the signed-in user changes. Public list state uses `useTableUrlState`; tabbed datasets use `useListTabs`, with complete owned parameter keys and permission-filtered tabs. Follow the synchronized [list navigation rules](../skills/nocobase-app-development/references/frontend/references/child-routes.md#list-tab-breadcrumbs-and-private-conditions). Default back links use an empty ancestor query when no source visit exists; explicit return destinations remain application-owned.
+
+## Page data freshness
+
+Follow the synchronized [page data freshness rules](../skills/nocobase-app-development/references/frontend/references/page-freshness.md): ordinary pages have no persistent Refresh action. Preserve contextual read retries, write invalidation and live progress updates. Dependency upgrades do not rewrite application-owned pages or installed Registry source; reconcile them through the template upgrade workflow.

package/AGENTS.md

@@ -57,13 +57,13 @@ A feature with a page and an API touches five places: a migration for the table,
 
 ## System settings are part of feature delivery
 
-A bare create-app shows Home to signed-in users and System settings → App foundation only to unrestricted administrators. The Foundation plugin owns this initial settings group; the navigation transform merges its entry into the application settings group when business administration is registered. As the application develops business capabilities, inspect its current state on every iteration and automatically register the prepared Users and Roles and permissions contribution from `client/pages/settings/routes.ts` once in `client/routes.ts`; preserve it and reconcile missing management surfaces on every iteration, without a first-build flag or one-time setup stage. Whenever an application adds lifecycles, workflows, approvals, notifications, files or other configurable capabilities, automatically include their real administration surfaces without requiring a second user request. Follow [system settings delivery](.agents/skills/nocobase-app-development/references/system-settings.md); in particular, every used process includes a definitions directory, standard diagram, supported parameters and authorized execution history. Do not add demo plugins or empty settings for unused capabilities. The template preinstalls `#components/lifecycle-diagram` (React Flow + ELK) and `client/extensions/nocobase-workflow-management/`: use them by default, preserve their visuals unless the user explicitly requests another style, and connect authorized parameter bindings through `LifecycleDiagram.configuration` to the real editor. These are UI Registry sources; an npm package lookup is not a component availability check.
+A bare create-app shows Home to signed-in users and, only to unrestricted administrators, one System settings entry whose home page holds the App foundation card. Every administration surface joins that structure — one sidebar entry, a home of cards by category, tabs inside a module — as [System settings navigation](.agents/skills/nocobase-app-development/references/settings-navigation.md) describes; never add another sidebar entry for administration. As the application develops business capabilities, inspect its current state on every iteration and automatically register the prepared Users and Permission management contribution from `client/pages/settings/routes.ts` once in `client/routes.ts`; preserve it and reconcile missing management surfaces on every iteration, without a first-build flag or one-time setup stage. Whenever an application adds lifecycles, workflows, approvals, notifications, files or other configurable capabilities, automatically include their real administration surfaces without requiring a second user request. Follow [system settings delivery](.agents/skills/nocobase-app-development/references/system-settings.md); in particular, every used process includes a definitions directory, standard diagram, supported parameters and authorized execution history. Do not add demo plugins or empty settings for unused capabilities. The template preinstalls `#components/lifecycle-diagram` (React Flow + ELK) and `client/extensions/nocobase-workflow-management/`: use them by default, preserve their visuals unless the user explicitly requests another style, and connect authorized parameter bindings through `LifecycleDiagram.configuration` to the real editor. These are UI Registry sources; an npm package lookup is not a component availability check.
 
 ## Rules that apply everywhere
 
 ### Pages and routes
 
-Declare every page in `client/routes.ts` with `defineAppRoutes()` and keep its component behind a lazy `componentLoader` whose module default-exports it. Never write the deployment base path such as `/main` into a route — the runtime restores it. `auth` controls browser navigation only and is not server security. Declare `navigation` on the route to put it in a menu, and always declare `authz` on the first page of every path; the page id identifies stored page grants, so changing it requires migrating the grants that reference it. Read [pages and routes](.agents/skills/nocobase-app-development/references/frontend/references/page.md), and [overlays](.agents/skills/nocobase-app-development/references/frontend/references/overlay.md) before implementing dialogs, drawers or close guards.
+Declare every page in `client/routes.ts` with `defineAppRoutes()` and keep its component behind a lazy `componentLoader` whose module default-exports it. Never write the deployment base path such as `/main` into a route — the runtime restores it. `auth` controls browser navigation only and is not server security. Declare `navigation` on the route to put it in a menu, and always declare `authz` on the first page of every path; the page id identifies stored page grants, so changing it requires migrating the grants that reference it. Every new independent detail/edit page follows the [navigation pattern](.agents/skills/nocobase-app-development/references/frontend/references/navigation.md), including a parent during loading/errors and mobile return; omit duplicate page back links under the shell. Read [pages and routes](.agents/skills/nocobase-app-development/references/frontend/references/page.md), and [overlays](.agents/skills/nocobase-app-development/references/frontend/references/overlay.md) before implementing dialogs, drawers or close guards.
 
 Every route listed as a page permission needs a localized display name: use its existing navigation/breadcrumb title, or add its application route name to `client/pages/settings/page-permission-titles.ts` for an overlay or other page with no title metadata. Do not add breadcrumbs/menus just to label an overlay. Run `tests/client/page-permission-titles.test.ts`; it requires non-empty English/Chinese labels and rejects missing or stale mappings. Never rename route/permission ids or change `authz` to fix display text.
 
@@ -138,3 +138,5 @@ Standard Repository writes require an operation key through the registered submi
 Assign application business roles to explicitly identified users through the prepared User management role-assignment UI. Never seed a business permission set onto `authenticated:*`, broaden the inherited platform `member` role, or write startup reconciliation that grants access to everyone merely to make a feature usable. Unchecked actions in one role do not revoke grants inherited from another. If the user explicitly requests a global default role, first deliver a permission-protected administration control that shows its recipients and allows changing or removing the assignment; show inherited roles and their source in user access details. Without that UI, use explicit user assignments and explain the limitation. Keep page access independent from business operations.
 
 Run `pnpm exec vitest run tests/server/authorization-assignment-safety.test.ts` after permission initialization changes and before delivery. It boots the real application on an isolated database and inspects initialized wildcard assignments and the inherited member role. Keep this test in generated applications. An intentional global default requires explicit user authorization, a working administration surface and corresponding acceptance tests before deliberately updating the expected baseline; do not delete, skip or loosen the guard to make tests pass. Test an ordinary user with only the configured role: inspect all effective grant sources and verify both hidden buttons and rejected direct API calls.
+
+For notification business, follow [notification template delivery](.agents/rules/notification-templates.md), including source-owned scenario registration and synthetic-only preview.

package/README.MD

@@ -139,11 +139,11 @@ The three files named `runtime.ts`, `plugins.ts`, and `routes.ts` are compositio
 
 ### Everyday development
 
-| Script             | What it does                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| `pnpm dev`         | Start the API server and client with hot reload                                      |
-| `pnpm build`       | Build the client and server into `dist/`                                             |
-| `pnpm start`       | Run the built server; requires `pnpm build` first                                    |
+| Script             | What it does                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm dev`         | Start the API server and client with hot reload                                                                                 |
+| `pnpm build`       | Build the client and server into `dist/`                                                                                        |
+| `pnpm start`       | Run the built server; requires `pnpm build` first                                                                               |
 | `pnpm build --tar` | Build, then pack `dist/`, `config.example.yml` and the `Dockerfile` with its `.dockerignore` into `storage/exports/dist.tar.gz` |
 
 ### Database
@@ -453,3 +453,9 @@ Set `NOCOBASE_STRICT_STARTUP=true` when running `pnpm dev` or `pnpm start` in au
 ## Internal workspace packages
 
 The application can also be the root of a pnpm workspace, with internal packages under `packages/*` and the existing `client/`, `server/` and `database/` directories unchanged. New projects receive this workspace pattern automatically. Internal packages use `workspace:*` dependencies and may remain private. Run installation, development and deployment builds from the application root; `pnpm check` includes the internal packages' own checks. See [internal packages](.agents/rules/workspace.md) for configuration and development conventions.
+
+### Registration feedback
+
+Password registration signs in new accounts by default (`auth.emailAndPassword.autoSignIn: true` in `server/config/auth.ts` and `config.example.yml`). An existing email returns an explicit error, exposing whether that email is registered. For enumeration protection, explicitly set `autoSignIn: false` and configure email verification with a sender or `onExistingUserSignUp` to notify the email owner. Existing explicit overrides remain effective; no configuration migration is performed. The authentication plugin warns at startup about registration with auto sign-in disabled and neither verification nor an existing-user notification.
+
+The registration page treats `usePasswordRegistration().isSuccess` as request acceptance only. A refreshed session navigates signed-in users into the application. Visitors who remain signed out see neutral sign-in and recovery guidance, without an account-creation or email-delivery promise. Applications customizing this page must keep that distinction.

package/client/components/back-button.tsx

@@ -1,16 +1,21 @@
 import { useTranslation } from '@nocobase/i18n/client';
 import { ArrowLeftIcon } from 'lucide-react';
 import type { ReactElement, ReactNode } from 'react';
-import { Link, type To, useResolvedPath } from 'react-router';
+import { Link, type To, parsePath, useResolvedPath } from 'react-router';
 
-import { useRouteSearches } from '../routing/route-context.js';
+import { navigationDestination } from '../routing/navigation-destination.js';
+import {
+  useRouteTree,
+  useRouteAccess,
+  useRouteSearches,
+} from '../routing/route-context.js';
 
 import { cn } from 'cn';
 
 export interface BackButtonProps {
   /**
    * Where it leads. Defaults to the parent route with its last visited query; a directly opened detail falls back
-   * to the default parent list. An explicit destination is kept unchanged.
+   * to the default parent list. An explicit destination must match an authorized application page.
    */
   readonly to?: To;
   /** The label, "Back" by default. */
@@ -31,11 +36,36 @@ export function BackButton({
   children,
   className,
   to,
-}: BackButtonProps = {}): ReactElement {
+}: BackButtonProps = {}): ReactElement | null {
   const { t } = useTranslation();
   const parent = useResolvedPath('..');
+  const resolved = useResolvedPath(to ?? '..');
+  const routes = useRouteTree();
+  const access = useRouteAccess();
   const searches = useRouteSearches();
 
+  const fallback = {
+    ...parent,
+    search: searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
+  };
+  const rawPath =
+    typeof to === 'string' ? parsePath(to).pathname : to?.pathname;
+  const unsafe =
+    rawPath &&
+    (/^(?:[a-z][a-z\d+.-]*:|\/\/)/iu.test(rawPath) ||
+      rawPath.includes('\\') ||
+      [...rawPath].some((character) => character.charCodeAt(0) <= 32));
+  const primary = unsafe
+    ? undefined
+    : navigationDestination(
+        to && rawPath?.startsWith('/') ? to : to ? resolved : fallback,
+        routes,
+        access,
+      );
+  const destination =
+    primary ?? navigationDestination(fallback, routes, access);
+  if (!destination) return null;
+
   return (
     <Link
       replace
@@ -43,16 +73,11 @@ export function BackButton({
         'inline-flex w-fit items-center gap-1 text-sm text-muted-foreground transition-colors hover:text-foreground',
         className,
       )}
-      to={
-        to ?? {
-          pathname: '..',
-          search:
-            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
-        }
-      }
+      to={destination}
     >
       <ArrowLeftIcon className='size-4' />
-      {children ?? t('navigation.back', { defaultValue: 'Back' })}
+      {(primary ? children : undefined) ??
+        t('navigation.back', { defaultValue: 'Back' })}
     </Link>
   );
 }

package/client/components/body-portal.tsx

@@ -0,0 +1,25 @@
+import {
+  useLayoutEffect,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+export interface BodyPortalProps {
+  readonly children: ReactNode;
+}
+
+/** Detach body content when its page is hidden by Activity, retaining its React state for the next permission result. */
+export function BodyPortal({ children }: BodyPortalProps): ReactElement {
+  const [container] = useState(() => {
+    const element = document.createElement('div');
+    element.style.display = 'contents';
+    return element;
+  });
+  useLayoutEffect(() => {
+    document.body.append(container);
+    return () => container.remove();
+  }, [container]);
+  return createPortal(children, container);
+}

package/client/components/brand-loading-mark.tsx

@@ -1,7 +1,10 @@
 import type { ComponentPropsWithoutRef, ReactElement } from 'react';
 import { cn } from 'cn';
 
-import { BRAND_MARK_PATH, BRAND_MARK_TRANSLATE } from './brand-mark-geometry';
+import {
+  BRAND_MARK_PATH,
+  BRAND_MARK_TRANSLATE,
+} from './brand-mark-geometry.js';
 
 /** Keep the brand recognizable; the orbit, rather than the bricks, conveys progress. */
 export function BrandLoadingMark({
@@ -25,7 +28,7 @@ export function BrandLoadingMark({
         strokeWidth='2'
         opacity='.12'
       />
-      <g className='nocobase-loading-orbit'>
+      <g className='origin-center motion-safe:animate-spin'>
         <path
           d='M32 4a28 28 0 0 1 28 28'
           stroke='currentColor'

package/client/components/brand-mark-geometry.ts

@@ -1,7 +1,7 @@
 /** Official Logomark vector from the supplied logos/Transparent/Vectors asset.
  * Keep geometry unchanged; color, size and decorative animation belong to consumers.
  */
-export const BRAND_MARK_VIEW_BOX = '0 0 100 87.19720458984375';
-export const BRAND_MARK_TRANSLATE = 'translate(0 -6.401886463165283)';
-export const BRAND_MARK_PATH =
+export const BRAND_MARK_VIEW_BOX: string = '0 0 100 87.19720458984375';
+export const BRAND_MARK_TRANSLATE: string = 'translate(0 -6.401886463165283)';
+export const BRAND_MARK_PATH: string =
   'M99.876 55.369c-.025-.045-.076-.072-.109-.111-.066-.078-.125-.168-.217-.221l-.014-.008-.001-.002h-.001L80.368 43.648v-24.67a.92.92 0 0 0-.124-.459c-.026-.045-.075-.072-.108-.111-.066-.08-.126-.168-.218-.221l-.014-.008-.001-.002h-.002L60.286 6.531a.92.92 0 0 0-.94 0L20.099 29.834h-.002l-.001.002-.014.006c-.092.055-.151.143-.218.221-.033.041-.082.068-.108.113a.907.907 0 0 0-.124.457v1.361L.466 43.373H.465l-.001.002c-.098.055-.162.143-.23.227-.034.041-.084.068-.109.113a.898.898 0 0 0-.125.457v25.195c0 .324.171.625.45.791l39.264 23.311c.002.002.006 0 .008.002l.007.008a.924.924 0 0 0 .911 0c.003-.002.004-.006.008-.008.001-.002.005 0 .007-.002l19.161-11.377 19.162 11.377c.002.002.006 0 .008.002.004.002.004.006.007.008a.924.924 0 0 0 .911 0c.003-.002.004-.006.008-.008.002-.002.005 0 .007-.002L99.55 81.812a.916.916 0 0 0 .45-.791V55.828a.92.92 0 0 0-.124-.459zM41.104 65.867V42.812l37.424-22.219v23.055L41.104 65.867zM59.815 8.391l17.83 10.588L59.82 29.561 40.185 41.219l-17.83-10.586 37.46-22.242zM39.264 42.812V65.866L21.472 55.305V32.248l17.792 10.564z';

package/client/components/breadcrumbs.tsx

@@ -1,6 +1,7 @@
 import { usePageBreadcrumbLevels } from '@nocobase/app-client';
 import type { PageBreadcrumbLevel } from '@nocobase/app-client';
 import { useTranslation } from '@nocobase/i18n/client';
+import { ArrowLeftIcon } from 'lucide-react';
 import { Fragment, type ReactElement } from 'react';
 import { Link } from 'react-router';
 
@@ -19,13 +20,17 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '#components/ui/dropdown-menu';
+import { settingsHomeRoute } from '#lib/navigation-transform';
 import { cn } from 'cn';
 
 import {
+  useRouteTree,
+  useRouteAccess,
   useRouteTrail,
   useRouteSearches,
   type RouteTrailEntry,
 } from '../routing/route-context.js';
+import { navigationDestination } from '../routing/navigation-destination.js';
 import { routeKey } from '../routing/route-navigation.js';
 
 export interface BreadcrumbsProps {
@@ -44,7 +49,7 @@ export interface BreadcrumbsProps {
  * `usePageBreadcrumb` from `@nocobase/app-client`. Earlier levels link where a page sits behind them; the last is the
  * current page.
  *
- * On a phone only the last level shows, beside the brand; on a medium screen a trail of three or more levels keeps its
+ * On a phone the current title and a link to the nearest authorized parent show; on a medium screen a trail of three or more levels keeps its
  * first and last and folds the middle into a menu.
  */
 export function Breadcrumbs({
@@ -52,14 +57,34 @@ export function Breadcrumbs({
   denied,
 }: BreadcrumbsProps = {}): ReactElement | null {
   const trail = useRouteTrail();
+  const routes = useRouteTree();
+  const contextAccess = useRouteAccess();
+  const access = denied
+    ? {
+        ...contextAccess,
+        denied: new Set([...contextAccess.denied, ...denied]),
+      }
+    : contextAccess;
   const searches = useRouteSearches();
   const declared = usePageBreadcrumbLevels();
   const { t } = useTranslation();
-  const trailLevels =
+  const candidates =
     declared ??
     trail.flatMap((entry): PageBreadcrumbLevel[] => {
       const title = routeLevelTitle(entry);
       if (title === undefined || denied?.has(routeKey(entry.route))) return [];
+      // The settings group links to its home page, the way back from any settings module.
+      const home = settingsHomeRoute(entry.route);
+      if (home)
+        return [
+          {
+            label: t(title, {
+              ns: entry.route.packageName,
+              defaultValue: title,
+            }),
+            to: { pathname: home.path, search: searches.get(home.path) ?? '' },
+          },
+        ];
       return [
         {
           label: t(title, {
@@ -80,6 +105,19 @@ export function Breadcrumbs({
       ];
     });
 
+  const trailLevels = candidates.flatMap(
+    (level, index): PageBreadcrumbLevel[] => {
+      if (!level.to) return [level];
+      const to = navigationDestination(level.to, routes, access);
+      // Keep the current title during permission checks, but never expose an inaccessible ancestor's name.
+      return to
+        ? [{ ...level, to }]
+        : index === candidates.length - 1
+          ? [{ label: level.label }]
+          : [];
+    },
+  );
+
   if (trailLevels.length === 0) return null;
   // A level is told apart by its depth and label; two levels may share either alone.
   const levels = trailLevels.map((level, depth) => ({
@@ -88,6 +126,7 @@ export function Breadcrumbs({
   }));
   const last = levels.length - 1;
   const folded = levels.slice(1, last);
+  const parent = levels.slice(0, last).findLast((level) => level.to);
 
   return (
     <Breadcrumb
@@ -95,6 +134,21 @@ export function Breadcrumbs({
       className={cn('min-w-0', className)}
     >
       <BreadcrumbList className='flex-nowrap'>
+        {parent ? (
+          <BreadcrumbItem className='shrink-0 md:hidden'>
+            <BreadcrumbLink
+              aria-label={t('navigation.backTo', {
+                label: parent.label,
+                defaultValue: `Back to ${parent.label}`,
+              })}
+              title={parent.label}
+              className='inline-flex size-9 items-center justify-center rounded-sm focus-visible:outline-2 focus-visible:outline-ring'
+              render={<Link to={parent.to!} replace />}
+            >
+              <ArrowLeftIcon aria-hidden='true' className='size-4' />
+            </BreadcrumbLink>
+          </BreadcrumbItem>
+        ) : null}
         {levels.map((level, index) => (
           <Fragment key={level.key}>
             {index === 1 && folded.length > 0 ? (
@@ -141,7 +195,10 @@ export function Breadcrumbs({
               )}
             >
               {index === last ? (
-                <BreadcrumbPage className='truncate font-medium'>
+                <BreadcrumbPage
+                  title={level.label}
+                  className='truncate font-medium'
+                >
                   {level.label}
                 </BreadcrumbPage>
               ) : level.to ? (

package/client/components/data-table/data-table.tsx

@@ -1,5 +1,6 @@
 import type { ListState } from '@nocobase/app-client';
 import { ListFeedback, ListFeedbackActions } from '#components/list-feedback';
+import { RefreshIndicator } from '#components/loading';
 import {
   type ColumnDef,
   type PaginationState,
@@ -17,7 +18,14 @@ import {
   getSortedRowModel,
   useReactTable,
 } from '@tanstack/react-table';
-import { type ReactElement, type ReactNode, useMemo, useState } from 'react';
+import {
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 import { DataTablePagination } from './pagination.js';
 import {
@@ -41,7 +49,18 @@ export interface DataTableProps<TData, TValue = unknown> {
   readonly sortingState?: SortingState;
   readonly onSortingChange?: OnChangeFn<SortingState>;
   readonly showSelectedCount?: boolean;
+  /**
+   * The current request is in flight. With rows of the current query and permission scope this is a background
+   * refresh: rows stay and a delayed refresh indicator appears. Without them the body shows the loading state.
+   * Explicit false pauses loading feedback for an unresolved, inactive query; omitting it uses listState.
+   */
   readonly loading?: boolean;
+  /**
+   * The current query's stable identity, such as its request path. When it
+   * changes the loading and refresh feedback restart their display delay;
+   * the table, its rows' geometry and its controls stay mounted.
+   */
+  readonly loadingIdentity?: unknown;
   readonly listState?: ListState;
   readonly onRetry?: () => void;
   readonly onClearFilters?: () => void;
@@ -95,7 +114,8 @@ export function DataTable<TData, TValue = unknown>({
   sortingState,
   onSortingChange,
   showSelectedCount = true,
-  loading = false,
+  loading,
+  loadingIdentity,
   listState,
   onRetry,
   onClearFilters,
@@ -176,6 +196,37 @@ export function DataTable<TData, TValue = unknown>({
     rows.length > 0 && (state === 'ready' || state === 'refresh-failed');
   const showFeedback = !showRows || state === 'refresh-failed';
   const feedbackColumnCount = Math.max(1, table.getVisibleLeafColumns().length);
+  const showPagination =
+    pagination &&
+    (state === 'ready' || (state === 'refresh-failed' && rows.length > 0));
+  // A new query hides the previous rows at once; keep their body and footer
+  // geometry while it loads so the page below does not jump.
+  const bodyRef = useRef<HTMLTableSectionElement>(null);
+  const footerRef = useRef<HTMLDivElement>(null);
+  const [reserved, setReserved] = useState<{
+    readonly body: number;
+    readonly footer: number;
+  }>();
+  if (!showRows && state !== 'loading' && reserved !== undefined)
+    setReserved(undefined);
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!showRows || !body || typeof ResizeObserver === 'undefined') return;
+    const footer = footerRef.current;
+    const observer = new ResizeObserver(() => {
+      const next = {
+        body: body.offsetHeight,
+        footer: footer?.offsetHeight ?? 0,
+      };
+      setReserved((old) =>
+        old?.body === next.body && old.footer === next.footer ? old : next,
+      );
+    });
+    observer.observe(body);
+    if (footer) observer.observe(footer);
+    return () => observer.disconnect();
+  }, [showRows, showPagination]);
+  const reserving = state === 'loading' && reserved !== undefined;
 
   return (
     <div className={cn('flex flex-col gap-4', className)}>
@@ -194,8 +245,14 @@ export function DataTable<TData, TValue = unknown>({
           />
         </div>
       ) : null}
-      <div className='overflow-hidden rounded-lg border'>
-        <Table aria-busy={loading}>
+      <div className='relative overflow-hidden rounded-lg border'>
+        {/* A retry after a refresh failure is announced by its own toolbar button. */}
+        <RefreshIndicator
+          pending={Boolean(loading && showRows && state !== 'refresh-failed')}
+          identity={loadingIdentity}
+        />
+        {/* Only retained rows are busy; a loading body owns its own busy region and status. */}
+        <Table aria-busy={loading && showRows}>
           <TableHeader>
             {table.getHeaderGroups().map((headerGroup) => (
               <TableRow key={headerGroup.id}>
@@ -224,15 +281,27 @@ export function DataTable<TData, TValue = unknown>({
               </TableRow>
             ))}
           </TableHeader>
-          <TableBody>
+          <TableBody ref={bodyRef}>
             {showFeedback ? (
               <TableRow>
-                <TableCell colSpan={feedbackColumnCount} className='p-0'>
-                  <ListFeedback
-                    state={state}
-                    empty={emptyMessage}
-                    emptyAction={emptyAction}
-                  />
+                <TableCell
+                  colSpan={feedbackColumnCount}
+                  className='p-0'
+                  style={
+                    reserving && reserved.body > 0
+                      ? { height: reserved.body }
+                      : undefined
+                  }
+                >
+                  {/* Readiness may stay unresolved while the parent query is paused. */}
+                  {state !== 'loading' || loading !== false ? (
+                    <ListFeedback
+                      state={state}
+                      identity={loadingIdentity}
+                      empty={emptyMessage}
+                      emptyAction={emptyAction}
+                    />
+                  ) : null}
                 </TableCell>
               </TableRow>
             ) : null}
@@ -258,14 +327,16 @@ export function DataTable<TData, TValue = unknown>({
           </TableBody>
         </Table>
       </div>
-      {pagination &&
-      (state === 'ready' || (state === 'refresh-failed' && rows.length > 0)) ? (
-        <DataTablePagination
-          table={table}
-          pageSizeOptions={pageSizeOptions}
-          showSelectedCount={showSelectedCount}
-          disabled={loading}
-        />
+      {showPagination || (pagination && reserving) ? (
+        <div ref={footerRef} data-slot='data-table-footer'>
+          <DataTablePagination
+            table={table}
+            pageSizeOptions={pageSizeOptions}
+            showSelectedCount={showSelectedCount}
+            disabled={loading || !showPagination}
+            countPending={!showPagination}
+          />
+        </div>
       ) : null}
     </div>
   );

package/client/components/data-table/pagination.tsx

@@ -26,6 +26,8 @@ export interface DataTablePaginationProps<
   /** Hide the "n of m selected" summary for tables without row selection. */
   readonly showSelectedCount?: boolean;
   readonly disabled?: boolean;
+  /** The current query has no total yet: keep the controls' place but show no previous count. */
+  readonly countPending?: boolean;
 }
 
 const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[] = [10, 20, 30, 40, 50];
@@ -40,6 +42,7 @@ export function DataTablePagination<TData>({
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
   showSelectedCount = true,
   disabled = false,
+  countPending = false,
   className,
   ...props
 }: DataTablePaginationProps<TData>): ReactElement {
@@ -60,7 +63,13 @@ export function DataTablePagination<TData>({
       )}
       {...props}
     >
-      <div className='flex-1 text-sm text-muted-foreground'>
+      <div
+        className={cn(
+          'flex-1 text-sm text-muted-foreground',
+          countPending && 'invisible',
+        )}
+        aria-hidden={countPending || undefined}
+      >
         {showSelectedCount
           ? t('dataTable.selectedCount', {
               defaultValue: '{{selected}} of {{total}} row(s) selected.',
@@ -102,7 +111,13 @@ export function DataTablePagination<TData>({
             </SelectContent>
           </Select>
         </div>
-        <div className='shrink-0 text-sm font-medium whitespace-nowrap tabular-nums'>
+        <div
+          className={cn(
+            'shrink-0 text-sm font-medium whitespace-nowrap tabular-nums',
+            countPending && 'invisible',
+          )}
+          aria-hidden={countPending || undefined}
+        >
           {t('dataTable.pageOf', {
             defaultValue: 'Page {{page}} of {{pageCount}}',
             page: pageIndex + 1,