@colixsystems/widget-sdk 0.38.0 → 0.39.0

package/README.md

@@ -8,7 +8,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | ----------- | ------- | -------- |
 | `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` |
 | `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` |
-| `ctx.files` | `@colixsystems/files-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useFile()` resolves |
+| `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` resolves |
 | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
 
 **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.
@@ -32,7 +32,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
-| **FILES** (`ctx.files`) | `useFile(id)` | `{ url, file, loading, error, refetch }` | `ctx.files.get` — no scope |
+| **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (edits also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
@@ -47,7 +47,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.38.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.39.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.39.0
+
+**Web entry is bundled, not just transpiled (sc-1064).** A first-party / dev widget's WEB entry (`widget.web.jsx`, or the cross-platform `widget.jsx`) is now esbuild-**bundled** by both `appstudio-widget dev` and the publish packer, so vetted web-only deps the host doesn't shim — `react-leaflet`, `leaflet`, its CSS, and its marker PNG assets — are inlined instead of left as bare imports the Studio loader can't resolve. The native entry (`widget.native.jsx`) is still Sucrase transpile-only (Metro bundles its native deps in the export).
+
+- **New `./dev-shims` exports**: `hostExternalSpecifiers()` — the canonical, single-source list of bare specifiers the runtime web host resolves (react family, `react-dom` + `react-dom/client`, `@colixsystems/widget-sdk`, and the vetted shimmed packages), i.e. exactly what the bundler externalises; and `REACT_DOM_NAMED_EXPORTS` — the react-dom named surface (`createPortal`, …) the host shim re-exports so `react-leaflet`'s portal-based Popup/Pane share the host's single react-dom instance.
+- **New optional dependency `esbuild`** — lazily imported only on the `dev`/pack bundle paths (same pattern as the optional `sucrase`); the published runtime never forces it.
 
 ### What's new in 0.38.0
 
@@ -185,10 +192,10 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 
 **The data layer splits into four injected domain clients; the SDK becomes core-only.**
 
-- **The SDK no longer owns any data facade.** The bespoke per-hook facades that used to live on `WidgetContext` (`ctx.datastore` as an opaque host object, `ctx.directory.listUsers`, `ctx.users`, `ctx.groups`, `ctx.recordPermissions`, `ctx.files.get`) are replaced by four host-instantiated, host-injected domain clients: `ctx.datastore` (`@colixsystems/datastore-client`), `ctx.directory` (`@colixsystems/directory-client`), `ctx.files` (`@colixsystems/files-client`, flattened), `ctx.payments` (`@colixsystems/payments-client`). The SDK imports none of them and ships no HTTP.
+- **The SDK no longer owns any data facade.** The bespoke per-hook facades that used to live on `WidgetContext` (`ctx.datastore` as an opaque host object, `ctx.directory.listUsers`, `ctx.users`, `ctx.groups`, `ctx.recordPermissions`, `ctx.assets.get`) are replaced by four host-instantiated, host-injected domain clients: `ctx.datastore` (`@colixsystems/datastore-client`), `ctx.directory` (`@colixsystems/directory-client`), `ctx.assets` (`@colixsystems/assets-client`, flattened), `ctx.payments` (`@colixsystems/payments-client`). The SDK imports none of them and ships no HTTP.
 - **`ctx.recordPermissions`, `ctx.users`, `ctx.groups` are removed.** Per-record permission management moved under `ctx.datastore.records(tableId).permissions(recordId)`; user / group administration moved under `ctx.directory.users` / `ctx.directory.groups`. The hooks (`useRecordPermissions`, `useUsers`, `useGroups`) keep the same names and signatures — only the client slice they read changed.
 - **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Hook return rows and `useUser()` fields are therefore snake_case (`display_name`, `group_ids`, `is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`).
-- **Companion package versions:** `datastore-client 0.5.0`, `files-client 0.3.0`, `directory-client 0.1.0`, `payments-client 0.1.0`.
+- **Companion package versions:** `datastore-client 0.5.0`, `assets-client 0.4.0`, `directory-client 0.1.0`, `payments-client 0.1.0`.
 - **`CONTRACT.version` → `1.9.0`.** Breaking for `WidgetContext` consumers (removed slices, renamed wire fields); the hook export surface is unchanged.
 
 ### What was in 0.18.0
@@ -227,7 +234,7 @@ The tenant's **Theme Settings** now flow all the way into `useTheme()`.
 The "split-implementation + vetted package list" pivot.
 
 - **`CONTRACT.vettedImports` (new).** A curated allowlist of bare specifiers a widget may import — `react`, `@colixsystems/widget-sdk`, `react-native`, `axios`, `date-fns`, `react-native-svg`, `lucide-react-native`, `react-native-maps`, `leaflet`, `react-leaflet`, `expo-av`, `@react-native-community/datetimepicker`, `expo-clipboard`, `expo-haptics`. Each entry carries `platforms` (one or both of `"web"` / `"native"`) and a `category` so the linter and the marketplace listing can render honest platform badges. `CONTRACT.allowedBareImports` (the existing field) is now derived from `vettedImports` and stays a plain `string[]` for back-compat.
-- **`fetch` and `XMLHttpRequest` come off `CONTRACT.bannedApis`.** Widgets may call third-party APIs directly. Calls to the host's own `/api/*` surface will 401 because the JWT token is never shared with widget code; the linter emits a soft `no-host-api-url` warning when it sees host-URL substrings so authors learn the rule statically. Use SDK hooks (`useDatastoreQuery`, `useUsers`, `useFile`, …) for workspace data; use `axios` / `fetch` for third-party APIs.
+- **`fetch` and `XMLHttpRequest` come off `CONTRACT.bannedApis`.** Widgets may call third-party APIs directly. Calls to the host's own `/api/*` surface will 401 because the JWT token is never shared with widget code; the linter emits a soft `no-host-api-url` warning when it sees host-URL substrings so authors learn the rule statically. Use SDK hooks (`useDatastoreQuery`, `useUsers`, `useAsset`, …) for workspace data; use `axios` / `fetch` for third-party APIs.
 - **`import-not-vetted` linter rule (new).** Every bare `import` specifier is validated against `CONTRACT.vettedImports`. Relative imports inside the bundle (`./shared.js`) are allowed so split-impl widgets can share helpers; `../` and absolute paths are rejected.
 - **`import-platform-mismatch` linter rule (new).** A single-source widget that imports a native-only package while `manifest.supportedPlatforms` includes `"web"` fails the lint. The author either drops the platform from the manifest OR ships a `widget.web.jsx` + `widget.native.jsx` pair where the platform-specific import lives in the file that targets its platform.
 - **Lint findings carry `severity`.** `"error"` (default) blocks publish; `"warning"` (currently only `no-host-api-url`) surfaces to reviewers without blocking. The `lintSource(...)` return shape stays `{ ok, findings }` — `ok` is true iff no error-severity findings exist.
@@ -257,7 +264,7 @@ The "split-implementation + vetted package list" pivot.
 ### What's new in 0.12.0
 
 - **`useDatastoreRecord(tableId, recordId)` is wired.** Returns `{ data, loading, error, refetch }` for a single record fetched through the host's `records(table).get(id)`. Sister to `useDatastoreQuery`; mirrors its ref discipline so `refetch` stays a stable callback identity. A 404 surfaces as `DatastoreError.code === "NOT_FOUND"`. Additive.
-- **`useFile(fileId)` is wired** + new `WidgetContext.files` slice. Returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL the widget can drop straight into `<Image source>`. Backed by a new `files.get(fileId)` host facade (web: `widgetHostFiles` through `api/client`; native: `hostFiles` in the export's `widgetHost.js`). Additive.
+- **`useAsset(fileId)` is wired** + new `WidgetContext.assets` slice. Returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL the widget can drop straight into `<Image source>`. Backed by a new `files.get(fileId)` host facade (web: `widgetHostFiles` through `api/client`; native: `hostFiles` in the export's `widgetHost.js`). Additive.
 
 ### What's new in 0.11.0
 
@@ -331,7 +338,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`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, 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. `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `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).
 - `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`). The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
@@ -347,7 +354,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme.
-- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useFile()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
+- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 
 **Honest ceilings:** the styling surface is React Native style objects, not full CSS. There are no per-widget gradients, no custom CSS keyframe animations or `transition` strings, and shadows are limited to the five elevation presets (`none / sm / md / lg / xl`). Aim for clean, confident, professional polish within those bounds.

package/dist/cli.js

@@ -14,7 +14,10 @@ function usage() {
   stderr.write(
     "Usage:\n" +
       "  appstudio-widget lint <path>\n" +
-      "  appstudio-widget dev <entry.jsx> [--port <n>] [--manifest <path>]\n",
+      "  appstudio-widget dev <entry.jsx|widget-dir> [--port <n>] [--manifest <path>]\n" +
+      "    A directory containing widget.json runs in multi-file mode " +
+      "(REQ-WSDK-DEVKIT v2): the dev server reads the canonical web entry, " +
+      "serves siblings under /file/<rel>, and watches the whole tree.\n",
   );
   exit(2);
 }
@@ -93,14 +96,19 @@ async function runDev(rest) {
   }
 
   stdout.write(
-    `\nappstudio-widget dev — serving ${resolve(entry)}\n` +
+    `\nappstudio-widget dev — serving ${resolve(entry)} ` +
+      `(${handle.directoryMode ? "directory" : "single-file"} mode)\n` +
       `  bundle:   ${handle.url}/widget.mjs\n` +
       `  manifest: ${handle.url}/manifest.json\n` +
       `  reload:   ${handle.url}/__dev/events (SSE)\n` +
+      (handle.directoryMode
+        ? `  files:    ${handle.url}/file/<relpath>\n  shims:    ${handle.url}/shim/<slug>\n`
+        : "") +
       (handle.manifestId ? `  id:       ${handle.manifestId}\n` : "") +
       `\nIn the Studio Builder (dev mode), open the "Dev widgets" panel and add:\n` +
       `  ${handle.url}\n` +
-      `Edits to the entry hot-reload the widget on the canvas. Ctrl+C to stop.\n\n`,
+      `Edits to ${handle.directoryMode ? "any file in the widget directory" : "the entry"} ` +
+      `hot-reload the widget on the canvas. Ctrl+C to stop.\n\n`,
   );
 
   const shutdown = () => {

package/dist/contract.cjs

@@ -143,16 +143,16 @@ const HOOKS = [
     scopes: ["datastore.read:<table>"],
   },
   {
-    name: "useFile",
-    signature: "useFile(fileId)",
+    name: "useAsset",
+    signature: "useAsset(assetId)",
     returnShape: {
       url: "string | null",
-      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      asset: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: ["files.get"],
+    requiredContextSlice: ["assets.get"],
     scopes: null,
   },
   {
@@ -900,11 +900,11 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { users: "object", groups: "object", bankid: "object" },
   },
-  files: {
+  assets: {
     description:
-      "Injected @colixsystems/files-client instance, FLATTENED so file ops are top-level. " +
-      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData), folders: { list, create }, shares: { list, create, remove } }. " +
-      "Backs useFile(); the returned file already carries an absolute url the widget can drop into an <Image source>.",
+      "Injected @colixsystems/assets-client instance, FLATTENED so asset ops are top-level. " +
+      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData) }. " +
+      "Backs useAsset(); the returned asset already carries an absolute url the widget can drop into an <Image source>.",
     required: true,
     fields: { get: "function" },
   },
@@ -1245,12 +1245,27 @@ const VETTED_IMPORTS = [
   },
 ];
 
+// sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
+// but that are NOT author-facing "vetted widget libraries". `react-dom` and
+// `react-dom/client` are transitive — `react-leaflet`'s Popup/Pane render
+// through `createPortal` from `react-dom`, so the host externalises + shims
+// them — but widget authors should never be encouraged to import react-dom
+// directly (unlike axios/date-fns/leaflet/…). They belong on
+// `allowedBareImports` (so the loader's shim⊆vetted guard treats them as
+// vetted) WITHOUT bloating the rich `VETTED_IMPORTS` reference the AI prompt /
+// Developer guide enumerate — the SAME treatment `react/jsx-runtime` gets, but
+// kept out of the author-facing list. Mirror of contract.js.
+const CORE_INFRA_BARE_IMPORTS = ["react-dom", "react-dom/client"];
+
 // Back-compat shape — every existing consumer (widgetLoader, the static
 // analyzer's DEPENDENCY_ALLOWLIST, the AI prompt's "Allowed imports" line)
 // reads a plain `string[]` from `CONTRACT.allowedBareImports`. Derive it
-// from the rich list so a single edit in VETTED_IMPORTS propagates to
-// every surface.
-const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
+// from the rich list (plus the CORE infra specifiers above) so a single edit
+// in VETTED_IMPORTS propagates to every surface.
+const ALLOWED_BARE_IMPORTS = [
+  ...VETTED_IMPORTS.map((v) => v.specifier),
+  ...CORE_INFRA_BARE_IMPORTS,
+];
 
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
@@ -1390,7 +1405,7 @@ const CONTRACT = deepFreeze({
   //    records(t).permissions(r) replaces the deleted ctx.recordPermissions),
   //    ctx.directory is a @colixsystems/directory-client (users/groups
   //    namespaces replace the deleted ctx.users / ctx.groups; list returns
-  //    envelopes), ctx.files is a flattened @colixsystems/files-client,
+  //    envelopes), ctx.assets is a flattened @colixsystems/assets-client,
   //    ctx.payments is a @colixsystems/payments-client. All rows/bodies are
   //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
   //    SDK stays duck-typed — it imports none of the four data SDKs. Minor

package/dist/contract.js

@@ -143,16 +143,16 @@ const HOOKS = [
     scopes: ["datastore.read:<table>"],
   },
   {
-    name: "useFile",
-    signature: "useFile(fileId)",
+    name: "useAsset",
+    signature: "useAsset(assetId)",
     returnShape: {
       url: "string | null",
-      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      asset: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: ["files.get"],
+    requiredContextSlice: ["assets.get"],
     scopes: null,
   },
   {
@@ -900,11 +900,11 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { users: "object", groups: "object", bankid: "object" },
   },
-  files: {
+  assets: {
     description:
-      "Injected @colixsystems/files-client instance, FLATTENED so file ops are top-level. " +
-      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData), folders: { list, create }, shares: { list, create, remove } }. " +
-      "Backs useFile(); the returned file already carries an absolute url the widget can drop into an <Image source>.",
+      "Injected @colixsystems/assets-client instance, FLATTENED so asset ops are top-level. " +
+      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData) }. " +
+      "Backs useAsset(); the returned asset already carries an absolute url the widget can drop into an <Image source>.",
     required: true,
     fields: { get: "function" },
   },
@@ -1245,12 +1245,27 @@ const VETTED_IMPORTS = [
   },
 ];
 
+// sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
+// but that are NOT author-facing "vetted widget libraries". `react-dom` and
+// `react-dom/client` are transitive — `react-leaflet`'s Popup/Pane render
+// through `createPortal` from `react-dom`, so the host externalises + shims
+// them — but widget authors should never be encouraged to import react-dom
+// directly (unlike axios/date-fns/leaflet/…). They belong on
+// `allowedBareImports` (so the loader's shim⊆vetted guard treats them as
+// vetted) WITHOUT bloating the rich `VETTED_IMPORTS` reference the AI prompt /
+// Developer guide enumerate — the SAME treatment `react/jsx-runtime` gets, but
+// kept out of the author-facing list. Mirror of contract.cjs.
+const CORE_INFRA_BARE_IMPORTS = ["react-dom", "react-dom/client"];
+
 // Back-compat shape — every existing consumer (widgetLoader, the static
 // analyzer's DEPENDENCY_ALLOWLIST, the AI prompt's "Allowed imports" line)
 // reads a plain `string[]` from `CONTRACT.allowedBareImports`. Derive it
-// from the rich list so a single edit in VETTED_IMPORTS propagates to
-// every surface.
-const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
+// from the rich list (plus the CORE infra specifiers above) so a single edit
+// in VETTED_IMPORTS propagates to every surface.
+const ALLOWED_BARE_IMPORTS = [
+  ...VETTED_IMPORTS.map((v) => v.specifier),
+  ...CORE_INFRA_BARE_IMPORTS,
+];
 
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
@@ -1390,7 +1405,7 @@ const CONTRACT = deepFreeze({
   //    records(t).permissions(r) replaces the deleted ctx.recordPermissions),
   //    ctx.directory is a @colixsystems/directory-client (users/groups
   //    namespaces replace the deleted ctx.users / ctx.groups; list returns
-  //    envelopes), ctx.files is a flattened @colixsystems/files-client,
+  //    envelopes), ctx.assets is a flattened @colixsystems/assets-client,
   //    ctx.payments is a @colixsystems/payments-client. All rows/bodies are
   //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
   //    SDK stays duck-typed — it imports none of the four data SDKs. Minor

package/dist/dev-shims.js

@@ -0,0 +1,255 @@
+// REQ-WSDK-DEVKIT v2 (sc-1027): shared shim-source generator used by BOTH
+// `widgetLoader.buildShims()` (Studio runtime, blob URLs) AND the dev server's
+// `/shim/<spec>` endpoint (when serving siblings of a multi-file widget).
+//
+// Both code paths produce ESM that re-exports the matching key out of
+// `globalThis.__appstudioWidgetHost__` — populated by the Studio's `buildShims`
+// before any widget bundle is evaluated. Keeping the shim sources in one place
+// means a vetted-package addition lands once and both paths see it.
+//
+// Pure JS, no runtime deps — safe to import from the SDK dev server (Node)
+// and from the Studio loader (browser).
+//
+// LIMITATION (v1): for SIBLING files served by the dev server's `/file/<rel>`
+// endpoint, only the specifiers with a statically-known named-export list are
+// shimmable through `/shim/<spec>`: `react`, `react/jsx-runtime`,
+// `react/jsx-dev-runtime`, and `@colixsystems/widget-sdk`. Any other vetted
+// package (`lucide-react-native`, `react-native-svg`, `date-fns`, ...) must be
+// imported from the widget's ENTRY (where the Studio's blob-shim path
+// runtime-enumerates the host's namespace). Imports of these packages from a
+// sibling .jsx file return `422` from the dev server with a clear message.
+
+// React named exports the Studio re-exposes through the shim. Mirrors the
+// browser's `react` named-export surface. Adding a new hook in a React minor
+// release means appending it here.
+export const REACT_NAMED_EXPORTS = [
+  "Children",
+  "Component",
+  "Fragment",
+  "Profiler",
+  "PureComponent",
+  "StrictMode",
+  "Suspense",
+  "cloneElement",
+  "createContext",
+  "createElement",
+  "createFactory",
+  "createRef",
+  "forwardRef",
+  "isValidElement",
+  "lazy",
+  "memo",
+  "startTransition",
+  "useCallback",
+  "useContext",
+  "useDebugValue",
+  "useDeferredValue",
+  "useEffect",
+  "useId",
+  "useImperativeHandle",
+  "useInsertionEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useReducer",
+  "useRef",
+  "useState",
+  "useSyncExternalStore",
+  "useTransition",
+  "version",
+];
+
+// React's automatic JSX runtime: jsx / jsxs / Fragment, plus the dev variant.
+export const REACT_JSX_RUNTIME_EXPORTS = ["jsx", "jsxs", "Fragment", "jsxDEV"];
+
+// REQ-WSDK-PLATFORM bundle (sc-1064): the canonical list of bare specifiers the
+// runtime web host RESOLVES for a loaded widget — i.e. the ones the Studio's
+// `widgetLoader.buildShims()` re-exports from `globalThis.__appstudioWidgetHost__`
+// rather than letting a bundle inline a second copy. The web-entry bundler
+// (`webbundle.bundleWebEntry`, used by both the publish packer and the dev
+// server) marks EXACTLY these `external`, so everything else the entry imports
+// (`react-leaflet`, `leaflet`, CSS, PNG assets, …) gets inlined.
+//
+// This is the SINGLE source of truth (CLAUDE.md §3). It MUST stay in lockstep
+// with the frontend's `widgetLoader._hostVettedModules()` + the core React/SDK
+// shims it builds. Two backstops enforce the equality: (1) this list's
+// contents are pinned by the SDK-side importable test
+// (`packages/widget-sdk/src/__tests__/host-externals.test.js`), and (2) the
+// loader's own module-load guard in `frontend/src/services/widgetLoader.js`
+// throws at import time if `hostShimmedSpecifiers()` drifts from
+// `hostExternalSpecifiers()` — the loader's shimmed set can't be asserted from
+// a Node test (it imports `react-dom` etc.), so that equality is enforced by
+// the load-time guard rather than a separate frontend test.
+//
+// Why each entry is host-resolved (NOT bundled):
+//   * `react`, `react/jsx-runtime`, `react/jsx-dev-runtime` — the widget MUST
+//     share the host's ONE React instance (hooks + context); a bundled second
+//     React breaks both.
+//   * `react-dom`, `react-dom/client` — `react-leaflet`'s Popup/Pane render
+//     through `createPortal` from `react-dom`. A bundled second react-dom
+//     paired with the host's external React is a mismatched renderer and
+//     crashes. The Studio is a React-DOM app, so it shims its own react-dom.
+//     On React 19 the two specifiers expose DIFFERENT surfaces — createPortal /
+//     flushSync / version live on `react-dom`, createRoot / hydrateRoot on
+//     `react-dom/client` — so the loader stashes + shims each from its own real
+//     host namespace (sc-1064).
+//   * `@colixsystems/widget-sdk` — the widget must route hooks through the SAME
+//     SDK instance the host built (datastore/theme/navigation live there).
+//   * `lucide-react-native`, `react-native-svg`, `date-fns` — vetted packages
+//     the host already bundles + shims (`_hostVettedModules`); sharing the
+//     host copy keeps icons/SVG on the host's react-native-web instance.
+const HOST_EXTERNAL_SPECIFIERS = [
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/client",
+  "@colixsystems/widget-sdk",
+  "lucide-react-native",
+  "react-native-svg",
+  "date-fns",
+];
+
+/**
+ * The canonical "host-resolved at runtime" bare-specifier set — the externals
+ * the web-entry bundler must NOT inline. Returns a fresh array each call so a
+ * caller can't mutate the source of truth.
+ *
+ * @returns {string[]}
+ */
+export function hostExternalSpecifiers() {
+  return [...HOST_EXTERNAL_SPECIFIERS];
+}
+
+function reactShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.React";
+  const named = REACT_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function reactJsxRuntimeShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactJSXRuntime";
+  const named = REACT_JSX_RUNTIME_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return named;
+}
+
+// react-dom named exports a bundled widget might reach through the host shim.
+// `react-leaflet`'s Popup/Pane/SVGOverlay use `createPortal`; `flushSync`
+// rounds out the surface react-leaflet may touch. These are the names that
+// genuinely EXIST on the `react-dom` namespace in React 19 — `createRoot` /
+// `hydrateRoot` moved to `react-dom/client`, and `render` /
+// `unmountComponentAtNode` / `findDOMNode` were removed entirely, so listing
+// them here would re-export `undefined` (sc-1064). `version` is always present.
+// Mirrors REACT_NAMED_EXPORTS' hand-list-of-the-named-surface approach (a blob
+// module can't `export *`).
+export const REACT_DOM_NAMED_EXPORTS = ["createPortal", "flushSync", "version"];
+
+// React 19: `createRoot` / `hydrateRoot` live ONLY on `react-dom/client`. The
+// `react-dom/client` shim sources these from the host's REAL `react-dom/client`
+// namespace (stashed as `ReactDOMClient`), NOT from the `react-dom` namespace
+// where they are `undefined` on v19. `version` is present on both.
+export const REACT_DOM_CLIENT_NAMED_EXPORTS = [
+  "createRoot",
+  "hydrateRoot",
+  "version",
+];
+
+function reactDomShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactDOM";
+  const named = REACT_DOM_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function reactDomClientShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactDOMClient";
+  const named = REACT_DOM_CLIENT_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function sdkShimSrc(sdkNamedExports) {
+  const host = "globalThis.__appstudioWidgetHost__.sdk";
+  const names = (Array.isArray(sdkNamedExports) ? sdkNamedExports : []).filter(
+    (n) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(n),
+  );
+  const named = names
+    .map((n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`)
+    .join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+/**
+ * Build a shim ESM source for a vetted bare specifier with a statically-known
+ * named-export shape. Returns null when the specifier isn't shimmable from a
+ * sibling file — the caller surfaces this as a clear error.
+ *
+ * @param {string} specifier  bare import specifier (e.g. "react")
+ * @param {object} [opts]
+ * @param {string[]} [opts.sdkExports]  named-export list for
+ *   "@colixsystems/widget-sdk" — caller passes this since the dev server
+ *   doesn't statically load the SDK.
+ * @returns {string | null}
+ */
+export function getShimSource(specifier, opts = {}) {
+  switch (specifier) {
+    case "react":
+      return reactShimSrc();
+    case "react/jsx-runtime":
+    case "react/jsx-dev-runtime":
+      return reactJsxRuntimeShimSrc();
+    case "react-dom":
+      return reactDomShimSrc();
+    case "react-dom/client":
+      return reactDomClientShimSrc();
+    case "@colixsystems/widget-sdk":
+      return sdkShimSrc(opts.sdkExports);
+    default:
+      return null;
+  }
+}
+
+/**
+ * The set of bare specifiers a SIBLING file may import — i.e. the keys
+ * `getShimSource` recognises. Anything outside this set must move to the
+ * entry, where the Studio's runtime blob-shim path enumerates the full
+ * `CONTRACT.allowedBareImports` surface (REQ-WSDK-PLATFORM §3.4).
+ *
+ * @returns {string[]}
+ */
+export function shimmableSpecifiersForSiblings() {
+  return [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "@colixsystems/widget-sdk",
+  ];
+}
+
+/**
+ * Stable URL-safe slug for a bare specifier — used as the path segment under
+ * `/shim/` so a specifier like `react/jsx-runtime` doesn't need URL encoding
+ * on the wire. Reversed by `shimSpecifierFromSlug` on the server.
+ *
+ * @param {string} specifier
+ * @returns {string}
+ */
+export function shimSlugFor(specifier) {
+  return specifier.replace(/\//g, "__").replace(/@/g, "_at_");
+}
+
+/**
+ * Reverse of `shimSlugFor`. Returns the bare specifier; the caller validates
+ * it against `shimmableSpecifiersForSiblings()` before serving.
+ *
+ * @param {string} slug
+ * @returns {string}
+ */
+export function shimSpecifierFromSlug(slug) {
+  return slug.replace(/_at_/g, "@").replace(/__/g, "/");
+}