@multiplatform.one/backoffice 7.2.1 → 7.3.0

package/src/desk/DeskSurface.tsx

@@ -0,0 +1,132 @@
+/**
+ * DeskSurface — the target→surface switch plus the surface override
+ * registry (MPO-14 / gaps GL-1 assembly half + GL-6, spec 09 §3, §5.1).
+ *
+ * A pure dispatch: every branch renders an EXISTING wired component; no
+ * fetch, no filter construction, no visual values (DK-2/DK-3). Overrides
+ * ride props (per-Desk by construction, DK-7): per-doctype first, then
+ * per-kind, then the built-in.
+ */
+import { Spinner, YStack } from "@multiplatform.one/components";
+import { useMemo, type ComponentType } from "react";
+import { setCreatePrefill } from "../form/createPrefill";
+import { DocFormScreen } from "../form/DocFormScreen";
+import { DoctypeListScreen } from "../list/DoctypeListScreen";
+import type { BackofficeView } from "../navigation/paths";
+import { QueryReportScreen } from "../report/QueryReportScreen";
+import type { FrappeFilters } from "../shared/types";
+import { HomeRedirect } from "../shell/HomeRedirect";
+import { NotFoundScreen } from "../shell/NotFoundScreen";
+import { DoctypeViewScreen } from "../views/DoctypeViewScreen";
+import { WorkspaceScreen } from "../workspace/WorkspaceScreen";
+import type { DeskTarget } from "./target";
+
+export type DeskSurfaceKind = DeskTarget["kind"];
+
+/** The whole contract an override receives — thin enough to wrap the built-in. */
+export interface DeskSurfaceProps {
+  target: DeskTarget;
+  readOnly?: boolean;
+}
+
+/** A component per kind, or per doctype under that kind. */
+export type DeskSurfaceOverride =
+  | ComponentType<DeskSurfaceProps>
+  | Record<string, ComponentType<DeskSurfaceProps>>;
+
+export type DeskSurfaceOverrides = Partial<Record<DeskSurfaceKind, DeskSurfaceOverride>>;
+
+function resolveOverride(
+  overrides: DeskSurfaceOverrides | undefined,
+  target: DeskTarget,
+): ComponentType<DeskSurfaceProps> | undefined {
+  const entry = overrides?.[target.kind];
+  if (!entry) return undefined;
+  if (typeof entry === "function") return entry;
+  const doctype = "doctype" in target ? target.doctype : undefined;
+  return doctype ? entry[doctype] : undefined;
+}
+
+/** Create mode, `?d=`/pin defaults routed through the ONE prefill stash. */
+function NewDocSurface({
+  doctype,
+  defaults,
+  readOnly,
+}: {
+  doctype: string;
+  defaults?: Record<string, unknown>;
+  readOnly?: boolean;
+}) {
+  const defaultsKey = JSON.stringify(defaults ?? null);
+  // Stash in a memo (not an effect) so the values land before
+  // DocFormScreen's create-mode seeding runs — same contract as the old
+  // host route screen this replaces.
+  useMemo(() => {
+    if (defaults && Object.keys(defaults).length > 0) setCreatePrefill(doctype, defaults);
+    // oxlint-disable-next-line exhaustive-deps
+  }, [doctype, defaultsKey]);
+  // Keyed on defaults: same-doctype navigation with different `?d=` must
+  // remount to re-seed.
+  return <DocFormScreen key={defaultsKey} doctype={doctype} name="new" readOnly={readOnly} />;
+}
+
+export interface DeskSurfaceHostProps extends DeskSurfaceProps {
+  overrides?: DeskSurfaceOverrides;
+  /** Seed for the list surface's user-editable filter channel. */
+  initialFilters?: FrappeFilters;
+  /** View-switcher allowlist forwarded to the list surface. */
+  views?: readonly BackofficeView[];
+}
+
+export function DeskSurface({
+  target,
+  overrides,
+  readOnly,
+  initialFilters,
+  views,
+}: DeskSurfaceHostProps) {
+  const Override = resolveOverride(overrides, target);
+  if (Override) return <Override target={target} readOnly={readOnly} />;
+
+  switch (target.kind) {
+    case "home":
+      return <HomeRedirect />;
+    case "workspace":
+      return <WorkspaceScreen workspace={target.workspace} />;
+    case "list":
+      return (
+        <DoctypeListScreen
+          doctype={target.doctype}
+          filtersParam={target.filtersParam}
+          sortParam={target.sortParam}
+          initialFilters={initialFilters}
+          views={views}
+        />
+      );
+    case "view":
+      return <DoctypeViewScreen doctype={target.doctype} view={target.view} />;
+    case "new":
+      return (
+        <NewDocSurface doctype={target.doctype} defaults={target.defaults} readOnly={readOnly} />
+      );
+    case "form":
+      // MPO-15: DocFormScreen is the strong form today. When the form-engine
+      // seam collapses (formLayout + useFormEngine hoisted into frappe-ui,
+      // gap GL-3), the exported FrappeForm becomes this branch's renderer —
+      // swap here, nowhere else.
+      return <DocFormScreen doctype={target.doctype} name={target.name} readOnly={readOnly} />;
+    case "report":
+      return <QueryReportScreen reportName={target.reportName} />;
+    case "not-found":
+      return <NotFoundScreen />;
+  }
+}
+
+/** The resolving state — same presentation as the slug route's spinner. */
+export function DeskSurfaceLoading() {
+  return (
+    <YStack flex={1} alignItems="center" justifyContent="center">
+      <Spinner size="large" />
+    </YStack>
+  );
+}

