@multiplatform.one/frappe-ui 7.6.3 → 7.7.0

package/src/formEngine/createPrefill.ts

@@ -0,0 +1,28 @@
+/**
+ * One-shot create-mode prefill hand-off.
+ *
+ * Two producers, one mechanism:
+ * - Duplicate and Amend navigate to `newDocPath(doctype)` and stash the
+ *   copied values here (in-memory only — a refresh honestly falls back to
+ *   a blank form; no URL-size limits for large docs).
+ * - NewDocRouteScreen stashes parsed `?d=` URL defaults (kanban column "+",
+ *   calendar day click, connections "+") before rendering the form — those
+ *   survive refresh because the URL re-stashes them.
+ *
+ * The create-mode form (useFormEngine seeding) consumes and clears the
+ * stash on mount, merging it over meta defaults. Last stash per doctype
+ * wins, so a `?d=` navigation cannot double-apply with a stale
+ * Duplicate/Amend hand-off.
+ */
+
+const prefills = new Map<string, Record<string, unknown>>();
+
+export function setCreatePrefill(doctype: string, values: Record<string, unknown>): void {
+  prefills.set(doctype, values);
+}
+
+export function takeCreatePrefill(doctype: string): Record<string, unknown> | undefined {
+  const values = prefills.get(doctype);
+  if (values) prefills.delete(doctype);
+  return values;
+}

package/src/formEngine/dirtyTracking.spec.ts

