@multiplatform.one/frappe-ui 7.28.0 → 7.29.0

package/src/formEngine/docPermissions.spec.ts

@@ -3,7 +3,14 @@
 // get_role_permissions: permlevel 0 only, OR across the user's roles,
 // if_owner rows scoped to the user's own records except create.
 import { describe, expect, it } from "vitest";
-import { allDocRights, resolveDocRights, sessionDocRights, type DocRights } from "./docPermissions";
+import {
+  allDocRights,
+  docinfoRights,
+  fixtureDocRights,
+  resolveDocRights,
+  sessionDocRights,
+  type DocRights,
+} from "./docPermissions";
 import type { DocPermissionRule } from "./doctypeMeta";
 
 const pokeMove: DocPermissionRule[] = [
@@ -143,3 +150,31 @@ describe("sessionDocRights", () => {
     expect([rights.create, rights.write, rights.delete]).toEqual([true, true, true]);
   });
 });
+
+describe("docinfoRights", () => {
+  it("takes the bench's per-record answer as it is", () => {
+    const rights = docinfoRights({ read: 1, write: 1, submit: 0, print: 1 });
+    expect(rights && granted(rights)).toEqual(["print", "read", "write"]);
+  });
+
+  it("is no answer when the payload carries no read key (token-auth {null: 0})", () => {
+    expect(docinfoRights({ null: 0 })).toBeUndefined();
+    expect(docinfoRights(undefined)).toBeUndefined();
+  });
+});
+
+describe("fixtureDocRights", () => {
+  it("grants what any permlevel-0 row grants, never a higher level's rights", () => {
+    const rights = fixtureDocRights({ permissions: pokeMove });
+    expect(granted(rights)).toEqual(["create", "delete", "export", "read", "write"]);
+  });
+
+  it("keeps write, create, email and print for a doctype without rows", () => {
+    expect(granted(fixtureDocRights({ permissions: [] }))).toEqual([
+      "create",
+      "email",
+      "print",
+      "write",
+    ]);
+  });
+});

package/src/formEngine/docPermissions.ts