package/src/desk/doctrine.spec.ts

@@ -0,0 +1,48 @@
+/**
+ * The doctrine greps (spec 09 §9.2), shipped as spec tests — a rule nobody
+ * runs is a wish.
+ *
+ * DK-2: Desk contains no data wiring. Every byte it displays is fetched by
+ * a component it renders or an exported hook.
+ * DK-3: Desk contains no visual values — no color literal, no pixel literal.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const DESK_DIR = join(__dirname);
+
+function deskSources(extensions: readonly string[]): { file: string; source: string }[] {
+  return readdirSync(DESK_DIR)
+    .filter(
+      (file) =>
+        extensions.some((extension) => file.endsWith(extension)) &&
+        !file.includes(".spec.") &&
+        !file.includes(".stories."),
+    )
+    .map((file) => ({ file, source: readFileSync(join(DESK_DIR, file), "utf8") }));
+}
+
+/** Match lines, reporting file:line so a failure names its violation. */
+function violations(sources: { file: string; source: string }[], pattern: RegExp): string[] {
+  const found: string[] = [];
+  for (const { file, source } of sources) {
+    source.split("\n").forEach((line, index) => {
+      if (pattern.test(line)) found.push(`${file}:${index + 1}: ${line.trim()}`);
+    });
+  }
+  return found;
+}
+
+describe("desk doctrine (spec 09 §9.2)", () => {
+  it("DK-2: no data wiring anywhere in src/desk", () => {
+    const pattern =
+      /HttpClient|useFrappeCollection|useLiveQuery|\bfetch\(|axios|\/api\/(resource|method)/;
+    expect(violations(deskSources([".ts", ".tsx"]), pattern)).toEqual([]);
+  });
+
+  it("DK-3: no color or pixel literals anywhere in src/desk", () => {
+    const pattern = /#[0-9a-fA-F]{3,8}\b|rgba?\(|\b(width|height|padding|margin|fontSize)=\{[0-9]/;
+    expect(violations(deskSources([".tsx"]), pattern)).toEqual([]);
+  });
+});

package/src/desk/resolveDeskPath.spec.ts

@@ -0,0 +1,174 @@
+/**
+ * DM-1 correctness proof (spec 09 §4.3): for every builder in
+ * `createBackofficePaths`, `resolveDeskPath(paths.x(...))` returns the
+ * address that built it — both halves are pure, so the round-trip is the
+ * whole contract.
+ */
+import { describe, expect, it } from "vitest";
+import { parseBackofficeHref } from "../navigation/navigator";
+import { BACKOFFICE_VIEWS, createBackofficePaths } from "../navigation/paths";
+import { resolveDeskPath, type DeskAddress } from "./resolveDeskPath";
+
+const BASE_PATHS = ["/backoffice", "/admin", "/", "/nested/desk"] as const;
+
+/** Split a built href the way the navigator does, then resolve it. */
+function resolve(href: string, basePath: string): DeskAddress {
+  const { path, params } = parseBackofficeHref(href);
+  return resolveDeskPath(path, basePath, params);
+}
+
+describe.each(BASE_PATHS)("resolveDeskPath round-trips createBackofficePaths at %s", (basePath) => {
+  const paths = createBackofficePaths(basePath);
+
+  it("home() → home", () => {
+    expect(resolve(paths.home(), basePath)).toEqual({ kind: "home" });
+  });
+
+  it("workspace() → slug (ambiguity is data, resolved downstream)", () => {
+    expect(resolve(paths.workspace("Accounting"), basePath)).toEqual({
+      kind: "slug",
+      slug: "accounting",
+      filtersParam: undefined,
+      sortParam: undefined,
+    });
+  });
+
+  it("list() → slug", () => {
+    expect(resolve(paths.list("Sales Order"), basePath)).toMatchObject({
+      kind: "slug",
+      slug: "sales-order",
+    });
+  });
+
+  it.each(BACKOFFICE_VIEWS.filter((view) => view !== "list"))("view(%s) → slug-view", (view) => {
+    expect(resolve(paths.view("Sales Order", view), basePath)).toEqual({
+      kind: "slug-view",
+      slug: "sales-order",
+      view,
+    });
+  });
+
+  it("view('list') → the list surface, exactly like list()", () => {
+    expect(resolve(paths.view("Sales Order", "list"), basePath)).toMatchObject({
+      kind: "slug",
+      slug: "sales-order",
+    });
+  });
+
+  it("newDoc() → slug-new, without and with ?d= defaults", () => {
+    expect(resolve(paths.newDoc("Sales Order"), basePath)).toEqual({
+      kind: "slug-new",
+      slug: "sales-order",
+      defaults: undefined,
+    });
+    const defaults = { customer: "ACME & Sons", qty: 2 };
+    expect(resolve(paths.newDoc("Sales Order", defaults), basePath)).toEqual({
+      kind: "slug-new",
+      slug: "sales-order",
+      defaults,
+    });
+  });
+
+  it("form() → slug-name, decoding encoded document names", () => {
+    expect(resolve(paths.form("Sales Order", "SO-0001"), basePath)).toEqual({
+      kind: "slug-name",
+      slug: "sales-order",
+      name: "SO-0001",
+    });
+    expect(resolve(paths.form("File", "a b/c#1"), basePath)).toEqual({
+      kind: "slug-name",
+      slug: "file",
+      name: "a b/c#1",
+    });
+  });
+
+  it("a document literally named 'new' still resolves as create mode (desk parity)", () => {
+    expect(resolve(paths.form("Task", "new"), basePath)).toMatchObject({ kind: "slug-new" });
+  });
+
+  it("queryReport() → report, decoding encoded report names", () => {
+    expect(resolve(paths.queryReport("Accounts Receivable"), basePath)).toEqual({
+      kind: "report",
+      reportName: "Accounts Receivable",
+      filtersParam: undefined,
+    });
+  });
+});
+
+describe("resolveDeskPath search params", () => {
+  const paths = createBackofficePaths("/backoffice");
+
+  it("carries ?f=/?sort= on the list address", () => {
+    const address = resolveDeskPath("/backoffice/todo", "/backoffice", {
+      f: '[["status","=","Open"]]',
+      sort: "modified.desc",
+    });
+    expect(address).toEqual({
+      kind: "slug",
+      slug: "todo",
+      filtersParam: '[["status","=","Open"]]',
+      sortParam: "modified.desc",
+    });
+  });
+
+  it("carries ?board=/?field=/?f= on the view address", () => {
+    const address = resolveDeskPath(`${paths.view("ToDo", "kanban")}`, "/backoffice", {
+      board: "My Board",
+      field: "date",
+    });
+    expect(address).toEqual({
+      kind: "slug-view",
+      slug: "todo",
+      view: "kanban",
+      params: { board: "My Board", field: "date", filtersParam: undefined },
+    });
+  });
+
+  it("carries ?filters= on the report address", () => {
+    const address = resolveDeskPath(
+      "/backoffice/query-report/Accounts%20Receivable",
+      "/backoffice",
+      {
+        filters: '{"company":"ACME"}',
+      },
+    );
+    expect(address).toEqual({
+      kind: "report",
+      reportName: "Accounts Receivable",
+      filtersParam: '{"company":"ACME"}',
+    });
+  });
+});
+
+describe("resolveDeskPath rejections", () => {
+  it("paths outside basePath are not-found", () => {
+    expect(resolveDeskPath("/elsewhere/todo", "/backoffice")).toEqual({
+      kind: "not-found",
+      path: "/elsewhere/todo",
+    });
+    // Prefix must match on a segment boundary.
+    expect(resolveDeskPath("/backofficex/todo", "/backoffice")).toMatchObject({
+      kind: "not-found",
+    });
+  });
+
+  it("malformed shapes are not-found", () => {
+    expect(resolveDeskPath("/backoffice/todo/view/nope", "/backoffice")).toMatchObject({
+      kind: "not-found",
+    });
+    expect(resolveDeskPath("/backoffice/todo/view/kanban/extra", "/backoffice")).toMatchObject({
+      kind: "not-found",
+    });
+    expect(resolveDeskPath("/backoffice/query-report", "/backoffice")).toMatchObject({
+      kind: "not-found",
+    });
+  });
+
+  it("trailing slashes normalize", () => {
+    expect(resolveDeskPath("/backoffice/", "/backoffice")).toEqual({ kind: "home" });
+    expect(resolveDeskPath("/backoffice/todo/", "/backoffice")).toMatchObject({
+      kind: "slug",
+      slug: "todo",
+    });
+  });
+});

package/src/desk/resolveDeskPath.ts

@@ -0,0 +1,111 @@
+/**
+ * resolveDeskPath — the pure path→surface resolver (MPO-14 / gap GL-1,
+ * spec 09 §DM-1, §4.3).
+ *
+ * One inverse for every builder in `createBackofficePaths`, so dispatch
+ * lives in the package once instead of being re-derived per host route
+ * file. Pure: no network, no React. The slug half of an address stays
+ * AMBIGUOUS here (workspace vs doctype is data, resolved by
+ * `useSlugTarget`); `useDeskTarget` composes the two.
+ */
+import type { BackofficeParams } from "../navigation/navigator";
+import {
+  BACKOFFICE_BASE,
+  isBackofficeView,
+  parseDocDefaults,
+  type BackofficeView,
+} from "../navigation/paths";
+
+/** View search params the view surface reads (board/field/f — spec §2.2). */
+export interface DeskViewParams {
+  /** `?board=` kanban board selection. */
+  board?: string;
+  /** `?field=` calendar date field. */
+  field?: string;
+  /** `?f=` report base filters (raw urlencoded JSON). */
+  filtersParam?: string;
+}
+
+/**
+ * A resolved desk address: the shape of the URL, before slug disambiguation.
+ * `slug` kinds still need the runtime workspace/doctype index.
+ */
+export type DeskAddress =
+  | { kind: "home" }
+  | { kind: "slug"; slug: string; filtersParam?: string; sortParam?: string }
+  | {
+      kind: "slug-view";
+      slug: string;
+      view: Exclude<BackofficeView, "list">;
+      params?: DeskViewParams;
+    }
+  | { kind: "slug-new"; slug: string; defaults?: Record<string, unknown> }
+  | { kind: "slug-name"; slug: string; name: string }
+  | { kind: "report"; reportName: string; filtersParam?: string }
+  | { kind: "not-found"; path: string };
+
+function first(value: string | string[] | undefined): string | undefined {
+  return typeof value === "string" ? value : value?.[0];
+}
+
+function decode(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment; // malformed escape — keep the raw segment
+  }
+}
+
+/**
+ * Resolve `path` (no query string; query lives in `params`, One-router
+ * semantics) against the six route shapes `createBackofficePaths` writes.
+ * Paths outside `basePath` resolve to `not-found`.
+ */
+export function resolveDeskPath(
+  path: string,
+  basePath: string = BACKOFFICE_BASE,
+  params: BackofficeParams = {},
+): DeskAddress {
+  const base = basePath.replace(/\/+$/, "") || "/";
+  const clean = path.replace(/\/+$/, "") || "/";
+  let rest: string;
+  if (base === "/") rest = clean;
+  else if (clean === base) rest = "/";
+  else if (clean.startsWith(`${base}/`)) rest = clean.slice(base.length);
+  else return { kind: "not-found", path };
+
+  const segments = rest.split("/").filter(Boolean).map(decode);
+  if (segments.length === 0) return { kind: "home" };
+
+  if (segments[0] === "query-report") {
+    if (segments.length === 2 && segments[1]) {
+      return { kind: "report", reportName: segments[1], filtersParam: first(params.filters) };
+    }
+    return { kind: "not-found", path };
+  }
+
+  const slug = segments[0];
+  if (segments.length === 1) {
+    return { kind: "slug", slug, filtersParam: first(params.f), sortParam: first(params.sort) };
+  }
+  if (segments.length === 2 && segments[1] === "new") {
+    return { kind: "slug-new", slug, defaults: parseDocDefaults(first(params.d)) };
+  }
+  if (segments.length === 3 && segments[1] === "view" && isBackofficeView(segments[2])) {
+    const view = segments[2];
+    // /view/list is the list surface (DoctypeViewScreen bounces it too).
+    if (view === "list") {
+      return { kind: "slug", slug, filtersParam: first(params.f), sortParam: first(params.sort) };
+    }
+    const board = first(params.board);
+    const field = first(params.field);
+    const filtersParam = first(params.f);
+    const viewParams: DeskViewParams | undefined =
+      board || field || filtersParam ? { board, field, filtersParam } : undefined;
+    return { kind: "slug-view", slug, view, ...(viewParams && { params: viewParams }) };
+  }
+  if (segments.length === 2) {
+    return { kind: "slug-name", slug, name: segments[1] };
+  }
+  return { kind: "not-found", path };
+}