@@ -0,0 +1,91 @@
+// R-1 false "Not Saved": engine-level dirty-tracking contract.
+// An untouched existing doc must read pristine, a real edit must read dirty,
+// create mode must read dirty from applied defaults (desk parity).
+import { describe, expect, it } from "vitest";
+import { computeDirtyFields, isSameValue } from "./dirtyTracking";
+
+describe("isSameValue (normalization-insensitive equality)", () => {
+  it("treats null / undefined / empty string / empty array as one empty state", () => {
+    expect(isSameValue(null, "")).toBe(true);
+    expect(isSameValue(undefined, "")).toBe(true);
+    expect(isSameValue(null, undefined)).toBe(true);
+    expect(isSameValue([], null)).toBe(true);
+    expect(isSameValue("  ", "")).toBe(true);
+  });
+
+  it("folds boolean and wire 0/1 representations", () => {
+    expect(isSameValue(false, 0)).toBe(true);
+    expect(isSameValue(true, 1)).toBe(true);
+    expect(isSameValue(0, false)).toBe(true);
+    expect(isSameValue(true, 0)).toBe(false);
+    expect(isSameValue(false, 1)).toBe(false);
+  });
+
+  it("does not conflate empty with falsy non-empty values", () => {
+    expect(isSameValue(0, "")).toBe(false);
+    expect(isSameValue(false, "")).toBe(false);
+    expect(isSameValue(0, null)).toBe(false);
+  });
+
+  it("stays strict for real values — no deep equality", () => {
+    expect(isSameValue("a", "a")).toBe(true);
+    expect(isSameValue("a", "b")).toBe(false);
+    // Distinct array/object identities read as different even when
+    // structurally equal (deliberate: no deep-equality time bombs).
+    expect(isSameValue([{ a: 1 }], [{ a: 1 }])).toBe(false);
+    // Representation changes of real content are edits (the field layer is
+    // responsible for not emitting them during initialization).
+    expect(isSameValue("plain", "<p>plain</p>")).toBe(false);
+  });
+});
+
+describe("computeDirtyFields", () => {
+  const baseline = {
+    doctype: "ToDo",
+    name: "abc",
+    description: "hello",
+    status: "Open",
+    color: null,
+    priority: "Medium",
+    date: "2026-08-12",
+    checked: 0,
+  };
+
+  it("existing doc mount: local === baseline snapshot reads pristine", () => {
+    expect(computeDirtyFields({ ...baseline }, baseline)).toEqual([]);
+  });
+
+  it("field re-representation during init does not dirty (null→'' and 0→false)", () => {
+    const local = { ...baseline, color: "", checked: false };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("a real edit reads dirty", () => {
+    const local = { ...baseline, description: "hello edited" };
+    expect(computeDirtyFields(local, baseline)).toEqual(["description"]);
+  });
+
+  it("revert to the exact baseline value reads clean again", () => {
+    // Documented behavior: value equality, not edit history — typing and
+    // deleting back to the original string is pristine. An equivalent-but-
+    // differently-represented value (e.g. tiptap-normalized HTML) would
+    // still read dirty, which matches desk.
+    const local = { ...baseline, description: "hello" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("bookkeeping keys never dirty", () => {
+    const local = { ...baseline, name: "renamed", doctype: "Other" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("new doc (no baseline) with applied create-defaults reads dirty — desk parity", () => {
+    const local = { doctype: "ToDo", status: "Open", priority: "Medium", description: "" };
+    expect(computeDirtyFields(local, undefined)).toEqual(["status", "priority"]);
+  });
+
+  it("new doc with only empty values reads pristine", () => {
+    const local = { doctype: "ToDo", description: "", color: null };
+    expect(computeDirtyFields(local, undefined)).toEqual([]);
+  });
+});

package/src/formEngine/dirtyTracking.ts

@@ -0,0 +1,64 @@
+/**
+ * Dirty tracking for the desk form engine (R-1 false "Not Saved" fix).
+ *
+ * The engine diffs the locally edited doc against the last server baseline.
+ * A strict `!==` diff falsely armed Save on untouched documents whenever a
+ * field's *representation* of a value differed from the wire format (mount
+ * emitters have been fixed at the field level — forms contract: initialization
+ * must not emit change events — but the engine stays defensive).
+ */
+
+export function isEmptyValue(value: unknown): boolean {
+  if (value === undefined || value === null) return true;
+  if (typeof value === "string" && value.trim() === "") return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+
+/**
+ * Init-aware value equality. Two representation classes are folded:
+ *
+ * - empty: null / undefined / "" / [] are one empty state (a field
+ *   normalizing null → "" is not an edit)
+ * - boolean: Check wires 0/1 but a control may emit true/false
+ *
+ * Everything else stays strict equality — deliberately shallow and honest
+ * (no deep equality): desk parity means an edit reverted to a value that is
+ * merely *equivalent* (not identical) may still read dirty, while reverting
+ * to the exact original value reads clean.
+ */
+export function isSameValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (isEmptyValue(a) && isEmptyValue(b)) return true;
+  if (typeof a === "boolean" || typeof b === "boolean") {
+    const an = a === true ? 1 : a === false ? 0 : a;
+    const bn = b === true ? 1 : b === false ? 0 : b;
+    return an === bn;
+  }
+  return false;
+}
+
+/**
+ * Names of fields whose local value differs from the baseline.
+ *
+ * - Edit mode (baseline defined): normalization-insensitive diff via
+ *   `isSameValue` — an untouched doc reads pristine even if a field
+ *   re-represented its value during initialization.
+ * - Create mode (no baseline): any non-empty value counts, defaults included —
+ *   desk parity, a new doc shows "Not Saved".
+ *
+ * `doctype` / `name` are bookkeeping, never dirty.
+ */
+export function computeDirtyFields(
+  localDoc: Record<string, unknown>,
+  baseline: Record<string, unknown> | undefined,
+): string[] {
+  const dirty: string[] = [];
+  for (const key of Object.keys(localDoc)) {
+    if (key === "doctype" || key === "name") continue;
+    if (baseline ? !isSameValue(localDoc[key], baseline[key]) : !isEmptyValue(localDoc[key])) {
+      dirty.push(key);
+    }
+  }
+  return dirty;
+}

package/src/formEngine/doctypeMeta.ts

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ */
+
+/** 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;
+}

package/src/formEngine/fetchFrom.spec.ts

@@ -0,0 +1,92 @@
+/**
+ * fetchFrom — fetch_from preview parity with desk script_manager.js
+ * setup_add_fetch + link.js validate_link_and_fetch.
+ */
+import { describe, expect, it } from "vitest";
+import type { DocFieldMeta } from "./doctypeMeta";
+import { applyFetchedValues, buildFetchMap, isFetchLocked } from "./fetchFrom";
+
+function field(overrides: Partial<DocFieldMeta> & { fieldname: string }): DocFieldMeta {
+  return { fieldtype: "Data", ...overrides };
+}
+
+describe("buildFetchMap", () => {
+  it("registers scalar fieldtypes keyed by their link field", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "customer", fieldtype: "Link", options: "Customer" }),
+      field({ fieldname: "customer_name", fetch_from: "customer.customer_name" }),
+      field({ fieldname: "territory", fieldtype: "Select", fetch_from: "customer.territory" }),
+    ]);
+    expect(map.get("customer")).toEqual([
+      { target: "customer_name", source: "customer_name", fetchIfEmpty: false },
+      { target: "territory", source: "territory", fetchIfEmpty: false },
+    ]);
+  });
+
+  it("skips fetch_from without a dot and non-registered fieldtypes", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "bad", fetch_from: "customer" }),
+      field({ fieldname: "html", fieldtype: "HTML", fetch_from: "customer.blurb" }),
+    ]);
+    expect(map.size).toBe(0);
+  });
+
+  it("includes non-scalar fieldtypes when read_only (script_manager gate)", () => {
+    const map = buildFetchMap([
+      field({
+        fieldname: "blurb",
+        fieldtype: "HTML Editor",
+        fetch_from: "customer.blurb",
+        read_only: 1,
+      }),
+    ]);
+    expect(map.get("customer")).toHaveLength(1);
+  });
+
+  it("records fetch_if_empty", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "note", fetch_from: "customer.note", fetch_if_empty: 1 }),
+    ]);
+    expect(map.get("customer")?.[0].fetchIfEmpty).toBe(true);
+  });
+});
+
+describe("applyFetchedValues", () => {
+  const rules = [
+    { target: "customer_name", source: "customer_name", fetchIfEmpty: false },
+    { target: "note", source: "note", fetchIfEmpty: true },
+  ];
+
+  it("writes fetched values onto targets", () => {
+    const patch = applyFetchedValues(rules, { customer_name: "Acme", note: "VIP" }, {});
+    expect(patch).toEqual({ customer_name: "Acme", note: "VIP" });
+  });
+
+  it("fetch_if_empty targets keep an existing value", () => {
+    const patch = applyFetchedValues(
+      rules,
+      { customer_name: "Acme", note: "VIP" },
+      { note: "user wrote this" },
+    );
+    expect(patch).toEqual({ customer_name: "Acme" });
+  });
+
+  it("clearing the link blanks plain targets but spares fetch_if_empty values", () => {
+    const patch = applyFetchedValues(rules, {}, { customer_name: "Acme", note: "mine" });
+    expect(patch).toEqual({ customer_name: "" });
+  });
+});
+
+describe("isFetchLocked", () => {
+  it("locks while the source link holds a value, unless fetch_if_empty", () => {
+    const target = field({ fieldname: "customer_name", fetch_from: "customer.customer_name" });
+    expect(isFetchLocked(target, { customer: "CUST-1" })).toBe(true);
+    expect(isFetchLocked(target, {})).toBe(false);
+    const softTarget = field({
+      fieldname: "note",
+      fetch_from: "customer.note",
+      fetch_if_empty: 1,
+    });
+    expect(isFetchLocked(softTarget, { customer: "CUST-1" })).toBe(false);
+  });
+});

