@colixsystems/widget-sdk 0.219.1 → 0.221.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). |
@@ -83,7 +84,65 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.219.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.221.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.221.0 (contract 1.177.0)
+
+**A row's file goes in the row's record space, and `upload()` names the record per call.** A file a widget keeps in a `FILE` column belongs in that row's `record` space: exactly the people who may read the row may read the file, so a private table's attachments stay private, and a table that lets everyone read still serves them to logged-out visitors. A `public` file, by contrast, is readable by anyone holding its link whatever the table's permissions say. A row must exist before a file can be attached to it, and a create form only learns the new row's id inside its submit handler, after the hook rendered. So `upload(file, { recordId })` now takes the record per call, the way it already took `folderId`:
+
+```js
+const { create, update } = useDatastoreMutation(tableId);
+const { upload } = useFilestoreUpload({ spaceType: "record" });
+
+const row = await create({ Title: title });            // without the file
+const stored = await upload(file, { recordId: row.id }); // into that row's space
+await update(row.id, { Receipt: stored.id });
+```
+
+A per-call `recordId` wins over the hook's; outside a `record` space it is ignored. A record upload that names no record now rejects with `useFilestoreUpload: a record space needs a recordId` instead of the misleading `Sign in to upload`. A logged-out visitor cannot upload into a record space, so ask them to sign in to attach a file. `useCamera()` and `useImageEditor()` now point at `useFilestoreUpload` for the upload: their descriptions named `ctx.assets.upload`, which widget code cannot reach. Additive.
+
+### 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
 
@@ -1452,9 +1511,7 @@ const { edit } = useImageEditor();
 const shot = await capture();
 const small = await edit(shot.uri, [{ resize: { width: 800 } }], { format: "jpeg", compress: 0.8 });
 
-const fd = new FormData();
-fd.append("file", small.file);
-await ctx.assets.upload(fd);
+await upload(small.file); // upload from useFilestoreUpload()
 ```
 
 `edit(uri, actions, options?)` applies `actions` in order and resolves the SAME normalised asset shape `useCamera()` yields, so capture → edit → upload is one code path on both hosts. Actions are `{ resize: { width?, height? } }`, `{ crop: { originX, originY, width, height } }`, `{ rotate: degrees }` and `{ flip: "horizontal" | "vertical" }`; output is `{ format: "jpeg" | "png" | "webp", compress, base64? }`.
@@ -1668,12 +1725,10 @@ When you take the `useCanWrite`-only route, omit the USER column for a guest (`i
 
 **Dismissing the picker resolves `null`, not an error.** Backing out is the most common outcome, so it is deliberately not a rejection — your happy path needs no `try/catch`. A genuine failure (permission refused, no host broker) rejects with a structured `CameraError` (new named export) carrying a stable `.code` (`PERMISSION_DENIED` / `UNSUPPORTED` / `INTERNAL`).
 
-**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a browser `File` on web, expo-file-system's `File` on native. (Never React Native's legacy `{ uri, name, type }` part: the native host streams the file off disk, and Expo's fetch rejects that part outright anyway. Do not branch on the part's type — an expo-file-system `File` is NOT `instanceof Blob` at runtime.) So the same three lines work everywhere:
+**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a browser `File` on web, expo-file-system's `File` on native. (Never React Native's legacy `{ uri, name, type }` part: the native host streams the file off disk, and Expo's fetch rejects that part outright anyway. Do not branch on the part's type — an expo-file-system `File` is NOT `instanceof Blob` at runtime.) So the same line works everywhere:
 
 ```js
-const fd = new FormData();
-fd.append("file", asset.file);
-await ctx.assets.upload(fd);
+await upload(asset.file); // upload from useFilestoreUpload()
 ```
 
 `options` (`{ allowsEditing, quality }`) are **hints**: the Expo export applies both, the web camera applies `quality` only — so never depend on a cropped result. `reset()` clears the asset and releases it (on web that revokes the blob URL, which otherwise leaks for the life of the document). **Gate your camera button on `supported`** — a host that brokers no camera reports `false` rather than throwing. The web Player brokers it via `getUserMedia` — a live preview with a shutter — on every web host: it is the only camera a DESKTOP browser will open, and a phone reaches the same preview rather than its own camera app. It falls back to a file input (`capture="environment"`) only where getUserMedia is absent up front: an insecure origin or an older browser. Once the permission prompt has been shown the user gesture is spent, so a camera that then fails to open rejects (`PERMISSION_DENIED` if refused, `UNSUPPORTED` if there is no usable device) rather than falling back to a file dialog the browser would refuse to open. The Expo export uses `expo-image-picker`, whose config plugin declares the camera and photo-library permissions the runtime needs.

package/dist/contract.cjs

@@ -938,6 +938,38 @@ 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()",
@@ -1337,7 +1369,7 @@ const HOOKS = [
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
-      "ctx.filestore.files.upload. `upload(file, { folderId?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1355,13 +1387,20 @@ const HOOKS = [
       "ORIGINAL matters (a document archive, a photo the user re-downloads, " +
       "anything with an exact-bytes requirement). " +
       "ALWAYS pass spaceType explicitly — omitting it falls back to " +
-      "'project', which is unreadable by a logged-out visitor. Choose it by " +
-      "who must SEE the file: 'public' for content the app displays to " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -2786,8 +2825,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2853,7 +2892,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -2990,7 +3029,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -3565,26 +3604,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   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:
@@ -5812,7 +5856,19 @@ 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.
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  version: "1.177.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -938,6 +938,38 @@ 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()",
@@ -1337,7 +1369,7 @@ const HOOKS = [
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
-      "ctx.filestore.files.upload. `upload(file, { folderId?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1355,13 +1387,20 @@ const HOOKS = [
       "ORIGINAL matters (a document archive, a photo the user re-downloads, " +
       "anything with an exact-bytes requirement). " +
       "ALWAYS pass spaceType explicitly — omitting it falls back to " +
-      "'project', which is unreadable by a logged-out visitor. Choose it by " +
-      "who must SEE the file: 'public' for content the app displays to " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -2786,8 +2825,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2853,7 +2892,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -2990,7 +3029,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -3561,26 +3600,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   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:
@@ -5808,7 +5852,19 @@ 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.
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  version: "1.177.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -391,6 +391,80 @@ 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 a box of
  * definite height — a widget in the section a fit-to-screen page stretches to
@@ -4626,7 +4700,10 @@ export function useFilestoreFile(fileId) {
  * same way the read hooks do (tenant for PROJECT, app user for PERSONAL, the
  * record for RECORD) and posts a multipart FormData to `ctx.filestore.files.upload`.
  *
- * `upload(file, { folderId?, fileName? })` takes a browser `File` on the web
+ * sc-10937: `upload(file, { recordId })` names the record per call, so a
+ * widget can create a row and attach to it in the same handler.
+ *
+ * `upload(file, { folderId?, recordId?, fileName? })` takes a browser `File` on the web
  * Player and expo-file-system's `File` on the Expo export, as `<FilePicker>`,
  * `useCamera()` and `useImageEditor()` all hand back. Never React Native's
  * legacy `{ uri, name, type }` part: the native host streams the file off
@@ -4660,7 +4737,8 @@ export function useFilestoreUpload(options) {
     folderId: defaultFolderId = null,
     compress: defaultCompress = true,
   } = options || {};
-  const ownerId = _filestoreOwnerId(ctx, spaceType, recordId);
+  const isRecordSpace = String(spaceType || "project").toUpperCase() === "RECORD";
+  const defaultOwnerId = _filestoreOwnerId(ctx, spaceType, recordId);
 
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
@@ -4672,19 +4750,25 @@ export function useFilestoreUpload(options) {
   const upload = useCallback(
     async (file, overrides) => {
       if (!file) throw new Error("useFilestoreUpload: file is required");
+      const hasOverride = (key) =>
+        Boolean(overrides) && Object.prototype.hasOwnProperty.call(overrides, key);
+      const ownerId =
+        isRecordSpace && hasOverride("recordId")
+          ? overrides.recordId || null
+          : defaultOwnerId;
+      if (isRecordSpace && !ownerId) {
+        // Not "Sign in": the widget forgot which row to attach to.
+        const err = new Error("useFilestoreUpload: a record space needs a recordId");
+        setError(err);
+        throw err;
+      }
       if (!ownerId) {
         const err = new Error("Sign in to upload");
         setError(err);
         throw err;
       }
-      const folderId =
-        overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
-          ? overrides.folderId
-          : defaultFolderId;
-      const compress =
-        overrides && Object.prototype.hasOwnProperty.call(overrides, "compress")
-          ? overrides.compress
-          : defaultCompress;
+      const folderId = hasOverride("folderId") ? overrides.folderId : defaultFolderId;
+      const compress = hasOverride("compress") ? overrides.compress : defaultCompress;
       const form = new FormData();
       form.append("space_type", String(spaceType || "project").toUpperCase());
       form.append("owner_id", ownerId);
@@ -4726,7 +4810,7 @@ export function useFilestoreUpload(options) {
         throw err;
       }
     },
-    [ownerId, defaultFolderId, defaultCompress, spaceType],
+    [defaultOwnerId, isRecordSpace, defaultFolderId, defaultCompress, spaceType],
   );
 
   return { upload, uploading, error, lastUploaded };

package/dist/index.d.ts

@@ -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,6 +1951,59 @@ 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 a
  * box of definite height (a widget in the section a fit-to-screen page
@@ -2395,7 +2452,7 @@ export interface CameraAsset {
   /**
    * Ready-to-upload part — a Blob on both hosts: a `File` on web,
    * expo-file-system's `File` on native. Expo's fetch rejects any other shape.
-   * Append it to a FormData and hand that to `ctx.assets.upload(...)`.
+   * Pass it to `upload(file)` from `useFilestoreUpload`.
    */
   file: unknown;
 }

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.1",
+  "version": "0.221.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,6 +938,38 @@ 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()",
@@ -1337,7 +1369,7 @@ const HOOKS = [
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
-      "ctx.filestore.files.upload. `upload(file, { folderId?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1355,13 +1387,20 @@ const HOOKS = [
       "ORIGINAL matters (a document archive, a photo the user re-downloads, " +
       "anything with an exact-bytes requirement). " +
       "ALWAYS pass spaceType explicitly — omitting it falls back to " +
-      "'project', which is unreadable by a logged-out visitor. Choose it by " +
-      "who must SEE the file: 'public' for content the app displays to " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -2786,8 +2825,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2853,7 +2892,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -2990,7 +3029,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -3561,26 +3600,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   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:
@@ -5808,7 +5852,19 @@ 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.
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  version: "1.177.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,