@colixsystems/widget-sdk 0.229.0 → 0.231.0

package/README.md

@@ -45,7 +45,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useGeolocation(options)` (optional: options) | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. |
 | **CORE** | `useSpeechToText(options)` (optional: options) | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
-| **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. |
+| **CORE** | `useI18n()` | `{ t, locale, languages, canSetLocale, setLocale }` | `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. `languages` lists the app's active languages (`[{ code, name, is_base }]`); `setLocale(code)` switches the whole app live — saved to a signed-in user's account, kept on the device for a visitor, `null` for the app default. Rejects with `.code` `INVALID_LOCALE` \| `UNSUPPORTED`; `canSetLocale` is false where the host cannot switch (the Builder canvas). |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
@@ -84,7 +84,57 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.229.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.231.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.231.0 (contract 1.186.0)
+
+**A whole-screen widget can run to the bottom edge of a phone — `useFitScreenInsets()`.** In the exported app, a Fit to screen section whose widget scrolls itself (`prefersFitToScreen: true`) and calls the new `useFitScreenInsets()` runs all the way to the screen's bottom edge, under the iPhone home indicator or the Android navigation bar, so your widget's background fills the screen with no strip of page colour below it. Keep your bottom-anchored controls clear of that area with the new `useFitScreenInsets()`: it returns `{ top, right, bottom, left }` in px, the parts of the device's safe area your surface runs under. Pad your composer, a pinned bar or the end of a list by `bottom`, with your background behind the padding.
+
+```jsx
+import * as sdk from "@colixsystems/widget-sdk";
+import { View, TextInput } from "@colixsystems/widget-sdk";
+
+// A host older than 0.231.0 has no useFitScreenInsets.
+const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+const useFitScreenInsets =
+  typeof sdk.useFitScreenInsets === "function" ? sdk.useFitScreenInsets : () => NO_INSETS;
+
+function ComposerBar({ theme }) {
+  const { bottom } = useFitScreenInsets();
+  return (
+    <View style={{ backgroundColor: theme.colors.surface, padding: 10, paddingBottom: 10 + bottom }}>
+      <TextInput placeholder="Message" />
+    </View>
+  );
+}
+```
+
+The host decides the value, so you never subtract anything yourself: it is `0` while the keyboard is up (the keyboard covers that area, and your composer sits right on it), when the app's bottom bar already holds the inset, on web (the browser keeps the page inside its own safe area), and for every widget that is not a self-scrolling fit surface ending the page. Calling the hook is the opt-in: a widget that never calls it, or does not scroll itself, keeps the inset below its section, as before, so an existing widget's controls never move under the indicator. Nor does a widget with something drawn below it inside the section, such as a bottom tab bar. Use this hook rather than `useSafeAreaInsets()` from `react-native-safe-area-context`: the device's raw inset would also pad a composer that sits on a bottom bar or on the keyboard.
+
+Additive: a host without the `fitScreenFoot` hint reads zeros, so a widget that pads by it looks exactly as before there.
+
+### What's new in 0.230.0 (contract 1.185.0)
+
+**A widget can switch the app's language — `useI18n().setLocale(code)`.** `useI18n()` now also returns `languages`, the app's active languages as `[{ code, name, is_base }]`, and `setLocale(code)`, which switches the whole app to that language at once, with no reload. A signed-in user's choice is saved to their account, so it follows them to other devices; a visitor who is not signed in keeps it on this device. `setLocale(null)` returns to the app's default language. It rejects with an `Error` whose `.code` is `INVALID_LOCALE` (not one of `languages`) or `UNSUPPORTED` (the host cannot switch — the Builder canvas). Gate your controls on `canSetLocale` and render them disabled when it is false. The same on the web Player and the exported app.
+
+```jsx
+import { useI18n, Pressable, Text } from "@colixsystems/widget-sdk";
+
+export default function Languages() {
+  const { languages, locale, setLocale, canSetLocale } = useI18n();
+  return languages.map((l) => (
+    <Pressable
+      key={l.code}
+      disabled={!canSetLocale}
+      onPress={() => setLocale(l.code).catch(() => { /* show "try again" */ })}
+    >
+      <Text>{l.code === locale ? `✓ ${l.name}` : l.name}</Text>
+    </Pressable>
+  ));
+}
+```
+
+AppStudio also ships a ready-made **Language picker** built-in widget on the same hook.
 
 ### What's new in 0.229.0 (contract unchanged)
 