package/src/formEngine/fetchFrom.ts

@@ -0,0 +1,111 @@
+/**
+ * fetch_from client-side preview — desk parity with
+ * frappe/public/js/frappe/form/script_manager.js (`setup_add_fetch`) and
+ * controls/link.js (`validate_link_and_fetch`):
+ *
+ * - A field participates when `fetch_from` is "<link_field>.<source_field>"
+ *   AND (its fieldtype is in the scalar set desk registers, or it is
+ *   read_only / is_virtual).
+ * - When the link field changes to a value, desk calls
+ *   `frappe.client.validate_link` with the source columns and writes the
+ *   returned values onto the targets; clearing the link clears the targets.
+ * - `fetch_if_empty` targets keep a non-empty existing value (server
+ *   semantics; desk leaves such fields editable — see
+ *   `read_only_because_of_fetch_from`, base_input.js:56-66).
+ *
+ * The server remains authoritative: this is a preview so the user sees the
+ * fetched values before save.
+ */
+
+import type { DocFieldMeta } from "./doctypeMeta";
+
+/** Fieldtypes desk registers for client-side fetch (script_manager.js:196-215). */
+const FETCHABLE_FIELDTYPES = new Set([
+  "Data",
+  "Read Only",
+  "Text",
+  "Small Text",
+  "Currency",
+  "Check",
+  "Text Editor",
+  "Attach Image",
+  "Code",
+  "Link",
+  "Float",
+  "Int",
+  "Date",
+  "Datetime",
+  "Select",
+  "Duration",
+  "Time",
+]);
+
+export interface FetchRule {
+  /** Field to populate. */
+  target: string;
+  /** Column on the linked doc to read. */
+  source: string;
+  /** Only fill when the target is currently empty; never lock the field. */
+  fetchIfEmpty: boolean;
+}
+
+/** Map of link fieldname → fetch rules hanging off that link. */
+export type FetchMap = Map<string, FetchRule[]>;
+
+export function buildFetchMap(fields: DocFieldMeta[]): FetchMap {
+  const map: FetchMap = new Map();
+  for (const field of fields) {
+    const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
+    if (!fetchFrom || !fetchFrom.includes(".")) continue;
+    const eligible =
+      FETCHABLE_FIELDTYPES.has(field.fieldtype) ||
+      !!field.read_only ||
+      !!(field as { is_virtual?: 0 | 1 }).is_virtual;
+    if (!eligible) continue;
+    const [linkField, ...rest] = fetchFrom.split(".");
+    const source = rest.join(".");
+    if (!linkField || !source) continue;
+    const rules = map.get(linkField) ?? [];
+    rules.push({
+      target: field.fieldname,
+      source,
+      fetchIfEmpty: !!field.fetch_if_empty,
+    });
+    map.set(linkField, rules);
+  }
+  return map;
+}
+
+function isEmpty(value: unknown): boolean {
+  return value === undefined || value === null || value === "";
+}
+
+/**
+ * Values to patch onto the doc after the linked doc's columns arrive.
+ * `fetched` is empty when the link was cleared — desk then blanks the
+ * targets; `fetch_if_empty` targets holding a value are left alone in both
+ * directions (they belong to the user until the server reconciles).
+ */
+export function applyFetchedValues(
+  rules: FetchRule[],
+  fetched: Record<string, unknown>,
+  currentDoc: Record<string, unknown>,
+): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  for (const rule of rules) {
+    if (rule.fetchIfEmpty && !isEmpty(currentDoc[rule.target])) continue;
+    patch[rule.target] = fetched[rule.source] ?? "";
+  }
+  return patch;
+}
+
+/**
+ * Desk's `read_only_because_of_fetch_from`: a fetch target without
+ * `fetch_if_empty` renders read-only while its source link holds a value.
+ */
+export function isFetchLocked(field: DocFieldMeta, doc: Record<string, unknown>): boolean {
+  const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
+  if (!fetchFrom || !fetchFrom.includes(".") || field.fetch_if_empty) return false;
+  const linkField = fetchFrom.split(".")[0];
+  return !isEmpty(doc[linkField]);
+}