@@ -126,3 +126,37 @@ export function sessionDocRights({
   if (!meta || !roles) return allDocRights(false);
   return resolveDocRights({ permissions: meta.permissions, roles, user, owner, shares });
 }
+
+/**
+ * A record's rights as the bench evaluated them for this user: docinfo's
+ * `permissions` (desk `frm.perm[0]` from getdoc). A payload with no `read`
+ * key is not an answer (a token-auth bench sends `{"null": 0}`), so it gives
+ * undefined and the caller keeps the session's rights.
+ */
+export function docinfoRights(
+  permissions: Readonly<Record<string, unknown>> | null | undefined,
+): DocRights | undefined {
+  if (!permissions || !("read" in permissions)) return undefined;
+  const rights = allDocRights(false);
+  for (const right of docRightNames) rights[right] = !!permissions[right];
+  return rights;
+}
+
+/**
+ * The desk's rights on a fixtures connection, where no session exists: what
+ * any permlevel-0 DocPerm row of the doctype grants, so a story offers the
+ * actions its meta allows. A doctype without rows keeps write, create,
+ * email and print.
+ */
+export function fixtureDocRights(meta: Pick<DoctypeMeta, "permissions"> | undefined): DocRights {
+  const rows = (meta?.permissions ?? []).filter((row) => !(Number(row.permlevel ?? 0) || 0));
+  const rights = allDocRights(false);
+  for (const right of docRightNames) rights[right] = rows.some((row) => !!row[right]);
+  if ((meta?.permissions ?? []).length === 0) {
+    rights.write = true;
+    rights.create = true;
+    rights.email = true;
+    rights.print = true;
+  }
+  return rights;
+}

package/src/formEngine/index.ts

@@ -35,7 +35,14 @@ export type { FormEngine } from "./useFormEngine";
 export { useFrappeSession, useSessionRoles } from "./useSessionRoles";
 export type { FrappeSession } from "./useSessionRoles";
 
-export { allDocRights, docRightNames, resolveDocRights, sessionDocRights } from "./docPermissions";
+export {
+  allDocRights,
+  docinfoRights,
+  docRightNames,
+  fixtureDocRights,
+  resolveDocRights,
+  sessionDocRights,
+} from "./docPermissions";
 export type {
   DocRight,
   DocRights,

package/src/frappeRemainder.designLaw.spec.ts

@@ -102,7 +102,15 @@ describe("Frappe remainder wrappers — design-law 100%", () => {
   });
 
   it("FrappeReportBuilder uses house Button + PopoverContent and R7 weight 400", () => {
-    const source = read("FrappeReportBuilder.tsx");
+    // The builder composes its toolbar and grid (MPO-15, GL-28); the law
+    // holds over the three files together.
+    const source = [
+      "FrappeReportBuilder.tsx",
+      "report/ReportViewToolbar.tsx",
+      "report/ReportGrid.tsx",
+    ]
+      .map(read)
+      .join("\n");
     expect(source).toContain("PopoverContent");
     expect(source).toContain('from "@multiplatform.one/forms"');
     expect(source).toContain("Button");

package/src/frappeRoutes.spec.tsx

@@ -69,6 +69,8 @@ let writes: Write[] = [];
 let guest = false;
 let session: { user: string; roles: string[] } | null = editor;
 let sessionAnswered = false;
+let movesListed: Promise<void> = Promise.resolve();
+let markMovesListed = () => {};
 let confirmDelete = vi.fn(() => true);
 
 function json(body: unknown, status = 200) {
@@ -115,6 +117,7 @@ function stubBench() {
       const rows = [...moves.values()].filter((row) =>
         matchesNameFilter(row, url.searchParams.get("filters")),
       );
+      if (url.searchParams.get("fields")?.includes('"move_name"')) markMovesListed();
       return json({ data: rows });
     }
     if (url.pathname.startsWith(`${resource}/`)) {
@@ -209,6 +212,9 @@ beforeEach(() => {
   guest = false;
   session = editor;
   sessionAnswered = false;
+  movesListed = new Promise((resolve) => {
+    markMovesListed = resolve;
+  });
   writes = [];
   moves = new Map([
     [
@@ -283,6 +289,9 @@ describe("FrappeListView with a route", () => {
   it("offers no Add to a reader who cannot load the doctype's meta", async () => {
     guest = true;
     const { container } = renderAt("/moves", "list");
+    // A 403 on meta costs two more round trips before a row can show: a
+    // one-doc peek, then the re-read with its keys. Wait for that read.
+    await movesListed;
     await waitFor(() => expect(screen.getByText("tackle")).toBeTruthy());
     expect(() => button(container, `Add ${doctype}`)).toThrow();
   });

package/src/frappeViews.designLaw.spec.ts

@@ -75,11 +75,24 @@ describe("Frappe view adapters — design-law 100%", () => {
     expect(source).not.toMatch(/fontSize="\$1"|fontSize="\$2"/);
   });
 
+  it("report view toolbar filters are catalog Chip, not 999-radius wells", () => {
+    const source = read("report/ReportViewToolbar.tsx");
+    expect(source).toContain("<Chip");
+    expect(source).not.toMatch(/borderRadius=\{999\}/);
+  });
+
   it("FrappeReportBuilder toolbar is house Button and captions lock 400 (R7 / LC-54)", () => {
-    const source = read("FrappeReportBuilder.tsx");
+    // The builder composes its toolbar and grid (MPO-15, GL-28); the law
+    // holds over the three files together.
+    const source = [
+      "FrappeReportBuilder.tsx",
+      "report/ReportViewToolbar.tsx",
+      "report/ReportGrid.tsx",
+    ]
+      .map(read)
+      .join("\n");
     expect(source).toMatch(/import \{[^}]*Button[^}]*\} from "@multiplatform.one\/forms"/);
     expect(source).not.toMatch(/Button.*from "tamagui"/);
-    expect(source).toContain("formCommonColors");
     expect(source).not.toMatch(/fontWeight="600"|fontWeight="500"/);
     expect(source).toContain('fontWeight="400"');
     expect(source).not.toMatch(/<Button\b[^>]*\b(?:controlFill|backgroundColor|borderColor)=/);

package/src/guestFallback.spec.tsx

@@ -0,0 +1,236 @@
+// LC-96 (MPO-15 AC10): a data-aware view degrades to the weakest honest
+// rendering, never a blank. The bench below refuses getdoctype the way Frappe
+// refuses it to Guest, answers or refuses the record reads per test, and
+// refuses or breaks a query report's run. Each rung of the ladder is one test:
+// meta refused but the rows readable, the record refused too, nothing to
+// create from, and a read that failed for some other reason, for the form, the
+// list and both report views.
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FrappeForm } from "./FrappeForm";
+import { FrappeListView } from "./FrappeListView";
+import { frappeRouteTarget, type FrappeNavigation } from "./frappeNavigation";
+import { FrappeProvider } from "./FrappeProvider";
+import { FrappeReportBuilder } from "./FrappeReportBuilder";
+import { FrappeReportView } from "./FrappeReportView";
+
+const doctype = "Poke Move";
+const route = "/moves";
+
+interface Move {
+  name: string;
+  doctype: string;
+  move_name?: string;
+  power?: number;
+}
+
+const tackle = {
+  name: "a1b2c3",
+  doctype,
+  owner: "Administrator",
+  modified: "2026-09-29 10:00:00",
+  docstatus: 0,
+  idx: 0,
+  _user_tags: null,
+  move_name: "tackle",
+  power: 40,
+  accuracy: 0.95,
+};
+
+const settle = { timeout: 8000 };
+
+let run = 0;
+let bench = "";
+let metaAnswer: "refused" | "broken" = "refused";
+let recordsReadable = true;
+let reportRun: "refused" | "broken" = "refused";
+const reportName = "Move Usage";
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function stubBench() {
+  vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+    const url = new URL(String(input instanceof Request ? input.url : input));
+    const method = url.pathname.replace(/^\/api\/method\//, "");
+    if (method === "frappe.desk.form.load.getdoctype") {
+      return metaAnswer === "refused"
+        ? json({ exc_type: "PermissionError", exception: "Not permitted" }, 403)
+        : json({ exc_type: "ValidationError", exception: "Poke Move is being migrated" }, 417);
+    }
+    if (method === "frappe.desk.query_report.run") {
+      return reportRun === "refused"
+        ? json(
+            {
+              exc_type: "PermissionError",
+              _server_messages: JSON.stringify([
+                JSON.stringify({ message: `You don't have access to Report: ${reportName}` }),
+              ]),
+            },
+            403,
+          )
+        : json({ exc_type: "ValidationError", exception: "Move Usage timed out" }, 417);
+    }
+    if (method === "frappe.auth.get_logged_user" || method.endsWith(".get_roles")) {
+      return json({ exc_type: "PermissionError" }, 403);
+    }
+    const resource = `/api/resource/${encodeURIComponent(doctype)}`;
+    if (url.pathname === resource || url.pathname.startsWith(`${resource}/`)) {
+      if (!recordsReadable) {
+        return json({ exc_type: "PermissionError", exception: "Not permitted" }, 403);
+      }
+      return url.pathname === resource ? json({ data: [tackle] }) : json({ data: tackle });
+    }
+    return json({ data: [], message: [] });
+  });
+}
+
+function renderAt(pathname: string, page: "list" | "form") {
+  const navigation: FrappeNavigation = {
+    usePathname: () => pathname,
+    useNavigate: () => () => undefined,
+  };
+  return renderWithProviders(
+    <FrappeProvider baseURL={bench} realtime={false} navigation={navigation}>
+      {page === "list" ? (
+        <FrappeListView<Move> doctype={doctype} route={route} defaultViewMode="table" />
+      ) : (
+        <FrappeForm<Move> doctype={doctype} route={route} />
+      )}
+    </FrappeProvider>,
+  );
+}
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  run += 1;
+  bench = `http://guest-fallback-${run}.spec.test`;
+  metaAnswer = "refused";
+  recordsReadable = true;
+  reportRun = "refused";
+  stubBench();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("LC-96 guest fallback: meta refused, rows readable", () => {
+  it("a record page lays out the record's own fields, read-only", async () => {
+    expect(frappeRouteTarget(route, "/moves/a1b2c3")).toEqual({ mode: "view", name: "a1b2c3" });
+    renderAt("/moves/a1b2c3", "form");
+    const power = (await screen.findByLabelText("Power", { exact: false }, settle)) as HTMLElement;
+    const input = power instanceof HTMLInputElement ? power : power.querySelector("input");
+    expect(input?.value).toBe("40");
+    expect(input?.disabled || input?.readOnly).toBe(true);
+    expect(screen.getByLabelText("Accuracy", { exact: false })).toBeTruthy();
+    for (const bookkeeping of ["Owner", "Modified", "Docstatus", "Idx", "User Tags"]) {
+      expect(screen.queryByLabelText(bookkeeping, { exact: true })).toBeNull();
+    }
+  });
+
+  it("a list table takes its columns from one record instead of a lone Name", async () => {
+    renderAt("/moves", "list");
+    await waitFor(() => expect(screen.getAllByText("tackle").length).toBeGreaterThan(0), settle);
+    await waitFor(() => expect(screen.getByText("Move Name")).toBeTruthy(), settle);
+    expect(screen.getByText("Power")).toBeTruthy();
+    expect(screen.queryByText("Owner")).toBeNull();
+  });
+});
+
+describe("LC-96 guest fallback: nothing readable to fall back to", () => {
+  it("a create page says the reader can't create, with the server's reason, not a load failure", async () => {
+    renderAt("/moves/new", "form");
+    const state = await screen.findByTestId("frappe-form-not-permitted", {}, settle);
+    expect(state.textContent).toContain(`You can't create ${doctype}`);
+    expect(screen.queryByText(`Failed to load ${doctype} form`)).toBeNull();
+  });
+
+  it("a record page whose record is refused too says the reader can't open it, with no retry", async () => {
+    recordsReadable = false;
+    renderAt("/moves/a1b2c3", "form");
+    const state = await screen.findByTestId("frappe-form-not-permitted", {}, settle);
+    expect(state.textContent).toContain(`You can't open ${doctype} a1b2c3`);
+    expect(screen.queryByText(`Failed to load ${doctype}`)).toBeNull();
+    expect(screen.queryByRole("button", { name: /retry/i })).toBeNull();
+  });
+
+  it("a meta read that failed for another reason is an error state, not a permission one", async () => {
+    metaAnswer = "broken";
+    renderAt("/moves/new", "form");
+    const alert = await screen.findByText(`Failed to load ${doctype} form`, {}, settle);
+    expect(alert).toBeTruthy();
+    expect(screen.queryByTestId("frappe-form-not-permitted")).toBeNull();
+  });
+});
+
+function renderReport(view: "builder" | "query") {
+  return renderWithProviders(
+    <FrappeProvider baseURL={bench} realtime={false}>
+      {view === "builder" ? (
+        <FrappeReportBuilder doctype={doctype} />
+      ) : (
+        <FrappeReportView reportName={reportName} debounceMs={0} />
+      )}
+    </FrappeProvider>,
+  );
+}
+
+describe("LC-96 guest fallback: report views", () => {
+  it("a doctype report takes its columns from one record and saves nothing", async () => {
+    renderReport("builder");
+    await waitFor(() => expect(screen.getAllByText("tackle").length).toBeGreaterThan(0), settle);
+    expect(screen.getByText("Move Name")).toBeTruthy();
+    expect(screen.getByText("Power")).toBeTruthy();
+    expect(screen.getByText("Accuracy")).toBeTruthy();
+    expect(screen.queryByText("Owner")).toBeNull();
+    expect(screen.queryByText(/Couldn't load/)).toBeNull();
+    expect(screen.queryByRole("button", { name: /save as/i })).toBeNull();
+  });
+
+  it("a doctype report whose rows are refused too says the reader can't open it, with no retry", async () => {
+    recordsReadable = false;
+    renderReport("builder");
+    const state = await screen.findByTestId("frappe-report-not-permitted", {}, settle);
+    expect(state.textContent).toContain(`You can't open the ${doctype} report`);
+    expect(screen.queryByRole("button", { name: /retry/i })).toBeNull();
+  });
+
+  it("a doctype report whose meta failed for another reason stays an error", async () => {
+    metaAnswer = "broken";
+    renderReport("builder");
+    expect(await screen.findByText(`Couldn't load the ${doctype} report`, {}, settle)).toBeTruthy();
+    expect(screen.queryByTestId("frappe-report-not-permitted")).toBeNull();
+  });
+
+  it("a refused query report says the reader can't run it, with the server's reason and no retry", async () => {
+    renderReport("query");
+    const state = await screen.findByTestId("frappe-report-not-permitted", {}, settle);
+    expect(state.textContent).toContain(`You can't run ${reportName}`);
+    expect(state.textContent).toContain(`You don't have access to Report: ${reportName}`);
+    expect(screen.queryByRole("button", { name: /retry|refresh/i })).toBeNull();
+  });
+
+  it("a query report that failed for another reason stays a retryable error", async () => {
+    reportRun = "broken";
+    renderReport("query");
+    expect(await screen.findByText(`Error running ${reportName}`, {}, settle)).toBeTruthy();
+    expect(screen.queryByTestId("frappe-report-not-permitted")).toBeNull();
+    expect(screen.getByRole("button", { name: /retry/i })).toBeTruthy();
+  });
+});

package/src/index.ts

@@ -54,6 +54,15 @@ export {
 
 export { FrappeTable, filterValueToFrappeTuple, type FrappeTableProps } from "./FrappeTable";
 export { FrappeForm, type FrappeConnectionRows, type FrappeFormProps } from "./FrappeForm";
+export {
+  useFrappeForm,
+  type FrappeFormConnectionConfig,
+  type FrappeFormController,
+  type FrappeFormFieldTarget,
+  type FrappeFormMetaSource,
+  type FrappeFormStatus,
+  type UseFrappeFormOptions,
+} from "./useFrappeForm";
 export {
   FrappeFormConnectionSection,
   FrappeFormConnections,
@@ -146,13 +155,6 @@ export { FrappeGantt, type FrappeGanttProps } from "./FrappeGantt";
 
 export { resolveFrappeEventColor, frappeEventColorNames } from "./frappeEventColor";
 
-export {
-  FrappeReportBuilder,
-  type FrappeReportBuilderProps,
-  type ReportColumn,
-  type GroupByConfig,
-} from "./FrappeReportBuilder";
-
 export {
   FrappeDashboard,
   type FrappeDashboardProps,
@@ -207,6 +209,17 @@ export {
   type UseFrappeRowsResult,
 } from "./useFrappeRows";
 
+// What a view lays itself out from when meta is refused (LC-96).
+export {
+  fieldsFromRecord,
+  recordFieldKeys,
+  recordKeyLabel,
+  useRecordShape,
+  type RecordShape,
+  type RecordShapeConnection,
+} from "./recordShape";
+export { isPermissionError, refusalReason } from "./liveErrors";
+
 export {
   useFrappeAggregate,
   type FrappeAggregateConnection,
@@ -455,32 +468,118 @@ export { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
 export type { DataTableColumn } from "@multiplatform.one/table";
 
 // ---------------------------------------------------------------------------
-// Report View (server-side Query / Script reports)
+// Report models (MPO-15, GL-28): a named query/script report and a doctype's
+// report view, one model each. FrappeReportView and the desk's
+// QueryReportScreen render the first through one transport;
+// FrappeReportBuilder, the desk's view=report, renders the second.
 // ---------------------------------------------------------------------------
 
 export {
   FrappeReportView,
-  useFrappeReport,
+  reportColumnToDataTableColumn,
+  reportFieldtypeToTableField,
+  reportRowLabel,
+  type FrappeReportViewProps,
+} from "./FrappeReportView";
+export {
+  buildRunFilters,
   compactFilterValues,
+  compactQueryReportFilters,
+  defaultFilterValues,
+  extractScriptFilters,
+  humanizeFrappeError,
+  isEmptyFilterValue,
+  normalizeFilterMeta,
+  normalizeQueryReportColumns,
+  normalizeQueryReportPayload,
+  normalizeQueryReportRows,
   normalizeReportColumn,
   normalizeReportPayload,
   normalizeReportRows,
-  reportColumnToDataTableColumn,
-  reportFieldtypeToTableField,
-  reportRowLabel,
   scrubFieldname,
+  stripHtml as stripReportHtml,
   type FrappeReportColumn,
-  type FrappeReportConnection,
   type FrappeReportFilterDef,
-  type FrappeReportFixture,
   type FrappeReportPayload,
   type FrappeReportRow,
   type FrappeReportRunResponse,
   type FrappeReportValues,
-  type FrappeReportViewProps,
+  type QueryReportColumn,
+  type QueryReportFilterInput,
+  type QueryReportFilterMeta,
+  type QueryReportFilters,
+  type QueryReportFixture,
+  type QueryReportMeta,
+  type QueryReportPayload,
+  type QueryReportRow,
+  type QueryReportRunMessage,
+  type ScriptFilterExtraction,
+} from "./report/queryReport";
+export {
+  reportCall,
+  useFrappeReport,
+  type FrappeReportConnection,
+  type FrappeReportFixture,
   type UseFrappeReportOptions,
   type UseFrappeReportResult,
-} from "./FrappeReportView";
+} from "./report/useFrappeReport";
+export {
+  useQueryReport,
+  type UseQueryReportOptions,
+  type UseQueryReportResult,
+} from "./report/useQueryReport";
+export {
+  buildQueryReportColumns,
+  buildQueryReportCsv,
+  type BuildQueryReportColumnsArgs,
+} from "./report/queryReportColumns";
+export {
+  FrappeReportBuilder,
+  type FrappeReportBuilderProps,
+  type ReportColumn,
+  type GroupByConfig,
+} from "./FrappeReportBuilder";
+export {
+  buildGridRows as buildReportGridRows,
+  buildReportCsv,
+  columnAlign as reportColumnAlign,
+  columnFilterTuple as reportColumnFilterTuple,
+  columnFilterTuples as reportColumnFilterTuples,
+  compareCellValues as compareReportCellValues,
+  computeTotals as computeReportTotals,
+  DEFAULT_REPORT_PAGE_SIZE,
+  defaultColumnWidth as defaultReportColumnWidth,
+  defaultReportFieldnames,
+  fromDeskReportSettings,
+  orderReportRows,
+  parseDeskOrderBy,
+  parseReportFiltersParam,
+  REPORT_NUMERIC_FIELDTYPES,
+  REPORT_PAGE_SIZES,
+  reportColumnsFromMeta,
+  resolveSelectedColumns as resolveReportColumns,
+  toDeskReportSettings,
+  type DeskReportSettings,
+  type ReportColumnDef,
+  type ReportDataRow,
+  type ReportFilters,
+  type ReportGridRow,
+  type ReportGroupHeader,
+  type ReportMetaSource,
+  type ReportRow,
+  type ReportSortState,
+  type ReportTotalsCell,
+  type ReportViewConfig,
+} from "./report/reportViewModel";
+export { ReportGrid, type ReportGridProps } from "./report/ReportGrid";
+export { ReportViewToolbar, type ReportViewToolbarProps } from "./report/ReportViewToolbar";
+export {
+  useSavedReports,
+  type SavedReportSummary,
+  type SavedReportsConnection,
+  type UseSavedReportsResult,
+} from "./report/savedReports";
+export { dialogBodyMinWidth, overlayListMaxHeight } from "./measures";
 
 // ---------------------------------------------------------------------------
 // Desk Form Engine (MPO-15)
@@ -507,7 +606,9 @@ export {
   canReadLevel,
   canWriteLevel,
   computeDirtyFields,
+  docinfoRights,
   docRightNames,
+  fixtureDocRights,
   isEmptyValue,
   isFetchLocked,
   isPromptNamed,

package/src/liveErrors.spec.ts

@@ -8,6 +8,16 @@ describe("isPermissionError", () => {
     expect(isPermissionError(Object.assign(new Error("nope"), { status: 500 }))).toBe(false);
   });
 
+  it("treats a PermissionError exc_type as permission, whatever the sentence", () => {
+    const err = Object.assign(new Error("You don't have access to Report: ToDo"), {
+      exc_type: "PermissionError",
+    });
+    expect(isPermissionError(err)).toBe(true);
+    expect(
+      isPermissionError(Object.assign(new Error("Timed out"), { exc_type: "ValidationError" })),
+    ).toBe(false);
+  });
+
   it("treats a PermissionError-shaped message as permission", () => {
     expect(isPermissionError(new Error("PermissionError"))).toBe(true);
     expect(isPermissionError(new Error("You don't have access to Report: ToDo"))).toBe(false);

package/src/liveErrors.ts

@@ -9,10 +9,14 @@
  * from "the load failed".
  */
 
-/** True when the error is an auth/permission rejection (403 or PermissionError). */
+/**
+ * True when the error is an auth/permission rejection: a 403 or 401, a
+ * PermissionError `exc_type`, or a PermissionError-shaped message.
+ */
 export function isPermissionError(error: unknown): boolean {
-  const status = (error as { status?: number } | undefined)?.status;
-  if (status === 403 || status === 401) return true;
+  const shaped = error as { status?: number; exc_type?: unknown } | undefined;
+  if (shaped?.status === 403 || shaped?.status === 401) return true;
+  if (shaped?.exc_type === "PermissionError") return true;
   const message = error instanceof Error ? error.message : String(error ?? "");
   return /permission|not permitted|forbidden/i.test(message);
 }
@@ -22,6 +26,15 @@ function isTracebackDetail(detail: string): boolean {
   return /Traceback \(most recent call last\)/i.test(detail);
 }
 
+/**
+ * The server's own sentence for a refusal, for a permission state's
+ * description: undefined when there is none or it is a python traceback.
+ */
+export function refusalReason(error: unknown): string | undefined {
+  const detail = error instanceof Error ? error.message : String(error ?? "");
+  return detail && !isTracebackDetail(detail) ? detail : undefined;
+}
+
 /**
  * Normalizes an initial-sync failure into an Error with an honest,
  * user-facing message. `permissionMessage` / `genericMessage` come from the

package/src/measures.ts

@@ -0,0 +1,11 @@
+import { sizeRecipeEscape } from "@multiplatform.one/theme";
+
+export const dialogBodyMinWidth = sizeRecipeEscape(
+  280,
+  "dialog body floor: a reading width for the form inside a dialog or popover",
+);
+
+export const overlayListMaxHeight = sizeRecipeEscape(
+  360,
+  "overlay list cap: a menu or popover list scrolls past this height instead of growing",
+);