@multiplatform.one/backoffice 7.2.2 → 7.3.0

package/src/config/BackofficeProvider.tsx

@@ -5,15 +5,16 @@
  * It composes @multiplatform.one/frappe-ui's FrappeProvider internally (the
  * `frappe` prop), publishes the navigation seam + capability flags + slots +
  * event bus through BackofficeConfigContext (consumed by every backoffice
- * surface), registers the package's "backoffice" i18n namespace, and applies
- * host field-registry overrides.
+ * surface), registers the package's "backoffice" i18n namespace, and scopes
+ * host field overrides to this subtree via FieldOverridesProvider (never the
+ * module-global registry — GL-4).
  *
  * Surfaces render without a provider too (stories/tests): the context
  * default is a fully-enabled config with an inert navigator.
  */
 import {
+  FieldOverridesProvider,
   FrappeProvider,
-  registerField,
   type FieldRenderProps,
   type FrappeProviderProps,
 } from "@multiplatform.one/frappe-ui";
@@ -155,8 +156,9 @@ export interface BackofficeProviderProps {
   /** Restrict which doctypes are reachable (awesomebar, lists, links). */
   doctypes?: BackofficeDoctypeScope;
   /**
-   * Field-renderer overrides merged into frappe-ui's field registry
-   * (fieldtype → component), e.g. `{ Rating: MyRating }`.
+   * Field-renderer overrides (fieldtype → component), e.g.
+   * `{ Rating: MyRating }` — context-scoped to this provider, so two
+   * providers with different overrides coexist on one page.
    */
   fields?: Record<string, ComponentType<FieldRenderProps>>;
   /** Host-injected custom actions (form/list toolbars). */
@@ -271,18 +273,6 @@ export function BackofficeProvider({
     return true;
   });
 
-  // Host field-registry overrides — applied during render (frappe-ui's
-  // registry is module-global) so first-pass field rendering sees them.
-  const appliedFields = useRef<Record<string, ComponentType<FieldRenderProps>>>({});
-  if (fields) {
-    for (const [fieldtype, component] of Object.entries(fields)) {
-      if (appliedFields.current[fieldtype] !== component) {
-        registerField(fieldtype, component);
-        appliedFields.current[fieldtype] = component;
-      }
-    }
-  }
-
   // Keep the handler on a ref so the wrapped navigator's identity survives
   // inline `onEvent` props.
   const onEventRef = useRef<BackofficeEventHandler | undefined>(onEvent);
@@ -373,7 +363,10 @@ export function BackofficeProvider({
         socketOptions={frappe.socketOptions}
         fixtures={frappe.fixtures}
       >
-        {children}
+        {/* Context-scoped field overrides (GL-4): per-provider, never the
+            module-global registry — two providers with different `fields` on
+            one page must not clobber each other. */}
+        <FieldOverridesProvider fields={fields}>{children}</FieldOverridesProvider>
       </FrappeProvider>
     </BackofficeConfigContext.Provider>
   );

package/src/desk/Desk.spec.tsx

@@ -0,0 +1,287 @@
+/**
+ * <Desk /> assembly specs (MPO-14):
+ * - end-to-end render over a mocked (fixture) doctype, both chrome modes
+ * - navigator-driven dispatch through the resolver + slug index
+ * - surface override registry (GL-6): per-kind and per-doctype
+ * - two Desks on one page: field-registry (GL-4) and scope (GL-5) isolation
+ */
+import React from "react";
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { getFieldComponent, useFieldResolver } from "@multiplatform.one/frappe-ui";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useBackofficeNavigator, useBackofficePaths } from "../config/BackofficeProvider";
+import { createMemoryNavigator } from "../navigation/navigator";
+import { Desk } from "./Desk";
+import type { DeskSurfaceProps } from "./DeskSurface";
+import { useDeskScope } from "./scope";
+
+const MOCK_HOST = "https://desk-assembly.mock.test";
+
+const makeFixtures = () =>
+  new InMemoryFixtureProvider({
+    Workspace: [
+      {
+        name: "Tools",
+        doctype: "Workspace",
+        title: "Tools",
+        icon: "tool",
+        parent_page: "",
+        public: 1,
+        for_user: "",
+        sequence_id: 1,
+        module: "Automation",
+        is_hidden: 0,
+      },
+    ],
+    DocType: [{ name: "ToDo", doctype: "DocType" }],
+    "Notification Log": [],
+  });
+
+const frappe = () => ({ baseURL: MOCK_HOST, fixtures: makeFixtures() });
+
+function SurfaceProbe({ target }: DeskSurfaceProps) {
+  return <div data-testid={`probe-${target.kind}`}>{JSON.stringify(target)}</div>;
+}
+
+describe("<Desk /> chrome and dispatch", () => {
+  it("renders the full desk with no required props (DK-1)", async () => {
+    renderWithProviders(<Desk frappe={frappe()} />);
+    // Full chrome mounts...
+    expect(screen.getByTestId("backoffice-shell")).toBeTruthy();
+    expect(screen.getByTestId("backoffice-awesomebar")).toBeTruthy();
+    // ...and home lands on the default workspace (fixture-backed redirect).
+    await waitFor(() => {
+      expect(screen.getAllByText("Tools").length).toBeGreaterThan(0);
+    });
+  });
+
+  it("a doctype pin renders that doctype's surface in content chrome, host URL untouched", () => {
+    const onTargetChange = vi.fn();
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        doctype="Sales Order"
+        surfaces={{ list: SurfaceProbe }}
+        onTargetChange={onTargetChange}
+      />,
+    );
+    // content chrome: no banner, no rail
+    expect(screen.queryByTestId("backoffice-shell")).toBeNull();
+    // the pin dispatched the list surface for the proper-cased doctype
+    expect(screen.getByTestId("probe-list").textContent).toContain('"Sales Order"');
+    expect(onTargetChange).toHaveBeenCalledWith({ kind: "list", doctype: "Sales Order" });
+  });
+
+  it("doctype + name renders the form surface; chrome='full' overrides the pin default", () => {
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        doctype="Sales Order"
+        name="SO-0001"
+        chrome="full"
+        surfaces={{ form: SurfaceProbe }}
+      />,
+    );
+    expect(screen.getByTestId("backoffice-shell")).toBeTruthy();
+    const probe = screen.getByTestId("probe-form");
+    expect(probe.textContent).toContain('"Sales Order"');
+    expect(probe.textContent).toContain('"SO-0001"');
+  });
+
+  it("workspace and report pins dispatch their surfaces", () => {
+    renderWithProviders(
+      <Desk frappe={frappe()} workspace="Accounting" surfaces={{ workspace: SurfaceProbe }} />,
+    );
+    expect(screen.getByTestId("probe-workspace").textContent).toContain('"Accounting"');
+
+    renderWithProviders(
+      <Desk frappe={frappe()} report="Accounts Receivable" surfaces={{ report: SurfaceProbe }} />,
+    );
+    expect(screen.getByTestId("probe-report").textContent).toContain('"Accounts Receivable"');
+  });
+
+  it("resolves navigator-driven paths through the slug index (routed mode)", async () => {
+    const navigation = createMemoryNavigator("/backoffice/todo");
+    renderWithProviders(
+      <Desk frappe={frappe()} navigation={navigation} surfaces={{ list: SurfaceProbe }} />,
+    );
+    // "todo" is ambiguous until the fixture index resolves it to ToDo.
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-list").textContent).toContain('"ToDo"');
+    });
+  });
+
+  it("re-resolves when the navigator moves: list → form → back (deep-link round-trip)", async () => {
+    const navigation = createMemoryNavigator("/backoffice/todo");
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        navigation={navigation}
+        surfaces={{ list: SurfaceProbe, form: SurfaceProbe, "not-found": SurfaceProbe }}
+      />,
+    );
+    await waitFor(() => expect(screen.getByTestId("probe-list")).toBeTruthy());
+
+    navigation.navigate("/backoffice/todo/T-0001");
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-form").textContent).toContain('"T-0001"');
+    });
+
+    navigation.back();
+    await waitFor(() => expect(screen.getByTestId("probe-list")).toBeTruthy());
+  });
+
+  it("onNavigate intercepts desk-issued navigation and cancels it (the drawer seam)", async () => {
+    // The override navigates the way every surface does: through the
+    // provider's navigator — the seam onNavigate wraps.
+    function ListWithRowPress() {
+      const navigator = useBackofficeNavigator();
+      const paths = useBackofficePaths();
+      return (
+        <button
+          type="button"
+          data-testid="open-doc"
+          onClick={() => navigator.navigate(paths.form("ToDo", "T-0001"))}
+        >
+          open
+        </button>
+      );
+    }
+    const seen: string[] = [];
+    const navigation = createMemoryNavigator("/backoffice/todo");
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        navigation={navigation}
+        surfaces={{ list: ListWithRowPress, form: SurfaceProbe }}
+        onNavigate={(target) => {
+          seen.push(target.kind);
+          if (target.kind === "form") return false;
+        }}
+      />,
+    );
+    await waitFor(() => expect(screen.getByTestId("open-doc")).toBeTruthy());
+
+    fireEvent.click(screen.getByTestId("open-doc"));
+    // cancelled: the host saw the target, the desk never left the list
+    expect(seen).toContain("form");
+    expect(navigation.getLocation().path).toBe("/backoffice/todo");
+    expect(screen.queryByTestId("probe-form")).toBeNull();
+  });
+
+  it("per-doctype surface overrides beat per-kind, and miss falls through", () => {
+    function DoctypeProbe({ target }: DeskSurfaceProps) {
+      return <div data-testid="doctype-probe">{JSON.stringify(target)}</div>;
+    }
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        doctype="Sales Order"
+        surfaces={{ list: { "Sales Order": DoctypeProbe } }}
+      />,
+    );
+    expect(screen.getByTestId("doctype-probe")).toBeTruthy();
+
+    // A record keyed by a different doctype misses → built-in list mounts
+    // (its loading state), not the probe.
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        doctype="ToDo"
+        surfaces={{ list: { "Sales Order": DoctypeProbe } }}
+      />,
+    );
+    expect(screen.queryAllByTestId("doctype-probe")).toHaveLength(1);
+  });
+
+  it("basePath rebinds resolution (mounted at /admin)", async () => {
+    const navigation = createMemoryNavigator("/admin/todo");
+    renderWithProviders(
+      <Desk
+        frappe={frappe()}
+        navigation={navigation}
+        basePath="/admin"
+        surfaces={{ list: SurfaceProbe }}
+      />,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-list").textContent).toContain('"ToDo"');
+    });
+  });
+});
+
+describe("two Desks on one page (DK-7)", () => {
+  function FieldProbe({ testId }: { testId: string }) {
+    const resolve = useFieldResolver();
+    const Field = resolve("Data");
+    if (!Field) return null;
+    return (
+      <div data-testid={testId}>
+        <Field value="" onChange={() => {}} label="probe" />
+      </div>
+    );
+  }
+
+  it("field overrides are per-Desk and never touch the module registry (GL-4)", () => {
+    const globalData = getFieldComponent("Data");
+    const CustomA = () => <div data-testid="custom-a">A</div>;
+    const CustomB = () => <div data-testid="custom-b">B</div>;
+    const probeA = () => <FieldProbe testId="desk-a-field" />;
+    const probeB = () => <FieldProbe testId="desk-b-field" />;
+
+    renderWithProviders(
+      <>
+        <Desk
+          frappe={frappe()}
+          doctype="ToDo"
+          fields={{ Data: CustomA }}
+          surfaces={{ list: probeA }}
+        />
+        <Desk
+          frappe={frappe()}
+          doctype="ToDo"
+          fields={{ Data: CustomB }}
+          surfaces={{ list: probeB }}
+        />
+      </>,
+    );
+
+    // Each Desk resolves its own override…
+    expect(
+      screen.getByTestId("desk-a-field").querySelector('[data-testid="custom-a"]'),
+    ).toBeTruthy();
+    expect(
+      screen.getByTestId("desk-b-field").querySelector('[data-testid="custom-b"]'),
+    ).toBeTruthy();
+    expect(screen.getByTestId("desk-a-field").querySelector('[data-testid="custom-b"]')).toBeNull();
+    // …and the module-global default table is untouched.
+    expect(getFieldComponent("Data")).toBe(globalData);
+  });
+
+  it("scope is per-Desk context (GL-5)", () => {
+    function ScopeProbe({ testId }: { testId: string }) {
+      const scope = useDeskScope();
+      return <div data-testid={testId}>{JSON.stringify(scope)}</div>;
+    }
+    renderWithProviders(
+      <>
+        <Desk
+          frappe={frappe()}
+          doctype="ToDo"
+          scope={[["company", "=", "A"]]}
+          surfaces={{ list: () => <ScopeProbe testId="scope-a" /> }}
+        />
+        <Desk
+          frappe={frappe()}
+          doctype="ToDo"
+          scope={[["company", "=", "B"]]}
+          surfaces={{ list: () => <ScopeProbe testId="scope-b" /> }}
+        />
+      </>,
+    );
+    expect(screen.getByTestId("scope-a").textContent).toBe('[["company","=","A"]]');
+    expect(screen.getByTestId("scope-b").textContent).toBe('[["company","=","B"]]');
+  });
+});

