@multiplatform.one/frappe-ui 7.11.0 → 7.15.0

package/src/fields/Date/sheetKeyboard.spec.ts

@@ -16,16 +16,25 @@ import {
 
 describe("dateSheetMaxHeight", () => {
   it("uses the 85% detent when the keyboard is down", () => {
-    expect(dateSheetMaxHeight(800, 0)).toBe(Math.round(800 * 0.85));
+    expect(dateSheetMaxHeight(800, 0, 47)).toBe(Math.round(800 * 0.85));
   });
 
   it("caps to the space above the keyboard, less the 48pt backdrop strip", () => {
-    expect(dateSheetMaxHeight(800, 400)).toBe(800 - 400 - DATE_SHEET_BACKDROP_STRIP);
-    expect(dateSheetMaxHeight(800, 400)).toBeLessThan(dateSheetMaxHeight(800, 0));
+    expect(dateSheetMaxHeight(800, 400, 0)).toBe(800 - 400 - DATE_SHEET_BACKDROP_STRIP);
+    expect(dateSheetMaxHeight(800, 400, 0)).toBeLessThan(dateSheetMaxHeight(800, 0, 0));
+  });
+
+  it("keeps the backdrop strip below the status bar, not inside it", () => {
+    const windowHeight = 874;
+    const keyboardInset = 335;
+    const topInset = 62;
+    const sheetTop =
+      windowHeight - keyboardInset - dateSheetMaxHeight(windowHeight, keyboardInset, topInset);
+    expect(sheetTop - topInset).toBe(DATE_SHEET_BACKDROP_STRIP);
   });
 
   it("never collapses below the minimum sheet height", () => {
-    expect(dateSheetMaxHeight(800, 700)).toBe(DATE_SHEET_MIN_HEIGHT);
+    expect(dateSheetMaxHeight(800, 700, 47)).toBe(DATE_SHEET_MIN_HEIGHT);
   });
 });
 
@@ -35,7 +44,7 @@ describe("datePickerHeight", () => {
   });
 
   it("shrinks the calendar so the sheet can sit above the keyboard", () => {
-    const maxHeight = dateSheetMaxHeight(800, 400);
+    const maxHeight = dateSheetMaxHeight(800, 400, 47);
     const height = datePickerHeight("date", maxHeight);
     expect(height).toBeLessThan(DATE_PICKER_CALENDAR_HEIGHT);
     expect(height).toBeLessThanOrEqual(maxHeight);

package/src/fields/Date/sheetKeyboard.ts

@@ -3,8 +3,9 @@
  *
  * The Date iOS sheet used to give the calendar a fixed 360pt height inside a
  * Modal. KeyboardAvoidingView cannot shrink that shape — it pads the container
- * and the sheet overflows off the top. Cap the sheet to the space ABOVE the
- * keyboard (less a strip of backdrop) and shrink the picker to fit.
+ * and the sheet overflows off the top. Cap the sheet to the space between the
+ * status bar and the keyboard (less a strip of backdrop) and shrink the picker
+ * to fit.
  */
 
 export const DATE_SHEET_MAX_HEIGHT_RATIO = 0.85;
@@ -15,12 +16,19 @@ export const DATE_PICKER_CALENDAR_HEIGHT = 360;
 export const DATE_PICKER_WHEEL_HEIGHT = 200;
 const minPickerHeight = 120;
 
-export function dateSheetMaxHeight(windowHeight: number, keyboardInset: number): number {
+export function dateSheetMaxHeight(
+  windowHeight: number,
+  keyboardInset: number,
+  topInset: number,
+): number {
   const available = Math.max(0, windowHeight - keyboardInset);
   return Math.max(
     DATE_SHEET_MIN_HEIGHT,
     Math.round(
-      Math.min(windowHeight * DATE_SHEET_MAX_HEIGHT_RATIO, available - DATE_SHEET_BACKDROP_STRIP),
+      Math.min(
+        windowHeight * DATE_SHEET_MAX_HEIGHT_RATIO,
+        available - topInset - DATE_SHEET_BACKDROP_STRIP,
+      ),
     ),
   );
 }

package/src/fields/DateRange/DateRange.spec.tsx

@@ -8,7 +8,9 @@
  * spec pass). Both are now wired, and the range is carried as the two calendar
  * dates comma-separated — the shape the registry feeds in and reads back.
  */
+import { Form } from "@multiplatform.one/forms";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { useForm } from "@tanstack/react-form";
 import { act, cleanup, fireEvent, waitFor } from "@testing-library/react";
 import type React from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -181,6 +183,71 @@ describe("DateRangeField controlled value (MPO-137)", () => {
   });
 });
 
+describe("DateRangeField uncontrolled and form-bound paths (MPO-137)", () => {
+  it("seeds an uncontrolled field from a wire defaultValue and still emits a pick", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateRangeField label="Period" defaultValue="2026-03-05,2026-03-31" onChange={onChange} />,
+    );
+    expect(trigger(result.container)?.value).toBe("Mar 5, 2026 – Mar 31, 2026");
+
+    await act(async () => {
+      fireEvent.click(trigger(result.container)!);
+    });
+    await waitFor(() => {
+      expect(getDayButton(15)).toBeTruthy();
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(15)!);
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(20)!);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("2026-03-15,2026-03-20");
+    expect(trigger(result.container)?.value).toBe("Mar 15, 2026 – Mar 20, 2026");
+  });
+
+  it("binds name/form inside a TanStack form: the form value paints and a pick writes back", async () => {
+    type Range = { start: Date | null; end: Date | null } | null;
+    let formApi: { state: { values: { period: Range } } } | undefined;
+    function Harness() {
+      const form = useForm({
+        defaultValues: {
+          period: { start: new Date(2026, 2, 5), end: new Date(2026, 2, 31) } as Range,
+        },
+      });
+      formApi = form as unknown as typeof formApi;
+      return (
+        <Form form={form}>
+          <DateRangeField label="Period" name="period" form={form} />
+        </Form>
+      );
+    }
+    const result = renderWithProviders(<Harness />);
+    await waitFor(() => {
+      expect(trigger(result.container)?.value).toBe("Mar 5, 2026 – Mar 31, 2026");
+    });
+
+    await act(async () => {
+      fireEvent.click(trigger(result.container)!);
+    });
+    await waitFor(() => {
+      expect(getDayButton(15)).toBeTruthy();
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(15)!);
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(20)!);
+    });
+    const period = formApi?.state.values.period;
+    expect(period?.start?.toDateString()).toBe(new Date(2026, 2, 15).toDateString());
+    expect(period?.end?.toDateString()).toBe(new Date(2026, 2, 20).toDateString());
+    expect(trigger(result.container)?.value).toBe("Mar 15, 2026 – Mar 20, 2026");
+  });
+});
+
 describe("registry resolution (Date Range fieldtype)", () => {
   function propsFor(overrides: Partial<FieldRenderProps> = {}): FieldRenderProps {
     return { value: "", onChange: () => {}, ...overrides };

package/src/fields/DateRange/index.tsx

@@ -97,6 +97,10 @@ export function DateRangeField<
   // re-seeds its display state from every new `value` identity, which would
   // otherwise discard a half-picked range on an unrelated re-render.
   const rangeValue = useMemo(() => toPickerRange(wireValue), [wireValue]);
+  const rangeDefault = useMemo(
+    () => (typeof defaultValue === "string" ? toPickerRange(defaultValue) : defaultValue),
+    [defaultValue],
+  );
 
   return (
     <FormsDateRangePicker
@@ -105,7 +109,7 @@ export function DateRangeField<
       validators={validators}
       value={rangeValue}
       onChange={(range) => emit?.(toWireValue(range))}
-      defaultValue={defaultValue}
+      defaultValue={rangeDefault}
       label={fieldProps.label}
       labelProps={fieldProps.labelProps}
       error={fieldProps.error}

package/src/fields/LinkTree.spec.tsx

@@ -101,6 +101,14 @@ describe("LinkTree adapter (MPO-111)", () => {
     expect(screen.queryByText("Should not win")).toBeNull();
   });
 
+  it("still mounts TreeSelect with the placeholder when the forest is empty", () => {
+    mockUseLiveQuery.mockReturnValue({ data: [], isLoading: false, isError: false });
+    const result = renderTree();
+    expect(result.container.querySelector('[data-testid="tree-select"]')).toBeTruthy();
+    expect(result.container.querySelector('[data-testid="tree-select-trigger"]')).toBeTruthy();
+    expect(screen.getByText("Select Account")).toBeTruthy();
+  });
+
   it("does not call onChange when disabled", () => {
     const onChange = vi.fn();
     renderTree({ value: "Assets", onChange, disabled: true });

package/src/fields/LinkTree.stories.tsx

@@ -114,12 +114,9 @@ function regionMeta(name: string) {
   };
 })();
 
-function host(children: ReactNode) {
+function host(children: ReactNode, docs: Region[] = regionDocs) {
   return (
-    <FrappeProvider
-      baseURL={MOCK_HOST}
-      fixtures={new InMemoryFixtureProvider({ QaRegion: regionDocs })}
-    >
+    <FrappeProvider baseURL={MOCK_HOST} fixtures={new InMemoryFixtureProvider({ QaRegion: docs })}>
       {children}
     </FrappeProvider>
   );
@@ -160,6 +157,32 @@ export const AllStates = () =>
     </YStack>,
   );
 
+export const Empty = () => host(<ControlledTree label="Region (empty forest)" />, []);
+Empty.parameters = {
+  docs: {
+    description: {
+      story:
+        "Tree DocType with no rows: TreeSelect still mounts with the placeholder and an empty forest, so the field never degrades to a blank or a spinner that never settles.",
+    },
+  },
+};
+
+export const Nested = () =>
+  host(
+    <YStack gap="$4" width={400}>
+      <ControlledTree label="Leaf, three levels deep" value="North A1" />
+      <ControlledTree label="Branch, two levels deep" value="North A" />
+    </YStack>,
+  );
+Nested.parameters = {
+  docs: {
+    description: {
+      story:
+        "North > North A > North A1: a stored link to a nested node resolves through the loaded forest, so the trigger shows the node's title_field, not its name.",
+    },
+  },
+};
+
 export const ViaLink = () => {
   const [value, setValue] = useState("North A");
   return host(

package/src/fields/Select/Select.hydration.spec.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+/**
+ * MPO-279: the Frappe `Select` field (the registry's SelectField) server-renders
+ * the sheet trigger at every width, because the server has no viewport. These
+ * hydrate that markup at a phone width and a desktop width, then drive the
+ * hydrated control by pointer and by keyboard and read its combobox ARIA.
+ */
+import { TestProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, waitFor } from "@testing-library/react";
+import { act, useLayoutEffect, useState } from "react";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Select } from ".";
+
+const options = ["Alpha", "Beta", "Gamma", "Delta"];
+let onChange = vi.fn();
+let hydrationTrigger: Element | null = null;
+
+function CommitProbe() {
+  useLayoutEffect(() => {
+    hydrationTrigger ??= document.querySelector('[role="combobox"]');
+  }, []);
+  return null;
+}
+
+function Fixture() {
+  const [value, setValue] = useState("Beta");
+  return (
+    <TestProviders>
+      <output>{value}</output>
+      <Select
+        label="Choice"
+        options={options}
+        value={value}
+        onChange={(next: unknown) => {
+          onChange(next);
+          setValue(String(next));
+        }}
+      />
+      <CommitProbe />
+    </TestProviders>
+  );
+}
+
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+let errors: unknown[] = [];
+
+async function hydrateAt(width: number) {
+  vi.spyOn(window, "scrollTo").mockImplementation(() => {});
+  Object.defineProperty(window, "innerWidth", { configurable: true, value: width, writable: true });
+  const browserWindow = window;
+  let html: string;
+  vi.stubGlobal("window", undefined);
+  try {
+    html = renderToString(<Fixture />);
+  } finally {
+    vi.stubGlobal("window", browserWindow);
+  }
+  container = document.createElement("div");
+  container.innerHTML = html;
+  document.body.append(container);
+  const serverTrigger = container.querySelector('[role="combobox"]');
+  errors = [];
+  hydrationTrigger = null;
+  onChange = vi.fn();
+  vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+  await act(async () => {
+    root = hydrateRoot(container!, <Fixture />, {
+      onRecoverableError: (error) => errors.push(error),
+    });
+  });
+  return { serverTrigger, view: container };
+}
+
+const hydrationErrors = () =>
+  errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error)));
+const trigger = () => document.querySelector('[role="combobox"]') as HTMLElement;
+const listOptions = () => [...document.querySelectorAll('[role="option"]')] as HTMLElement[];
+const option = (label: string) => listOptions().find((node) => node.textContent?.includes(label))!;
+
+/** One act per event: a browser flushes React between discrete events. */
+async function press(node: Element) {
+  await act(async () => fireEvent.pointerDown(node, { button: 0, pointerId: 1 }));
+  await act(async () => fireEvent.mouseDown(node, { detail: 1 }));
+  await act(async () => fireEvent.mouseUp(node, { detail: 1 }));
+  await act(async () => fireEvent.click(node, { detail: 1 }));
+}
+
+const focused = () => document.activeElement as HTMLElement;
+
+async function key(node: Element, name: string) {
+  await act(async () => {
+    fireEvent.keyDown(node, { key: name, code: name === " " ? "Space" : name });
+  });
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = undefined;
+  container?.remove();
+  container = undefined;
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("SelectField SSR to hydration (MPO-279)", () => {
+  it.each([390, 1200])(
+    "hydrates the server trigger at %i pixels with no recoverable error",
+    async (width) => {
+      const { serverTrigger } = await hydrateAt(width);
+      expect(serverTrigger).toBeTruthy();
+      expect(hydrationTrigger).toBe(serverTrigger);
+      expect(hydrationErrors()).toEqual([]);
+      await waitFor(() => expect(trigger().textContent).toContain("Beta"));
+      expect(trigger().getAttribute("aria-haspopup")).toBe("listbox");
+      expect(trigger().getAttribute("aria-expanded")).toBe("false");
+      if (width === 390) expect(trigger()).toBe(serverTrigger);
+    },
+  );
+
+  it("desktop: keyboard opens on the selected option, navigates, selects and closes", async () => {
+    await hydrateAt(1200);
+    await key(trigger(), "Enter");
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("true"));
+    expect(listOptions().map((node) => node.textContent?.trim())).toEqual(options);
+    expect(option("Beta").getAttribute("aria-selected")).toBe("true");
+    expect(document.querySelector('[role="listbox"]')).toBeTruthy();
+
+    await waitFor(() => expect(focused()).toBe(option("Beta")));
+    await key(focused(), "ArrowDown");
+    await waitFor(() => expect(focused()).toBe(option("Gamma")));
+    await key(focused(), "Enter");
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("false"));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith("Gamma");
+    expect(container?.querySelector("output")?.textContent).toBe("Gamma");
+    expect(trigger().textContent).toContain("Gamma");
+  });
+
+  it("desktop: Escape closes without changing the value", async () => {
+    await hydrateAt(1200);
+    await key(trigger(), "ArrowDown");
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("true"));
+    await key(document.activeElement ?? document.body, "Escape");
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("false"));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(trigger().textContent).toContain("Beta");
+  });
+
+  it("desktop: pointer opens, selects, and an outside press dismisses", async () => {
+    await hydrateAt(1200);
+    await press(trigger());
+    await waitFor(() => expect(listOptions().length).toBe(options.length));
+    await press(option("Delta"));
+    await waitFor(() => expect(container?.querySelector("output")?.textContent).toBe("Delta"));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith("Delta");
+
+    await press(trigger());
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("true"));
+    await press(document.body);
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("false"));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("phone: the sheet opens by pointer and selects, and wires aria-controls while open", async () => {
+    await hydrateAt(390);
+    await press(trigger());
+    await waitFor(() => expect(trigger().getAttribute("aria-expanded")).toBe("true"));
+    const controls = trigger().getAttribute("aria-controls");
+    expect(controls).toBeTruthy();
+    expect(document.getElementById(controls!)?.getAttribute("role")).toBe("listbox");
+    await press(option("Alpha"));
+    await waitFor(() => expect(container?.querySelector("output")?.textContent).toBe("Alpha"));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith("Alpha");
+  });
+});

