@colixsystems/widget-sdk 0.45.1 → 0.48.0

package/README.md

@@ -13,7 +13,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
-**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (19 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
+**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (20 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
@@ -40,6 +40,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
+| **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
 
@@ -49,7 +50,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.45.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.48.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.48.0
+
+**New `useSendNotification()` hook — send an in-app notification to an app user (sc-890).** A new NOTIFICATIONS hook reading a newly-injected `ctx.notifications` slice (the `@colixsystems/notifications-client`, now constructed by both the web Player and the native Expo export). Returns `{ send, sending, error }`. `send({ recipient_user_id, title, body, link?, payload? })` posts a notification to one app user **in the same workspace** and resolves to the created row; `recipient_user_id` must be a member of the tenant or the call is rejected (cross-workspace targets never resolve). Call it from an **event handler** (a `Pressable.onPress`, a submit, a mutation callback) — never in render, where the abuse/rate-limit guard would fire on every paint. Gated by the new `notifications.send:appUser` scope, which the widget declares in its manifest `requestedScopes`. Rejections surface as a structured `NotificationError` (new named export) with a stable `.code` (`INVALID_TITLE` / `INVALID_BODY` / `INVALID_RECIPIENT` / `INVALID_PAYLOAD` / `VALIDATION` / `AUTH_REQUIRED` / `FORBIDDEN` / `RECIPIENT_NOT_FOUND` / `RATE_LIMITED` / `INTERNAL`). `CONTRACT.version` → `1.35.0`. Additive — one new hook, one new context slice, one new scope, one new error class; no existing export changed signature.
+
+### What's new in 0.47.0
+
+**`<FilePicker>` native variant is real (sc-1378 follow-up).** The Expo-export shell of `<FilePicker>` now wraps the vetted `expo-document-picker` and reports `FilePicker.isSupported = true`. Result: the Files widget's `allowUpload` toggle works on **both** the web Player and the native Expo export — no more disabled stub on mobile. `expo-document-picker` is added to `CONTRACT.vettedImports` (`platforms: ["native"]`); the compiler's `generatePackageJson` was already pinning it for the export build, so no new export-pin work was needed. `useFilestoreUpload` accepts whatever the host's FormData reads as a binary part — a browser `File` on web, the React Native `{ uri, name, type }` shape from the picker on native — so the same hook code path feeds the multipart on both platforms. `CONTRACT.version` → `1.34.0`, additive.
+
+### What's new in 0.46.0
+
+**End-user upload primitive + hook (sc-1378).** Widgets can now let an end user upload a file to the Filestore from the published app. Two pieces ship together:
+
+- **New SDK hook `useFilestoreUpload({ spaceType, folderId? })`.** Resolves `owner_id` the same way the read filestore hooks do, builds a multipart `FormData` with the snake_case fields the backend reads verbatim (`space_type`, `owner_id`, `folder_id`, plus the binary `file`), and POSTs through `ctx.filestore.files.upload`. Returns `{ upload(file, { folderId? }), uploading, error, lastUploaded }`. A 404 from the backend means the destination folder denied a write (REQ-FSH `canWrite` gate).
+- **New SDK primitive `<FilePicker accept onPick>`.** Web wraps a hidden DOM `<input type="file">` (children render as the visible click target inside a `<label>` so the click reaches the file dialog without ref plumbing). Native renders a disabled trigger and exposes `FilePicker.isSupported = false` until a vetted Expo picker pin lands.
+- **Files widget `allowUpload`.** The built-in Files widget grew an `Allow uploading files` toggle (manifest v2.2.0). When enabled, the toolbar renders an Upload trigger that pipes the picked file through the new hook into the currently-open folder; the `typeFilter` setting narrows the `accept` MIME so an "Images" filter shows only images in the OS dialog.
+- **`CONTRACT.version` → `1.33.0`.** Additive — new hook + new primitive; no existing hook, primitive, manifest field, or token changed shape.
 
 ### What's new in 0.45.1
 
@@ -151,6 +169,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 **Filestore browsing + BankID file signing for widgets (REQ-FS / REQ-SIGN).** Three new hooks read a newly-injected `ctx.filestore` (the `@colixsystems/filestore-client`, now constructed by both the web and native hosts):
 - `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space.
 - `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
+- `useFilestoreUpload({ spaceType, folderId? })` → `{ upload, uploading, error, lastUploaded }` — POSTs a multipart upload to `ctx.filestore.files.upload`. Resolves `owner_id` from the host context (like the read hooks) so the widget only picks the space + destination folder. Pair with the `<FilePicker>` primitive for the visible trigger. Requires the `files.write:*` scope.
 - `useFileSignature(fileId)` → `{ status, qr, signerName, verdict, initiate, refresh, cancel, verify, … }` — drives a BankID signing flow for a file (the backend hashes the bytes server-side, binds the digest into the signature, and verifies the proof offline).
 
 `CONTRACT.version` → `1.20.0` (additive — no existing hook changed).
@@ -382,7 +401,7 @@ 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`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `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, display_name, roles, group_ids }` (snake_case verbatim; `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). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(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`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `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`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, display_name, roles, group_ids }` (snake_case verbatim; `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). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(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`, `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` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives 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.

package/dist/contract.cjs

@@ -214,6 +214,27 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreUpload",
+    signature: "useFilestoreUpload({ spaceType, folderId? })",
+    description:
+      "Upload a file into the end-user's Filestore space. The widget passes " +
+      "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
+      "from the host context, builds a multipart FormData with the " +
+      "snake_case fields the backend reads verbatim (`space_type`, " +
+      "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
+      "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
+      "to the created file row or throws the wire error; a 404 means the " +
+      "destination folder denied a write (REQ-FSH canWrite gate).",
+    returnShape: {
+      upload: "(file, { folderId? }) => Promise<FilestoreFile>",
+      uploading: "boolean",
+      error: "Error | null",
+      lastUploaded: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -399,6 +420,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-890 — send an in-app notification to one app user in the tenant.
+  // IMPERATIVE: send() never fires on mount; the widget calls it from an
+  // event handler. Reads ctx.notifications.send (the injected
+  // @colixsystems/notifications-client). Requires the
+  // notifications.send:appUser scope.
+  {
+    name: "useSendNotification",
+    signature: "useSendNotification()",
+    returnShape: {
+      send: "({ recipient_user_id, title, body, link?, payload? }) => Promise<notification>  // rejects with NotificationError",
+      sending: "boolean",
+      error: "NotificationError | null",
+    },
+    requiredContextSlice: ["notifications.send"],
+    scopes: ["notifications.send:appUser"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
@@ -710,6 +747,19 @@ const PRIMITIVES = [
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
+  // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
+  // file-picker on the web Player so end users can upload files to the
+  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // a hidden DOM `<input type="file">`; native renders a disabled trigger
+  // and exposes `FilePicker.isSupported = false` until a vetted Expo
+  // picker pin lands.
+  {
+    name: "FilePicker",
+    description:
+      'End-user file picker primitive. `<FilePicker accept="image/*" multiple={false} disabled={false} onPick={(file) => …}>…trigger…</FilePicker>`. Children render as the visible click target (a Pressable + Icon + Text is the common shape) and are wrapped in a hidden-input <label> so the click reaches the file dialog without any ref plumbing. Pair with useFilestoreUpload to upload the picked File to the end-user filestore. `FilePicker.isSupported` is `true` on the web Player and `false` on the native Expo export — widgets should branch on it to hide the trigger when uploads are not yet wired natively.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -992,6 +1042,13 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // sc-890 — backs useSendNotification(). Mirror of contract.js.
+  notifications: {
+    description:
+      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification> }. Backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount).",
+    required: true,
+    fields: { send: "function" },
+  },
   // REQ-WSDK-DOMAIN-CLIENTS — the AppUser administration, AppUserGroup
   // administration, and per-record VirtualPermission facades that used to
   // live here (`users`, `groups`, `recordPermissions`) were folded into the
@@ -1169,6 +1226,13 @@ const VETTED_IMPORTS = [
     description:
       "Canvas-style 2D/GPU drawing & animation (games, custom graphics) on native. Native-only — author it in widget.native.jsx and pair it with a web variant in widget.web.jsx (a <canvas> or react-native-svg). There is no Skia web build wired into the Player.",
   },
+  {
+    specifier: "expo-document-picker",
+    platforms: ["native"],
+    category: "files",
+    description:
+      "Native file picker used by the SDK's <FilePicker> primitive on the Expo export (web uses a hidden DOM <input type=\"file\">, mapped to the same { accept, onPick } contract). Most widgets reach <FilePicker> through the SDK rather than importing this directly; a widget that does import it goes in widget.native.jsx and is pinned by the compiler's generatePackageJson — Expo SDK 56 ships 56.0.x.",
+  },
   {
     specifier: "lucide-react-native",
     platforms: ["web", "native"],
@@ -1681,7 +1745,40 @@ const CONTRACT = deepFreeze({
   //    instance — one StyleSheet/context, no double-instance conflicts. The
   //    vetted-import SET is unchanged (react-native was already vetted); only
   //    its web resolution + description changed — minor bump.
-  version: "1.32.0",
+  //
+  // 1.33.0: additive (sc-1378) — `useFilestoreUpload({ spaceType, folderId? })`
+  //    posts a multipart upload to `ctx.filestore.files.upload` after the
+  //    same owner_id resolution the read filestore hooks use (tenant for
+  //    PROJECT, app user for PERSONAL). Paired with the new `<FilePicker>`
+  //    primitive — web wraps a hidden DOM `<input type="file">`, native
+  //    renders a disabled trigger and exposes `FilePicker.isSupported =
+  //    false` until a vetted Expo picker pin lands. Backs the Files widget's
+  //    new `allowUpload` toggle. No existing hook, primitive, manifest
+  //    field, or token changed shape — minor bump.
+  //
+  // 1.34.0: additive (sc-1378 follow-up) — `<FilePicker>` native variant
+  //    now wraps the vetted `expo-document-picker` and reports
+  //    `FilePicker.isSupported = true` on the Expo export (the build was
+  //    already pinning the package in `generatePackageJson`). Closes the
+  //    REQ-FW-03 native gap; the Files widget's Upload button now works on
+  //    both the web Player and the Expo export. New vetted entry
+  //    `expo-document-picker` (`platforms: ["native"]`). `useFilestoreUpload`
+  //    accepts both a browser `File` and the React Native `{ uri, name,
+  //    type }` shape the native picker returns, so the same hook code path
+  //    feeds the multipart in both hosts. No existing hook, primitive, or
+  //    manifest field changed shape — minor bump.
+  //
+  // 1.35.0: additive (sc-890) — new `useSendNotification()` hook reading the
+  //    newly-injected `ctx.notifications` (@colixsystems/notifications-client).
+  //    Returns `{ send, sending, error }`; `send({ recipient_user_id, title,
+  //    body, link?, payload? })` POSTs to `/notifications/send` and resolves to
+  //    the created notification row, rejecting with a structured
+  //    NotificationError. Imperative — never fires on mount. New required field
+  //    on the new `notifications` context slice (`send: "function"`) + the new
+  //    `notifications.send:appUser` scope it gates on. No existing hook,
+  //    primitive, manifest field, or token changed shape — minor bump on the
+  //    pre-1.0 channel.
+  version: "1.35.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -214,6 +214,27 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreUpload",
+    signature: "useFilestoreUpload({ spaceType, folderId? })",
+    description:
+      "Upload a file into the end-user's Filestore space. The widget passes " +
+      "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
+      "from the host context, builds a multipart FormData with the " +
+      "snake_case fields the backend reads verbatim (`space_type`, " +
+      "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
+      "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
+      "to the created file row or throws the wire error; a 404 means the " +
+      "destination folder denied a write (REQ-FSH canWrite gate).",
+    returnShape: {
+      upload: "(file, { folderId? }) => Promise<FilestoreFile>",
+      uploading: "boolean",
+      error: "Error | null",
+      lastUploaded: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -399,6 +420,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-890 — send an in-app notification to one app user in the tenant.
+  // IMPERATIVE: send() never fires on mount; the widget calls it from an
+  // event handler. Reads ctx.notifications.send (the injected
+  // @colixsystems/notifications-client). Requires the
+  // notifications.send:appUser scope.
+  {
+    name: "useSendNotification",
+    signature: "useSendNotification()",
+    returnShape: {
+      send: "({ recipient_user_id, title, body, link?, payload? }) => Promise<notification>  // rejects with NotificationError",
+      sending: "boolean",
+      error: "NotificationError | null",
+    },
+    requiredContextSlice: ["notifications.send"],
+    scopes: ["notifications.send:appUser"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
@@ -710,6 +747,19 @@ const PRIMITIVES = [
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
+  // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
+  // file-picker on the web Player so end users can upload files to the
+  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // a hidden DOM `<input type="file">`; native renders a disabled trigger
+  // and exposes `FilePicker.isSupported = false` until a vetted Expo
+  // picker pin lands.
+  {
+    name: "FilePicker",
+    description:
+      'End-user file picker primitive. `<FilePicker accept="image/*" multiple={false} disabled={false} onPick={(file) => …}>…trigger…</FilePicker>`. Children render as the visible click target (a Pressable + Icon + Text is the common shape) and are wrapped in a hidden-input <label> so the click reaches the file dialog without any ref plumbing. Pair with useFilestoreUpload to upload the picked File to the end-user filestore. `FilePicker.isSupported` is `true` on the web Player and `false` on the native Expo export — widgets should branch on it to hide the trigger when uploads are not yet wired natively.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -992,6 +1042,13 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // sc-890 — backs useSendNotification(). Mirror of contract.cjs.
+  notifications: {
+    description:
+      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification> }. Backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount).",
+    required: true,
+    fields: { send: "function" },
+  },
   // REQ-WSDK-DOMAIN-CLIENTS — the AppUser administration, AppUserGroup
   // administration, and per-record VirtualPermission facades that used to
   // live here (`users`, `groups`, `recordPermissions`) were folded into the
@@ -1169,6 +1226,13 @@ const VETTED_IMPORTS = [
     description:
       "Canvas-style 2D/GPU drawing & animation (games, custom graphics) on native. Native-only — author it in widget.native.jsx and pair it with a web variant in widget.web.jsx (a <canvas> or react-native-svg). There is no Skia web build wired into the Player.",
   },
+  {
+    specifier: "expo-document-picker",
+    platforms: ["native"],
+    category: "files",
+    description:
+      "Native file picker used by the SDK's <FilePicker> primitive on the Expo export (web uses a hidden DOM <input type=\"file\">, mapped to the same { accept, onPick } contract). Most widgets reach <FilePicker> through the SDK rather than importing this directly; a widget that does import it goes in widget.native.jsx and is pinned by the compiler's generatePackageJson — Expo SDK 56 ships 56.0.x.",
+  },
   {
     specifier: "lucide-react-native",
     platforms: ["web", "native"],
@@ -1681,7 +1745,40 @@ const CONTRACT = deepFreeze({
   //    instance — one StyleSheet/context, no double-instance conflicts. The
   //    vetted-import SET is unchanged (react-native was already vetted); only
   //    its web resolution + description changed — minor bump.
-  version: "1.32.0",
+  //
+  // 1.33.0: additive (sc-1378) — `useFilestoreUpload({ spaceType, folderId? })`
+  //    posts a multipart upload to `ctx.filestore.files.upload` after the
+  //    same owner_id resolution the read filestore hooks use (tenant for
+  //    PROJECT, app user for PERSONAL). Paired with the new `<FilePicker>`
+  //    primitive — web wraps a hidden DOM `<input type="file">`, native
+  //    renders a disabled trigger and exposes `FilePicker.isSupported =
+  //    false` until a vetted Expo picker pin lands. Backs the Files widget's
+  //    new `allowUpload` toggle. No existing hook, primitive, manifest
+  //    field, or token changed shape — minor bump.
+  //
+  // 1.34.0: additive (sc-1378 follow-up) — `<FilePicker>` native variant
+  //    now wraps the vetted `expo-document-picker` and reports
+  //    `FilePicker.isSupported = true` on the Expo export (the build was
+  //    already pinning the package in `generatePackageJson`). Closes the
+  //    REQ-FW-03 native gap; the Files widget's Upload button now works on
+  //    both the web Player and the Expo export. New vetted entry
+  //    `expo-document-picker` (`platforms: ["native"]`). `useFilestoreUpload`
+  //    accepts both a browser `File` and the React Native `{ uri, name,
+  //    type }` shape the native picker returns, so the same hook code path
+  //    feeds the multipart in both hosts. No existing hook, primitive, or
+  //    manifest field changed shape — minor bump.
+  //
+  // 1.35.0: additive (sc-890) — new `useSendNotification()` hook reading the
+  //    newly-injected `ctx.notifications` (@colixsystems/notifications-client).
+  //    Returns `{ send, sending, error }`; `send({ recipient_user_id, title,
+  //    body, link?, payload? })` POSTs to `/notifications/send` and resolves to
+  //    the created notification row, rejecting with a structured
+  //    NotificationError. Imperative — never fires on mount. New required field
+  //    on the new `notifications` context slice (`send: "function"`) + the new
+  //    `notifications.send:appUser` scope it gates on. No existing hook,
+  //    primitive, manifest field, or token changed shape — minor bump on the
+  //    pre-1.0 channel.
+  version: "1.35.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/filepicker.js

@@ -0,0 +1,93 @@
+// sc-1378 — `<FilePicker>` SDK primitive (web implementation).
+//
+// React Native (and react-native-web) has no native equivalent of the
+// browser's `<input type="file">`, so the web build renders the DOM input
+// directly (the same trick the web DateTimePicker uses: `React.createElement
+// ("input", ...)`). The input is visually hidden so authors style the
+// trigger themselves — children are rendered inside a label so any
+// Pressable / View / Text the widget passes in becomes the click target.
+//
+// Public contract (mirror in filepicker.native.js — keep them in lockstep):
+//   accept:    string | undefined   — same value as the DOM `accept`
+//              attribute. "image/*" / "image/png,image/jpeg" narrow the
+//              picker; omit / "" lets the OS picker show every file type.
+//   multiple:  boolean              — default false. When true, `onPick`
+//              fires once with an array of File objects.
+//   disabled:  boolean              — gates the click; renders a muted
+//              label.
+//   onPick:    (file | File[]) => void
+//   children:  ReactNode            — the visible trigger (a Pressable +
+//              an icon + a label is the common shape). Wrapped in a
+//              `<label>` so the click reaches the hidden input
+//              everywhere — no manual ref / `.click()` plumbing needed.
+//   accessibilityLabel: string?     — written to the wrapper label.
+
+import React, { useRef, useCallback } from "react";
+
+const HIDDEN_INPUT_STYLE = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+const LABEL_STYLE = {
+  display: "inline-flex",
+  cursor: "pointer",
+};
+
+const LABEL_STYLE_DISABLED = {
+  ...LABEL_STYLE,
+  cursor: "not-allowed",
+  opacity: 0.5,
+};
+
+export function FilePicker({
+  accept,
+  multiple = false,
+  disabled = false,
+  onPick,
+  children,
+  accessibilityLabel,
+}) {
+  const inputRef = useRef(null);
+
+  const handleChange = useCallback(
+    (event) => {
+      const list = event && event.target && event.target.files;
+      if (!list || list.length === 0) return;
+      if (typeof onPick === "function") {
+        onPick(multiple ? Array.from(list) : list[0]);
+      }
+      // Reset the input so picking the SAME file twice in a row still fires
+      // onChange — DOM dedupes by value, the SDK contract does not.
+      event.target.value = "";
+    },
+    [onPick, multiple],
+  );
+
+  return React.createElement(
+    "label",
+    {
+      style: disabled ? LABEL_STYLE_DISABLED : LABEL_STYLE,
+      "aria-label": accessibilityLabel,
+    },
+    React.createElement("input", {
+      ref: inputRef,
+      type: "file",
+      accept: accept || undefined,
+      multiple,
+      disabled,
+      onChange: handleChange,
+      style: HIDDEN_INPUT_STYLE,
+    }),
+    children,
+  );
+}
+
+FilePicker.isSupported = true;

package/dist/filepicker.native.js

@@ -0,0 +1,100 @@
+// sc-1378 — `<FilePicker>` SDK primitive (native — Expo export).
+//
+// Wraps `expo-document-picker` (a vetted import, native-only; pinned by
+// the compiler's generatePackageJson at expo-document-picker ~56.0.x).
+// The web variant in ./filepicker.js wraps a hidden DOM
+// `<input type="file">` because react-native-web has no equivalent of the
+// system file picker; this native variant calls the OS document picker
+// directly. Both honour the same public contract — `accept` / `multiple`
+// / `disabled` / `onPick` / `children` / `accessibilityLabel`.
+//
+// `onPick` receives the same shape on both platforms:
+//   - web → the browser's `File` object (a `Blob` with name + type).
+//   - native → `{ uri, name, type, size }` — React Native's
+//     FormData-friendly file part. `useFilestoreUpload` appends whichever
+//     verbatim into the multipart body; the React Native fetch
+//     implementation reads `uri` and streams the bytes.
+
+import React, { useCallback, useMemo } from "react";
+import { Pressable, View } from "react-native";
+// eslint-disable-next-line no-restricted-syntax
+import { getDocumentAsync } from "expo-document-picker";
+
+// Map an HTML `accept` string (the web contract — "image/*", "audio/*",
+// "image/png,image/jpeg", …) to expo-document-picker's `type` arg, which
+// accepts either a single MIME string or an array of MIME strings. We
+// pass the array form unchanged so a comma-separated list narrows the
+// same way it does on web. An empty / falsy accept maps to "*/*"
+// (DocumentPicker's wide-open default — every file type is offered).
+function _mapAccept(accept) {
+  if (!accept || typeof accept !== "string") return "*/*";
+  const parts = accept
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return "*/*";
+  if (parts.length === 1) return parts[0];
+  return parts;
+}
+
+// expo-document-picker returns `{ canceled, assets: [{ uri, name,
+// mimeType, size }] }`. Normalise each asset to the FormData-friendly
+// `{ uri, name, type, size }` shape useFilestoreUpload appends into the
+// multipart body — `type` is the field React Native's FormData reads
+// for the part's content-type, mirroring the browser File's `.type`.
+function _asset(picked) {
+  return {
+    uri: picked.uri,
+    name: picked.name || "upload",
+    type: picked.mimeType || "application/octet-stream",
+    size: typeof picked.size === "number" ? picked.size : undefined,
+  };
+}
+
+export function FilePicker({
+  accept,
+  multiple = false,
+  disabled = false,
+  onPick,
+  children,
+  accessibilityLabel,
+}) {
+  const type = useMemo(() => _mapAccept(accept), [accept]);
+
+  const handlePress = useCallback(async () => {
+    if (disabled) return;
+    let result;
+    try {
+      result = await getDocumentAsync({
+        type,
+        multiple,
+        copyToCacheDirectory: true,
+      });
+    } catch {
+      return;
+    }
+    if (!result || result.canceled) return;
+    const assets = Array.isArray(result.assets) ? result.assets : [];
+    if (assets.length === 0) return;
+    if (typeof onPick !== "function") return;
+    if (multiple) {
+      onPick(assets.map(_asset));
+    } else {
+      onPick(_asset(assets[0]));
+    }
+  }, [disabled, type, multiple, onPick]);
+
+  return React.createElement(
+    Pressable,
+    {
+      onPress: handlePress,
+      disabled,
+      accessibilityRole: "button",
+      accessibilityLabel,
+      accessibilityState: { disabled },
+    },
+    React.createElement(View, { style: disabled ? { opacity: 0.5 } : undefined }, children),
+  );
+}
+
+FilePicker.isSupported = true;

package/dist/hooks.js

@@ -1364,6 +1364,82 @@ export function useFilestoreFiles(options) {
   return { files, loading, error, refetch };
 }
 
+/**
+ * sc-1378 — upload a file into the end-user's Filestore space. Returns
+ * `{ upload, uploading, error, lastUploaded }`. The widget passes the
+ * SPACE (`{ spaceType, folderId? }`); the hook resolves `owner_id` the
+ * same way the read hooks do (tenant for PROJECT, app user for PERSONAL)
+ * and posts a multipart FormData to `ctx.filestore.files.upload`.
+ *
+ * `upload(file, { folderId? })` accepts whatever the host's FormData
+ * implementation reads as a binary file part — on the web Player a
+ * browser `File`, on the Expo export the React Native shape
+ * `{ uri, name, type }` returned by `<FilePicker>` (which wraps
+ * `expo-document-picker` natively and a hidden DOM `<input type="file">`
+ * on web). FormData serialises both verbatim, so the same hook code path
+ * feeds the multipart on both platforms.
+ *
+ * A 404 from the backend means the destination folder denied a write —
+ * the widget should surface a friendly "you can't upload here" message
+ * rather than the raw error.
+ */
+export function useFilestoreUpload(options) {
+  const ctx = useWidgetContextOrThrow("useFilestoreUpload");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.upload !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreUpload: host did not inject a filestore client (ctx.filestore.files.upload)",
+    );
+  }
+  const { spaceType = "project", folderId: defaultFolderId = null } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastUploaded, setLastUploaded] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+
+  const upload = useCallback(
+    async (file, overrides) => {
+      if (!file) throw new Error("useFilestoreUpload: file is required");
+      if (!ownerId) {
+        const err = new Error("Sign in to upload");
+        setError(err);
+        throw err;
+      }
+      const folderId =
+        overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
+          ? overrides.folderId
+          : defaultFolderId;
+      const form = new FormData();
+      form.append("space_type", String(spaceType || "project").toUpperCase());
+      form.append("owner_id", ownerId);
+      if (folderId) form.append("folder_id", folderId);
+      form.append("file", file);
+      setUploading(true);
+      setError(null);
+      try {
+        const created = await filesRef.current.upload(form);
+        setLastUploaded(created || null);
+        setUploading(false);
+        return created;
+      } catch (err) {
+        setError(err);
+        setUploading(false);
+        throw err;
+      }
+    },
+    [ownerId, defaultFolderId, spaceType],
+  );
+
+  return { upload, uploading, error, lastUploaded };
+}
+
 /**
  * Browse the end-user's Filestore folders. Returns { folders, loading, error,
  * refetch }. Mirrors useFilestoreFiles for subfolder navigation: the widget
@@ -2477,3 +2553,124 @@ export function usePayments() {
   }, []);
   return { requestPayment, getPayment };
 }
+
+/* ============================================================================
+ * NOTIFICATIONS CLIENT — ctx.notifications (@colixsystems/notifications-client)
+ *
+ * send. Covers: useSendNotification.
+ * ==========================================================================*/
+
+/**
+ * sc-890 — structured error thrown by `useSendNotification().send`. Carries a
+ * stable `code` so widgets can branch without parsing message strings; mirrors
+ * the shape of `PaymentError` / `DirectoryError`.
+ *
+ * `code` is one of:
+ *   - "INVALID_TITLE" / "INVALID_BODY" / "INVALID_RECIPIENT" /
+ *     "INVALID_PAYLOAD" / "VALIDATION" — 400 (bad request)
+ *   - "AUTH_REQUIRED"        — 401 (no signed-in app user)
+ *   - "FORBIDDEN"            — 403 (widget lacks notifications.send:appUser)
+ *   - "RECIPIENT_NOT_FOUND"  — 404 (recipient not a member of the tenant)
+ *   - "RATE_LIMITED"         — 429 (too many sends)
+ *   - "INTERNAL"             — anything else (network, 5xx)
+ *
+ * The server's stable `code` (when volunteered in the error body) is preserved
+ * over the status-derived one.
+ */
+export class NotificationError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "NotificationError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toNotificationError(err) {
+  if (err instanceof NotificationError) return err;
+  // The injected notifications-client rejects with its own NotificationError
+  // subclass carrying { code, status }; the host facade may instead throw an
+  // axios-shaped error ({ response: { status, data: { code, error } } }). Read
+  // both shapes so the hook surfaces a stable code either way.
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : err && typeof err.status === "number"
+        ? err.status
+        : null;
+  const bodyCode =
+    (err && err.response && err.response.data && err.response.data.code) ||
+    (err && typeof err.code === "string" ? err.code : null);
+  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 === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "RECIPIENT_NOT_FOUND";
+  else if (status === 429) code = "RATE_LIMITED";
+  else if (status === 400) code = "VALIDATION";
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Send notification failed");
+  return new NotificationError(code, message, { cause: err });
+}
+
+/**
+ * sc-890 — send an in-app notification to one app user in the tenant. Returns
+ * `{ send, sending, error }`.
+ *
+ *   send({ recipient_user_id, title, body, link?, payload? })
+ *     → Promise<notification>. Body is snake_case VERBATIM (the wire contract,
+ *       REQ-GEN-09) — the SDK does NOT transform it. Resolves to the created
+ *       notification row (`{ id, tenant_id, user_id, title, body, link,
+ *       payload, read_at, created_at }`) and rejects with a `NotificationError`.
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls `send`
+ * from an event handler (a button press, a form submit). `sending` tracks an
+ * in-flight call and `error` holds the last `NotificationError` (cleared at the
+ * start of each `send`). Reads the injected
+ * `@colixsystems/notifications-client` at `ctx.notifications`.
+ *
+ * Requires the `notifications.send:appUser` scope in the manifest's
+ * `requestedScopes`. A widget that declares the scope but whose caller is not
+ * permitted receives a `NotificationError { code: "FORBIDDEN" }`.
+ */
+export function useSendNotification() {
+  const ctx = useWidgetContextOrThrow("useSendNotification");
+  if (!ctx.notifications || typeof ctx.notifications.send !== "function") {
+    throw new Error(
+      "useSendNotification: host did not inject a notifications client. The " +
+        "widget must declare the notifications.send:appUser scope and be " +
+        "installed in a workspace whose host supports notifications.",
+    );
+  }
+  // `ctx` is a fresh identity each host render — hold the send fn in a ref so
+  // the callback stays stable.
+  const sendRef = useRef(ctx.notifications.send);
+  sendRef.current = ctx.notifications.send;
+
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState(null);
+
+  const send = useCallback(async (body) => {
+    setSending(true);
+    setError(null);
+    try {
+      // body is snake_case verbatim ({ recipient_user_id, title, body, link?,
+      // payload? }) — passed straight through.
+      const row = await sendRef.current(body);
+      setSending(false);
+      return row;
+    } catch (err) {
+      const e = toNotificationError(err);
+      setError(e);
+      setSending(false);
+      throw e;
+    }
+  }, []);
+
+  return { send, sending, error };
+}

package/dist/index.d.ts

@@ -395,6 +395,16 @@ export interface PaymentsClient {
   getPayment(paymentId: string): Promise<PaymentResult>;
 }
 
+/**
+ * Structural shape of the injected `@colixsystems/notifications-client`
+ * (`ctx.notifications`, sc-890). Backs `useSendNotification`. `send` POSTs the
+ * body snake_case verbatim to `/notifications/send` and resolves to the created
+ * notification row.
+ */
+export interface NotificationsClient {
+  send(body: SendNotificationRequest): Promise<NotificationRow>;
+}
+
 export interface WidgetContext<TProps = unknown> {
   props: TProps;
   widget: { id: string; instanceId: string; version: string };
@@ -435,6 +445,8 @@ export interface WidgetContext<TProps = unknown> {
   assets: AssetsClient;
   /** Injected @colixsystems/payments-client. */
   payments: PaymentsClient;
+  /** Injected @colixsystems/notifications-client; backs useSendNotification. */
+  notifications: NotificationsClient;
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
   renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
@@ -612,6 +624,52 @@ export interface PaymentsApi {
  */
 export function usePayments(): PaymentsApi;
 
+/**
+ * Arguments for `useSendNotification().send(...)`. snake_case VERBATIM — this
+ * is the wire contract (REQ-GEN-09). `recipient_user_id`, `title`, and `body`
+ * are required; `link` and `payload` are optional.
+ */
+export interface SendNotificationRequest {
+  recipient_user_id: string;
+  title: string;
+  body: string;
+  link?: string | null;
+  payload?: Record<string, unknown> | null;
+}
+
+/**
+ * A notification row, snake_case verbatim as returned by the backend
+ * (`POST /notifications/send`, 201). The shape is open-ended; the well-known
+ * fields are listed.
+ */
+export interface NotificationRow {
+  id: string;
+  tenant_id?: string;
+  user_id?: string;
+  title?: string;
+  body?: string;
+  link?: string | null;
+  payload?: Record<string, unknown> | null;
+  read_at?: string | null;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export interface SendNotificationApi {
+  send(body: SendNotificationRequest): Promise<NotificationRow>;
+  sending: boolean;
+  error: NotificationError | null;
+}
+
+/**
+ * sc-890 — send an in-app notification to one app user in the tenant. Returns
+ * `{ send, sending, error }`. The hook is imperative — `send` never fires on
+ * mount; the widget calls it from an event handler. Rejects with a
+ * `NotificationError`. Requires the `notifications.send:appUser` scope in the
+ * widget manifest.
+ */
+export function useSendNotification(): SendNotificationApi;
+
 export function useTheme(): ThemeTokens;
 
 /**
@@ -905,6 +963,30 @@ export class DirectoryError extends Error {
   );
 }
 
+/**
+ * sc-890 — error class thrown by `useSendNotification().send`. The `code` is a
+ * stable categorisation widgets can branch on.
+ */
+export class NotificationError extends Error {
+  code:
+    | "INVALID_TITLE"
+    | "INVALID_BODY"
+    | "INVALID_RECIPIENT"
+    | "INVALID_PAYLOAD"
+    | "VALIDATION"
+    | "AUTH_REQUIRED"
+    | "FORBIDDEN"
+    | "RECIPIENT_NOT_FOUND"
+    | "RATE_LIMITED"
+    | "INTERNAL"
+    | string;
+  constructor(
+    code: NotificationError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 // --------------------------------------------------------------- useUsers
 //
 // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.

package/dist/index.js

@@ -9,6 +9,7 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  NotificationError,
   DirectoryError,
   PermissionError,
   useDatastoreQuery,
@@ -17,6 +18,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreUpload,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
@@ -31,6 +33,7 @@ export {
   useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
+  useSendNotification,
   useTheme,
   useWidgetStyle,
   useI18n,
@@ -61,6 +64,7 @@ export {
   Linking,
   Icon,
   DateTimePicker,
+  FilePicker,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -9,6 +9,7 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  NotificationError,
   DirectoryError,
   PermissionError,
   useDatastoreQuery,
@@ -17,6 +18,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreUpload,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
@@ -29,6 +31,7 @@ export {
   useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
+  useSendNotification,
   useTheme,
   useWidgetStyle,
   useI18n,
@@ -57,6 +60,7 @@ export {
   Linking,
   Icon,
   DateTimePicker,
+  FilePicker,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/linter.cjs

@@ -240,11 +240,31 @@ function _classifySpecifier(spec) {
   return "bare";
 }
 
+// The package root of a bare specifier: `leaflet/dist/leaflet.css` → "leaflet",
+// `@scope/pkg/sub` → "@scope/pkg". A subpath/asset import of a vetted package
+// belongs to that package, so the root carries the vetting + platforms.
+// Mirror of linter.js.
+function _packageRoot(spec) {
+  const parts = spec.split("/");
+  // A traversal / empty segment is a non-canonical specifier — never resolve it
+  // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
+  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
 function _importRules(source, manifest) {
   const findings = [];
   const allowed = new Map(
     CONTRACT.vettedImports.map((v) => [v.specifier, v]),
   );
+  // Core-infra specifiers (react-dom, react-dom/client) are host-shimmed on
+  // both runtimes but kept off the author-facing vetted list — accept them so
+  // a bundle's transitive react-dom import isn't flagged import-not-vetted.
+  for (const spec of CONTRACT.allowedBareImports) {
+    if (!allowed.has(spec)) {
+      allowed.set(spec, { specifier: spec, platforms: ["web", "native"] });
+    }
+  }
   const declaredPlatforms =
     manifest &&
     Array.isArray(manifest.supportedPlatforms) &&
@@ -279,7 +299,7 @@ function _importRules(source, manifest) {
         });
         continue;
       }
-      const entry = allowed.get(spec);
+      const entry = allowed.get(spec) || allowed.get(_packageRoot(spec));
       if (!entry) {
         findings.push({
           rule: "import-not-vetted",
@@ -574,6 +594,20 @@ function _lucideIconRules(source) {
   return findings;
 }
 
+// Narrow a split-impl widget's manifest to the platform a single bundle file
+// ships to, so `import-platform-mismatch` lints each file against what it
+// actually targets. Mirror of linter.js.
+function narrowManifestForFile(manifest, filename) {
+  if (!manifest || typeof manifest !== "object") return manifest;
+  if (filename === "widget.web.jsx") {
+    return { ...manifest, supportedPlatforms: ["web"] };
+  }
+  if (filename === "widget.native.jsx") {
+    return { ...manifest, supportedPlatforms: ["native"] };
+  }
+  return manifest;
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -630,4 +664,4 @@ function lintSource(source, options) {
   return { ok: !hasErrors, findings };
 }
 
-module.exports = { lintSource, bannedIdentifiers };
+module.exports = { lintSource, bannedIdentifiers, narrowManifestForFile };

package/dist/linter.js

@@ -266,9 +266,29 @@ function _classifySpecifier(spec) {
   return "bare";
 }
 
+// The package root of a bare specifier: `leaflet/dist/leaflet.css` → "leaflet",
+// `@scope/pkg/sub` → "@scope/pkg". A subpath/asset import of a vetted package
+// (its CSS, a marker PNG, react-dom/client) belongs to that package, so the
+// root carries the vetting + platform metadata.
+function _packageRoot(spec) {
+  const parts = spec.split("/");
+  // A traversal / empty segment is a non-canonical specifier — never resolve it
+  // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
+  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
 function _importRules(source, manifest) {
   const findings = [];
   const allowed = new Map(CONTRACT.vettedImports.map((v) => [v.specifier, v]));
+  // Core-infra specifiers (react-dom, react-dom/client) are host-shimmed on
+  // both runtimes but kept off the author-facing vetted list — accept them so
+  // a bundle's transitive react-dom import isn't flagged import-not-vetted.
+  for (const spec of CONTRACT.allowedBareImports) {
+    if (!allowed.has(spec)) {
+      allowed.set(spec, { specifier: spec, platforms: ["web", "native"] });
+    }
+  }
   // Track declared `supportedPlatforms` so a widget that claims "web only"
   // doesn't import a native-only package (and vice versa) without the
   // marketplace listing being honest about which platforms ship.
@@ -307,8 +327,9 @@ function _importRules(source, manifest) {
         });
         continue;
       }
-      // Bare specifier — validate against the vetted list.
-      const entry = allowed.get(spec);
+      // Bare specifier — validate against the vetted list. A subpath/asset
+      // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
+      const entry = allowed.get(spec) || allowed.get(_packageRoot(spec));
       if (!entry) {
         findings.push({
           rule: "import-not-vetted",
@@ -662,6 +683,24 @@ function _lucideIconRules(source) {
   return findings;
 }
 
+/**
+ * Narrow a split-impl widget's manifest to the platform a single bundle file
+ * ships to, so `import-platform-mismatch` lints each file against what it
+ * actually targets. `widget.web.jsx` → ["web"], `widget.native.jsx` →
+ * ["native"], cross-platform `widget.jsx` keeps the manifest's union claim.
+ * Returns a shallow clone; the original is untouched.
+ */
+export function narrowManifestForFile(manifest, filename) {
+  if (!manifest || typeof manifest !== "object") return manifest;
+  if (filename === "widget.web.jsx") {
+    return { ...manifest, supportedPlatforms: ["web"] };
+  }
+  if (filename === "widget.native.jsx") {
+    return { ...manifest, supportedPlatforms: ["native"] };
+  }
+  return manifest;
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {

package/dist/primitives.js

@@ -70,3 +70,9 @@ export { Icon } from "./icon.js";
 // react-native-web mapping. Both implementations honour the same
 // ISO 8601 value / onChange contract.
 export { DateTimePicker } from "./datetimepicker.js";
+// sc-1378 — `<FilePicker>` (web). Wraps a hidden DOM `<input type="file">`
+// because react-native-web has no native equivalent. The native build's
+// counterpart (./filepicker.native.js) degrades to a disabled trigger until
+// a vetted expo-document-picker pin lands. `isSupported` is a static
+// boolean widgets branch on to hide the trigger on native.
+export { FilePicker } from "./filepicker.js";

package/dist/primitives.native.js

@@ -31,3 +31,8 @@ export { Icon } from "./icon.js";
 // `./datetimepicker.js`. Both files honour the same ISO 8601 value /
 // onChange contract.
 export { DateTimePicker } from "./datetimepicker.native.js";
+// sc-1378 — `<FilePicker>` (native). Web counterpart (./filepicker.js)
+// wraps a hidden DOM `<input type="file">`; native has no portable
+// equivalent yet, so this build renders a disabled trigger and exposes
+// `FilePicker.isSupported = false` for widgets to branch on.
+export { FilePicker } from "./filepicker.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.45.1",
+  "version": "0.48.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
   },
   "engines": {
     "node": ">=18"