package/src/formEngine/fieldPermissions.spec.ts

@@ -0,0 +1,61 @@
+/**
+ * fieldPermissions — permlevel matrix parity with desk perm.js
+ * get_role_permissions / get_field_display_status.
+ */
+import { describe, expect, it } from "vitest";
+import { buildPermLevelMatrix, canReadLevel, canWriteLevel } from "./fieldPermissions";
+
+const userDoctypePerms = [
+  { role: "System Manager", permlevel: 0, read: 1 as const, write: 1 as const },
+  { role: "System Manager", permlevel: 1, read: 1 as const, write: 1 as const },
+  { role: "Desk User", permlevel: 0, read: 0 as const, write: 0 as const },
+];
+
+describe("buildPermLevelMatrix", () => {
+  it("unions rights across the user's matching roles", () => {
+    const matrix = buildPermLevelMatrix(
+      [
+        { role: "Blogger", permlevel: 1, read: 1 as const, write: 0 as const },
+        { role: "Website Manager", permlevel: 1, read: 1 as const, write: 1 as const },
+      ],
+      ["Blogger", "Website Manager"],
+    );
+    expect(matrix?.[1]).toEqual({ read: true, write: true });
+  });
+
+  it("ignores rows for roles the user does not hold (User doctype shape)", () => {
+    const matrix = buildPermLevelMatrix(userDoctypePerms, ["Desk User"]);
+    expect(matrix?.[1]).toBeUndefined();
+    expect(canReadLevel(matrix, 1)).toBe(false);
+    expect(canWriteLevel(matrix, 1)).toBe(false);
+  });
+
+  it("returns undefined without roles or permission rows (fallback signal)", () => {
+    expect(buildPermLevelMatrix(userDoctypePerms, undefined)).toBeUndefined();
+    expect(buildPermLevelMatrix([], ["System Manager"])).toBeUndefined();
+    expect(buildPermLevelMatrix(undefined, ["System Manager"])).toBeUndefined();
+  });
+});
+
+describe("canReadLevel / canWriteLevel", () => {
+  const matrix = buildPermLevelMatrix(userDoctypePerms, ["System Manager"]);
+
+  it("level 0 defers to doc-level perms (always true here)", () => {
+    expect(canReadLevel(matrix, 0)).toBe(true);
+    expect(canWriteLevel(matrix, 0)).toBe(true);
+    expect(canReadLevel(undefined, 0)).toBe(true);
+    expect(canWriteLevel(undefined, 0)).toBe(true);
+  });
+
+  it("higher levels resolve from the matrix", () => {
+    expect(canReadLevel(matrix, 1)).toBe(true);
+    expect(canWriteLevel(matrix, 1)).toBe(true);
+    // Level with no rows at all → hidden (desk fills gaps with {}).
+    expect(canReadLevel(matrix, 2)).toBe(false);
+  });
+
+  it("without a matrix: visible but read-only above level 0 (coarse fallback)", () => {
+    expect(canReadLevel(undefined, 1)).toBe(true);
+    expect(canWriteLevel(undefined, 1)).toBe(false);
+  });
+});

