@colixsystems/widget-sdk 0.14.1 → 0.16.0

package/README.md

@@ -6,9 +6,33 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.14.1` — 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.16.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.14.1
+### What's new in 0.16.0
+
+REQ-THEME — the tenant's **Theme Settings** now flow all the way into `useTheme()`.
+
+- **`themeTokens.colors` gains `secondary` + `onSecondary`.** `useTheme().colors.secondary` reflects the tenant's *Secondary Color* picker (with `onSecondary` as its readable contrast color), alongside the existing `primary` / `onPrimary`. Built-in widgets like Button use it for their secondary variant; third-party widgets can use it for a branded second accent. The full `colors` shape is now `{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }`.
+- **`colors.primary` / `colors.secondary` / `typography.fontFamily` are tenant-resolved.** The host maps the Studio Theme Settings blob (Primary Color, Secondary Color, Global Font) onto the default tokens before handing them to `useTheme()`, on both the live Player and the exported app — so a widget that reads tokens re-themes automatically. (Custom Google fonts render in the Player today; the exported app falls back to the system face for non-system fonts until font bundling lands.)
+- **`CONTRACT.version` → `1.6.0`** (additive: two new `themeTokens.colors` keys). No existing export changed signature.
+
+### 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`.
@@ -101,9 +125,9 @@ 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`, `useUsers`, `useGroups`, `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. `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).
+- `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

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

@@ -12,6 +12,8 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
     primary: "#ff6b5b",
     onPrimary: "#ffffff",
+    secondary: "#475569",
+    onSecondary: "#ffffff",
     surface: "#ffffff",
     onSurface: "#111827",
     surfaceMuted: "#f8fafc",
@@ -37,7 +39,7 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
       spacing: "{ xs, sm, md, lg, xl }",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
@@ -240,6 +242,42 @@ const HOOKS = [
     ],
     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
@@ -334,6 +372,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 = [
@@ -551,6 +605,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 = [
@@ -573,6 +638,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." },
   {
@@ -601,23 +675,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.",
   },
   {
-    identifier: "XMLHttpRequest",
-    reason:
-      "Direct network calls bypass the datastore client + tenant auth.",
+    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: "import(",
-    reason: "Dynamic import bypasses the loader's allowlist.",
+    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.",
+  },
+  {
+    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;
@@ -627,7 +822,22 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.4.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).
+  //
+  // 1.6.0: additive — `themeTokens.colors` gains `secondary` + `onSecondary`
+  // so the tenant's Theme Settings "Secondary Color" flows through
+  // `useTheme().colors.secondary` (Button secondary variant + any widget
+  // that wants the brand's second accent).
+  version: "1.6.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -637,7 +847,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) {