package/src/formEngine/doctypeMeta.ts

@@ -1,117 +1,18 @@
 /**
- * DocType meta shapes as `frappe.desk.form.load.getdoctype` returns them.
- *
- * These were declared in `@multiplatform.one/backoffice`
- * (`shared/useDoctypeMeta.ts`) while the desk form engine lived there. The
- * engine now lives here (MPO-15), so the shapes it consumes live here too —
- * a lower-tier package must never reach up into backoffice for a type.
- * `useDoctypeMeta` (the loader hook, which needs the backoffice app context)
- * stays where it is and re-exports these.
- *
- * Deliberately loose: the server is the source of truth, `0 | 1` flags are
- * what the RPC actually sends, and the index signature carries the keys no
- * surface has needed yet. `fieldtype` stays `string` here; narrowing it to
- * the `FrappeFieldType` union is the remaining half of MPO-15's meta-model
- * criterion and is tracked there, not silently done in a move.
+ * The desk's names for the one DocType meta model, which
+ * `@multiplatform.one/frappe` declares (MPO-15). These are aliases, not
+ * shapes: the form engine, the backoffice surfaces and `useDocTypeMeta`
+ * all read the same `DocTypeField` / `DocTypeMeta`, so a field key the
+ * server sends reaches every one of them or none.
  */
