@colixsystems/widget-sdk 0.13.0 → 0.15.0

package/README.md

@@ -6,7 +6,35 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.13.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.15.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.15.0
+
+REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. See [`docs/design/req-widget-sdk-cross-platform-primitives.md`](../../docs/design/req-widget-sdk-cross-platform-primitives.md) for the full design and rationale.
+
+- **`CONTRACT.vettedImports` (new).** A curated allowlist of bare specifiers a widget may import — `react`, `@colixsystems/widget-sdk`, `react-native`, `axios`, `date-fns`, `react-native-svg`, `lucide-react-native`, `react-native-maps`, `leaflet`, `react-leaflet`, `expo-av`, `@react-native-community/datetimepicker`, `expo-clipboard`, `expo-haptics`. Each entry carries `platforms` (one or both of `"web"` / `"native"`) and a `category` so the linter and the marketplace listing can render honest platform badges. `CONTRACT.allowedBareImports` (the existing field) is now derived from `vettedImports` and stays a plain `string[]` for back-compat.
+- **`fetch` and `XMLHttpRequest` come off `CONTRACT.bannedApis`.** Widgets may call third-party APIs directly. Calls to the host's own `/api/*` surface will 401 because the JWT token is never shared with widget code; the linter emits a soft `no-host-api-url` warning when it sees host-URL substrings so authors learn the rule statically. Use SDK hooks (`useDatastoreQuery`, `useUsers`, `useFile`, …) for workspace data; use `axios` / `fetch` for third-party APIs.
+- **`import-not-vetted` linter rule (new).** Every bare `import` specifier is validated against `CONTRACT.vettedImports`. Relative imports inside the bundle (`./shared.js`) are allowed so split-impl widgets can share helpers; `../` and absolute paths are rejected.
+- **`import-platform-mismatch` linter rule (new).** A single-source widget that imports a native-only package while `manifest.supportedPlatforms` includes `"web"` fails the lint. The author either drops the platform from the manifest OR ships a `widget.web.jsx` + `widget.native.jsx` pair where the platform-specific import lives in the file that targets its platform.
+- **Lint findings carry `severity`.** `"error"` (default) blocks publish; `"warning"` (currently only `no-host-api-url`) surfaces to reviewers without blocking. The `lintSource(...)` return shape stays `{ ok, findings }` — `ok` is true iff no error-severity findings exist.
+- **Four Tier A SDK additions:**
+  - `<Icon>` primitive — `<Icon name="check" size={16} color={theme.colors.primary} />`. Wraps `lucide-react-native`; works on both platforms.
+  - `<DateTimePicker>` primitive — `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. Wraps `@react-native-community/datetimepicker` and normalizes the value to ISO 8601 strings (the datastore wire format).
+  - `useClipboard()` hook — `{ copy, paste, hasContent }`. Web via `navigator.clipboard`; native via `expo-clipboard`. Rejections are a structured `ClipboardError` with `.code` in `PERMISSION_DENIED | INTERNAL`.
+  - `useToast()` hook — `{ showToast }`. The host installs a workspace-themed renderer at `WidgetContext.toast.showToast`; if omitted, the web variant dispatches an `appstudio:widget-toast` CustomEvent and native logs to the console.
+- **`CONTRACT.version` → `1.5.0`** (additive: two new contract fields — `vettedImports`, `hostApiUrlPatterns` — two banned APIs removed, two primitives + two hooks added, one optional `widgetContextShape.toast` slot). No existing export changed signature.
+
+### What was in 0.14.1
+
+- **`groupRef` property type (REQ-USERMGMT M4 / §4.8).** Authors can now declare `{ type: 'groupRef', label: 'Group' }` in their `propertySchema` to render a Group picker in the Studio Properties Panel. The widget receives a bare `AppUserGroup` UUID — REQ-GEN-07 compliant, so tenant-copy walks the value transparently. Used by the built-in `appstudio.user-management` widget for its `defaultGroupId` prop and available to third-party widgets that need to anchor behaviour on a specific group.
+- **Patch bump** — additive enumeration entry, no exported function signature changed. `CONTRACT.version` stays `1.4.0`.
+
+### What's new in 0.14.0
+
+- **`useUsers()` + `useGroups()` — AppUser administration hooks (REQ-USERMGMT / REQ-ACL-SYS M3).** A widget can now invite, deactivate, reactivate, and remove members, and create / delete groups + add / remove members, from a published-app surface. Returns `{ users | groups, loading, error, refetch, ... }` plus imperative mutation methods. Reads gated by `users.read:*` / `groups.read:*`; mutations by `users.write:*` / `groups.write:*`. Rejections surface as a structured `DirectoryError` (new named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY`. The host signs an `X-Widget-Scopes` header against `JWT_SECRET` so an APP_USER cannot forge a scope set, and the backend additionally gates the request behind a SystemAcl `users.*` / `groups.*` capability grant (REQ-ACL-SYS M1 + M3).
+- **Managing app users from a widget — see the section below.**
+- **New linter rule `no-scope-mismatch-useUsers` / `no-scope-mismatch-useGroups`.** Calling `useUsers().invite()` / `.deactivate()` / `.reactivate()` / `.remove()` without `users.write:*` in the manifest's `requestedScopes` fails the lint; calling `useGroups()` mutation methods without `groups.write:*` fails the lint. Keeps the manifest honest at submission time.
+- **`CONTRACT.version` → `1.4.0`** (additive: two new hooks, two new context slices, six new scope verbs, one new error class). No existing export changed signature.
 
 ### What's new in 0.13.0
 
