@colixsystems/widget-sdk 0.219.0 → 0.220.0

package/README.md

@@ -23,6 +23,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **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** | `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). |
@@ -32,7 +33,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. A sibling's input reads the payload, and a page action the author binds to the event (Run action, Navigate) runs with it — fired from one control, only that control runs it. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
-| **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
+| **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill a box of definite height: a widget in the section a fit-to-screen page stretches to the bottom of the screen, or one given a fixed slot height. Media-style widgets, and a chat or feed that scrolls its own content, switch to a `flex: 1` / `height: "100%"` layout and scroll inside it; others ignore it. Defaults `false`. |
 | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
 | **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. |
 | **CORE** | `widthTier(width)` | `"narrow" \| "medium" \| "wide"` | No context slice, no scope. Which of THREE layouts a measured width calls for: narrow below `NARROW_WIDTH_PX` (480), wide at or above `WIDE_WIDTH_PX` (960), medium between. `widthTier(w) === "narrow"` exactly when `isNarrowWidth(w)`; an unmeasured width (0) is "wide". |
@@ -83,7 +84,54 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.219.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.220.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.220.0 (contract 1.176.0)
+
+**An app can let a visitor continue without an email — `useAnonymousAccount()`.** Some apps must let a person act without identifying themselves and still come back later: someone files a report and returns to follow it. The new hook lets a widget offer an account that has no email address. The server generates a login code and a password, and the visitor signs in again later with that pair on the app's sign-in screen ("Sign in with a login code").
+
+```jsx
+import { useAnonymousAccount, useUser, Button, Text, View } from "@colixsystems/widget-sdk";
+
+export default function ContinueWithoutEmail() {
+  const user = useUser();
+  const { supported, canCreate, creating, error, create } = useAnonymousAccount();
+
+  if (!supported) {
+    return <Text>Continuing without an email is not available here.</Text>;
+  }
+  if (user.id) {
+    return <Text>You are signed in.</Text>;
+  }
+  if (!canCreate) return null;
+
+  return (
+    <View>
+      <Button
+        title="Continue without an email"
+        disabled={creating}
+        onPress={() => create().catch(() => {})}
+      />
+      {error && error.code !== "CANCELLED" ? (
+        <Text>Could not create the account. Try again.</Text>
+      ) : null}
+    </View>
+  );
+}
+```
+
+- **The widget only asks; the app does the rest.** `create()` takes no arguments and opens the app's own dialog. It asks the visitor to confirm, shows the captcha notice when a captcha will run, creates the account, shows the login code and password once with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved them (or opens the sign-in screen's two-factor step when the workspace requires one). Do not build a confirmation, a captcha notice or a credentials screen of your own.
+- **The widget never receives the login code or the password.** `create()` resolves `{ created: true }` and nothing else. Widgets on a page share one context, so a credential that cannot be reset is kept out of it altogether. This is a contract boundary, not a sandbox: the SDK never hands the pair to a widget, but every widget on a page still runs inside the app.
+- **Call `create()` from a user action.** A button's `onPress`, never on mount or in an effect. Nothing is created until the visitor confirms in the dialog.
+- **Failures carry a `code`.** `create()` rejects with an Error whose `code` is the server's refusal (`ANONYMOUS_ACCOUNT_LIMIT_REACHED`, `RATE_LIMITED`, `CAPTCHA_FAILED`, …), `CAPTCHA_UNAVAILABLE` when the captcha could not run (there is no fallback), `ALREADY_SIGNED_IN`, `CANCELLED` when the visitor closes the dialog, or `UNSUPPORTED`. The dialog shows a failure itself and lets the visitor retry, so a rejection means they gave up; treat `CANCELLED` as no error. `error` holds the last one.
+- **`supported` and `canCreate`.** `supported` is false where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview and for a badge counter: render a visible "not available" state. `canCreate` is false while someone is signed in. The hook never throws at render and needs no scope.
+- **What the account can do.** It is not treated as a signed-in member: it gets only what the workspace grants to everyone or to the group chosen for these accounts, plus the records it owns. `useUser().email` is `null` for it.
+
+A host backs the hook with the new optional `WidgetContext.account.anonymous` member, `{ canCreate, create() }`. `account`'s photo actions are now optional members, so a host may publish `account` with either or both. Additive.
+
+### What's new in 0.219.1
+
+**`useFill()` says when it is true today.** It described a page-grid tile with a "Fill tile height" choice, a layout that no longer exists. A host now fills a widget in two cases: the widget sits in the section a fit-to-screen page stretches to the bottom of the screen, or the widget has a fixed slot height. A chat or feed that scrolls its own content is one of the widgets that should honour it. A documentation correction; `CONTRACT.version` is unchanged.
 
 ### What's new in 0.219.0 (contract 1.175.0)
 

package/dist/contract.cjs

@@ -938,17 +938,50 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3549,40 +3582,46 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
   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. Not a data-client.",
+      "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.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5810,7 +5849,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -938,17 +938,50 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3545,40 +3578,46 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
   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. Not a data-client.",
+      "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.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5806,7 +5845,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -391,15 +391,90 @@ export function useUserPhoto() {
   return { url, canEdit, upload, remove, uploading, error };
 }
 
+const ANONYMOUS_ACCOUNT_UNSUPPORTED =
+  "Creating an account without an email is not available here";
+
+/**
+ * Offer an account that needs no email address. The server generates a login
+ * code and a password; the person signs in later with that pair. Returns
+ * `{ supported, canCreate, creating, error, create }`.
+ *
+ * A widget only asks. `create()` takes no arguments and opens the app's own dialog
+ * (`ctx.account.anonymous`), which asks the visitor to confirm, runs the
+ * captcha, creates the account, shows the login code and password once and
+ * signs the visitor in when they confirm they saved them. The widget never
+ * receives the pair: `create()` resolves `{ created: true }`. It rejects with
+ * an Error carrying `code` — the server's refusal, `CAPTCHA_UNAVAILABLE`,
+ * `ALREADY_SIGNED_IN`, `CANCELLED` when the visitor closes the dialog, or
+ * `UNSUPPORTED`.
+ *
+ * Call `create()` from a user action (a button press), never on mount.
+ * `ctx.account.anonymous` is optional: where it is absent (the workspace has
+ * the feature off, the Builder canvas, a preview, a badge counter)
+ * `supported` is false and `create()` rejects instead of the hook throwing at
+ * render. `canCreate` is false while someone is signed in.
+ */
+export function useAnonymousAccount() {
+  const ctx = useWidgetContextOrThrow("useAnonymousAccount");
+  const member = ctx.account ? ctx.account.anonymous : null;
+  const supported = Boolean(member) && typeof member.create === "function";
+
+  const hostRef = useRef(null);
+  hostRef.current = supported ? member : null;
+  const inFlightRef = useRef(null);
+  const [creating, setCreating] = useState(false);
+  const [error, setError] = useState(null);
+
+  const create = useCallback(() => {
+    if (inFlightRef.current) return inFlightRef.current;
+    const host = hostRef.current;
+    if (!host) {
+      const err = Object.assign(new Error(ANONYMOUS_ACCOUNT_UNSUPPORTED), {
+        code: "UNSUPPORTED",
+      });
+      setError(err);
+      return Promise.reject(err);
+    }
+    setCreating(true);
+    setError(null);
+    const attempt = Promise.resolve()
+      .then(() => host.create())
+      .then(
+        () => {
+          inFlightRef.current = null;
+          setCreating(false);
+          return { created: true };
+        },
+        (err) => {
+          inFlightRef.current = null;
+          setCreating(false);
+          setError(err);
+          throw err;
+        },
+      );
+    inFlightRef.current = attempt;
+    return attempt;
+  }, []);
+
+  return {
+    supported,
+    canCreate: supported && member.canCreate === true,
+    creating,
+    error,
+    create,
+  };
+}
+
 /**
- * Returns `true` when the host has sized this widget to fill the available
- * height of its layout slot — today that means a page-grid tile whose author
- * chose "Fill tile height" (or a widget type that fills by default, like
- * containers and media). When `true`, a widget that has a meaningful filled
- * form (Image, Chart, Map, Video, …) should switch from its intrinsic height
- * to a stretch style (`flex: 1` / `height: "100%"`); widgets with no useful
- * filled form may ignore it. Defaults to `false` everywhere the host has not
- * opted the widget into filling, so calling it is always safe.
+ * Returns `true` when the host has sized this widget to fill a box of
+ * definite height — a widget in the section a fit-to-screen page stretches to
+ * the bottom of the screen, or a widget given a fixed slot height. When
+ * `true`, a widget that has a meaningful filled form (Image, Chart, Map,
+ * Video, a chat or feed that scrolls its own content, …) should switch from
+ * its intrinsic height to a stretch style (`flex: 1` / `height: "100%"`) and
+ * scroll inside it; widgets with no useful filled form may ignore it.
+ * Defaults to `false` everywhere the host has not opted the widget into
+ * filling, so calling it is always safe.
  *
  * The SAME value is injected by the web Player host and the native export
  * host (widget-parity skill), so a widget's fill behaviour is identical on both

package/dist/index.d.ts

@@ -728,8 +728,8 @@ export interface WidgetContext<TProps = unknown> {
   };
   /**
    * REQ-LAY-08 — optional host layout hint backing `useFill()`. `true` when
-   * the host sized this widget to fill its layout slot's available height (a
-   * page-grid tile set to "Fill tile height", or a default-fill widget type).
+   * the host sized this widget to fill a box of definite height (a
+   * fit-to-screen page's stretched section, or a fixed slot height).
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
@@ -744,14 +744,18 @@ export interface WidgetContext<TProps = unknown> {
     groupIds: string[];
   };
   /**
-   * Optional self-service account actions backing `useUserPhoto()`. The host
-   * performs the request and updates its own session, so `user.photoUrl`
-   * changes for every widget. Absent where the photo cannot be changed (the
-   * Builder canvas preview); `useUserPhoto().canEdit` is then false.
+   * Optional self-service account actions; every member is optional too.
+   * `setPhoto` / `removePhoto` back `useUserPhoto()` and are present only
+   * while a user is signed in: the host performs the request and updates its
+   * own session, so `user.photoUrl` changes for every widget. `anonymous`
+   * backs `useAnonymousAccount()` and is present only where the workspace
+   * offers accounts without an email. The whole slice is absent on the
+   * Builder canvas, in the preview panes and for a badge counter.
    */
   account?: {
-    setPhoto(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
-    removePhoto(): Promise<{ photoUrl: null }>;
+    setPhoto?(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
+    removePhoto?(): Promise<{ photoUrl: null }>;
+    anonymous?: AnonymousAccountHost;
   };
   workspace: {
     id: string;
@@ -1947,12 +1951,67 @@ export interface UserPhotoApi {
  */
 export function useUserPhoto(): UserPhotoApi;
 
+/** A `create()` failure. `code` names the refusal. */
+export type AnonymousAccountError = Error & {
+  /**
+   * The server's refusal (`ANONYMOUS_ACCOUNT_LIMIT_REACHED`, `RATE_LIMITED`,
+   * `CAPTCHA_FAILED`, …), or `CAPTCHA_UNAVAILABLE`
+   * (the captcha could not run), `ALREADY_SIGNED_IN`, `CANCELLED` (the
+   * visitor closed the dialog) or `UNSUPPORTED`. Absent when the failure has
+   * no code.
+   */
+  code?: string;
+  /** The HTTP status of a server refusal; 0 when there was no response. */
+  status?: number;
+};
+
+/** `WidgetContext.account.anonymous`: what a host provides for `useAnonymousAccount()`. */
+export interface AnonymousAccountHost {
+  /** True only while nobody is signed in and no two-factor step is pending. */
+  canCreate: boolean;
+  /**
+   * Opens the host's own dialog, which confirms, creates the account, shows
+   * the login code and password once and signs the visitor in. The pair
+   * never leaves that dialog.
+   */
+  create(): Promise<{ created: true }>;
+}
+
+export interface AnonymousAccountApi {
+  /** False where the host does not offer accounts without an email. */
+  supported: boolean;
+  /** True when `supported` and nobody is signed in. */
+  canCreate: boolean;
+  /** True while a `create()` call is in flight: the app's dialog is open. */
+  creating: boolean;
+  /** The last `create()` failure; cleared by the next attempt. */
+  error: AnonymousAccountError | null;
+  /**
+   * Ask the app to create the account. Call it from a user action. The app
+   * shows the login code and password itself; the widget never receives
+   * them. Rejects with an `AnonymousAccountError`.
+   */
+  create(): Promise<{ created: true }>;
+}
+
+/**
+ * Offer an account that needs no email address: the server generates a
+ * login code and a password, and the person signs in later with that pair.
+ * The app confirms, shows the pair once and signs the visitor in, all in its
+ * own dialog. Never throws at render: where the host does not offer it (the
+ * workspace has it off, the Builder canvas, a preview, a badge counter)
+ * `supported` is false and `create()` rejects with `code: "UNSUPPORTED"`.
+ */
+export function useAnonymousAccount(): AnonymousAccountApi;
+
 /**
- * REQ-LAY-08 — returns `true` when the host has sized this widget to fill its
- * layout slot's available height (a page-grid tile set to "Fill tile height",
- * or a default-fill widget type — containers + media). Widgets that can
- * stretch (Image, Chart, Map, Video, …) should switch to a fill style
- * (`flex: 1` / `height: "100%"`) when this is `true`; others may ignore it.
+ * REQ-LAY-08 — returns `true` when the host has sized this widget to fill a
+ * box of definite height (a widget in the section a fit-to-screen page
+ * stretches to the bottom of the screen, or one given a fixed slot height).
+ * Widgets that can stretch (Image, Chart, Map, Video, a chat or feed that
+ * scrolls itself, …) should switch to a fill style (`flex: 1` /
+ * `height: "100%"`) and scroll inside it when this is `true`; others may
+ * ignore it.
  * Defaults to `false`, so calling it is always safe, and the same value is
  * injected on web and native so fill behaviour is identical on both platforms.
  */

package/dist/index.js

@@ -78,6 +78,7 @@ export {
   LinkPreviewError,
   useUser,
   useUserPhoto,
+  useAnonymousAccount,
   useFill,
   useNavigation,
   useRouteParams,

package/dist/index.native.js

@@ -78,6 +78,7 @@ export {
   LinkPreviewError,
   useUser,
   useUserPhoto,
+  useAnonymousAccount,
   useFill,
   useNavigation,
   useRouteParams,

package/package.json

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

@@ -938,17 +938,50 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3545,40 +3578,46 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
   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. Not a data-client.",
+      "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.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5806,7 +5845,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,