package/src/desk/Desk.tsx

@@ -0,0 +1,308 @@
+/**
+ * <Desk /> — the whole desk as one importable component (MPO-14 / gap GL-2,
+ * spec 09). One required prop, and that prop is nothing: `<Desk />` renders
+ * the full desk; everything else is a narrowing.
+ *
+ * Desk is assembly, not implementation: prop normalization into
+ * BackofficeProvider, a navigator pick (host adapter or an internal
+ * MemoryNavigator seeded from the pins), the path→surface resolution
+ * (useDeskTarget), and the chrome pick. No fetch, no filter construction,
+ * no field mapping, no visual values — the §9.2 doctrine greps over this
+ * directory ship as a spec test (doctrine.spec.ts).
+ */
+import { YStack } from "@multiplatform.one/components";
+import { useFrappeConfig, type FieldRenderProps } from "@multiplatform.one/frappe-ui";
+import type { ComponentType } from "react";
+import { useEffect, useMemo, useRef } from "react";
+import {
+  BackofficeProvider,
+  type BackofficeActions,
+  type BackofficeAppearance,
+  type BackofficeFrappeConfig,
+  type BackofficeIntegrations,
+} from "../config/BackofficeProvider";
+import type { BackofficeEventHandler } from "../config/events";
+import type { BackofficeCapabilities, BackofficeDoctypeScope } from "../config/capabilities";
+import type { BackofficeSlots } from "../config/slots";
+import { createMemoryNavigator, type BackofficeNavigator } from "../navigation/navigator";
+import { BACKOFFICE_BASE, createBackofficePaths, type BackofficeView } from "../navigation/paths";
+import type { FrappeFilters } from "../shared/types";
+import { BackofficeShell } from "../shell/BackofficeShell";
+import { DeskSurface, DeskSurfaceLoading, type DeskSurfaceOverrides } from "./DeskSurface";
+import { DeskScopeProvider } from "./scope";
+import {
+  guessDeskTarget,
+  hasDeskPin,
+  useDeskTarget,
+  type DeskPins,
+  type DeskTarget,
+} from "./target";
+
+export type DeskChrome = "full" | "bare" | "content";
+
+export interface DeskProps {
+  // ─── connection ────────────────────────────────────────────────────────
+  /**
+   * Frappe connection. Omit to inherit an ambient FrappeProvider (or
+   * BackofficeProvider). IGNORED when an ambient provider exists — Desk
+   * warns once, because the SyncModule is cached per baseURL and a second
+   * config for the same server silently loses to the first.
+   */
+  frappe?: BackofficeFrappeConfig;
+
+  // ─── what it shows (the pins) ──────────────────────────────────────────
+  /** Pin the desk to one doctype. Sets the initial target AND the scope. */
+  doctype?: string;
+  /** With `doctype`: a document name, or "new". Renders the form. */
+  name?: string;
+  /** With `doctype`: which view. Default "list". */
+  view?: BackofficeView;
+  /** Pin the desk to one workspace page. */
+  workspace?: string;
+  /** Pin the desk to one Query/Script Report. */
+  report?: string;
+  /**
+   * Explicit surface address relative to `basePath` (e.g.
+   * "/sales-order/SO-0001"). Wins over every pin — the escape hatch for a
+   * host with its own address scheme.
+   */
+  path?: string;
+
+  // ─── scoping ───────────────────────────────────────────────────────────
+  /** Seed the user-visible filter channel; the user can change or clear. */
+  filters?: FrappeFilters;
+  /**
+   * ALWAYS ANDed into every doctype-homed query, invisible to the filter
+   * chrome, not removable — the tenant seam (DeskScopeProvider).
+   */
+  scope?: FrappeFilters;
+  /** Doctype reachability. A `doctype` pin defaults this to that doctype. */
+  doctypes?: BackofficeDoctypeScope;
+
+  // ─── which surfaces are enabled ────────────────────────────────────────
+  /** Feature flags, everything defaults on (config/capabilities.ts). */
+  capabilities?: BackofficeCapabilities;
+  /** View-switcher allowlist, intersected with capabilities.views.allow. */
+  views?: readonly BackofficeView[];
+  /** Force every form read-only regardless of permissions. */
+  readOnly?: boolean;
+
+  // ─── chrome ────────────────────────────────────────────────────────────
+  /**
+   * "full" banner + workspace rail; "bare" banner only; "content" no
+   * chrome. Default: "content" when any pin is set, "full" otherwise.
+   */
+  chrome?: DeskChrome;
+  /** Sugar for chrome="content". */
+  embedded?: boolean;
+  /** Render-prop chrome replacements (config/slots.ts). */
+  slots?: BackofficeSlots;
+  /** Color-scheme adapter for the user menu's "Toggle Theme". */
+  appearance?: BackofficeAppearance;
+  /** Router-integration hooks (navigation blocker, …). */
+  integrations?: BackofficeIntegrations;
+
+  // ─── routing ───────────────────────────────────────────────────────────
+  /**
+   * Host router adapter. Supply it and Desk owns URLs; omit it and Desk
+   * navigates internally over a MemoryNavigator seeded from the pins.
+   */
+  navigation?: BackofficeNavigator;
+  /** URL prefix Desk is mounted under. Default "/backoffice". */
+  basePath?: string;
+  /**
+   * Intercept push/replace navigations before they happen; return false to
+   * cancel (host renders the target itself, e.g. in a drawer). The target
+   * is resolved best-effort: an ambiguous slug degrades to a title-cased
+   * doctype guess, the same degrade the slug index applies offline.
+   */
+  onNavigate?: (target: DeskTarget, path: string) => boolean | void;
+  /** Fires whenever the resolved surface changes (host breadcrumbs/titles). */
+  onTargetChange?: (target: DeskTarget) => void;
+
+  // ─── extension ─────────────────────────────────────────────────────────
+  /** Replace a whole surface, per kind or per doctype under a kind. */
+  surfaces?: DeskSurfaceOverrides;
+  /** Replace a field control by fieldtype — context-scoped per Desk. */
+  fields?: Record<string, ComponentType<FieldRenderProps>>;
+  /** Host actions on form and list toolbars, optionally per-doctype. */
+  actions?: BackofficeActions;
+  /** Every notable desk action lands here (config/events.ts). */
+  onEvent?: BackofficeEventHandler;
+}
+
+/** Pins → the internal navigator's seed path. */
+function pinnedPath(pins: DeskPins, basePath: string): string {
+  const paths = createBackofficePaths(basePath);
+  if (pins.path) {
+    const prefix = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+    return `${prefix}${pins.path}`;
+  }
+  if (pins.doctype) {
+    if (pins.name === "new") return paths.newDoc(pins.doctype);
+    if (pins.name) return paths.form(pins.doctype, pins.name);
+    if (pins.view && pins.view !== "list") return paths.view(pins.doctype, pins.view);
+    return paths.list(pins.doctype);
+  }
+  if (pins.workspace) return paths.workspace(pins.workspace);
+  if (pins.report) return paths.queryReport(pins.report);
+  return paths.home();
+}
+
+export function Desk(props: DeskProps) {
+  const {
+    doctype,
+    name,
+    view,
+    workspace,
+    report,
+    path,
+    basePath = BACKOFFICE_BASE,
+    chrome: chromeProp,
+    embedded,
+    onNavigate,
+  } = props;
+
+  const pins = useMemo<DeskPins>(
+    () => ({ doctype, name, view, workspace, report, path }),
+    [doctype, name, view, workspace, report, path],
+  );
+
+  // ── connection: ambient provider wins over the prop, warned once ──────
+  const ambient = useFrappeConfig();
+  const warned = useRef(false);
+  if (ambient && props.frappe && !warned.current) {
+    warned.current = true;
+    console.warn(
+      "[backoffice] <Desk frappe> is ignored: an ambient FrappeProvider exists and the SyncModule is cached per baseURL.",
+    );
+  }
+  const frappe = useMemo<BackofficeFrappeConfig>(() => {
+    if (ambient) {
+      return { baseURL: ambient.baseURL, auth: ambient.auth, fixtures: ambient.fixtures };
+    }
+    return props.frappe ?? { baseURL: "" };
+  }, [ambient, props.frappe]);
+
+  // ── navigation: host adapter, else internal memory (seeded once) ──────
+  const memoryNavigator = useMemo(
+    () => (props.navigation ? undefined : createMemoryNavigator(pinnedPath(pins, basePath))),
+    // The seed is the ENTRY; later pin changes re-enter through useDeskTarget.
+    // oxlint-disable-next-line exhaustive-deps
+    [props.navigation ? "host" : "memory"],
+  );
+  const baseNavigation = props.navigation ?? memoryNavigator!;
+
+  const onNavigateRef = useRef(onNavigate);
+  onNavigateRef.current = onNavigate;
+  const navigation = useMemo<BackofficeNavigator>(() => {
+    const intercept = (path: string): boolean =>
+      onNavigateRef.current?.(guessDeskTarget(path, basePath), path) !== false;
+    return {
+      ...baseNavigation,
+      navigate: (path) => {
+        if (intercept(path)) baseNavigation.navigate(path);
+      },
+      replace: (path) => {
+        if (intercept(path)) baseNavigation.replace(path);
+      },
+      back: () => baseNavigation.back(),
+      getLocation: () => baseNavigation.getLocation(),
+      subscribe: (listener) => baseNavigation.subscribe(listener),
+      ...(baseNavigation.setParams
+        ? {
+            setParams: (params: Record<string, string | undefined>) =>
+              baseNavigation.setParams?.(params),
+          }
+        : {}),
+    };
+  }, [baseNavigation, basePath]);
+
+  // ── narrowings: chrome, doctype fence, bare-chrome capability merge ───
+  const chrome: DeskChrome = chromeProp ?? (embedded || hasDeskPin(pins) ? "content" : "full");
+  const doctypes = props.doctypes ?? (doctype ? { allow: [doctype] } : undefined);
+  const capabilities = useMemo<BackofficeCapabilities | undefined>(
+    () => (chrome === "bare" ? { ...props.capabilities, sidebar: false } : props.capabilities),
+    [chrome, props.capabilities],
+  );
+
+  return (
+    <BackofficeProvider
+      frappe={frappe}
+      navigation={navigation}
+      basePath={basePath}
+      capabilities={capabilities}
+      doctypes={doctypes}
+      fields={props.fields}
+      actions={props.actions}
+      slots={props.slots}
+      appearance={props.appearance}
+      integrations={props.integrations}
+      onEvent={props.onEvent}
+    >
+      <DeskScopeProvider scope={props.scope}>
+        <DeskBody
+          pins={pins}
+          chrome={chrome}
+          readOnly={props.readOnly}
+          surfaces={props.surfaces}
+          initialFilters={props.filters}
+          views={props.views}
+          onTargetChange={props.onTargetChange}
+        />
+      </DeskScopeProvider>
+    </BackofficeProvider>
+  );
+}
+
+interface DeskBodyProps {
+  pins: DeskPins;
+  chrome: DeskChrome;
+  readOnly?: boolean;
+  surfaces?: DeskSurfaceOverrides;
+  initialFilters?: FrappeFilters;
+  views?: readonly BackofficeView[];
+  onTargetChange?: (target: DeskTarget) => void;
+}
+
+/** Inside the provider: resolve the target, pick the chrome, mount the surface. */
+function DeskBody({
+  pins,
+  chrome,
+  readOnly,
+  surfaces,
+  initialFilters,
+  views,
+  onTargetChange,
+}: DeskBodyProps) {
+  const target = useDeskTarget(pins);
+
+  const onTargetChangeRef = useRef(onTargetChange);
+  onTargetChangeRef.current = onTargetChange;
+  const targetKey = target ? JSON.stringify(target) : undefined;
+  useEffect(() => {
+    if (target) onTargetChangeRef.current?.(target);
+    // oxlint-disable-next-line exhaustive-deps
+  }, [targetKey]);
+
+  const surface = target ? (
+    <DeskSurface
+      target={target}
+      overrides={surfaces}
+      readOnly={readOnly}
+      initialFilters={initialFilters}
+      views={views}
+    />
+  ) : (
+    <DeskSurfaceLoading />
+  );
+
+  if (chrome === "content") {
+    return (
+      <YStack flex={1} minHeight={0} minWidth={0}>
+        {surface}
+      </YStack>
+    );
+  }
+  return <BackofficeShell>{surface}</BackofficeShell>;
+}