package/dist/contract.cjs

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -1009,6 +1021,31 @@ const HOOKS = [
     requiredContextSlice: ["fitScreen"],
     scopes: null,
   },
+  {
+    name: "useFitScreenInsets",
+    signature: "useFitScreenInsets()",
+    description:
+      "Returns { top, right, bottom, left } in px: the parts of the device's " +
+      "safe area (the home indicator, a system navigation bar) that this " +
+      "widget's surface runs under. Calling it opts the widget in: only then " +
+      "does a Fit to screen section whose widget scrolls itself (manifest " +
+      "prefersFitToScreen) run to the screen's bottom edge in the exported " +
+      "app, so the widget's background fills it; a widget that never calls it " +
+      "keeps the inset below its section. Pad the bottom-anchored controls (a composer, a pinned bar, the end of " +
+      "a list) by bottom so they stay clear, with the background behind the " +
+      "padding. The host reports 0 while the keyboard is up (it covers that " +
+      "area), when the app's bottom bar holds the inset, on web (the browser " +
+      "keeps the page inside its own safe area) and for every widget that is " +
+      "not such a surface, so calling it is always safe.",
+    returnShape: {
+      top: "number",
+      right: "number",
+      bottom: "number",
+      left: "number",
+    },
+    requiredContextSlice: ["fitScreenFoot"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3594,7 +3631,7 @@ const MANIFEST_SCHEMA = {
     type: "boolean",
     required: false,
     description:
-      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). In the exported app a widget that also calls useFitScreenInsets() has that box run to the screen's bottom edge, under the home indicator: keep the background filling it and pad bottom-anchored controls by useFitScreenInsets().bottom (a widget that never calls it keeps the inset below its section). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
     default: false,
   },
   events: {
@@ -3682,6 +3719,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11615 — optional host hint backing useFitScreenInsets(): the screen's
+  // foot a self-scrolling fit surface may claim.
+  fitScreenFoot: {
+    description:
+      "Optional host layout hint ({ claim } or null). Set only for a " +
+      "self-scrolling Fit to screen surface with nothing below it in the " +
+      "exported app: claim(onInset) runs the surface under the bottom safe " +
+      "area, calls onInset(px) now and on every change, and returns the " +
+      "release. Backs useFitScreenInsets(); null or absent reads as zeros " +
+      "and leaves the inset below the section.",
+    required: false,
+    fields: {
+      claim: "(onInset: (bottom: number) => void) => () => void",
+    },
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -3924,12 +3976,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5978,7 +6032,15 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  // 1.186.0: additive (sc-11615) — `useFitScreenInsets()` with its optional
+  //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
+  //    calls it runs under the bottom safe area on native and pads its
+  //    controls by it. Hosts without the hint read zeros.
+  version: "1.186.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -1009,6 +1021,31 @@ const HOOKS = [
     requiredContextSlice: ["fitScreen"],
     scopes: null,
   },
+  {
+    name: "useFitScreenInsets",
+    signature: "useFitScreenInsets()",
+    description:
+      "Returns { top, right, bottom, left } in px: the parts of the device's " +
+      "safe area (the home indicator, a system navigation bar) that this " +
+      "widget's surface runs under. Calling it opts the widget in: only then " +
+      "does a Fit to screen section whose widget scrolls itself (manifest " +
+      "prefersFitToScreen) run to the screen's bottom edge in the exported " +
+      "app, so the widget's background fills it; a widget that never calls it " +
+      "keeps the inset below its section. Pad the bottom-anchored controls (a composer, a pinned bar, the end of " +
+      "a list) by bottom so they stay clear, with the background behind the " +
+      "padding. The host reports 0 while the keyboard is up (it covers that " +
+      "area), when the app's bottom bar holds the inset, on web (the browser " +
+      "keeps the page inside its own safe area) and for every widget that is " +
+      "not such a surface, so calling it is always safe.",
+    returnShape: {
+      top: "number",
+      right: "number",
+      bottom: "number",
+      left: "number",
+    },
+    requiredContextSlice: ["fitScreenFoot"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3590,7 +3627,7 @@ const MANIFEST_SCHEMA = {
     type: "boolean",
     required: false,
     description:
-      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). In the exported app a widget that also calls useFitScreenInsets() has that box run to the screen's bottom edge, under the home indicator: keep the background filling it and pad bottom-anchored controls by useFitScreenInsets().bottom (a widget that never calls it keeps the inset below its section). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
     default: false,
   },
   events: {
@@ -3678,6 +3715,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11615 — optional host hint backing useFitScreenInsets(): the screen's
+  // foot a self-scrolling fit surface may claim.
+  fitScreenFoot: {
+    description:
+      "Optional host layout hint ({ claim } or null). Set only for a " +
+      "self-scrolling Fit to screen surface with nothing below it in the " +
+      "exported app: claim(onInset) runs the surface under the bottom safe " +
+      "area, calls onInset(px) now and on every change, and returns the " +
+      "release. Backs useFitScreenInsets(); null or absent reads as zeros " +
+      "and leaves the inset below the section.",
+    required: false,
+    fields: {
+      claim: "(onInset: (bottom: number) => void) => () => void",
+    },
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -3920,12 +3972,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5974,7 +6028,15 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  // 1.186.0: additive (sc-11615) — `useFitScreenInsets()` with its optional
+  //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
+  //    calls it runs under the bottom safe area on native and pads its
+  //    controls by it. Hosts without the hint read zeros.
+  version: "1.186.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -23,6 +23,7 @@ import React, {
   useContext,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -501,6 +502,47 @@ export function useFitScreen() {
   return ctx.fitScreen === true;
 }
 
+const NO_FIT_SCREEN_INSETS = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
+
+function insetPx(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Returns `{ top, right, bottom, left }` in px: the parts of the device's safe
+ * area (the home indicator, a system navigation bar) that this widget's
+ * surface runs under. Calling it OPTS the widget in: only then does the host
+ * run a self-scrolling Fit to screen surface (manifest `prefersFitToScreen`)
+ * to the screen's bottom edge in the exported app, so the widget's background
+ * fills it; pad your bottom-anchored controls (a composer, a pinned bar) by
+ * `bottom` to keep them clear. A widget that never calls it keeps the inset
+ * below its section. The host reports 0 while the keyboard is up (it covers
+ * that area), when the app's bottom bar holds the inset, on web (the browser
+ * keeps the page inside its own safe area) and for every widget that is not
+ * such a surface.
+ */
+export function useFitScreenInsets() {
+  const ctx = useWidgetContextOrThrow("useFitScreenInsets");
+  const foot = ctx.fitScreenFoot;
+  const claim = foot && typeof foot.claim === "function" ? foot.claim : null;
+  const [bottom, setBottom] = useState(0);
+  // Before paint, so the surface never shows a frame off the edge.
+  useLayoutEffect(() => {
+    if (!claim) {
+      setBottom(0);
+      return undefined;
+    }
+    const release = claim((value) => setBottom(insetPx(value)));
+    return () => {
+      if (typeof release === "function") release();
+    };
+  }, [claim]);
+  return useMemo(
+    () => (bottom === 0 ? NO_FIT_SCREEN_INSETS : { top: 0, right: 0, bottom, left: 0 }),
+    [bottom],
+  );
+}
+
 /**
  * Returns the host's child-node renderer:
  *   { renderNode(node) }.
@@ -954,17 +996,44 @@ export function useWidgetRoute(initial) {
   return [state, setState];
 }
 
+const NO_LANGUAGES = Object.freeze([]);
+
+function localeError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
 /**
- * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
- * the host's translation table and falls back to `fallback ?? key` when
- * the key is missing. The host's i18n.t may or may not honour the two-arg
- * form; we degrade gracefully either way.
+ * Returns { t, locale, languages, canSetLocale, setLocale }. `t(key,
+ * fallback)` resolves `{{t:key}}` against the host's translation table and
+ * falls back to `fallback ?? key` when the key is missing. The host's i18n.t
+ * may or may not honour the two-arg form; we degrade gracefully either way.
+ *
+ * sc-11482 — `setLocale(code)` switches the whole app through the host's own
+ * language switch (the same one its account screen uses).
  */
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
   const i18n = ctx.i18n || {};
   const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
   const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  const languages = Array.isArray(i18n.languages) ? i18n.languages : NO_LANGUAGES;
+  const hostSetLocale = typeof i18n.setLocale === "function" ? i18n.setLocale : null;
+  // Validated here so both hosts refuse an unknown code identically.
+  const setLocale = useCallback(
+    async (code) => {
+      if (!hostSetLocale) {
+        throw localeError("UNSUPPORTED", "The language cannot be changed here.");
+      }
+      const next = typeof code === "string" && code ? code : null;
+      if (next !== null && !languages.some((l) => l && l.code === next)) {
+        throw localeError("INVALID_LOCALE", `"${next}" is not one of this app's languages.`);
+      }
+      await hostSetLocale(next);
+    },
+    [hostSetLocale, languages],
+  );
   // REQ-L10N-WIDGET: the widget's own manifest translations are stored in the
   // tenant dictionary under `widget.<id>.<key>`. Derive the namespace from the
   // host-provided widget id so the author calls `t("greeting")` and never
@@ -1022,7 +1091,7 @@ export function useI18n() {
     },
     [hostT, widgetId],
   );
-  return { t, locale };
+  return { t, locale, languages, canSetLocale: hostSetLocale !== null, setLocale };
 }
 
 /**

package/dist/index.d.ts

@@ -799,6 +799,15 @@ export interface WidgetContext<TProps = unknown> {
    * the rest of the screen). Absent / `false` everywhere else.
    */
   fitScreen?: boolean;
+  /**
+   * sc-11615 — optional host hint backing `useFitScreenInsets()`: set only for
+   * a self-scrolling fit surface with nothing below it. `claim(onInset)` runs
+   * the surface under the bottom safe area, reports the inset in px now and
+   * on every change, and returns the release. Null / absent reads as zeros.
+   */
+  fitScreenFoot?: {
+    claim(onInset: (bottom: number) => void): () => void;
+  } | null;
   /** Active end-user identity from the host-built context (camelCase, not a wire payload). `id` is null when anonymous. */
   user: {
     id: string | null;
@@ -1961,9 +1970,26 @@ export function useAssetsByTag(
   refetch(): Promise<void>;
 };
 
+/** One of the app's active languages, as `useI18n().languages` lists it. */
+export interface AppLanguage {
+  code: string;
+  name: string;
+  is_base: boolean;
+}
+
+/**
+ * The app's translations and language. `setLocale(code)` switches the whole
+ * app live: a signed-in user's choice is saved to their account, a
+ * visitor's stays on the device, and `null` returns to the app's default.
+ * Rejects with an Error whose `.code` is `INVALID_LOCALE` or `UNSUPPORTED`
+ * (`canSetLocale` is false on a host that cannot switch).
+ */
 export function useI18n(): {
   locale: string;
   t(key: string, fallback?: string): string;
+  languages: AppLanguage[];
+  canSetLocale: boolean;
+  setLocale(code: string | null): Promise<void>;
 };
 
 /**
@@ -2160,6 +2186,26 @@ export function useFill(): boolean;
  */
 export function useFitScreen(): boolean;
 
+/** Insets in px, one per screen edge. */
+export interface FitScreenInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * sc-11615 — the parts of the device's safe area (the home indicator, a
+ * system navigation bar) that this widget's surface runs under. Calling it
+ * opts in: a Fit to screen section whose widget scrolls itself
+ * (`prefersFitToScreen`) then runs to the screen's bottom edge in the exported
+ * app; keep the background filling it and pad bottom-anchored controls (a
+ * composer, a pinned bar) by `bottom`. Never called, the inset stays below.
+ * All zeros while the keyboard is up, when the app's bottom bar holds the
+ * inset, on web, and for every widget that is not such a surface.
+ */
+export function useFitScreenInsets(): FitScreenInsets;
+
 /**
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
  * to an internal app page; `goBack()` pops the stack. `goToStartPage()`

package/dist/index.js

@@ -81,6 +81,7 @@ export {
   useAnonymousAccount,
   useFill,
   useFitScreen,
+  useFitScreenInsets,
   useNavigation,
   useRouteParams,
   usePageBadge,

package/dist/index.native.js

@@ -81,6 +81,7 @@ export {
   useAnonymousAccount,
   useFill,
   useFitScreen,
+  useFitScreenInsets,
   useNavigation,
   useRouteParams,
   usePageBadge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.229.0",
+  "version": "0.231.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -1009,6 +1021,31 @@ const HOOKS = [
     requiredContextSlice: ["fitScreen"],
     scopes: null,
   },
+  {
+    name: "useFitScreenInsets",
+    signature: "useFitScreenInsets()",
+    description:
+      "Returns { top, right, bottom, left } in px: the parts of the device's " +
+      "safe area (the home indicator, a system navigation bar) that this " +
+      "widget's surface runs under. Calling it opts the widget in: only then " +
+      "does a Fit to screen section whose widget scrolls itself (manifest " +
+      "prefersFitToScreen) run to the screen's bottom edge in the exported " +
+      "app, so the widget's background fills it; a widget that never calls it " +
+      "keeps the inset below its section. Pad the bottom-anchored controls (a composer, a pinned bar, the end of " +
+      "a list) by bottom so they stay clear, with the background behind the " +
+      "padding. The host reports 0 while the keyboard is up (it covers that " +
+      "area), when the app's bottom bar holds the inset, on web (the browser " +
+      "keeps the page inside its own safe area) and for every widget that is " +
+      "not such a surface, so calling it is always safe.",
+    returnShape: {
+      top: "number",
+      right: "number",
+      bottom: "number",
+      left: "number",
+    },
+    requiredContextSlice: ["fitScreenFoot"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3590,7 +3627,7 @@ const MANIFEST_SCHEMA = {
     type: "boolean",
     required: false,
     description:
-      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). In the exported app a widget that also calls useFitScreenInsets() has that box run to the screen's bottom edge, under the home indicator: keep the background filling it and pad bottom-anchored controls by useFitScreenInsets().bottom (a widget that never calls it keeps the inset below its section). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
     default: false,
   },
   events: {
@@ -3678,6 +3715,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11615 — optional host hint backing useFitScreenInsets(): the screen's
+  // foot a self-scrolling fit surface may claim.
+  fitScreenFoot: {
+    description:
+      "Optional host layout hint ({ claim } or null). Set only for a " +
+      "self-scrolling Fit to screen surface with nothing below it in the " +
+      "exported app: claim(onInset) runs the surface under the bottom safe " +
+      "area, calls onInset(px) now and on every change, and returns the " +
+      "release. Backs useFitScreenInsets(); null or absent reads as zeros " +
+      "and leaves the inset below the section.",
+    required: false,
+    fields: {
+      claim: "(onInset: (bottom: number) => void) => () => void",
+    },
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -3920,12 +3972,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5974,7 +6028,15 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  // 1.186.0: additive (sc-11615) — `useFitScreenInsets()` with its optional
+  //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
+  //    calls it runs under the bottom safe area on native and pads its
+  //    controls by it. Hosts without the hint read zeros.
+  version: "1.186.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,