+import type {
+  DocTypeField,
+  DocTypeLink,
+  DocTypeMeta,
+  DocTypePermission,
+} from "@multiplatform.one/frappe";
 
-/** A single DocField row from a DocType meta (loose — server is source of truth). */
-export interface DocFieldMeta {
-  fieldname: string;
-  label?: string;
-  fieldtype: string;
-  options?: string;
-  reqd?: 0 | 1;
-  hidden?: 0 | 1;
-  read_only?: 0 | 1;
-  bold?: 0 | 1;
-  in_list_view?: 0 | 1;
-  in_standard_filter?: 0 | 1;
-  in_global_search?: 0 | 1;
-  allow_in_quick_entry?: 0 | 1;
-  allow_on_submit?: 0 | 1;
-  no_copy?: 0 | 1;
-  collapsible?: 0 | 1;
-  collapsible_depends_on?: string;
-  depends_on?: string;
-  mandatory_depends_on?: string;
-  read_only_depends_on?: string;
-  fetch_from?: string;
-  permlevel?: number;
-  length?: number;
-  default?: string;
-  description?: string;
-  precision?: string | number;
-  idx?: number;
-  [key: string]: unknown;
-}
-
-/** DocType Link child row (Connections tab). Probed: `group` arrives null when unset. */
-export interface DocLinkMeta {
-  name?: string;
-  link_doctype: string;
-  link_fieldname: string;
-  group?: string | null;
-  hidden?: 0 | 1;
-  is_child_table?: 0 | 1;
-  parent_doctype?: string;
-  table_fieldname?: string;
-  [key: string]: unknown;
-}
-
-/** Role permission row from the DocType meta. */
-export interface DocPermissionRule {
-  role?: string;
-  permlevel?: number;
-  read?: 0 | 1;
-  write?: 0 | 1;
-  create?: 0 | 1;
-  delete?: 0 | 1;
-  submit?: 0 | 1;
-  cancel?: 0 | 1;
-  amend?: 0 | 1;
-  print?: 0 | 1;
-  email?: 0 | 1;
-  share?: 0 | 1;
-  if_owner?: 0 | 1;
-  [key: string]: unknown;
-}
-
-/** DocType meta as returned by frappe.desk.form.load.getdoctype (loose). */
-export interface DoctypeMeta {
-  doctype?: string;
-  name: string;
-  module?: string;
-  issingle?: 0 | 1;
-  istable?: 0 | 1;
-  is_submittable?: 0 | 1;
-  is_tree?: 0 | 1;
-  /** Desk treeview_settings asset (`{doctype}_tree.js`) — gates Tree. */
-  __tree_js?: string;
-  /** Desk calendar_settings asset (`{doctype}_calendar.js`) — gates Calendar. */
-  __calendar_js?: string;
-  is_virtual?: 0 | 1;
-  editable_grid?: 0 | 1;
-  track_changes?: 0 | 1;
-  quick_entry?: 0 | 1;
-  autoname?: string;
-  naming_rule?: string;
-  allow_rename?: 0 | 1;
-  allow_copy?: 0 | 1;
-  read_only?: 0 | 1;
-  in_create?: 0 | 1;
-  hide_toolbar?: 0 | 1;
-  max_attachments?: number;
-  title_field?: string;
-  image_field?: string;
-  search_fields?: string;
-  sort_field?: string;
-  sort_order?: string;
-  icon?: string;
-  document_type?: string;
-  fields: DocFieldMeta[];
-  permissions?: DocPermissionRule[];
-  links?: DocLinkMeta[];
-  states?: Array<{ title?: string; color?: string } & Record<string, unknown>>;
-  [key: string]: unknown;
-}
+export type DocFieldMeta = DocTypeField;
+export type DocLinkMeta = DocTypeLink;
+export type DocPermissionRule = DocTypePermission;
+export type DoctypeMeta = DocTypeMeta;