@@ -89,11 +117,58 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreMutation`, `useDirectory`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
-- `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet` — re-exported from `react-native`. The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. See https://reactnative.dev/docs/ for per-component props.
+- `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`, `DateTimePicker` wraps `@react-native-community/datetimepicker`). The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
+## Managing app users from a widget
+
+REQ-USERMGMT / REQ-ACL-SYS M3 added two hooks that let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. The hooks are gated by two layers: the widget's manifest must declare the scope (so the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability in the tenant (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller does not hold the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that to the end-user as a "you do not have permission to do that" message.
+
+```js
+import { Text, View, Pressable, useUsers, useGroups } from "@colixsystems/widget-sdk";
+
+export default function MemberManager() {
+  const { users, loading, invite, deactivate, remove } = useUsers({ q: "" });
+  const { groups, addMember } = useGroups();
+  if (loading) return <Text>Loading…</Text>;
+  return (
+    <View>
+      {users.map((u) => (
+        <View key={u.id}>
+          <Text>{u.name} — {u.isActive ? "active" : "inactive"}</Text>
+          <Pressable onPress={() => deactivate(u.id)}><Text>Deactivate</Text></Pressable>
+          <Pressable onPress={() => remove(u.id)}><Text>Remove</Text></Pressable>
+        </View>
+      ))}
+      <Pressable
+        onPress={async () => {
+          try {
+            await invite({ email: "a@b.com", name: "New User", groupIds: [groups[0]?.id].filter(Boolean) });
+          } catch (err) {
+            // err.code is one of FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY
+          }
+        }}
+      >
+        <Text>Invite</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+The matching manifest declares the scopes:
+
+```js
+{
+  // ...
+  requestedScopes: ["users.read:*", "users.write:*", "groups.read:*", "groups.write:*"],
+}
+```
+
+The host rejects calls whose scope is not declared in the manifest (the SDK linter catches this statically too). Declaring a write scope is also a consent prompt the Studio admin sees at install time — the wider the scope set, the more careful the admin is about granting the install.
+
 ## Linter
 
 ```sh

package/dist/clipboard.js

@@ -0,0 +1,88 @@
+// REQ-WSDK-PLATFORM §6 — `useClipboard()` hook (web implementation).
+//
+// Wraps the browser's `navigator.clipboard` API. Returns a stable object:
+//
+//   const { copy, paste, hasContent } = useClipboard();
+//
+//   - `copy(text)`     → Promise<void>. Writes a string. Rejects with a
+//                        `ClipboardError` on failure (most common code:
+//                        "PERMISSION_DENIED" — the page lacks the
+//                        clipboard-write permission, often because the
+//                        call wasn't triggered by a user gesture).
+//   - `paste()`        → Promise<string>. Reads the current clipboard
+//                        text. Returns "" when empty, rejects with
+//                        `ClipboardError` (code "PERMISSION_DENIED" on
+//                        sites that haven't asked for clipboard-read
+//                        permission).
+//   - `hasContent()`   → Promise<boolean>. Best-effort: reads the
+//                        clipboard and reports whether it had a
+//                        non-empty string. Same permission caveats as
+//                        `paste()`.
+//
+// The native build uses ./clipboard.native.js (Metro picks via the
+// package.json `react-native` resolution path through index.native.js).
+
+export class ClipboardError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ClipboardError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function _isPermissionError(err) {
+  if (!err) return false;
+  if (err.name === "NotAllowedError" || err.name === "SecurityError") return true;
+  const msg = typeof err.message === "string" ? err.message.toLowerCase() : "";
+  return msg.includes("permission") || msg.includes("not allowed");
+}
+
+function _wrap(err, label) {
+  if (err instanceof ClipboardError) return err;
+  const code = _isPermissionError(err) ? "PERMISSION_DENIED" : "INTERNAL";
+  return new ClipboardError(code, `${label}: ${err && err.message ? err.message : err}`, {
+    cause: err,
+  });
+}
+
+export function useClipboard() {
+  // Each method is a fresh function but the returned identity is stable
+  // per call site — callers passing one into useEffect dep arrays should
+  // pin the method, not the whole object.
+  return {
+    async copy(text) {
+      const value = text == null ? "" : String(text);
+      try {
+        if (typeof navigator === "undefined" || !navigator.clipboard) {
+          throw new ClipboardError("INTERNAL", "Clipboard API unavailable.");
+        }
+        await navigator.clipboard.writeText(value);
+      } catch (err) {
+        throw _wrap(err, "clipboard.copy");
+      }
+    },
+    async paste() {
+      try {
+        if (typeof navigator === "undefined" || !navigator.clipboard) {
+          throw new ClipboardError("INTERNAL", "Clipboard API unavailable.");
+        }
+        const text = await navigator.clipboard.readText();
+        return typeof text === "string" ? text : "";
+      } catch (err) {
+        throw _wrap(err, "clipboard.paste");
+      }
+    },
+    async hasContent() {
+      try {
+        if (typeof navigator === "undefined" || !navigator.clipboard) return false;
+        const text = await navigator.clipboard.readText();
+        return typeof text === "string" && text.length > 0;
+      } catch {
+        // Permission-denied reads return false instead of throwing —
+        // hasContent() is the "best-effort" probe, not a write gate.
+        return false;
+      }
+    },
+  };
+}

package/dist/clipboard.native.js

@@ -0,0 +1,64 @@
+// REQ-WSDK-PLATFORM §6 — `useClipboard()` hook (native implementation).
+//
+// Wraps expo-clipboard. Same return shape as the web counterpart
+// (./clipboard.js) so widget code is byte-for-byte identical across
+// platforms. The two implementations only differ in how `copy` / `paste`
+// reach the system clipboard.
+//
+// Errors are normalized to a structured `ClipboardError` with a stable
+// `.code`. Native clipboard reads cannot fail on permission grounds
+// (Android doesn't prompt; iOS reveals a paste banner but still
+// resolves), so "PERMISSION_DENIED" is web-only.
+
+// eslint-disable-next-line no-restricted-syntax
+import * as Clipboard from "expo-clipboard";
+
+export class ClipboardError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ClipboardError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function _wrap(err, label) {
+  if (err instanceof ClipboardError) return err;
+  return new ClipboardError(
+    "INTERNAL",
+    `${label}: ${err && err.message ? err.message : err}`,
+    { cause: err },
+  );
+}
+
+export function useClipboard() {
+  return {
+    async copy(text) {
+      const value = text == null ? "" : String(text);
+      try {
+        await Clipboard.setStringAsync(value);
+      } catch (err) {
+        throw _wrap(err, "clipboard.copy");
+      }
+    },
+    async paste() {
+      try {
+        const text = await Clipboard.getStringAsync();
+        return typeof text === "string" ? text : "";
+      } catch (err) {
+        throw _wrap(err, "clipboard.paste");
+      }
+    },
+    async hasContent() {
+      try {
+        if (typeof Clipboard.hasStringAsync === "function") {
+          return !!(await Clipboard.hasStringAsync());
+        }
+        const text = await Clipboard.getStringAsync();
+        return typeof text === "string" && text.length > 0;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/dist/contract.cjs

@@ -170,6 +170,112 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
+  // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
+  // Reads need `users.read:*` scope; mutations additionally need
+  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
+  // and returns the resulting AppUserInvite row (the email is sent by the
+  // host). Mutating users from a widget requires the corresponding
+  // SystemAcl `users.write` capability grant in the tenant; widgets that
+  // only call read methods need only `users.read:*`.
+  {
+    name: "useUsers",
+    signature: "useUsers(query?)",
+    description:
+      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
+      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
+      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
+      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+    returnShape: {
+      users: "Array<{ id, name, email?, role, isActive }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      invite:
+        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+      deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "users.listUsers",
+      "users.invite",
+      "users.deactivate",
+      "users.reactivate",
+      "users.remove",
+    ],
+    scopes: ["users.read:*"],
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
+  // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
+  // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
+  // member requires the corresponding `users.write` capability since it
+  // affects the user's effective access.
+  {
+    name: "useGroups",
+    signature: "useGroups(query?)",
+    description:
+      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
+      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "mutations need groups.write:*.",
+    returnShape: {
+      groups: "Array<{ id, name, memberCount }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      create:
+        "({ name }) => Promise<Group>  // rejects with DirectoryError",
+      remove: "(groupId) => Promise<void>  // rejects with DirectoryError",
+      addMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+      removeMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "groups.listGroups",
+      "groups.create",
+      "groups.remove",
+      "groups.addMember",
+      "groups.removeMember",
+    ],
+    scopes: ["groups.read:*"],
+  },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
+  {
+    name: "useClipboard",
+    signature: "useClipboard()",
+    description:
+      "Cross-platform clipboard access. Returns { copy, paste, hasContent }. " +
+      "All methods return Promises; rejections surface a structured ClipboardError " +
+      "with .code in PERMISSION_DENIED | INTERNAL. On web the browser may " +
+      "require a user gesture for read access — surface the error to the " +
+      "user as a 'try again after clicking' prompt when code === PERMISSION_DENIED.",
+    returnShape: {
+      copy:
+        "(text: string) => Promise<void>  // rejects with ClipboardError",
+      paste:
+        "() => Promise<string>  // rejects with ClipboardError",
+      hasContent: "() => Promise<boolean>  // best-effort, never throws",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useToast",
+    signature: "useToast()",
+    description:
+      "Surfaces a short auto-dismissing notification. Returns { showToast }. " +
+      "showToast({ kind: 'success' | 'error' | 'info' | 'warning', message }) " +
+      "asks the host to render a workspace-themed toast. If the host hasn't " +
+      "wired a renderer, the web variant dispatches an 'appstudio:widget-toast' " +
+      "CustomEvent on window; native logs to the console. The widget never " +
+      "owns the toast UI — that's the host's responsibility.",
+    returnShape: {
+      showToast: "({ kind, message }) => void",
+    },
+    requiredContextSlice: ["toast.showToast"],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -264,6 +370,22 @@ const PRIMITIVES = [
     rnComponent: "Linking",
     docsUrl: "https://reactnative.dev/docs/linking",
   },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK primitive.
+  {
+    name: "Icon",
+    description:
+      'Lucide icon. `<Icon name="check" size={16} color="..." />`. Unknown names render the Square fallback so the canvas always shows something visible. Names are the lucide icon ids (`https://lucide.dev/icons`). Works on both web and native.',
+    rnComponent: "lucide-react-native",
+    docsUrl: "https://lucide.dev/icons",
+  },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK primitive.
+  {
+    name: "DateTimePicker",
+    description:
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native input via react-native-web; native uses @react-native-community/datetimepicker.',
+    rnComponent: "@react-native-community/datetimepicker",
+    docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
+  },
 ];
 
 const CATEGORIES = [
@@ -433,6 +555,38 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
+  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
+  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
+  // APP_USER cannot forge scope claims, and the request is additionally
+  // gated by a SystemAcl `users.read` / `users.write` capability grant.
+  users: {
+    description:
+      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
+    required: true,
+    fields: {
+      listUsers: "function",
+      invite: "function",
+      deactivate: "function",
+      reactivate: "function",
+      remove: "function",
+    },
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
+  // backing useGroups(). Reads gated by `groups.read:*`; mutations by
+  // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
+  groups: {
+    description:
+      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
+    required: true,
+    fields: {
+      listGroups: "function",
+      create: "function",
+      remove: "function",
+      addMember: "function",
+      removeMember: "function",
+    },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -449,6 +603,17 @@ const WIDGET_CONTEXT_SHAPE = {
       error: "function",
     },
   },
+  // REQ-WSDK-PLATFORM §6 — backs useToast(). Mirror of contract.js.
+  toast: {
+    description:
+      "Optional host toast slot. { showToast({ kind, message }): void }. " +
+      "The host populates this to render workspace-themed notifications " +
+      "from any widget that calls useToast(). When omitted the SDK falls " +
+      "back to dispatching an 'appstudio:widget-toast' CustomEvent on web " +
+      "and console.log on native.",
+    required: false,
+    fields: { showToast: "function" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -471,6 +636,15 @@ const BUNDLE_EXPORT_CONTRACT = [
   },
 ];
 
+// REQ-WSDK-PLATFORM (docs/design/req-widget-sdk-cross-platform-primitives.md
+// §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. Widgets may call
+// third-party APIs directly. Same-origin requests to the host's own
+// `/api/*` surface are rejected at runtime by the WidgetContextProvider's
+// network gate (`no host-api access from widgets`) — the JWT token is
+// never shared with widget code, so the call would 401 anyway; the runtime
+// gate makes the failure mode "blocked" instead of "401 noise". A soft
+// linter warning (`no-host-api-url`) flags obvious host-URL substrings at
+// submission so authors learn the rule statically.
 const BANNED_APIS = [
   { identifier: "eval", reason: "Arbitrary code evaluation." },
   {
@@ -499,23 +673,144 @@ const BANNED_APIS = [
     reason: "Same reason as localStorage.",
   },
   {
-    identifier: "fetch",
-    reason:
-      "Direct network calls bypass the datastore client + tenant auth.",
+    identifier: "import(",
+    reason: "Dynamic import bypasses the loader's allowlist.",
+  },
+  { identifier: "globalThis", reason: "Host environment escape." },
+];
+
+// REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
+// specifier the widget bundle may import as a bare module specifier. The
+// linter validates every `import ... from "<spec>"` line against this
+// list; specifiers not on the list fail the lint. The compiler reads it
+// to know which packages to add to the exported Expo app's package.json.
+//
+// `platforms` is one or both of "web" / "native". A widget that imports a
+// native-only package implicitly drops "web" from the package's effective
+// `supportedPlatforms` (and vice versa) — the marketplace upload pipeline
+// surfaces the derived set so the listing shows honest badges.
+//
+// Adding a package is a CONTRACT change. Review burden: confirm the
+// package does what it claims, has a credible maintainer, and the
+// import shape (named exports, default export) is stable. After that,
+// every widget using the package inherits the review — the marketplace
+// reviewer only spot-checks usage, not the package source.
+const VETTED_IMPORTS = [
+  {
+    specifier: "react",
+    platforms: ["web", "native"],
+    category: "core",
+    description: "React. Hooks, JSX, lifecycle. Unchanged.",
+  },
+  {
+    specifier: "@colixsystems/widget-sdk",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "The AppStudio widget SDK — primitives, hooks, manifest helpers. Unchanged.",
+  },
+  {
+    specifier: "react-native",
+    platforms: ["web", "native"],
+    category: "primitive",
+    description:
+      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web the host bundler aliases this to react-native-web; on native Metro resolves the real library.",
   },
   {
-    identifier: "XMLHttpRequest",
-    reason:
-      "Direct network calls bypass the datastore client + tenant auth.",
+    specifier: "axios",
+    platforms: ["web", "native"],
+    category: "network",
+    description:
+      "HTTP client for third-party APIs. Calls to the host's /api/* surface are blocked at runtime — widgets get no JWT token, so use SDK hooks for workspace data.",
   },
   {
-    identifier: "import(",
-    reason: "Dynamic import bypasses the loader's allowlist.",
+    specifier: "date-fns",
+    platforms: ["web", "native"],
+    category: "utility",
+    description: "Pure-JS date math. Works on both platforms unchanged.",
+  },
+  {
+    specifier: "react-native-svg",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "Cross-platform SVG drawing primitives. Used by the built-in Chart widget; works on both platforms.",
+  },
+  {
+    specifier: "lucide-react-native",
+    platforms: ["web", "native"],
+    category: "iconography",
+    description:
+      "Lucide icon set as React components. Used by the built-in Icon widget; works on both platforms.",
+  },
+  {
+    specifier: "react-native-maps",
+    platforms: ["native"],
+    category: "geo",
+    description:
+      "Native map view + markers. Native-only; pair with leaflet/react-leaflet in widget.web.jsx for a web variant.",
+  },
+  {
+    specifier: "leaflet",
+    platforms: ["web"],
+    category: "geo",
+    description:
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+  },
+  {
+    specifier: "react-leaflet",
+    platforms: ["web"],
+    category: "geo",
+    description: "React bindings for leaflet. Web-only.",
+  },
+  {
+    specifier: "expo-av",
+    platforms: ["native"],
+    category: "media",
+    description:
+      "Native audio + video playback. Native-only; pair with browser <audio>/<video> in widget.web.jsx.",
+  },
+  {
+    specifier: "@react-native-community/datetimepicker",
+    platforms: ["native"],
+    category: "input",
+    description:
+      "Native date/time picker. The SDK's <DateTimePicker> primitive already wraps this; reach for it directly only if you need RN-specific options.",
+  },
+  {
+    specifier: "expo-clipboard",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Native clipboard. The SDK's useClipboard() hook already wraps this; reach for it directly only if you need RN-specific options.",
+  },
+  {
+    specifier: "expo-haptics",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Native haptic feedback. Pair with navigator.vibrate in widget.web.jsx.",
   },
-  { identifier: "globalThis", reason: "Host environment escape." },
 ];
 
-const ALLOWED_BARE_IMPORTS = ["react", "@colixsystems/widget-sdk"];
+// Back-compat shape — every existing consumer (widgetLoader, the static
+// analyzer's DEPENDENCY_ALLOWLIST, the AI prompt's "Allowed imports" line)
+// reads a plain `string[]` from `CONTRACT.allowedBareImports`. Derive it
+// from the rich list so a single edit in VETTED_IMPORTS propagates to
+// every surface.
+const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
+
+// REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
+// soft warning. None of these block the lint by themselves — they prompt
+// the marketplace reviewer to spot-check, and they help authors learn the
+// rule statically. Strings appear as literal substring matches (the URL
+// is reachable in widget code by composing it at runtime, so this is
+// best-effort).
+const HOST_API_URL_PATTERNS = [
+  "/api/v1",
+  "/uploads/",
+  "Authorization: Bearer",
+];
 
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
@@ -525,7 +820,17 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.2.0",
+  // REQ-WSDK-PLATFORM bump:
+  //   - `vettedImports` is a new field (rich allowlist with platforms +
+  //     category + description).
+  //   - `hostApiUrlPatterns` is a new field (soft-warning substrings).
+  //   - `bannedApis` no longer lists `fetch` / `XMLHttpRequest`.
+  //   - `allowedBareImports` is now derived from `vettedImports` (same
+  //     shape; same contents grow with each vetted addition).
+  // Permissive-direction change: minor bump on the contract's own
+  // versioning (per CLAUDE.md §4, pre-1.0 minor is the breaking channel —
+  // the package.json version bumps accordingly).
+  version: "1.5.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -535,7 +840,9 @@ const CONTRACT = deepFreeze({
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
+  vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostApiUrlPatterns: HOST_API_URL_PATTERNS,
 });
 
 function isHookAllowed(name) {