package/src/desk/scope.tsx

@@ -0,0 +1,52 @@
+/**
+ * Desk scope — the tenant seam (MPO-14 / gap GL-5, spec 09 §DM-4).
+ *
+ * `scope` filters are ALWAYS ANDed into every doctype-homed query, invisible
+ * to the filter chrome and not removable by the user. Before this context
+ * existed the seam reached exactly one surface (DoctypeListScreen's
+ * `fixedFilters`), so a scoped desk leaked rows the moment the user switched
+ * to kanban. Surfaces read the context themselves; hosts set it once via
+ * `<Desk scope={…} />` (or `DeskScopeProvider` directly).
+ *
+ * Scope applies to doctype-homed surfaces (list, kanban, calendar, tree,
+ * image, dashboard, report view). Query/Script reports run server-side SQL
+ * and the awesomebar searches across doctypes, so field-tuple scope cannot
+ * soundly AND into either; restrict those with `capabilities` instead.
+ */
+import type { ReactNode } from "react";
+import { createContext, useContext, useMemo } from "react";
+import type { FrappeFilters } from "../shared/types";
+
+const EMPTY_SCOPE: FrappeFilters = [];
+
+const DeskScopeContext = createContext<FrappeFilters>(EMPTY_SCOPE);
+
+export interface DeskScopeProviderProps {
+  /** Filter tuples ANDed into every doctype-homed query in the subtree. */
+  scope?: FrappeFilters;
+  children: ReactNode;
+}
+
+export function DeskScopeProvider({ scope, children }: DeskScopeProviderProps) {
+  // Value-keyed so unstable array literals from the host don't churn readers.
+  const scopeKey = JSON.stringify(scope ?? EMPTY_SCOPE);
+  const value = useMemo(() => (JSON.parse(scopeKey) as FrappeFilters) ?? EMPTY_SCOPE, [scopeKey]);
+  return <DeskScopeContext.Provider value={value}>{children}</DeskScopeContext.Provider>;
+}
+
+/** The ambient desk scope; `[]` outside any DeskScopeProvider. */
+export function useDeskScope(): FrappeFilters {
+  return useContext(DeskScopeContext);
+}
+
+/**
+ * AND the ambient scope into `filters`. Returns `undefined` when there is
+ * nothing to apply, so callers can spread-conditionally into leaf props.
+ */
+export function useScopedFilters(filters?: FrappeFilters): FrappeFilters | undefined {
+  const scope = useDeskScope();
+  return useMemo(() => {
+    if (scope.length === 0 && (!filters || filters.length === 0)) return undefined;
+    return [...scope, ...(filters ?? [])];
+  }, [scope, filters]);
+}

