@colixsystems/widget-sdk 0.17.0 → 0.19.0

package/dist/hooks.js

@@ -8,6 +8,14 @@
 // exported app) own the runtime semantics — this file is the SDK surface
 // widgets call.
 //
+// The hooks below are GROUPED by the domain client they read, so the
+// four-client mapping is obvious at a glance:
+//   - CORE       — WidgetContext + non-data hooks (no domain client)
+//   - DATASTORE  — ctx.datastore (@colixsystems/datastore-client)
+//   - FILES      — ctx.files (@colixsystems/files-client)
+//   - DIRECTORY  — ctx.directory (@colixsystems/directory-client)
+//   - PAYMENTS   — ctx.payments (@colixsystems/payments-client)
+//
 // This file avoids JSX so it can ship as a plain .js without a transform.
 
 import React, {
@@ -22,6 +30,172 @@ import React, {
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
 
+/* ============================================================================
+ * CORE — WidgetContext + non-data hooks (no domain client)
+ *
+ * The provider, the context accessor, and the hooks that read host-provided
+ * state directly off the WidgetContext (events, theme, user, renderer,
+ * navigation, i18n) rather than through one of the four domain clients.
+ * ==========================================================================*/
+
+/**
+ * Wraps children with the host-provided WidgetContext.
+ * The host (Studio/Player/native shell) builds the value and renders this provider.
+ */
+export function WidgetContextProvider({ value, children }) {
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
+// Exported for ./toast.js + future hook modules outside hooks.js. Internal
+// utility — widget code should not import this directly.
+export function useWidgetContextOrThrow(hookName) {
+  const ctx = useContext(HostWidgetContext);
+  if (ctx == null) {
+    throw new Error(
+      `${hookName} must be used inside a WidgetContextProvider. ` +
+        `The host (Studio, Player, or exported app) is responsible for mounting it.`,
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Emit a named widget event through ctx.events.emit. Page-level event
+ * bindings (subscribed by the host) decide what happens next.
+ */
+export function useWidgetEvent(name) {
+  const ctx = useWidgetContextOrThrow("useWidgetEvent");
+  return useCallback((payload) => ctx.events.emit(name, payload), [ctx, name]);
+}
+
+/**
+ * Returns the host-provided theme tokens. The host guarantees every field
+ * documented in CONTRACT.themeTokens is present (defaults merged with
+ * tenant overrides), so widgets read `theme.colors.primary` without
+ * optional chaining.
+ */
+export function useTheme() {
+  const ctx = useWidgetContextOrThrow("useTheme");
+  return ctx.workspace.theme;
+}
+
+/**
+ * Returns the active end-user identity VERBATIM from the host, e.g.
+ *   `{ id, email, display_name, roles, group_ids }` (snake_case fields).
+ *
+ * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
+ * which renders widgets as if signed-out so the public branch shows). The
+ * host (`buildHostWidgetContext` + the native `WidgetHost`) populates the
+ * fields; widgets read them directly. The current principal is host-provided
+ * — this hook does NOT read a data-client.
+ *
+ * Use this to render the signed-in user's name in a header, branch on
+ * roles, or stamp a created-by field.
+ */
+export function useUser() {
+  const ctx = useWidgetContextOrThrow("useUser");
+  return ctx.user;
+}
+
+/**
+ * Returns the host's child-node renderer:
+ *   { renderNode(node) }.
+ *
+ * Widgets like Tabs / Card / a custom container call `renderNode(child)`
+ * to render an author-authored page-tree node nested inside themselves.
+ * The renderer closes over the surrounding render context (breakpoint,
+ * page ctx, parent) that the host already knows, so the widget doesn't
+ * need to plumb any of that through.
+ *
+ * Prefer the `WidgetTree` component for the common case
+ * (`<WidgetTree node={child} />`); reach for the hook when you need to
+ * branch on the node's shape before rendering.
+ */
+export function useChildRenderer() {
+  const ctx = useWidgetContextOrThrow("useChildRenderer");
+  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
+    throw new Error(
+      "useChildRenderer: host did not inject a child-node renderer",
+    );
+  }
+  return ctx.renderer;
+}
+
+/**
+ * Renders an author-authored page-tree node through the host's child
+ * renderer. The widget hands off a node (or null) and gets back a React
+ * element rendered with the same dispatch the top-level page uses, so
+ * Tabs / Card / custom container widgets can host arbitrary child
+ * widgets without importing the host.
+ */
+export function WidgetTree({ node }) {
+  const ctx = useWidgetContextOrThrow("WidgetTree");
+  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
+    return null;
+  }
+  if (!node) return null;
+  return ctx.renderer.renderNode(node);
+}
+
+/**
+ * Returns the host-provided navigation surface:
+ *   `{ goTo, goBack, push, replace, back, currentRoute }`.
+ *
+ * `goTo(pageId, params?)` navigates to an internal app page. `goBack()`
+ * pops the stack. `push` / `replace` / `back` are aliases that map to
+ * the platform's native navigator (react-router on web, react-navigation
+ * on native). Missing methods degrade to no-ops on the Studio canvas
+ * preview, where there is no live router.
+ *
+ * For EXTERNAL URLs use the `Linking` primitive — `Linking.openURL(url)`
+ * works on both platforms.
+ */
+export function useNavigation() {
+  const ctx = useWidgetContextOrThrow("useNavigation");
+  return ctx.navigation;
+}
+
+/**
+ * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
+ * the host's translation table and falls back to `fallback ?? key` when
+ * the key is missing. The host's i18n.t may or may not honour the two-arg
+ * form; we degrade gracefully either way.
+ */
+export function useI18n() {
+  const ctx = useWidgetContextOrThrow("useI18n");
+  const i18n = ctx.i18n || {};
+  const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
+  const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  const t = useCallback(
+    (key, fallback) => {
+      if (typeof key !== "string" || !key) {
+        return typeof fallback === "string" ? fallback : "";
+      }
+      if (hostT) {
+        // Try the two-arg form first; if the host's `t` ignores `fallback`
+        // and returns the bare key on a miss, swap in the fallback.
+        const out = hostT(key, fallback);
+        if (typeof out === "string" && out.length > 0 && out !== key) {
+          return out;
+        }
+        // Host returned the key (unresolved) or nothing usable.
+        return typeof fallback === "string" ? fallback : key;
+      }
+      return typeof fallback === "string" ? fallback : key;
+    },
+    [hostT],
+  );
+  return { t, locale };
+}
+
+/* ============================================================================
+ * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
+ *
+ * Records, schema, aggregate, and record-level permissions. Covers:
+ *   useDatastoreQuery, useDatastoreRecord, useDatastoreSchema,
+ *   useDatastoreMutation, useRecordPermissions.
+ * ==========================================================================*/
+
 /**
  * Structured error thrown by `useDatastoreMutation` callbacks (and surfaced
  * by `useDatastoreQuery` in its `error` slot). Carries a stable `code` so
@@ -53,29 +227,6 @@ export class DatastoreError extends Error {
   }
 }
 
-/**
- * Wraps children with the host-provided WidgetContext.
- * The host (Studio/Player/native shell) builds the value and renders this provider.
- */
-export function WidgetContextProvider({ value, children }) {
-  return React.createElement(HostWidgetContext.Provider, { value }, children);
-}
-
-// Exported for ./toast.js + future hook modules outside hooks.js. Internal
-// utility — widget code should not import this directly.
-export function useWidgetContextOrThrow(hookName) {
-  const ctx = useContext(HostWidgetContext);
-  if (ctx == null) {
-    throw new Error(
-      `${hookName} must be used inside a WidgetContextProvider. ` +
-        `The host (Studio, Player, or exported app) is responsible for mounting it.`,
-    );
-  }
-  return ctx;
-}
-
-// --------------------------------------------------------------- helpers
-
 /**
  * Coerce an arbitrary thrown value (axios error, plain Error, string) into
  * a DatastoreError with a stable `.code`. Reads `error.response.status` if
@@ -127,15 +278,16 @@ function toDatastoreError(err) {
   });
 }
 
-// --------------------------------------------------------------- hooks
-
 /**
  * Stateful datastore query hook. Returns { data, loading, error, refetch }.
  *
- * The host's datastore client exposes `records(table).list(query)` which
- * returns a Promise<Record[]>. We hold the result in component state and
- * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs
- * the same call on demand.
+ * The host injects a `@colixsystems/datastore-client` instance at
+ * `ctx.datastore`. We call `ctx.datastore.records(table).list(query)`, which
+ * resolves to the `{ data, meta }` list envelope VERBATIM (the client no
+ * longer unwraps to a bare array), so we read `res.data` (defaulting to `[]`)
+ * into component state. Author column values inside each row keep whatever
+ * the author named them. We re-fetch when [table, JSON.stringify(query)]
+ * changes. `refetch` re-runs the same call on demand.
  *
  * When `table` is falsy (e.g. the user hasn't bound a `tableRef` property
  * yet), the hook resolves to { data: [], loading: false, error: null,
@@ -189,10 +341,13 @@ export function useDatastoreQuery(table, query) {
     setError(null);
     try {
       const ns = recordsRef.current(t);
-      const rows = await ns.list(queryRef.current);
+      const res = await ns.list(queryRef.current);
+      // The datastore-client returns the { data, meta } list envelope
+      // verbatim — unwrap to the rows array (default []).
+      const rows = res && Array.isArray(res.data) ? res.data : [];
       // Discard the result if a newer fetch has started since we kicked off.
       if (runRef.current !== myRun) return;
-      setData(Array.isArray(rows) ? rows : []);
+      setData(rows);
       setLoading(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
@@ -225,10 +380,12 @@ export function useDatastoreQuery(table, query) {
  * Stateful single-record query hook. Returns { data, loading, error, refetch }
  * where `data` is one row (`null` until loaded, never an array).
  *
- * The host's datastore client exposes `records(table).get(id)` which
- * resolves to a single record object. We hold the result in component
- * state and re-fetch when [table, id] changes. `refetch` re-runs the
- * call on demand.
+ * The host injects a `@colixsystems/datastore-client` instance at
+ * `ctx.datastore`. We call `ctx.datastore.records(table).get(id)`, which
+ * resolves to a single record object (no `{ data, meta }` envelope — `get`
+ * returns the row directly). Author column values keep whatever the author
+ * named them. We hold the result in component state and re-fetch when
+ * [table, id] changes. `refetch` re-runs the call on demand.
  *
  * When `table` OR `recordId` is falsy (e.g. the author hasn't bound the
  * record id yet), the hook resolves to { data: null, loading: false,
@@ -372,82 +529,27 @@ export function useDatastoreSchema(tableId) {
   return { schema, loading, error, refetch };
 }
 
-/**
- * Stateful file-asset resolver hook. Returns { url, file, loading, error,
- * refetch }.
- *
- * The host's file client exposes `files.get(fileId)` which resolves to
- * `{ url, ...meta }` — the absolute URL is composed against the host's
- * API base so the widget can drop it straight into an `<Image source>`
- * without knowing where the API lives. A missing/soft-deleted asset
- * surfaces as `{ url: null, error: <DatastoreError NOT_FOUND> }`.
- *
- * When `fileId` is falsy the hook collapses to { url: null, file: null,
- * loading: false, error: null, refetch } without a network round-trip,
- * so a widget rendering before the author has bound an asset stays
- * loop-free.
- */
-export function useFile(fileId) {
-  const ctx = useWidgetContextOrThrow("useFile");
-  if (!ctx.files || typeof ctx.files.get !== "function") {
-    throw new Error("useFile: host did not inject a files client");
-  }
-  const ready = Boolean(fileId);
-  const [file, setFile] = useState(null);
-  const [loading, setLoading] = useState(ready);
-  const [error, setError] = useState(null);
-
-  const fileIdRef = useRef(fileId);
-  const getRef = useRef(ctx.files.get);
-  fileIdRef.current = fileId;
-  getRef.current = ctx.files.get;
-
-  const runRef = useRef(0);
-
-  const doFetch = useCallback(async () => {
-    const myRun = ++runRef.current;
-    const id = fileIdRef.current;
-    if (!id) {
-      setLoading(false);
-      setError(null);
-      setFile(null);
-      return;
-    }
-    setLoading(true);
-    setError(null);
-    try {
-      const f = await getRef.current(id);
-      if (runRef.current !== myRun) return;
-      setFile(f || null);
-      setLoading(false);
-    } catch (err) {
-      if (runRef.current !== myRun) return;
-      setError(toDatastoreError(err));
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    doFetch();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [fileId]);
-
-  const refetch = useCallback(async () => {
-    await doFetch();
-  }, [doFetch]);
-
-  const url =
-    file && typeof file.url === "string" && file.url.length > 0
-      ? file.url
-      : null;
-  return { url, file, loading, error, refetch };
-}
-
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
- * returning a Promise. Rejected promises throw a DatastoreError carrying a
- * stable `.code` (`VALIDATION`, `CONSTRAINT_VIOLATION`, `FORBIDDEN`,
- * `NOT_FOUND`, `INTERNAL`) plus an optional `fieldErrors` map.
+ * returning a Promise. Routes through the injected
+ * `@colixsystems/datastore-client` at `ctx.datastore`:
+ * `ctx.datastore.records(table).{create,update,delete}`. `update` is a
+ * partial PATCH (the client issues PATCH), so callers pass only the changed
+ * fields. Values pass through verbatim (snake_case / author-named columns).
+ * Rejected promises throw a DatastoreError carrying a stable `.code`
+ * (`VALIDATION`, `CONSTRAINT_VIOLATION`, `FORBIDDEN`, `NOT_FOUND`,
+ * `INTERNAL`) plus an optional `fieldErrors` map.
+ *
+ * When `table` is falsy (the author hasn't bound a `tableRef` yet) the hook
+ * does NOT throw at render — it returns callbacks that reject with a
+ * `DatastoreError { code: "VALIDATION" }` only if actually invoked. This
+ * mirrors the guarded posture of `useDatastoreQuery` / `useDatastoreRecord`:
+ * a widget calls this hook unconditionally at the top of its body (Rules of
+ * Hooks) and renders its unbound empty state without crashing. The
+ * `records(table)` namespace is resolved lazily inside each callback — the
+ * client throws on an empty table, so building it eagerly at render would
+ * crash any widget mounted before its table is bound (the failure the Form
+ * Input widget hit).
  */
 export function useDatastoreMutation(table) {
   const ctx = useWidgetContextOrThrow("useDatastoreMutation");
@@ -456,314 +558,406 @@ export function useDatastoreMutation(table) {
       "useDatastoreMutation: host did not inject a datastore client",
     );
   }
-  const ns = ctx.datastore.records(table);
-  return {
-    create: async (values) => {
+
+  // Same ref discipline as useDatastoreQuery — `ctx` is a fresh object
+  // identity on every host render, so we hold the live table + records
+  // factory in refs to keep the returned callbacks stable. We deliberately
+  // do NOT call `records(table)` here at render.
+  const tableRef = useRef(table);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableRef.current = table;
+  recordsRef.current = ctx.datastore.records;
+
+  // Resolve records(table) lazily. Returns null when no table is bound so
+  // the callbacks reject with a clear VALIDATION error rather than letting
+  // the client's raw TypeError surface (or crashing at render).
+  const resolveNs = useCallback(() => {
+    const t = tableRef.current;
+    if (!t) return null;
+    return recordsRef.current(t);
+  }, []);
+
+  const create = useCallback(
+    async (values) => {
+      const ns = resolveNs();
+      if (!ns) {
+        throw new DatastoreError(
+          "VALIDATION",
+          "useDatastoreMutation: no table bound — set a source table before creating a record.",
+        );
+      }
       try {
         return await ns.create(values);
       } catch (err) {
         throw toDatastoreError(err);
       }
     },
-    update: async (id, values) => {
+    [resolveNs],
+  );
+
+  const update = useCallback(
+    async (id, values) => {
+      const ns = resolveNs();
+      if (!ns) {
+        throw new DatastoreError(
+          "VALIDATION",
+          "useDatastoreMutation: no table bound — set a source table before updating a record.",
+        );
+      }
       try {
         return await ns.update(id, values);
       } catch (err) {
         throw toDatastoreError(err);
       }
     },
-    delete: async (id) => {
+    [resolveNs],
+  );
+
+  const del = useCallback(
+    async (id) => {
+      const ns = resolveNs();
+      if (!ns) {
+        throw new DatastoreError(
+          "VALIDATION",
+          "useDatastoreMutation: no table bound — set a source table before deleting a record.",
+        );
+      }
       try {
         return await ns.delete(id);
       } catch (err) {
         throw toDatastoreError(err);
       }
     },
-  };
-}
+    [resolveNs],
+  );
+
+  return { create, update, delete: del };
+}
 
 /**
- * Stateful user-directory query hook. Returns { users, loading, error,
- * refetch }.
+ * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — structured error thrown by
+ * `useRecordPermissions` mutation callbacks (and surfaced by the hook's
+ * `error` slot when the initial list fetch fails). Carries a stable
+ * `code` so widgets can branch on the error class without parsing
+ * message strings; mirrors the shape of `DirectoryError`.
+ *
+ * `code` is one of:
+ *   - "FORBIDDEN"  — 403 from the host (caller lacks canGrant on the record).
+ *   - "VALIDATION" — 400 / 422 (missing principal, malformed body).
+ *   - "NOT_FOUND"  — 404 (record absent, cross-tenant, or permission row
+ *                    not found on revoke/update).
+ *   - "CONFLICT"   — 409 (e.g. trying to edit a template-derived row).
+ *   - "INTERNAL"   — anything else (network, 5xx).
+ */
+export class PermissionError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "PermissionError";
+    this.code = code;
+    if (opts && opts.status !== undefined) this.status = opts.status;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toPermissionError(err) {
+  if (err instanceof PermissionError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyCode =
+    err && err.response && err.response.data && err.response.data.code;
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  else if (status === 409) code = "CONFLICT";
+  else if (status === 400 || status === 422) code = "VALIDATION";
+  if (typeof bodyCode === "string" && bodyCode) {
+    // Preserve the server's stable code over the status-derived one when
+    // the server volunteered it (e.g. TEMPLATE_DERIVED on edit/delete of
+    // an inherit/template row).
+    code = bodyCode;
+  }
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Record permission call failed");
+  return new PermissionError(code, message, { status, cause: err });
+}
+
+const _NOOP_PERMISSIONS_RESULT = Object.freeze({
+  permissions: [],
+  loading: false,
+  error: null,
+  // Mutation no-ops resolve with null so a widget that does
+  // `await grant(...)` doesn't crash when called against an unbound
+  // (tableId / recordId null) hook.
+  grant: async () => null,
+  revoke: async () => undefined,
+  update: async () => null,
+  refetch: async () => undefined,
+});
+
+/**
+ * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — manage per-record VirtualPermission
+ * grants on a single record. Returns
+ * `{ permissions, loading, error, grant, revoke, update, refetch }`.
  *
- * The host's directory client exposes `listUsers(query)` which resolves
- * to an array of `{ id, name, role }` rows — the privacy-reduced
- * directory projection the backend hands to non-Studio (Player) callers.
- * Use it to build a chat people-list, an @-mention picker, or to resolve
- * an author id to a display name. Mutating users is NOT part of this
- * surface; the directory is read-only from a widget.
+ * `permissions` is an array of snake_case rows VERBATIM, e.g.
+ *   `{ id, user_id, group_id, can_read, can_write, can_delete, can_grant, ... }`.
  *
- * `query` is an optional `{ q?, role?, isActive?, limit?, offset? }`
- * object. `q` substring-matches the display name; `role` is `"USER"`
- * (default) or `"INTEGRATION"` or `"ALL"`. The hook re-fetches whenever
- * `JSON.stringify(query)` changes and exposes `refetch` for on-demand
- * reloads (e.g. a chat roster refresh).
+ * Reads through the injected `@colixsystems/datastore-client` at
+ * `ctx.datastore.records(tableId).permissions(recordId)`, which exposes:
+ *   - `list()` → `Promise<{ data, meta }>` (envelope; we unwrap `res.data`)
+ *   - `grant(body)` → `Promise<row>`
+ *   - `update(permissionId, patch)` → `Promise<row>`
+ *   - `revoke(permissionId)` → `Promise<void>`
  *
- * Requires the `directory.read:users` scope in the widget manifest's
- * `requestedScopes`.
+ * Grant / update bodies are snake_case verbatim
+ * (`{ user_id | group_id, can_read, can_write, can_delete, can_grant }`) —
+ * the SDK does NOT transform them. Rows come back snake_case too; widgets
+ * read those fields directly.
+ *
+ * When `tableId` OR `recordId` is null / undefined / empty (e.g. the
+ * widget hasn't picked an active channel yet), the hook collapses to a
+ * stable empty result without a network round-trip. Mutation methods
+ * are safe no-ops in that state so a widget can call them
+ * unconditionally.
+ *
+ * Requires the `acl.write:records` scope in the widget manifest's
+ * `requestedScopes`. The underlying REST endpoint gates the call on
+ * `can_grant` for the target record (Studio owners short-circuit;
+ * APP_USER actors must hold `can_grant` via REQ-ACL-05 / REQ-ACL-06).
+ * A widget that declares the scope but whose caller lacks the grant
+ * receives `PermissionError { code: "FORBIDDEN" }`.
  */
-export function useDirectory(query) {
-  const ctx = useWidgetContextOrThrow("useDirectory");
-  if (!ctx.directory || typeof ctx.directory.listUsers !== "function") {
-    throw new Error("useDirectory: host did not inject a directory client");
+export function useRecordPermissions(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useRecordPermissions");
+  if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
+    throw new Error(
+      "useRecordPermissions: host did not inject a datastore client (ctx.datastore.records)",
+    );
   }
-  const [users, setUsers] = useState([]);
-  const [loading, setLoading] = useState(true);
+  const ready = Boolean(tableId && recordId);
+  const [permissions, setPermissions] = useState([]);
+  const [loading, setLoading] = useState(ready);
   const [error, setError] = useState(null);
 
-  // Same ref discipline as useDatastoreQuery: the host rebuilds the
-  // WidgetContext value every render, so we capture the live query +
-  // client in refs to keep `refetch` a stable identity.
-  const queryRef = useRef(query);
-  const listUsersRef = useRef(ctx.directory.listUsers);
-  queryRef.current = query;
-  listUsersRef.current = ctx.directory.listUsers;
+  // Same ref discipline as useDirectory / useDatastoreQuery — the host
+  // rebuilds the WidgetContext value every render, so we capture the
+  // live ids + client in refs to keep refetch + grant + revoke + update
+  // stable callback identities.
+  const tableIdRef = useRef(tableId);
+  const recordIdRef = useRef(recordId);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableIdRef.current = tableId;
+  recordIdRef.current = recordId;
+  recordsRef.current = ctx.datastore.records;
+
+  // Resolve the per-record permissions namespace
+  // (ctx.datastore.records(tableId).permissions(recordId)) for the bound
+  // ids. Returns null when either id is missing.
+  const resolveNs = useCallback(() => {
+    const t = tableIdRef.current;
+    const r = recordIdRef.current;
+    if (!t || !r) return null;
+    const recordsNs = recordsRef.current(t);
+    if (!recordsNs || typeof recordsNs.permissions !== "function") {
+      throw new Error(
+        "useRecordPermissions: datastore client does not expose records(table).permissions(recordId)",
+      );
+    }
+    return recordsNs.permissions(r);
+  }, []);
 
   const runRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
+    const ns = resolveNs();
+    if (!ns) {
+      // Collapse to a stable empty result without a network round-trip
+      // so a widget rendering before an active record is picked stays
+      // loop-free.
+      setLoading(false);
+      setError(null);
+      setPermissions([]);
+      return;
+    }
     setLoading(true);
     setError(null);
     try {
-      const rows = await listUsersRef.current(queryRef.current);
+      const res = await ns.list();
+      // permissions().list() returns the { data, meta } envelope verbatim.
+      const rows = res && Array.isArray(res.data) ? res.data : [];
       if (runRef.current !== myRun) return;
-      setUsers(Array.isArray(rows) ? rows : []);
+      setPermissions(rows);
       setLoading(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
-      setError(toDatastoreError(err));
+      setError(toPermissionError(err));
       setLoading(false);
     }
-  }, []);
+  }, [resolveNs]);
 
-  const queryKey = (() => {
-    try {
-      return JSON.stringify(query);
-    } catch (_e) {
-      return null;
-    }
-  })();
   useEffect(() => {
+    if (!ready) {
+      // Reset the slot when the widget unbinds (e.g. user navigates
+      // back to the picker) so the next render doesn't show stale
+      // permissions from a previous record.
+      setPermissions([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
     doFetch();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [queryKey]);
+  }, [tableId, recordId]);
 
   const refetch = useCallback(async () => {
     await doFetch();
   }, [doFetch]);
 
-  return { users, loading, error, refetch };
-}
-
-/**
- * Emit a named widget event through ctx.events.emit. Page-level event
- * bindings (subscribed by the host) decide what happens next.
- */
-export function useWidgetEvent(name) {
-  const ctx = useWidgetContextOrThrow("useWidgetEvent");
-  return useCallback((payload) => ctx.events.emit(name, payload), [ctx, name]);
-}
-
-/**
- * Returns the host-provided theme tokens. The host guarantees every field
- * documented in CONTRACT.themeTokens is present (defaults merged with
- * tenant overrides), so widgets read `theme.colors.primary` without
- * optional chaining.
- */
-export function useTheme() {
-  const ctx = useWidgetContextOrThrow("useTheme");
-  return ctx.workspace.theme;
-}
+  const grant = useCallback(async (body) => {
+    const ns = resolveNs();
+    if (!ns) return null;
+    try {
+      // body is snake_case verbatim ({ user_id | group_id, can_read,
+      // can_write, can_delete, can_grant }) — passed straight through.
+      const row = await ns.grant(body);
+      // Refresh after the mutation so subsequent reads observe the
+      // grant. The client returns the created row too, which we hand
+      // back to the caller for inline use.
+      await doFetch();
+      return row;
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [resolveNs, doFetch]);
 
-/**
- * Returns the active end-user identity:
- *   `{ id, email, displayName, roles, groupIds }`.
- *
- * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
- * which renders widgets as if signed-out so the public branch shows). All
- * fields are guaranteed present by the host (`buildHostWidgetContext`
- * + the native `WidgetHost`); widgets read them without optional chaining.
- *
- * Use this to render the signed-in user's name in a header, branch on
- * roles, or stamp a created-by field. Email is opaque to widgets that
- * only need a display name — prefer `displayName` for UI strings.
- */
-export function useUser() {
-  const ctx = useWidgetContextOrThrow("useUser");
-  return ctx.user;
-}
+  const revoke = useCallback(async (permissionId) => {
+    const ns = resolveNs();
+    if (!ns) return undefined;
+    try {
+      await ns.revoke(permissionId);
+      await doFetch();
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [resolveNs, doFetch]);
 
-/**
- * Returns the host's child-node renderer:
- *   { renderNode(node) }.
- *
- * Widgets like Tabs / Card / a custom container call `renderNode(child)`
- * to render an author-authored page-tree node nested inside themselves.
- * The renderer closes over the surrounding render context (breakpoint,
- * page ctx, parent) that the host already knows, so the widget doesn't
- * need to plumb any of that through.
- *
- * Prefer the `WidgetTree` component for the common case
- * (`<WidgetTree node={child} />`); reach for the hook when you need to
- * branch on the node's shape before rendering.
- */
-export function useChildRenderer() {
-  const ctx = useWidgetContextOrThrow("useChildRenderer");
-  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
-    throw new Error(
-      "useChildRenderer: host did not inject a child-node renderer",
-    );
+  const update = useCallback(async (permissionId, body) => {
+    const ns = resolveNs();
+    if (!ns) return null;
+    try {
+      // body (the patch) is snake_case verbatim.
+      const row = await ns.update(permissionId, body);
+      await doFetch();
+      return row;
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [resolveNs, doFetch]);
+
+  if (!ready) {
+    // Mutation no-ops are safe: a widget that does
+    // `await grant({...})` against an unbound hook resolves to null
+    // rather than throwing. Same shape as the populated case so the
+    // caller can branch on `tableId/recordId` once, at the top.
+    return _NOOP_PERMISSIONS_RESULT;
   }
-  return ctx.renderer;
-}
 
-/**
- * Renders an author-authored page-tree node through the host's child
- * renderer. The widget hands off a node (or null) and gets back a React
- * element rendered with the same dispatch the top-level page uses, so
- * Tabs / Card / custom container widgets can host arbitrary child
- * widgets without importing the host.
- */
-export function WidgetTree({ node }) {
-  const ctx = useWidgetContextOrThrow("WidgetTree");
-  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
-    return null;
-  }
-  if (!node) return null;
-  return ctx.renderer.renderNode(node);
+  return { permissions, loading, error, grant, revoke, update, refetch };
 }
 
-/**
- * Returns the host-provided navigation surface:
- *   `{ goTo, goBack, push, replace, back, currentRoute }`.
- *
- * `goTo(pageId, params?)` navigates to an internal app page. `goBack()`
- * pops the stack. `push` / `replace` / `back` are aliases that map to
- * the platform's native navigator (react-router on web, react-navigation
- * on native). Missing methods degrade to no-ops on the Studio canvas
- * preview, where there is no live router.
+/* ============================================================================
+ * FILES CLIENT — ctx.files (@colixsystems/files-client)
  *
- * For EXTERNAL URLs use the `Linking` primitive — `Linking.openURL(url)`
- * works on both platforms.
- */
-export function useNavigation() {
-  const ctx = useWidgetContextOrThrow("useNavigation");
-  return ctx.navigation;
-}
+ * Files, folders, shares. Covers: useFile.
+ * ==========================================================================*/
 
 /**
- * Structured error thrown by `usePayments` callbacks. Carries a stable
- * `code` so widgets can branch without parsing message strings.
+ * Stateful file-asset resolver hook. Returns { url, file, loading, error,
+ * refetch }.
  *
- * `code` is one of:
- *   - "AUTH_REQUIRED"             — no signed-in app user
- *   - "PAYMENTS_SCOPE_NOT_GRANTED"— widget lacks payments.charge:appUser
- *   - "INVALID_AMOUNT" / "AMOUNT_TOO_LARGE" / "VALIDATION" — bad request
- *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
- *   - "DECLINED"                  — the charge was declined
- *   - "INTERNAL"                  — anything else
+ * The host injects a `@colixsystems/files-client` instance at `ctx.files`,
+ * FLATTENED so file ops are top-level. We call `ctx.files.get(fileId)`,
+ * which resolves to `{ url, ...meta }` — the returned file already carries
+ * an absolute URL so the widget can drop it straight into an `<Image
+ * source>` without knowing where the API lives. A missing/soft-deleted
+ * asset surfaces as `{ url: null, error: <DatastoreError NOT_FOUND> }`.
+ *
+ * When `fileId` is falsy the hook collapses to { url: null, file: null,
+ * loading: false, error: null, refetch } without a network round-trip,
+ * so a widget rendering before the author has bound an asset stays
+ * loop-free.
  */
-export class PaymentError extends Error {
-  constructor(code, message, opts) {
-    super(message);
-    this.name = "PaymentError";
-    this.code = code;
-    if (opts && opts.cause) this.cause = opts.cause;
+export function useFile(fileId) {
+  const ctx = useWidgetContextOrThrow("useFile");
+  if (!ctx.files || typeof ctx.files.get !== "function") {
+    throw new Error("useFile: host did not inject a files client");
   }
-}
+  const ready = Boolean(fileId);
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
 
-function toPaymentError(err) {
-  if (err instanceof PaymentError) return err;
-  const status =
-    err && err.response && typeof err.response.status === "number"
-      ? err.response.status
-      : null;
-  const bodyCode =
-    err && err.response && err.response.data && err.response.data.code;
-  const bodyMessage =
-    err && err.response && err.response.data && err.response.data.error;
-  let code = "INTERNAL";
-  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
-  else if (status === 401) code = "AUTH_REQUIRED";
-  else if (status === 402) code = "DECLINED";
-  else if (status === 403) code = "FORBIDDEN";
-  else if (status === 400) code = "VALIDATION";
-  const message =
-    (typeof bodyMessage === "string" && bodyMessage) ||
-    (err && typeof err.message === "string"
-      ? err.message
-      : "Payment request failed");
-  return new PaymentError(code, message, { cause: err });
-}
+  const fileIdRef = useRef(fileId);
+  const getRef = useRef(ctx.files.get);
+  fileIdRef.current = fileId;
+  getRef.current = ctx.files.get;
 
-/**
- * Incoming app-user payments (REQ-BILL-07-WIDGETPAY). Returns
- * `{ requestPayment, getPayment }`.
- *
- *   requestPayment({ amountCents, currency?, description, metadata? })
- *     → Promise<{ id, status, checkoutUrl?, ... }>. The host either
- *       auto-confirms (mock provider, `status: "PAID"`, no redirect) or
- *       returns a hosted-Checkout `checkoutUrl` the widget should open
- *       (Stripe provider, `status: "PENDING"`). Rejects with a
- *       `PaymentError`.
- *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
- *
- * Requires the `payments.charge:appUser` scope in the manifest's
- * `requestedScopes`. The charge settles to the workspace owner; the app
- * user confirms the amount in hosted Checkout. No card data touches the
- * widget — never collect card fields yourself.
- */
-export function usePayments() {
-  const ctx = useWidgetContextOrThrow("usePayments");
-  if (!ctx.payments || typeof ctx.payments.requestPayment !== "function") {
-    throw new Error(
-      "usePayments: host did not inject a payments client. The widget must " +
-        "declare the payments.charge:appUser scope and be installed in a " +
-        "workspace whose host supports payments.",
-    );
-  }
-  const requestRef = useRef(ctx.payments.requestPayment);
-  const getRef = useRef(
-    typeof ctx.payments.getPayment === "function"
-      ? ctx.payments.getPayment
-      : null,
-  );
-  requestRef.current = ctx.payments.requestPayment;
-  getRef.current =
-    typeof ctx.payments.getPayment === "function"
-      ? ctx.payments.getPayment
-      : null;
+  const runRef = useRef(0);
 
-  const requestPayment = useCallback(async (args) => {
-    try {
-      return await requestRef.current(args);
-    } catch (err) {
-      throw toPaymentError(err);
-    }
-  }, []);
-  const getPayment = useCallback(async (paymentId) => {
-    if (!getRef.current) {
-      throw new PaymentError(
-        "INTERNAL",
-        "getPayment is not supported by this host.",
-      );
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const id = fileIdRef.current;
+    if (!id) {
+      setLoading(false);
+      setError(null);
+      setFile(null);
+      return;
     }
+    setLoading(true);
+    setError(null);
     try {
-      return await getRef.current(paymentId);
+      const f = await getRef.current(id);
+      if (runRef.current !== myRun) return;
+      setFile(f || null);
+      setLoading(false);
     } catch (err) {
-      throw toPaymentError(err);
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
     }
   }, []);
-  return { requestPayment, getPayment };
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const url =
+    file && typeof file.url === "string" && file.url.length > 0
+      ? file.url
+      : null;
+  return { url, file, loading, error, refetch };
 }
 
-/**
- * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
- * the host's translation table and falls back to `fallback ?? key` when
- * the key is missing. The host's i18n.t may or may not honour the two-arg
- * form; we degrade gracefully either way.
- */
+/* ============================================================================
+ * DIRECTORY CLIENT — ctx.directory (@colixsystems/directory-client)
+ *
+ * Me, users, groups, invites. Covers:
+ *   useDirectory, useUsers, useGroups.
+ * ==========================================================================*/
+
 /**
  * REQ-USERMGMT / REQ-ACL-SYS M3 — structured error thrown by `useUsers` /
  * `useGroups` callbacks. Carries a stable `code` so widgets can branch
@@ -814,14 +1008,103 @@ function toDirectoryError(err) {
   return new DirectoryError(code, message, { cause: err });
 }
 
+/**
+ * Stateful user-directory query hook. Returns { users, loading, error,
+ * refetch }.
+ *
+ * The host injects a `@colixsystems/directory-client` instance at
+ * `ctx.directory`. We call `ctx.directory.users.list(query)`, which resolves
+ * to the `{ data, meta }` list envelope VERBATIM; we unwrap `res.data`
+ * (default `[]`) into the `users` slot. Rows are snake_case (`id`, `name`,
+ * `role`, …) — the privacy-reduced directory projection the backend hands to
+ * non-Studio (Player) callers. Use it to build a chat people-list, an
+ * @-mention picker, or to resolve an author id to a display name. Mutating
+ * users is NOT part of this surface; the directory is read-only here (see
+ * useUsers for administration).
+ *
+ * `query` is an optional `{ q?, role?, is_active?, limit?, offset? }`
+ * object passed through verbatim. The hook re-fetches whenever
+ * `JSON.stringify(query)` changes and exposes `refetch` for on-demand
+ * reloads (e.g. a chat roster refresh).
+ *
+ * Requires the `directory.read:users` scope in the widget manifest's
+ * `requestedScopes`.
+ */
+export function useDirectory(query) {
+  const ctx = useWidgetContextOrThrow("useDirectory");
+  if (
+    !ctx.directory ||
+    !ctx.directory.users ||
+    typeof ctx.directory.users.list !== "function"
+  ) {
+    throw new Error(
+      "useDirectory: host did not inject a directory client (ctx.directory.users.list)",
+    );
+  }
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDatastoreQuery: the host rebuilds the
+  // WidgetContext value every render, so we capture the live query +
+  // client in refs to keep `refetch` a stable identity.
+  const queryRef = useRef(query);
+  const usersNsRef = useRef(ctx.directory.users);
+  queryRef.current = query;
+  usersNsRef.current = ctx.directory.users;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await usersNsRef.current.list(queryRef.current);
+      // Directory list returns the { data, meta } envelope verbatim.
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      if (runRef.current !== myRun) return;
+      setUsers(rows);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { users, loading, error, refetch };
+}
+
 /**
  * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
  *
  * Returns `{ users, loading, error, refetch, invite, deactivate,
- * reactivate, remove }`. The list refetches whenever
- * `JSON.stringify(query)` changes; the imperative methods reject with a
- * `DirectoryError`. Reads require the `users.read:*` scope; mutations
- * additionally require `users.write:*`. The host's signed
+ * reactivate, remove }`. Reads through the injected
+ * `@colixsystems/directory-client` at `ctx.directory.users.{list, get,
+ * invite, deactivate, reactivate}` — `list` resolves to the `{ data, meta }`
+ * envelope VERBATIM, so we unwrap `res.data` (default `[]`). User rows are
+ * snake_case (`id`, `name`, `email`, `role`, `is_active`, …) and bodies
+ * (e.g. `{ email, name, group_ids? }`) pass through verbatim. The list
+ * refetches whenever `JSON.stringify(query)` changes; the imperative methods
+ * reject with a `DirectoryError`. Reads require the `users.read:*` scope;
+ * mutations additionally require `users.write:*`. The host's signed
  * `X-Widget-Scopes` header + a tenant-scoped SystemAcl `users.read` /
  * `users.write` capability grant gate the underlying endpoint
  * (REQ-ACL-SYS M3 §4.3) — a widget that declares the scopes but whose
@@ -829,17 +1112,23 @@ function toDirectoryError(err) {
  */
 export function useUsers(query) {
   const ctx = useWidgetContextOrThrow("useUsers");
-  if (!ctx.users || typeof ctx.users.listUsers !== "function") {
-    throw new Error("useUsers: host did not inject a users client");
+  if (
+    !ctx.directory ||
+    !ctx.directory.users ||
+    typeof ctx.directory.users.list !== "function"
+  ) {
+    throw new Error(
+      "useUsers: host did not inject a directory client (ctx.directory.users)",
+    );
   }
   const [users, setUsers] = useState([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
 
   const queryRef = useRef(query);
-  const usersRef = useRef(ctx.users);
+  const usersRef = useRef(ctx.directory.users);
   queryRef.current = query;
-  usersRef.current = ctx.users;
+  usersRef.current = ctx.directory.users;
 
   const runRef = useRef(0);
 
@@ -848,9 +1137,11 @@ export function useUsers(query) {
     setLoading(true);
     setError(null);
     try {
-      const rows = await usersRef.current.listUsers(queryRef.current);
+      const res = await usersRef.current.list(queryRef.current);
+      // Directory users.list returns the { data, meta } envelope verbatim.
+      const rows = res && Array.isArray(res.data) ? res.data : [];
       if (runRef.current !== myRun) return;
-      setUsers(Array.isArray(rows) ? rows : []);
+      setUsers(rows);
       setLoading(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
@@ -911,22 +1202,33 @@ export function useUsers(query) {
  * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration hook.
  *
  * Returns `{ groups, loading, error, refetch, create, remove, addMember,
- * removeMember }`. Reads require `groups.read:*`; mutations require
- * `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as `useUsers`.
+ * removeMember }`. Reads through the injected
+ * `@colixsystems/directory-client` at `ctx.directory.groups.{list, create,
+ * remove, addMember, removeMember, listMine}` — `list` resolves to the
+ * `{ data, meta }` envelope VERBATIM, so we unwrap `res.data` (default `[]`).
+ * Group rows are snake_case and bodies pass through verbatim. Reads require
+ * `groups.read:*`; mutations require `groups.write:*`. Same X-Widget-Scopes +
+ * SystemAcl gating as `useUsers`.
  */
 export function useGroups(query) {
   const ctx = useWidgetContextOrThrow("useGroups");
-  if (!ctx.groups || typeof ctx.groups.listGroups !== "function") {
-    throw new Error("useGroups: host did not inject a groups client");
+  if (
+    !ctx.directory ||
+    !ctx.directory.groups ||
+    typeof ctx.directory.groups.list !== "function"
+  ) {
+    throw new Error(
+      "useGroups: host did not inject a directory client (ctx.directory.groups)",
+    );
   }
   const [groups, setGroups] = useState([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
 
   const queryRef = useRef(query);
-  const groupsRef = useRef(ctx.groups);
+  const groupsRef = useRef(ctx.directory.groups);
   queryRef.current = query;
-  groupsRef.current = ctx.groups;
+  groupsRef.current = ctx.directory.groups;
 
   const runRef = useRef(0);
 
@@ -935,9 +1237,11 @@ export function useGroups(query) {
     setLoading(true);
     setError(null);
     try {
-      const rows = await groupsRef.current.listGroups(queryRef.current);
+      const res = await groupsRef.current.list(queryRef.current);
+      // Directory groups.list returns the { data, meta } envelope verbatim.
+      const rows = res && Array.isArray(res.data) ? res.data : [];
       if (runRef.current !== myRun) return;
-      setGroups(Array.isArray(rows) ? rows : []);
+      setGroups(rows);
       setLoading(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
@@ -994,29 +1298,114 @@ export function useGroups(query) {
   return { groups, loading, error, refetch, create, remove, addMember, removeMember };
 }
 
-export function useI18n() {
-  const ctx = useWidgetContextOrThrow("useI18n");
-  const i18n = ctx.i18n || {};
-  const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
-  const hostT = typeof i18n.t === "function" ? i18n.t : null;
-  const t = useCallback(
-    (key, fallback) => {
-      if (typeof key !== "string" || !key) {
-        return typeof fallback === "string" ? fallback : "";
-      }
-      if (hostT) {
-        // Try the two-arg form first; if the host's `t` ignores `fallback`
-        // and returns the bare key on a miss, swap in the fallback.
-        const out = hostT(key, fallback);
-        if (typeof out === "string" && out.length > 0 && out !== key) {
-          return out;
-        }
-        // Host returned the key (unresolved) or nothing usable.
-        return typeof fallback === "string" ? fallback : key;
-      }
-      return typeof fallback === "string" ? fallback : key;
-    },
-    [hostT],
+/* ============================================================================
+ * PAYMENTS CLIENT — ctx.payments (@colixsystems/payments-client)
+ *
+ * requestPayment, getPayment. Covers: usePayments.
+ * ==========================================================================*/
+
+/**
+ * Structured error thrown by `usePayments` callbacks. Carries a stable
+ * `code` so widgets can branch without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "AUTH_REQUIRED"             — no signed-in app user
+ *   - "PAYMENTS_SCOPE_NOT_GRANTED"— widget lacks payments.charge:appUser
+ *   - "INVALID_AMOUNT" / "AMOUNT_TOO_LARGE" / "VALIDATION" — bad request
+ *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
+ *   - "DECLINED"                  — the charge was declined
+ *   - "INTERNAL"                  — anything else
+ */
+export class PaymentError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "PaymentError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toPaymentError(err) {
+  if (err instanceof PaymentError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyCode =
+    err && err.response && err.response.data && err.response.data.code;
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 402) code = "DECLINED";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 400) code = "VALIDATION";
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Payment request failed");
+  return new PaymentError(code, message, { cause: err });
+}
+
+/**
+ * Incoming app-user payments (REQ-BILL-07-WIDGETPAY). Returns
+ * `{ requestPayment, getPayment }`.
+ *
+ *   requestPayment({ amountCents, currency?, description, metadata? })
+ *     → Promise<{ id, status, checkoutUrl?, ... }>. The host either
+ *       auto-confirms (mock provider, `status: "PAID"`, no redirect) or
+ *       returns a hosted-Checkout `checkoutUrl` the widget should open
+ *       (Stripe provider, `status: "PENDING"`). Rejects with a
+ *       `PaymentError`.
+ *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
+ *
+ * Requires the `payments.charge:appUser` scope in the manifest's
+ * `requestedScopes`. The charge settles to the workspace owner; the app
+ * user confirms the amount in hosted Checkout. No card data touches the
+ * widget — never collect card fields yourself.
+ */
+export function usePayments() {
+  const ctx = useWidgetContextOrThrow("usePayments");
+  if (!ctx.payments || typeof ctx.payments.requestPayment !== "function") {
+    throw new Error(
+      "usePayments: host did not inject a payments client. The widget must " +
+        "declare the payments.charge:appUser scope and be installed in a " +
+        "workspace whose host supports payments.",
+    );
+  }
+  const requestRef = useRef(ctx.payments.requestPayment);
+  const getRef = useRef(
+    typeof ctx.payments.getPayment === "function"
+      ? ctx.payments.getPayment
+      : null,
   );
-  return { t, locale };
+  requestRef.current = ctx.payments.requestPayment;
+  getRef.current =
+    typeof ctx.payments.getPayment === "function"
+      ? ctx.payments.getPayment
+      : null;
+
+  const requestPayment = useCallback(async (args) => {
+    try {
+      return await requestRef.current(args);
+    } catch (err) {
+      throw toPaymentError(err);
+    }
+  }, []);
+  const getPayment = useCallback(async (paymentId) => {
+    if (!getRef.current) {
+      throw new PaymentError(
+        "INTERNAL",
+        "getPayment is not supported by this host.",
+      );
+    }
+    try {
+      return await getRef.current(paymentId);
+    } catch (err) {
+      throw toPaymentError(err);
+    }
+  }, []);
+  return { requestPayment, getPayment };
 }