@colixsystems/widget-sdk 0.37.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.
@@ -26,13 +26,13 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
-| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) then falls back to the raw key. |
+| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **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,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.37.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
+
+**Predefined SHARED translation keys (REQ-L10N-SHARED).** The standard strings the default widgets repeat ("Submit", "Cancel", "Save", "Loading…", …) now have a tenant-wide shared namespace `shared.<key>` so an identical string is translated **once** and every widget that uses it inherits the translation.
+
+- **New contract field `CONTRACT.sharedTranslationKeys`** — the predefined map (`{ <key>: { en } }`) and the single source the host seeder reads.
+- **New exported helpers** `sharedTranslationPrefix()` / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)` (from `@colixsystems/widget-sdk/contract`).
+- **`useI18n().t(key)` resolution is now three-step**: the per-widget key (`widget.<id>.<key>`) first, then the shared key (`shared.<key>`) when `key` is one of the predefined shared keys, then the raw key / fallback. So a default widget that calls `t("submit")` picks up the shared translation with no manual key entry, and an author who sets `widget.<id>.submit` in the Translations admin still overrides **that instance only**. An author-invented bare key is never silently shared.
+- **The host auto-registers the shared keys** for a tenant at workspace-content seed time and whenever a marketplace or AI-generated widget is added — idempotent and non-destructive (an admin edit is never overwritten). Authors manage / translate them in the Studio Translations screen like any other key.
+- **`CONTRACT.version` → `1.28.0`** (additive: one new contract field + three helper exports + the `useI18n` shared-key step). No existing export changed signature.
 
 ### What's new in 0.37.0
 
@@ -175,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
@@ -217,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.
@@ -247,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
 
@@ -321,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.
@@ -337,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
@@ -1285,6 +1300,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1331,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
@@ -1486,7 +1560,23 @@ const CONTRACT = deepFreeze({
   //    on `react/jsx-runtime`. Adding them converges the linter onto the same
   //    contract every other surface already honoured (CLAUDE.md §3). No
   //    existing entry changed shape — minor bump on the pre-1.0 channel.
-  version: "1.27.0",
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1524,4 +1614,8 @@ module.exports = {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };

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
@@ -1285,6 +1300,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1331,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
@@ -1486,7 +1560,23 @@ const CONTRACT = deepFreeze({
   //    on `react/jsx-runtime`. Adding them converges the linter onto the same
   //    contract every other surface already honoured (CLAUDE.md §3). No
   //    existing entry changed shape — minor bump on the pre-1.0 channel.
-  version: "1.27.0",
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1524,4 +1614,8 @@ export {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };