@colixsystems/widget-sdk 0.221.1 → 0.223.0

package/README.md

@@ -24,7 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
 | **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
 | **CORE** | `useAnonymousAccount()` | `{ supported, canCreate, creating, error, create }` | The optional `ctx.account.anonymous` — no scope. Offers an account with a generated login code and password and no email. `create()` opens the app's own dialog, which confirms, creates the account, shows the pair once and signs the visitor in; the widget never receives the pair and `create()` resolves `{ created: true }`. `supported` is false where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview and for a badge counter; `canCreate` is false while someone is signed in. |
-| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
+| **CORE** | `useNavigation()` | `{ goTo, goToStartPage, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either; `goToStartPage()` opens the signed-in user's own start page (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useFilePreview(file)` | `{ uri }` | No scope. A temporary address an `<Image>` can show for a file the person picked but has not uploaded yet (a photo in a composer). Native picks use their own uri; on the web the SDK creates and releases an object URL, which widgets may not do themselves. `uri` is null for no file. |
 | **CORE** | `usePageBadge(count)` | `{ supported }` | `ctx.navigation.setBadge` — no scope. Puts `count` on the menu entry or tab of the page the widget is on (a chat's unread messages). The host sums the page's widgets and keeps the last count after the widget leaves the screen, until it reports again; `0` clears this widget's share. `supported` is false where the host draws no page badges (the Builder canvas). |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
@@ -84,7 +84,48 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.221.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.223.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.223.0 (contract 1.179.0)
+
+**A widget can send the user back to their start page — `useNavigation().goToStartPage()`.** An app opens on a start page that can differ per user, because page access is restricted per group. A "Back to start" or "Home" button should take each user to their own start page rather than to one hard-coded page they may not be allowed to open.
+
+```jsx
+import { useNavigation, Button } from "@colixsystems/widget-sdk";
+
+export default function BackToStart() {
+  const { goToStartPage } = useNavigation();
+  return <Button title="Back to the start page" onPress={() => goToStartPage()} />;
+}
+```
+
+The web Player and the exported app both go to the page the app opens on for the signed-in user. It takes no arguments and carries no params. It is a no-op where there is no live router (the Studio canvas, a badge counter). Additive.
+
+### What's new in 0.222.0 (contract 1.178.0)
+
+**A card can carry its picture as its background — `<Card image>`.** A small image with its title in a box underneath reads as a caption under a thumbnail. The same content with the picture filling the card and the title on it reads as designed, and until now a widget could only build that by hand: an absolutely positioned `Image`, its own translucent overlay, hand-picked light text. `<Card>` now does it.
+
+```jsx
+<Card
+  as={Pressable}
+  onPress={open}
+  image={urls ? urls.card : null}
+  scrim="bottom"
+  style={{ aspectRatio: 1, justifyContent: "flex-end" }}
+>
+  {({ colors }) => <Text style={{ color: colors.onSurface }}>{record.name}</Text>}
+</Card>
+```
+
+- **`image`** takes a URL or `{ uri }`. The picture fills the card to every edge, inside the card's own corner radius; the card's padding insets the content, not the picture.
+- **`scrim`** names the edge the text sits on: `"bottom"` (default), `"top"`, `"left"`, `"right"`, `"full"` for centred text, or `"none"`. It is a light gradient that is clear over most of the picture.
+- **`imagePosition`** (`"center"` default, `"top"`, `"bottom"`, `"left"`, `"right"`) keeps that part of the picture in frame when the crop is tight.
+- **Children may be a function.** It receives `{ colors, onImage }`: the theme colours as they read where the content sits. Over a picture `colors.onSurface` and `colors.onSurfaceMuted` are light; on a card with no image they are the theme's own. A `<Button>` inside the card reads its backdrop without help.
+- **No image, no change.** `image={null}` renders the ordinary card, so a record with an empty file cell needs no branch.
+- **A photo card is a `View` or a `Pressable`.** Put a scroller inside it, never as it (`as={ScrollView}`): the picture would scroll away with the content.
+- **Give it a size.** Nothing picture-shaped sizes a photo card, so `style` carries an `aspectRatio` or a `minHeight`. The keys that arrange content (`justifyContent`, `alignItems`, `gap`, `flexDirection`) apply to the content laid over the picture, also under `as={Pressable}`.
+
+Both hosts paint it: the web Player with a CSS background, the exported app with `expo-image`, which every export already bundles. Additive: a card given no `image` renders exactly as before.
 
 ### What's new in 0.221.1 (contract 1.177.1)
 
@@ -2726,7 +2767,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `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` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `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). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `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` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goToStartPage, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `goToStartPage()` opens the signed-in user's own start page (the page the app opens on for them); `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `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). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.
@@ -2779,7 +2820,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
-- **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. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a `16 / 9` card cover, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame.
+- **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. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a square photo tile, a `16 / 9` photo card, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame. When an item has a photograph, make it the card's background with the title on it — `<Card image={url} scrim="bottom">` with a function child for the colours — rather than a small picture with its text in a box underneath; keep the stacked form for a card whose text is long or dense.
 - **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. Gradients come from the `<Gradient>` primitive (not a CSS `linear-gradient` string), depth comes from `theme.elevation` (not arbitrary `box-shadow` stacks), and there are no custom CSS keyframe animations or `transition` strings (the hover/press lift comes built into `pressableLift` — never write your own), no `filter` / `backdrop-filter` / `clip-path` / `mask` / blend modes, and no opacity-faked tints (that's what `primarySoft` is for). Aim for clean, confident, professional polish within those bounds — lifted surfaces, generous corners, one accent moment.

package/dist/card-photo.js

@@ -0,0 +1,26 @@
+// The picture behind a photo-backed `<Card>` (web). A CSS background, because
+// `background-position` is what keeps the chosen part of a crop in frame.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+
+// A quote, backslash or newline would end the CSS `url("…")` early.
+function cssUrl(uri) {
+  const safe = uri.replace(/[\n\r\f]/g, "").replace(/\\/g, "%5C").replace(/"/g, "%22");
+  return `url("${safe}")`;
+}
+
+export function Photo({ uri, position, style }) {
+  return React.createElement(ReactNative.View, {
+    "aria-hidden": true,
+    style: [
+      style,
+      {
+        backgroundImage: cssUrl(uri),
+        backgroundSize: "cover",
+        backgroundPosition: position,
+        backgroundRepeat: "no-repeat",
+      },
+    ],
+  });
+}

package/dist/card-photo.native.js

@@ -0,0 +1,32 @@
+// The picture behind a photo-backed `<Card>` (native). expo-image, because
+// `contentPosition` is the only native equivalent of CSS background-position;
+// React Native's own Image can only centre a `cover` crop.
+
+import React from "react";
+import { Image } from "react-native";
+
+// Pinned in every export; only a dev client older than the pin lacks it.
+let ExpoImage = null;
+try {
+  ExpoImage = require("expo-image").Image;
+} catch (_) {
+  ExpoImage = null;
+}
+
+export function Photo({ uri, position, style }) {
+  if (!ExpoImage) {
+    return React.createElement(Image, {
+      source: { uri },
+      resizeMode: "cover",
+      style,
+      accessible: false,
+    });
+  }
+  return React.createElement(ExpoImage, {
+    source: { uri },
+    contentFit: "cover",
+    contentPosition: position,
+    style,
+    accessible: false,
+  });
+}

package/dist/card-style.js

@@ -11,6 +11,7 @@ import {
   normaliseComponentGradient,
   componentGradientColors,
   componentGradientMidpoint,
+  deriveSurfaceTokens,
 } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
@@ -160,3 +161,74 @@ function isOpaqueHex(value) {
 export function cardGradientProps(style) {
   return gradientProps(style && style.cardGradient);
 }
+
+// ---- The photo-backed card: a picture edge to edge, content laid over it ----
+
+export const CARD_SCRIMS = Object.freeze(["bottom", "top", "left", "right", "full", "none"]);
+export const DEFAULT_CARD_SCRIM = "bottom";
+
+export const CARD_IMAGE_POSITIONS = Object.freeze(["center", "top", "bottom", "left", "right"]);
+
+// What content over a photo is inked against, and what shows while it loads.
+export const CARD_PHOTO_BACKDROP = "#111827";
+
+// The dark end sits on the named edge, where the text is.
+const SCRIM_ANGLES = Object.freeze({ bottom: 180, top: 0, left: 270, right: 90 });
+// Clear over most of the picture, so the photo stays a photo.
+const SCRIM_EDGE = Object.freeze(["#00000000", "#00000026", "#000000b8"]);
+const SCRIM_FULL = Object.freeze(["#00000066", "#00000066"]);
+
+/** The picture's address from a URL or an RN `{ uri }` source, else null. */
+export function cardPhotoUri(image) {
+  const raw = image && typeof image === "object" ? image.uri : image;
+  if (typeof raw !== "string") return null;
+  const uri = raw.trim();
+  return uri ? uri : null;
+}
+
+/** The `<Gradient>` props that keep text readable on a photo; null for none. */
+export function cardScrimProps(scrim) {
+  const name = CARD_SCRIMS.includes(scrim) ? scrim : DEFAULT_CARD_SCRIM;
+  if (name === "none") return null;
+  if (name === "full") return { colors: [...SCRIM_FULL], angle: 180 };
+  return { colors: [...SCRIM_EDGE], angle: SCRIM_ANGLES[name] };
+}
+
+/** Which part of the picture a cropped card keeps in frame. */
+export function cardImagePosition(value) {
+  return CARD_IMAGE_POSITIONS.includes(value) ? value : "center";
+}
+
+/** Theme colours as content over a photo reads them, for a card with no host. */
+export function cardPhotoColors(colors) {
+  return {
+    ...colors,
+    ...deriveSurfaceTokens(CARD_PHOTO_BACKDROP),
+    backdrop: CARD_PHOTO_BACKDROP,
+  };
+}
+
+const RADIUS_FIELDS = Object.freeze([
+  "borderRadius", "borderTopLeftRadius", "borderTopRightRadius",
+  "borderBottomRightRadius", "borderBottomLeftRadius",
+]);
+
+/**
+ * The layer that holds a photo card's picture: it fills the card behind the
+ * content and rounds the picture to the card's corners. Its own layer, since
+ * iOS drops the shadow of a view that clips.
+ *
+ * @param {object|Array} styles - the card's composed container style.
+ */
+export function cardPhotoClip(styles) {
+  const flat = flattenStyle(styles);
+  const clip = {
+    position: "absolute", top: 0, right: 0, bottom: 0, left: 0,
+    overflow: "hidden",
+    pointerEvents: "none",
+  };
+  for (const key of RADIUS_FIELDS) {
+    if (flat[key] !== undefined) clip[key] = flat[key];
+  }
+  return clip;
+}

package/dist/card-view.js

@@ -4,6 +4,9 @@
 //
 // A gradient is a COMPONENT on both hosts, never a style value, so the element
 // swap lives here once rather than in each widget.
+//
+// A card given an `image` is a PHOTO card: the same element, with the picture
+// and a readability scrim on a layer behind its content.
 
 import React from "react";
 import { useHostTheme, BackdropScope } from "./hooks.js";
@@ -15,6 +18,12 @@ import {
   cardGradientProps,
   cardLayoutStyle,
   cardBackdrop,
+  cardPhotoUri,
+  cardScrimProps,
+  cardImagePosition,
+  cardPhotoClip,
+  cardPhotoColors,
+  CARD_PHOTO_BACKDROP,
 } from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 import { flattenStyle } from "./flatten-style.js";
@@ -31,6 +40,12 @@ const FILL_IN_GRADIENT = {
 
 const CLIP_TO_RADIUS = { overflow: "hidden" };
 
+// The fill shows while the picture loads, so light text never sits on white.
+const PHOTO_BOX = { backgroundColor: CARD_PHOTO_BACKDROP };
+const PHOTO_LAYER = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 };
+// The theme's hairline reads as a stray outline around a photograph.
+const NO_BORDER = { borderWidth: 0 };
+
 const CARD_FIELDS = CONTRACT.themeComponents.card.universalFields;
 
 // The convenience props, each named for the `card*` field it sets.
@@ -61,6 +76,19 @@ function themedFields(theme) {
   return out;
 }
 
+// Inside the card's scope, so a function child reads the card's own inks.
+function CardContent({ onImage, children }) {
+  const hosted = useHostTheme();
+  if (typeof children !== "function") return children;
+  // No host means no scope to re-ink through; the photo is dark regardless.
+  const colors = hosted
+    ? hosted.colors
+    : onImage
+      ? cardPhotoColors(DEFAULT_THEME_TOKENS.colors)
+      : DEFAULT_THEME_TOKENS.colors;
+  return children({ colors, onImage });
+}
+
 function themedBase(theme) {
   const { colors, radii, spacing } = theme;
   return {
@@ -75,10 +103,10 @@ function themedBase(theme) {
 /**
  * Bind the shared card to one platform's primitives.
  *
- * @param {{View: any, Gradient: any}} rn
+ * @param {{View: any, Gradient: any, Photo: any}} rn
  */
 export function makeCard(rn) {
-  const { View, Gradient } = rn;
+  const { View, Gradient, Photo } = rn;
 
   /**
    * @param {object|Array} [props.style] — `card*` fields, `shadow`, `margin`
@@ -101,6 +129,16 @@ export function makeCard(rn) {
    *   element receiving the other props, so a Pressable's feedback lands.
    * @param {boolean} [props.withoutMargin] — leave the margin off this surface
    *   for a widget that rides it on an outer root.
+   * @param {string|{uri: string}} [props.image] — a picture painted edge to
+   *   edge BEHIND the content. With none (a record without a photo) the card
+   *   is an ordinary card, so one widget serves both.
+   * @param {string} [props.imagePosition] — the part kept in frame when
+   *   cropped (`CARD_IMAGE_POSITIONS`).
+   * @param {string} [props.scrim] — the edge the readability gradient darkens
+   *   (`CARD_SCRIMS`); the edge the text sits on.
+   * @param {React.ReactNode|Function} [props.children] — a function is called
+   *   with `{ colors, onImage }`: the theme colours as they read where the
+   *   content sits, light over a photo and the theme's own without one.
    */
   function Card(props) {
     const {
@@ -110,6 +148,9 @@ export function makeCard(rn) {
       fillInGradient = false,
       containerStyle,
       withoutMargin = false,
+      image,
+      imagePosition,
+      scrim,
       children,
       ...others
     } = props;
@@ -118,6 +159,7 @@ export function makeCard(rn) {
       if (!(key in PROP_FIELDS)) rest[key] = value;
     }
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const uri = cardPhotoUri(image);
 
     const explicit = {};
     for (const [prop, field] of Object.entries(PROP_FIELDS)) {
@@ -137,17 +179,49 @@ export function makeCard(rn) {
     const layout = standalone ? cardLayoutStyle(own) : null;
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
-    const gradient = cardGradientProps(fields);
-    const basis = cardBackdrop(
-      [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
-      gradient,
+
+    const gradient = uri ? null : cardGradientProps(fields);
+    const basis = uri
+      ? CARD_PHOTO_BACKDROP
+      : cardBackdrop(
+          [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
+          gradient,
+        );
+    const scoped = React.createElement(
+      BackdropScope,
+      { basis, always: Boolean(uri) },
+      React.createElement(CardContent, { onImage: Boolean(uri) }, children),
     );
-    const scoped = React.createElement(BackdropScope, { basis }, children);
 
     if (!gradient) {
+      const box = [
+        base,
+        overlay,
+        layout,
+        uri ? PHOTO_BOX : null,
+        uri && !fields.cardBorderColor ? NO_BORDER : null,
+      ];
+      const scrimProps = uri ? cardScrimProps(scrim) : null;
+      const ownStyle = typeof containerStyle === "function" ? null : containerStyle;
+      // The layer keeps its slot with no photo, so content survives one arriving.
+      const layer = uri
+        ? React.createElement(
+            View,
+            { style: cardPhotoClip([box, ownStyle]) },
+            React.createElement(Photo, {
+              uri,
+              position: cardImagePosition(imagePosition),
+              style: PHOTO_LAYER,
+            }),
+            scrimProps
+              ? React.createElement(Gradient, { ...scrimProps, style: PHOTO_LAYER })
+              : null,
+          )
+        : null;
       return React.createElement(
         Container,
-        { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
+        { style: composeStyle(box, containerStyle), ...rest },
+        layer,
         scoped,
       );
     }

package/dist/card.js

@@ -3,6 +3,7 @@
 
 import * as ReactNative from "react-native-web";
 import { Gradient } from "./gradient.js";
+import { Photo } from "./card-photo.js";
 import { makeCard } from "./card-view.js";
 
-export const Card = makeCard({ View: ReactNative.View, Gradient });
+export const Card = makeCard({ View: ReactNative.View, Gradient, Photo });

package/dist/card.native.js

@@ -3,6 +3,7 @@
 
 import { View } from "react-native";
 import { Gradient } from "./gradient.native.js";
+import { Photo } from "./card-photo.native.js";
 import { makeCard } from "./card-view.js";
 
-export const Card = makeCard({ View, Gradient });
+export const Card = makeCard({ View, Gradient, Photo });

package/dist/contract.cjs

@@ -1128,6 +1128,8 @@ const HOOKS = [
       goTo:
         "(pageIdOrSlug: string, params?: object) => void — a page's UUID (a pageRef prop) OR its SLUG (e.g. a row's page-key field); both hosts resolve either. There is NO page-name lookup: a slug is the only data-carried navigation key.",
       openLink: "(link: string) => boolean",
+      goToStartPage:
+        "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -3245,7 +3247,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5874,7 +5876,13 @@ const CONTRACT = deepFreeze({
   // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
   //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
   //    error for the rest of the order.
-  version: "1.177.1",
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
+  //    the signed-in user's own start page on both hosts.
+  version: "1.179.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1128,6 +1128,8 @@ const HOOKS = [
       goTo:
         "(pageIdOrSlug: string, params?: object) => void — a page's UUID (a pageRef prop) OR its SLUG (e.g. a row's page-key field); both hosts resolve either. There is NO page-name lookup: a slug is the only data-carried navigation key.",
       openLink: "(link: string) => boolean",
+      goToStartPage:
+        "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -3245,7 +3247,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5870,7 +5872,13 @@ const CONTRACT = deepFreeze({
   // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
   //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
   //    error for the rest of the order.
-  version: "1.177.1",
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
+  //    the signed-in user's own start page on both hosts.
+  version: "1.179.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -72,17 +72,20 @@ export function WidgetContextProvider({ value, children }) {
  * @internal — a surface painting its own fill inside a coloured section
  * becomes the surface its content reads and its buttons are measured against
  * (`<Card>` uses it), by the derivation a layout container applies.
- * Outside such a section there is no backdrop and nothing changes.
+ * Outside such a section there is no backdrop and nothing changes, unless
+ * `always`: a surface whose fill is fixed (a photograph) re-inks everywhere.
  */
-export function BackdropScope({ basis, children }) {
+export function BackdropScope({ basis, always = false, children }) {
   const ctx = useContext(HostWidgetContext);
   const theme = ctx && ctx.workspace ? ctx.workspace.theme : null;
   const colors = theme && theme.colors;
-  const scoped = Boolean(basis && colors && colors.backdrop && colors.backdrop !== basis);
+  const scoped = Boolean(
+    basis && colors && (always || (colors.backdrop && colors.backdrop !== basis)),
+  );
   const value = useMemo(
     () =>
       scoped
-        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis } } } }
+        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis, backdropBase: colors.backdropBase || colors.surface } } } }
         : ctx,
     [scoped, ctx, theme, colors, basis],
   );
@@ -679,10 +682,11 @@ export function useContainerWidth() {
 
 /**
  * Returns the host-provided navigation surface:
- *   `{ goTo, goBack, push, replace, back, currentRoute }`.
+ *   `{ goTo, goToStartPage, goBack, push, replace, back, currentRoute }`.
  *
- * `goTo(pageId, params?)` navigates to an internal app page. `goBack()`
- * pops the stack. `push` / `replace` / `back` are aliases that map to
+ * `goTo(pageId, params?)` navigates to an internal app page. `goToStartPage()`
+ * opens the signed-in user's own start page, which can differ per user.
+ * `goBack()` pops the stack. `push` / `replace` / `back` are aliases that map to
  * the platform's native navigator (react-router on web, react-navigation
  * on native). Missing methods degrade to no-ops on the Studio canvas
  * preview, where there is no live router.

package/dist/index.d.ts

@@ -765,6 +765,7 @@ export interface WidgetContext<TProps = unknown> {
   };
   navigation: {
     goTo(pageId: string, params?: Record<string, string>): void;
+    goToStartPage(): void;
     goBack(): void;
     push(pageId: string, params?: Record<string, unknown>): void;
     replace(pageId: string, params?: Record<string, unknown>): void;
@@ -2019,12 +2020,14 @@ export function useFill(): boolean;
 
 /**
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
- * to an internal app page; `goBack()` pops the stack. Missing methods
- * degrade to no-ops on the Studio canvas preview where no live router is
- * mounted. For external URLs use the `Linking` primitive.
+ * to an internal app page; `goBack()` pops the stack. `goToStartPage()`
+ * opens the signed-in user's own start page, which can differ per user.
+ * Missing methods degrade to no-ops on the Studio canvas preview where no
+ * live router is mounted. For external URLs use the `Linking` primitive.
  */
 export function useNavigation(): {
   goTo(pageId: string, params?: Record<string, unknown>): void;
+  goToStartPage(): void;
   goBack(): void;
   push(pageId: string, params?: Record<string, unknown>): void;
   replace(pageId: string, params?: Record<string, unknown>): void;
@@ -3697,6 +3700,9 @@ export function initialsFor(name: unknown): string;
  * @example
  *   <Card><Text>…</Text></Card>
  *   <Card as={Pressable} onPress={open} radius={12} shadow="md">…</Card>
+ *   <Card image={url} scrim="bottom" style={{ aspectRatio: 1, justifyContent: "flex-end" }}>
+ *     {({ colors }) => <Text style={{ color: colors.onSurface }}>…</Text>}
+ *   </Card>
  */
 export const Card: (props: {
   background?: string;
@@ -3705,6 +3711,15 @@ export const Card: (props: {
   padding?: number | { top?: number; right?: number; bottom?: number; left?: number };
   shadow?: "none" | "sm" | "md" | "lg";
   gradient?: { from: string; to: string; angle?: number };
+  /**
+   * A picture painted edge to edge behind the content. With none the card is
+   * an ordinary card, so a record without a photo needs no branch.
+   */
+  image?: string | { uri: string } | null;
+  /** The part of the picture kept in frame when cropped. Default "center". */
+  imagePosition?: CardImagePosition;
+  /** The edge the readability gradient darkens. Default "bottom". */
+  scrim?: CardScrim;
   /**
    * `card*` style fields, `shadow`, `margin` — a widget's per-instance style.
    * With no `baseStyle` it also carries the box's layout (width, height, the
@@ -3721,10 +3736,17 @@ export const Card: (props: {
   fillInGradient?: boolean;
   containerStyle?: any;
   withoutMargin?: boolean;
-  children?: ReactNode;
+  /**
+   * A function is called with the theme colours as they read where the
+   * content sits: light over a picture, the theme's own without one.
+   */
+  children?: ReactNode | ((ink: { colors: Record<string, string>; onImage: boolean }) => ReactNode);
   [prop: string]: any;
 }) => any;
 
+export type CardScrim = "bottom" | "top" | "left" | "right" | "full" | "none";
+export type CardImagePosition = "center" | "top" | "bottom" | "left" | "right";
+
 export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger";
 export const BUTTON_VARIANTS: readonly ButtonVariant[];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.221.1",
+  "version": "0.223.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

@@ -1128,6 +1128,8 @@ const HOOKS = [
       goTo:
         "(pageIdOrSlug: string, params?: object) => void — a page's UUID (a pageRef prop) OR its SLUG (e.g. a row's page-key field); both hosts resolve either. There is NO page-name lookup: a slug is the only data-carried navigation key.",
       openLink: "(link: string) => boolean",
+      goToStartPage:
+        "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -3245,7 +3247,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5870,7 +5872,13 @@ const CONTRACT = deepFreeze({
   // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
   //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
   //    error for the rest of the order.
-  version: "1.177.1",
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
+  //    the signed-in user's own start page on both hosts.
+  version: "1.179.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,