@colixsystems/widget-sdk 0.45.0 → 0.47.0

package/README.md

@@ -49,7 +49,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.45.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.47.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.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
+
+**Fix `lucide-unknown-icon` false positive across adjacent imports (sc-1373).** The rule's import regex matched the brace block lazily (`[\s\S]*?`), so when another braced import preceded the lucide one — e.g. `import { View, Text, Pressable } from "react-native"` then `import { Sparkles } from "lucide-react-native"` — the capture spanned both and validated the `react-native` names (`Pressable`, …) as lucide icons, blocking a near-universal widget pattern. The capture is now `[^}]*`, which cannot cross a `}` into a neighbouring import. Fix-only; the rule's intent and the committed name set are unchanged.
 
 ### What's new in 0.45.0
 
@@ -147,6 +164,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).

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? })",
@@ -710,6 +731,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 = [
@@ -1169,6 +1203,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 +1722,29 @@ 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.
+  version: "1.34.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? })",
@@ -710,6 +731,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 = [
@@ -1169,6 +1203,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 +1722,29 @@ 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.
+  version: "1.34.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

package/dist/index.js

@@ -17,6 +17,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreUpload,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
@@ -61,6 +62,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

@@ -17,6 +17,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreUpload,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
@@ -57,6 +58,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",
@@ -523,8 +543,11 @@ function _manifestActionRules(manifest) {
 // so the agent's repair loop fixes them. The valid set is committed data
 // (lucideIconNames.cjs) because the linter runs where lucide is not installed.
 const LUCIDE_NAME_SET = new Set(LUCIDE_ICON_NAMES);
+// `[^}]*` (not `[\s\S]*?`) so the brace capture can never cross a `}` into a
+// neighbouring import — otherwise a preceding `import { View, Pressable } from
+// "react-native"` is swallowed and its names get validated as lucide icons.
 const LUCIDE_IMPORT_RE =
-  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([\s\S]*?)\}\s*from\s*["']lucide-react-native["']/g;
+  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([^}]*)\}\s*from\s*["']lucide-react-native["']/g;
 
 // lucide re-exports each base icon as `<Name>`, `<Name>Icon`, and `Lucide<Name>`;
 // the committed set holds only the base names, so normalise the alias forms
@@ -571,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 {
@@ -627,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",
@@ -611,8 +632,11 @@ function _manifestActionRules(manifest) {
 // so the agent's repair loop fixes them. The valid set is committed data
 // (lucideIconNames.js) because the linter runs where lucide is not installed.
 const LUCIDE_NAME_SET = new Set(LUCIDE_ICON_NAMES);
+// `[^}]*` (not `[\s\S]*?`) so the brace capture can never cross a `}` into a
+// neighbouring import — otherwise a preceding `import { View, Pressable } from
+// "react-native"` is swallowed and its names get validated as lucide icons.
 const LUCIDE_IMPORT_RE =
-  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([\s\S]*?)\}\s*from\s*["']lucide-react-native["']/g;
+  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([^}]*)\}\s*from\s*["']lucide-react-native["']/g;
 
 // lucide re-exports each base icon as `<Name>`, `<Name>Icon`, and `Lucide<Name>`;
 // the committed set holds only the base names, so normalise the alias forms
@@ -659,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.0",
+  "version": "0.47.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"