package/src/formEngine/fieldPermissions.ts

@@ -0,0 +1,68 @@
+/**
+ * Field-level permission matrix — desk parity with
+ * frappe/public/js/frappe/model/perm.js (`get_role_permissions` +
+ * `get_field_display_status`):
+ *
+ *   perm[level] = OR of meta.permissions rows whose role the session user
+ *   holds. A field at permlevel L then resolves to:
+ *     - no read at L  → hidden   ("None")
+ *     - read, no write → read-only ("Read")
+ *     - write          → editable ("Write", subject to the other rules)
+ *
+ * Levels that appear on fields but have no granting rows resolve to
+ * {read: false} — desk hides those fields (gap-filled `{}` in perm.js:153).
+ * When the caller has no role list (fixtures, roles RPC unavailable) the
+ * matrix is undefined and formLayout falls back to the conservative
+ * "permlevel > 0 → read-only" rule (never hides, never unlocks).
+ */
+
+import type { DocPermissionRule } from "./doctypeMeta";
+
+export interface LevelPerm {
+  read: boolean;
+  write: boolean;
+}
+
+/** Sparse array indexed by permlevel; missing entries mean "no rights". */
+export type PermLevelMatrix = LevelPerm[];
+
+export function buildPermLevelMatrix(
+  permissions: DocPermissionRule[] | undefined,
+  userRoles: string[] | undefined,
+): PermLevelMatrix | undefined {
+  if (!userRoles || !permissions || permissions.length === 0) return undefined;
+  const roles = new Set(userRoles);
+  const matrix: PermLevelMatrix = [];
+  for (const rule of permissions) {
+    if (!rule.role || !roles.has(rule.role)) continue;
+    const level = Number(rule.permlevel ?? 0) || 0;
+    const current = (matrix[level] ??= { read: false, write: false });
+    // if_owner rows are unioned in like desk's get_role_permissions — the
+    // owner check itself is enforced server-side (and via docinfo at level 0).
+    if (rule.read) current.read = true;
+    if (rule.write) current.write = true;
+  }
+  return matrix;
+}
+
+/**
+ * Read access at a permlevel. Level 0 is implied by having the doc at all
+ * (docinfo/doc-level perms govern it — including share/if_owner grants the
+ * role matrix can't see), so only higher levels consult the matrix.
+ */
+export function canReadLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
+  if (!permlevel) return true;
+  if (!matrix) return true; // caller falls back to the coarse read-only rule
+  return !!matrix[permlevel]?.read;
+}
+
+/**
+ * Write access at a permlevel. Level 0 defers to the doc-level write flag
+ * (formReadOnly); higher levels require a granting role row — without a
+ * matrix the coarse fallback keeps them read-only (desk-safe direction).
+ */
+export function canWriteLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
+  if (!permlevel) return true;
+  if (!matrix) return false;
+  return !!matrix[permlevel]?.write;
+}