package/src/desk/target.ts

@@ -0,0 +1,169 @@
+/**
+ * DeskTarget — the resolved surface (spec 09 §2.2) — and useDeskTarget, the
+ * hook that composes the pure resolver with the runtime slug index.
+ *
+ * Precedence (spec §2.3): `path` beats the pins, the pins beat the navigator
+ * location, the navigator location beats home. A pin plus a live navigator
+ * is legal: the pin is the ENTRY, and once the location moves the navigator
+ * drives, still fenced by whatever scope the pin implied.
+ *
+ * Desk writes no fetch: the only read here is `useSlugTarget`, the exported
+ * once-per-session slug index (DK-2 holding at the one place it was most at
+ * risk).
+ */
+import { useMemo, useRef } from "react";
+import { useBackofficeConfig, useBackofficeLocation } from "../config/BackofficeProvider";
+import { parseBackofficeHref } from "../navigation/navigator";
+import { slugToDisplayName, type BackofficeView } from "../navigation/paths";
+import { useSlugTarget } from "../shared/useSlugTarget";
+import { resolveDeskPath, type DeskAddress, type DeskViewParams } from "./resolveDeskPath";
+
+export type DeskTarget =
+  | { kind: "home" }
+  | { kind: "workspace"; workspace: string }
+  | { kind: "list"; doctype: string; filtersParam?: string; sortParam?: string }
+  | {
+      kind: "view";
+      doctype: string;
+      view: Exclude<BackofficeView, "list">;
+      params?: DeskViewParams;
+    }
+  | { kind: "new"; doctype: string; defaults?: Record<string, unknown> }
+  | { kind: "form"; doctype: string; name: string }
+  | { kind: "report"; reportName: string; filtersParam?: string }
+  | { kind: "not-found"; slug?: string };
+
+/** The surface pins a host sets on `<Desk />` (spec §2, "what it shows"). */
+export interface DeskPins {
+  doctype?: string;
+  name?: string;
+  view?: BackofficeView;
+  workspace?: string;
+  report?: string;
+  path?: string;
+}
+
+export function hasDeskPin(pins: DeskPins): boolean {
+  return Boolean(pins.doctype || pins.workspace || pins.report || pins.path);
+}
+
+/** Pins → target, directly: pins carry proper-cased names, no slug hop. */
+function pinnedTarget(pins: DeskPins): DeskTarget | undefined {
+  if (pins.doctype) {
+    if (pins.name === "new") return { kind: "new", doctype: pins.doctype };
+    if (pins.name) return { kind: "form", doctype: pins.doctype, name: pins.name };
+    if (pins.view && pins.view !== "list") {
+      return { kind: "view", doctype: pins.doctype, view: pins.view };
+    }
+    return { kind: "list", doctype: pins.doctype };
+  }
+  if (pins.workspace) return { kind: "workspace", workspace: pins.workspace };
+  if (pins.report) return { kind: "report", reportName: pins.report };
+  return undefined;
+}
+
+/** Address + resolved slug → target. Ambiguous slugs stay `undefined` while
+ * the index loads (the caller renders a spinner, exactly like SlugScreen). */
+function addressToTarget(
+  address: DeskAddress,
+  slugKind: "workspace" | "doctype" | "loading" | "not-found",
+  slugName: string | undefined,
+): DeskTarget | undefined {
+  switch (address.kind) {
+    case "home":
+      return { kind: "home" };
+    case "report":
+      return { kind: "report", reportName: address.reportName, filtersParam: address.filtersParam };
+    case "not-found":
+      return { kind: "not-found" };
+    default:
+      break;
+  }
+  if (slugKind === "loading") return undefined;
+  if (slugKind === "not-found" || !slugName) return { kind: "not-found", slug: address.slug };
+  if (slugKind === "workspace") {
+    // Only the bare slug route can be a workspace page; /new, /view/x and
+    // /[name] under a workspace slug are dead addresses.
+    return address.kind === "slug"
+      ? { kind: "workspace", workspace: slugName }
+      : { kind: "not-found", slug: address.slug };
+  }
+  switch (address.kind) {
+    case "slug":
+      return {
+        kind: "list",
+        doctype: slugName,
+        filtersParam: address.filtersParam,
+        sortParam: address.sortParam,
+      };
+    case "slug-view":
+      return { kind: "view", doctype: slugName, view: address.view, params: address.params };
+    case "slug-new":
+      return { kind: "new", doctype: slugName, defaults: address.defaults };
+    case "slug-name":
+      return { kind: "form", doctype: slugName, name: address.name };
+  }
+}
+
+/**
+ * Pure, best-effort address→target for pre-navigation interception
+ * (`onNavigate`): the slug degrades to a title-cased doctype guess, the same
+ * degrade `useSlugTarget` applies when the index is unavailable.
+ */
+export function guessDeskTarget(path: string, basePath: string): DeskTarget {
+  const { path: cleanPath, params } = parseBackofficeHref(path);
+  const address = resolveDeskPath(cleanPath, basePath, params);
+  const guess = "slug" in address ? slugToDisplayName(address.slug) : undefined;
+  return addressToTarget(address, guess ? "doctype" : "not-found", guess) ?? { kind: "not-found" };
+}
+
+/**
+ * The desk's current target. `undefined` while an ambiguous slug is still
+ * resolving against the once-per-session index. Must be called under
+ * BackofficeProvider (it reads the navigator location and the frappe
+ * connection from context).
+ */
+export function useDeskTarget(pins: DeskPins): DeskTarget | undefined {
+  const { basePath } = useBackofficeConfig();
+  const location = useBackofficeLocation();
+
+  // The pins (and the `path` prop) are the ENTRY: they win until the
+  // location moves, then the navigator drives (spec §2.3). Location
+  // snapshots have stable identity until they change, so reference
+  // equality against the mount-time snapshot is the "has it moved" test.
+  const initialLocation = useRef(location);
+  const entryActive = location === initialLocation.current;
+
+  const address = useMemo<DeskAddress | undefined>(() => {
+    if (entryActive && pins.path) {
+      const prefix = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+      const { path, params } = parseBackofficeHref(`${prefix}${pins.path}`);
+      return resolveDeskPath(path, basePath, params);
+    }
+    if (entryActive && hasDeskPin(pins)) return undefined; // pinned target, no address
+    return resolveDeskPath(location.path, basePath, location.params);
+  }, [entryActive, pins, basePath, location]);
+
+  const pinned = entryActive && !pins.path ? pinnedTarget(pins) : undefined;
+
+  const slug = !pinned && address && "slug" in address ? address.slug : undefined;
+  const slugTarget = useSlugTarget(slug);
+
+  return useMemo(() => {
+    if (pinned) return pinned;
+    if (!address) return undefined;
+    const slugKind =
+      slugTarget.status === "loading"
+        ? "loading"
+        : slugTarget.status === "not-found"
+          ? "not-found"
+          : slugTarget.kind;
+    const slugName =
+      slugTarget.status === "resolved"
+        ? slugTarget.kind === "workspace"
+          ? slugTarget.workspace
+          : slugTarget.doctype
+        : undefined;
+    return addressToTarget(address, slugKind, slugName);
+  }, [pinned, address, slugTarget]);
+}