package/src/formEngine/index.ts

@@ -31,3 +31,5 @@ export type { BuildTabsOptions, FormTab } from "./formLayout";
 
 export { useFormEngine } from "./useFormEngine";
 export type { FormEngine } from "./useFormEngine";
+
+export { useSessionRoles } from "./useSessionRoles";

package/src/formEngine/seam.spec.ts

@@ -20,9 +20,17 @@
  *     modules directly, so importing the engine never drags SchemaForm,
  *     FrappeTable and the whole table/native stack into a node-ish consumer.
  */
+import type {
+  DocTypeField,
+  DocTypeLink,
+  DocTypeMeta,
+  DocTypePermission,
+  FrappeFieldType,
+} from "@multiplatform.one/frappe";
 import fs from "node:fs";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import type { DocFieldMeta, DocLinkMeta, DocPermissionRule, DoctypeMeta } from "./doctypeMeta";
 import * as formEngine from "./index";
 
 const engineDir = path.resolve(__dirname);
@@ -129,10 +137,21 @@ describe("form-engine seam (MPO-15)", () => {
     }
   });
 
-  it("keeps the meta shapes here, where the engine that consumes them lives", () => {
+  it("takes the one meta model from @multiplatform.one/frappe and declares none of its own", () => {
+    expectTypeOf<DocFieldMeta>().toEqualTypeOf<DocTypeField>();
+    expectTypeOf<DoctypeMeta>().toEqualTypeOf<DocTypeMeta>();
+    expectTypeOf<DocPermissionRule>().toEqualTypeOf<DocTypePermission>();
+    expectTypeOf<DocLinkMeta>().toEqualTypeOf<DocTypeLink>();
+    expectTypeOf<DocFieldMeta["fieldtype"]>().toEqualTypeOf<FrappeFieldType>();
+
     const meta = fs.readFileSync(path.resolve(engineDir, "doctypeMeta.ts"), "utf-8");
-    for (const name of ["DocFieldMeta", "DocLinkMeta", "DocPermissionRule", "DoctypeMeta"]) {
-      expect(meta, name).toContain(`export interface ${name}`);
+    expect(meta).toMatch(/from ["']@multiplatform\.one\/frappe["']/);
+    for (const file of sourceFiles(srcDir)) {
+      if (file.includes(".spec.") || file.includes(".stories.")) continue;
+      const source = fs.readFileSync(file, "utf-8");
+      expect(source, file).not.toMatch(
+        /export interface (DocFieldMeta|DoctypeMeta|DocTypeField|DocTypeMeta)\b/,
+      );
     }
     // The shapes reach the engine by relative import, never through the barrel.
     for (const file of [

package/src/formEngine/useSessionRoles.ts

@@ -0,0 +1,73 @@
+/**
+ * Session user's role list — the client-side half of desk's
+ * `frappe.user_roles` (bootinfo). Fetched once per site via the whitelisted
+ * `frappe.core.doctype.user.user.get_roles` RPC (probed:
+ * `?uid=<user>` → `{"message": ["Role", ...]}`), keyed off
+ * `frappe.auth.get_logged_user`.
+ *
+ * Undefined while loading, on a fixtures-only connection, or when the RPC
+ * fails. The permlevel matrix then takes the conservative
+ * "permlevel > 0 → read-only" rule (fieldPermissions.ts).
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { createHttpClient, type FrappeConnection } from "./formActions";
+
+const rolesCache = new Map<string, Promise<string[]>>();
+
+function fetchSessionRoles(connection: FrappeConnection): Promise<string[]> {
+  const http = createHttpClient(connection);
+  return http
+    .get<{ message?: string }>("/api/method/frappe.auth.get_logged_user")
+    .then((res) => {
+      const user = res.payload?.message;
+      if (!user) throw new Error("No session user");
+      return http.get<{ message?: string[] }>(
+        "/api/method/frappe.core.doctype.user.user.get_roles",
+        { uid: user },
+      );
+    })
+    .then((res) => {
+      const list = res.payload?.message;
+      if (!Array.isArray(list)) throw new Error("No roles returned");
+      return list;
+    });
+}
+
+/** A connection that may not name a bench yet (a provider's config before it resolves). */
+type SessionConnection = Omit<FrappeConnection, "baseURL"> & { baseURL?: string };
+
+export function useSessionRoles(connection: SessionConnection | undefined): string[] | undefined {
+  const baseURL = connection?.baseURL;
+  const fixtures = connection?.fixtures;
+  const [roles, setRoles] = useState<string[] | undefined>(undefined);
+  const connectionRef = useRef(connection);
+  connectionRef.current = connection;
+
+  useEffect(() => {
+    const current = connectionRef.current;
+    if (!current || fixtures || !baseURL) {
+      setRoles(undefined);
+      return;
+    }
+    let cancelled = false;
+    let promise = rolesCache.get(baseURL);
+    if (!promise) {
+      promise = fetchSessionRoles({ ...current, baseURL });
+      rolesCache.set(baseURL, promise);
+      promise.catch(() => rolesCache.delete(baseURL));
+    }
+    promise
+      .then((list) => {
+        if (!cancelled) setRoles(list);
+      })
+      .catch(() => {
+        if (!cancelled) setRoles(undefined);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [baseURL, fixtures]);
+
+  return roles;
+}