@softr/sdk 0.0.68-props.0 → 0.0.69-alpha.0

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.68-props.0";
+var version = "0.0.69-alpha.0";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react5 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
+declare function SoftrPwaHead(): react5.FunctionComponentElement<react5.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/dist/pwa.js

@@ -2,9 +2,9 @@ import { logger } from "./logger.js";
 import { fetch } from "./fetch.js";
 import { sessionConfig } from "./auth/config.js";
 import { platformApiUrl } from "./auth/platform.js";
-import { z } from "zod";
 import { Fragment, createElement, useEffect, useState } from "react";
 import { createMiddleware } from "@tanstack/react-start";
+import { z } from "zod";
 
 //#region src/pwa.ts
 const MANIFEST_PATH = "/manifest.webmanifest";

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { upload } from "./core/file-upload.js";
 import { auth } from "./auth/server.js";
+import { RecordOption, RecordOptions } from "./core/options.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { auth, ds, integration, upload, workflow };
+export { type RecordOption, type RecordOptions, auth, ds, integration, upload, workflow };

package/dist/softr-config.schema.js

@@ -1,10 +1,6 @@
-import { assert, panic } from "./assertions.js";
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
 import { z } from "zod";
 
 //#region src/softr-config.schema.ts
-const SOFTR_CONFIG_FILE = "softr.json";
 const AccessBehaviour = z.union([
 	z.string(),
 	z.object({
@@ -13,49 +9,32 @@ const AccessBehaviour = z.union([
 	}),
 	z.object({ strategy: z.literal("throw") })
 ], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
-const AppPath = z.string().refine((path$1) => path$1.startsWith("/") && !path$1.includes("?") && !path$1.includes("#") && new URL(path$1, "https://app.invalid").origin === "https://app.invalid", { error: "must be a path on this app like \"/login\", with no \"?\" or \"#\"" });
-const SoftrConfigSchema = z.object({
-	auth: z.strictObject({
-		routes: z.strictObject({
-			login: z.strictObject({
-				path: AppPath,
-				redirectParam: z.string()
-			}),
-			resetPassword: z.strictObject({
-				path: AppPath,
-				tokenParam: z.string()
-			}),
-			acceptInvitation: z.strictObject({
-				path: AppPath,
-				tokenParam: z.string()
-			}),
-			magicLink: z.strictObject({
-				path: AppPath,
-				tokenParam: z.string()
-			})
+const AppPath = z.string().refine((path) => path.startsWith("/") && !path.includes("?") && !path.includes("#") && new URL(path, "https://app.invalid").origin === "https://app.invalid", { error: "must be a path on this app like \"/login\", with no \"?\" or \"#\"" });
+const SoftrConfigSchema = z.object({ auth: z.strictObject({
+	routes: z.strictObject({
+		login: z.strictObject({
+			path: AppPath,
+			redirectParam: z.string()
 		}),
-		guard: z.strictObject({
-			unauthenticated: AccessBehaviour,
-			forbidden: AccessBehaviour,
-			alreadyAuthenticated: AccessBehaviour
+		resetPassword: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
+		}),
+		acceptInvitation: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
+		}),
+		magicLink: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
 		})
 	}),
-	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional()
-});
-function loadSoftrConfig(root) {
-	const file = path.join(root, SOFTR_CONFIG_FILE);
-	assert(existsSync(file), `${SOFTR_CONFIG_FILE} is missing from ${root}`);
-	const source = readFileSync(file, "utf8");
-	let parsed;
-	try {
-		parsed = JSON.parse(source);
-	} catch (error) {
-		panic(`${SOFTR_CONFIG_FILE} is not valid JSON: ${error instanceof Error ? error.message : error}`);
-	}
-	const result = SoftrConfigSchema.safeParse(parsed);
-	if (!result.success) panic(`${SOFTR_CONFIG_FILE} does not match the schema:\n\n${z.prettifyError(result.error)}`);
-	return result.data;
-}
+	guard: z.strictObject({
+		unauthenticated: AccessBehaviour,
+		forbidden: AccessBehaviour,
+		alreadyAuthenticated: AccessBehaviour
+	})
+}) });
 
 //#endregion
-export { SOFTR_CONFIG_FILE, loadSoftrConfig };
+export { SoftrConfigSchema };

package/dist/visibility/route.js

@@ -1,5 +1,5 @@
-import { softrConfig } from "../softr-config.js";
 import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { softrConfig } from "../softr-config.js";
 import { redirect } from "@tanstack/react-router";
 
 //#region src/visibility/route.ts

package/dist/vite.js

@@ -1,8 +1,12 @@
-import { SOFTR_CONFIG_FILE, loadSoftrConfig } from "./softr-config.schema.js";
+import { assert, panic } from "./assertions.js";
+import { SoftrConfigSchema } from "./softr-config.schema.js";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { z } from "zod";
 import { pathToFileURL } from "node:url";
 
 //#region src/vite.ts
+const SOFTR_CONFIG_FILE = "softr.json";
 function softr() {
 	return [softrConfig(), editEngine()];
 }
@@ -23,6 +27,20 @@ function softrConfig() {
 		}
 	};
 }
+function loadSoftrConfig(root) {
+	const file = path.join(root, SOFTR_CONFIG_FILE);
+	assert(existsSync(file), `${SOFTR_CONFIG_FILE} is missing from ${root}`);
+	const source = readFileSync(file, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch (error) {
+		panic(`${SOFTR_CONFIG_FILE} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+	}
+	const result = SoftrConfigSchema.safeParse(parsed);
+	if (!result.success) panic(`${SOFTR_CONFIG_FILE} does not match the schema:\n\n${z.prettifyError(result.error)}`);
+	return result.data;
+}
 /**
 * The edit engine is provided by the pod runtime rather than an app dependency: it is never in the
 * app's `package.json` and never in its `node_modules`. The pod points `SOFTR_EDIT_ENGINE_DIR` at

package/package.json

@@ -1,37 +1,16 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.68-props.0",
+  "version": "0.0.69-alpha.0",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "bin": {
-    "softr-sdk": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "schema",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
+    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+  },
+  "bin": { "softr-sdk": "./dist/cli.js" },
+  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -63,9 +42,7 @@
       "optional": true
     }
   },
-  "keywords": [
-    "tanstack-intent"
-  ],
+  "keywords": ["tanstack-intent"],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/schema/softr.schema.json

@@ -54,19 +54,6 @@
       },
       "required": ["routes", "guard"],
       "additionalProperties": false
-    },
-    "user": {
-      "type": "object",
-      "description": "The signed-in user.",
-      "properties": {
-        "properties": {
-          "type": "object",
-          "description": "Fields of the users table the app reads as user.properties, keyed by the name the app uses. Each value is a field id. No other field leaves the server.",
-          "additionalProperties": { "type": "string" }
-        }
-      },
-      "required": ["properties"],
-      "additionalProperties": false
     }
   },
   "required": ["auth"],

package/skills/softr-sdk/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 # Softr SDK core
@@ -30,7 +30,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |

package/skills/softr-sdk/auth/SKILL.md

@@ -7,19 +7,18 @@ description: >-
   sign-in (verifyAuthenticator, startAuthenticatorSetup,
   confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
   authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator), the emailed password links
-  (requestPasswordReset, checkPasswordLink, setPasswordWithLink), and
-  getAuthSettings, AuthSettingsProvider and useAuthSettings for which sign-in
-  and sign-up methods the app has enabled. Covers the Result shape they answer
-  with and its codes invalidCredentials, tooManyAttempts, emailTaken,
-  invalidDetails, invalidCode, notAuthenticated, emailDomainNotAllowed and
-  linkExpired, the two-step sign-up, why a successful sign-in does not always
-  mean the visitor is signed in, and toReturnPath for where to land after
-  signing in.
+  resetAuthenticator, removeAuthenticator), updateProfile for the visitor's own
+  name and photo, the emailed password links (requestPasswordReset,
+  checkPasswordLink, setPasswordWithLink), and getAuthSettings,
+  AuthSettingsProvider and useAuthSettings for which sign-in and sign-up methods
+  the app has enabled. Covers the Result shape they answer with and its error
+  codes (invalidCredentials, emailTaken, notAuthenticated, notAnImage and the
+  rest), the two-step sign-up, why a successful sign-in does not always mean the
+  visitor is signed in, and toReturnPath for where to land after signing in.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -82,6 +81,12 @@ Changing an authenticator from a settings page:
 | `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
 | `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
+Changing the visitor's own profile:
+
+| Call | Does |
+| --- | --- |
+| `auth.updateProfile({ fullName?, avatar? })` | Changes their name, their photo, or both. `avatar: null` removes the photo |
+
 ## Setup
 
 `auth` is server-only, so every call sits inside a `createServerFn` handler:
@@ -451,6 +456,20 @@ All three need a signed-in visitor and answer `notAuthenticated` when there is n
 
 After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuthenticatorSetup`, which is also where the new backup codes come from. After a removal, an app that requires an authenticator asks the visitor to set one up again on their next sign-in.
 
+### Changing the visitor's name and photo
+
+```ts
+const result = await auth.updateProfile({ fullName: 'Ann Lee' })
+const result = await auth.updateProfile({ avatar: file })   // a File from an <input type="file">
+const result = await auth.updateProfile({ avatar: null })   // removes the photo
+```
+
+It answers with the updated `User`. Pass the file through a server function that takes `FormData`. The photo must be a PNG, JPEG or GIF of at most 5 MB, or it answers `notAnImage` or `fileTooLarge`. A blank or unacceptable name answers `invalidName`.
+
+Only some apps can store a photo. Show the photo controls only when `user.avatarEditable` is true; elsewhere a photo answers `avatarNotSupported`.
+
+The page keeps showing the old name and photo until its route context loads again, so call `router.invalidate()` after a success.
+
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor these calls establish

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -4,13 +4,12 @@ description: >-
   Read the signed-in Softr visitor: useCurrentUser and the User type,
   context.user in a route's beforeLoad, and context.user inside a server
   function handler, where Start types it from the app's registered request
-  middleware. Covers the null guest, the generated SoftrUserGroups that narrows
-  group ids to the app's own, and user.properties, the fields of the visitor's
-  row that softr.json declares.
+  middleware. Covers the null guest and the generated SoftrUserGroups that
+  narrows group ids to the app's own.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 # The current user
@@ -32,7 +31,8 @@ type User = {
   email: string
   fullName: string
   userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
-  properties: SoftrUserProperties         // the aliases softr.json declares
+  avatarUrl: string | null                 // their photo; show their initials when null
+  avatarEditable: boolean                  // whether auth.updateProfile can change the photo
 }
 ```
 
@@ -92,25 +92,6 @@ For every group's name and id, read `docs/user-groups.md`. It lists every group
 
 `user.userGroupIds` and every `customGroups` the SDK accepts take only those ids, so an id the app does not have stops compiling. A new group appears in the list once it exists on the app.
 
-### Fields of the visitor's row: `user.properties`
-
-To read more of the visitor's row in the users table, give each field an alias in `softr.json`, under `user.properties`. The value is the field's id:
-
-```json
-{
-  "user": {
-    "properties": {
-      "plan": "OeIz1",
-      "seats": "1iHKE"
-    }
-  }
-}
-```
-
-`user.properties` then holds exactly those aliases. To read them, see `docs/user-properties.md`.
-
-Attachment and long text fields, and linked record and lookup fields with multiple entries, cannot be properties. Read those with `defineQuery` on the users table. See [record-queries](../record-queries/SKILL.md).
-
 ## References
 
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/formatting/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 # Dates, times and numbers
@@ -116,6 +116,24 @@ The currency comes from the field or from the user, never from the locale. A Ger
 
 `formatDate` and `formatDateTime` show a timestamp in UTC while `formatting.timeZone` is `null`. In JSX, prefer `<FormattedDate />`, which waits instead.
 
+### A field's own text: `formatValue`
+
+A value a query read already knows how it should look: money with its symbol and cents, a percent, a rating out of its scale, a duration in hours and minutes, a date in the app's format, a choice or a linked record by its label, a checkbox as Yes or No, several values joined by a comma, `''` for nothing. `formatValue` reads the field's type and options from the generated `src/softr-fields.ts` and does all of it, so a page never branches on a type itself.
+
+```tsx
+import { formatValue, useFormatting } from '@softr/sdk'
+import { dealsQuery } from '#/server/deals.ts'
+
+function Amount({ deal }: { deal: Deal }) {
+  const formatting = useFormatting()
+  return <span>{formatValue(dealsQuery, 'amount', deal.fields.amount, formatting)}</span>
+}
+```
+
+The second argument is the alias the query holds the field under. `formatField(shape, value, formatting)` does the same for a shape in hand, and `fieldShape(query, alias)` reads one.
+
+The SDK's codegen writes `src/softr-fields.ts` beside `softr-env.d.ts` after every schema change; it registers the shapes as a side effect of being imported, and the root route imports it once. `formatValue` throws when that import is missing.
+
 ### Outside render: a server function or `beforeLoad`
 
 Not every date ends up in a component. A CSV or spreadsheet export, a text the server sends, or a value a loader prepares are formatted before React runs. There, `context.formatting` holds the same `Formatting` that `useFormatting()` returns. See [current-user](../current-user/SKILL.md) for how `context` reaches a handler.

package/skills/softr-sdk/integrations/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/mcp/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

package/skills/softr-sdk/pwa/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -135,6 +135,18 @@ await ds.update(updateProject, {
 
 A read answers a SELECT as `{ id, label }` and a write takes `{ id }`, so pass the id through rather than the whole value.
 
+### Show the edit before the loader re-runs
+
+A list whose rows a drawer or an inline control edits keeps the saved values over the loader's rows until a fresh read replaces them. `useOverrides` holds them by record id:
+
+```tsx
+const overrides = useOverrides<Partial<Deal['fields']>>()
+const rows = deals.map((deal) => ({ ...deal, fields: { ...deal.fields, ...overrides.of(deal.id) } }))
+<DealsDrawer onSaved={overrides.onSaved} />
+```
+
+`onSaved(recordId, patch)` is what a drawer calls before the write and again with the old value if the write fails; `clear(recordId)` drops a record's patch once the page has reloaded it.
+
 ### Form dropdowns for linked record fields
 
 A form select for a `LINKED_RECORD` field needs its options from the linked table, not from the record being edited. Query the linked table with its own `defineQuery` and `ds.list`; each result's `id` is what you pass to the write payload. See [record-queries](../record-queries/SKILL.md).

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -146,6 +146,18 @@ const listMyInvoices = createServerFn().handler(async ({ context }) => {
 })
 ```
 
+When the owner is a link to the Users table, the row to match is the visitor's own row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds it by email, or answers `null` when they are signed out or have no row:
+
+```ts
+import { auth, ds } from '@softr/sdk/server'
+
+const listMyDeals = createServerFn().handler(async ({ context }) => {
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return { records: [], nextOffset: null }
+  return await ds.list(deals).where((q) => q.owner.isOneOf([me.id]))
+})
+```
+
 The SDK enforces `permissions`, so a visitor outside the declared audience never reaches the records. Which of those records belong to one visitor is a separate question, and the `where` above answers it: a group says nothing about who owns a row, so a per-visitor read filters on `context.user`. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
 
 ### Populate a control from a linked table
@@ -178,6 +190,14 @@ Each returned record is one option: `record.id` is the value a `where` filter an
 ds.list(products).where((q) => q.status.is(selectedStatusId))
 ```
 
+For a picker that searches and pages, `ds.options` answers the shape a linked-record picker's `load` takes, `{ options: [{ id, label }], nextOffset }`, searched on the label field when a term is given:
+
+```ts
+const loadProductStatuses = createServerFn()
+  .validator(z.object({ term: z.string(), offset: z.number().nullable() }))
+  .handler(({ data }) => ds.options(productStatuses, { label: 'name', ...data }))
+```
+
 Skip this request when the options are predefined and fixed — hardcode them instead.
 
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status, followed by the reason the datasource gives when it sends one. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-props.0
+  library_version: 0.0.69-alpha.0
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.