@softr/sdk 0.0.87 → 0.0.88-signing.0

package/dist/auth/platform.js

@@ -1,7 +1,7 @@
 import { assert, panic } from "../assertions.js";
+import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { permissionsSchema } from "./permissions.js";
-import { softrApiUrl } from "../softr-api.js";
 import { softrConfig } from "../softr-config.js";
 import { z } from "zod";
 

package/dist/codegen/datasource-docs.js

@@ -73,16 +73,15 @@ function renderUserPropertiesDoc(users, context) {
 		"",
 		"```tsx",
 		"import { createFileRoute, redirect } from '@tanstack/react-router'",
-		"import { assertRouteAccess, definePage, pageHead } from '@softr/sdk'",
+		"import { assertRouteAccess, defineVisibility } from '@softr/sdk'",
 		"",
-		"const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] }, title: 'Example' })",
+		"const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })",
 		"",
 		"export const Route = createFileRoute('/example')({",
 		"  beforeLoad: (opts) => {",
-		"    assertRouteAccess(pageSettings, opts)",
+		"    assertRouteAccess(visibility, opts)",
 		`    if (opts.context.user.properties.${first} == null) throw redirect({ to: '/' })`,
 		"  },",
-		"  head: pageHead(pageSettings),",
 		"})",
 		"```",
 		"",
@@ -91,19 +90,14 @@ function renderUserPropertiesDoc(users, context) {
 		"```tsx",
 		"import { createFileRoute } from '@tanstack/react-router'",
 		"import { createServerFn } from '@tanstack/react-start'",
-		"import { definePage, guardRoute, pageHead } from '@softr/sdk'",
 		"",
 		`const get${pascalCase(first)} = createServerFn().handler(async ({ context }) => {`,
 		"  if (!context.user) throw new Error('Not signed in')",
 		`  return context.user.properties.${first}`,
 		"})",
 		"",
-		"const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] }, title: 'Example' })",
-		"",
 		"export const Route = createFileRoute('/example')({",
-		"  beforeLoad: guardRoute(pageSettings),",
 		`  loader: () => get${pascalCase(first)}(),`,
-		"  head: pageHead(pageSettings),",
 		"  component: Example,",
 		"})",
 		"",

package/dist/core/file-upload.js

@@ -1,7 +1,7 @@
+import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { sessionConfig } from "../auth/config.js";
 import { readSessionToken } from "../auth/session.js";
-import { softrApiUrl } from "../softr-api.js";
 import { randomUUID } from "node:crypto";
 
 //#region src/core/file-upload.ts

package/dist/core/workflow.js

@@ -1,7 +1,7 @@
+import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { sessionConfig } from "../auth/config.js";
 import { readSessionToken } from "../auth/session.js";
-import { softrApiUrl } from "../softr-api.js";
 
 //#region src/core/workflow.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/datasource/record.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../assertions.js";
+import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";
-import { softrApiUrl } from "../softr-api.js";
 import { isDatasourceAction } from "../action.js";
 import { buildFilterCriteria, buildOrderBy, dealiasFilterCriteria, dealiasOrderBy } from "./filter.js";
 import { andAll, makeFieldSet, makeSortSet } from "./fields.js";

package/dist/fetch.js

@@ -1,9 +1,29 @@
+import { version } from "./package.js";
+import { assert, requireDefined } from "./assertions.js";
 import { logger } from "./logger.js";
+import { softrApiUrl } from "./softr-api.js";
 
 //#region src/fetch.ts
 const fetch = async (input, init) => {
-	if (process.env.NODE_ENV === "production") return globalThis.fetch(input, init);
 	const url = input instanceof Request ? input.url : String(input);
+	if ([
+		softrApiUrl("SOFTR_PLATFORM_API_URL"),
+		softrApiUrl("SOFTR_DATASOURCE_API_URL"),
+		softrApiUrl("SOFTR_WORKFLOWS_API_URL")
+	].some((base) => url.startsWith(`${base}/`))) {
+		const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+		headers.set("user-agent", `softr-sdk/${version}`);
+		init = {
+			...init,
+			headers
+		};
+		const signed = await sign(input, init);
+		if (signed) {
+			input = signed;
+			init = void 0;
+		}
+	}
+	if (process.env.NODE_ENV === "production") return globalThis.fetch(input, init);
 	const method = init?.method ?? (input instanceof Request ? input.method : "GET");
 	const started = Date.now();
 	try {
@@ -16,6 +36,46 @@ const fetch = async (input, init) => {
 		throw error;
 	}
 };
+async function sign(input, init) {
+	const key = process.env.SOFTR_REQUEST_SIGNING_KEY;
+	const keyId = process.env.SOFTR_REQUEST_SIGNING_KEY_ID;
+	if (!key || !keyId) return void 0;
+	assert(/^[0-9a-f]{64}$/i.test(key), "SOFTR_REQUEST_SIGNING_KEY must be 64 hex characters");
+	assert(!/["\\]/.test(keyId), "SOFTR_REQUEST_SIGNING_KEY_ID must not contain quotes or backslashes");
+	const request = new Request(input, init);
+	const headers = new Headers(request.headers);
+	const { host, pathname, search } = new URL(request.url);
+	const derived = {
+		"@method": request.method,
+		"@authority": host,
+		"@path": pathname,
+		"@query": search || "?"
+	};
+	const fields = Object.keys(derived);
+	const body = request.body ? new Uint8Array(await request.arrayBuffer()) : void 0;
+	if (body) {
+		headers.set("content-digest", `sha-256=:${base64(await crypto.subtle.digest("SHA-256", body))}:`);
+		fields.push("content-type", "content-digest");
+	}
+	if (headers.has("authorization")) fields.push("authorization");
+	const created = Math.floor(Date.now() / 1e3);
+	const params = `(${fields.map((field) => `"${field}"`).join(" ")});created=${created};keyid="${keyId}";tag="softr-code-app"`;
+	const base = [...fields.map((field) => `"${field}": ${derived[field] ?? requireDefined(headers.get(field), field)}`), `"@signature-params": ${params}`].join("\n");
+	const hmacKey = await crypto.subtle.importKey("raw", Uint8Array.from(key.match(/../g) ?? [], (byte) => parseInt(byte, 16)), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = base64(await crypto.subtle.sign("HMAC", hmacKey, new TextEncoder().encode(base)));
+	headers.set("signature-input", `softr=${params}`);
+	headers.set("signature", `softr=:${signature}:`);
+	return new Request(request, {
+		headers,
+		body
+	});
+}
+function base64(bytes) {
+	return btoa(String.fromCharCode(...new Uint8Array(bytes)));
+}
 
 //#endregion
 export { fetch };

package/dist/locale-settings.js

@@ -1,8 +1,8 @@
 import { logger } from "./logger.js";
+import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
 import { readRequestCookies, serializeCookie, writeCookies } from "./cookies.js";
 import { sessionConfig } from "./auth/config.js";
-import { softrApiUrl } from "./softr-api.js";
 import { localeSettingsSchema } from "./formatting.js";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 

package/dist/mcp.js

@@ -1,8 +1,8 @@
 import { assert } from "./assertions.js";
+import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
 import { sessionConfig } from "./auth/config.js";
 import { readSessionToken, withSessionToken } from "./auth/session.js";
-import { softrApiUrl } from "./softr-api.js";
 import { isDatasourceAction } from "./action.js";
 import { softrConfig } from "./softr-config.js";
 import { makePlatform } from "./auth/platform.js";

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.87";
+var version = "0.0.88-signing.0";
 
 //#endregion
 export { version };

package/dist/pwa.js

@@ -1,7 +1,7 @@
 import { logger } from "./logger.js";
+import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
 import { sessionConfig } from "./auth/config.js";
-import { softrApiUrl } from "./softr-api.js";
 import { z } from "zod";
 import { Fragment, createElement, useEffect, useState } from "react";
 import { createMiddleware } from "@tanstack/react-start";
@@ -125,7 +125,7 @@ function usePwaInstall() {
 	useEffect(() => {
 		if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
 		let cancelled = false;
-		fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
+		globalThis.fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
 			if (!response.ok) return;
 			const parsed = installSchema.safeParse(await response.json());
 			if (!parsed.success || cancelled) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.87",
+  "version": "0.0.88-signing.0",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
 # Softr SDK core
@@ -17,7 +17,7 @@ metadata:
 
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 >
-> **CRITICAL**: Every route file must declare its settings with `definePage`, guard itself with them in `beforeLoad` and render them in `head`. There is no default and nothing is inherited from a sibling.
+> **CRITICAL**: Every route file must declare its audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
 >
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
 >
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `definePage`, `pageHead`, `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` | 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 | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
 # The current user
@@ -55,16 +55,12 @@ It returns `User | null` and never suspends or fetches. It selects off root rout
 
 ```tsx
 export const Route = createFileRoute('/_app/invoices')({
-  beforeLoad: guardRoute(pageSettings),
-  loader: (opts) => {
-    assertRouteAccess(pageSettings, opts)
-    return fetchInvoicesFor({ data: { userId: opts.context.user.id } })
-  },
-  head: pageHead(pageSettings),
+  beforeLoad: guardRoute(visibility),
+  loader: ({ context }) => fetchInvoicesFor({ data: { userId: context.user!.id } }),
 })
 ```
 
-A `guardRoute` in `beforeLoad` guarantees a visitor at runtime, but it does not change what the compiler sees. `context.user` is still `User | null` in the loader. `assertRouteAccess(pageSettings, opts)` at the top of the loader narrows it there, so prefer that over `!`. Take `opts` whole: a destructured `context` does not narrow. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
+A `guardRoute` in `beforeLoad` guarantees a visitor at runtime, but it does not change what the compiler sees. `context.user` is still `User | null` further down the route. `isAuthorized(visibility, context)` is the check that narrows it, so prefer that over `!`. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
 
 ### In a server function: `context`
 
@@ -98,7 +94,7 @@ For every group's name and id, read `docs/user-groups.md`. It lists every group
 
 ## References
 
-- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `assertRouteAccess` narrows `context.user` while applying the route's rule
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule
 - [region-visibility/SKILL.md](../region-visibility/SKILL.md): rendering a region only to the visitors a rule admits
 - [record-queries/SKILL.md](../record-queries/SKILL.md): filtering a query by the visitor, and who really authorizes the read
 - [auth/SKILL.md](../auth/SKILL.md): what changes the value `useCurrentUser` returns

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
 # Dates, times and numbers

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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.87
+  library_version: 0.0.88-signing.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.87
+  library_version: 0.0.88-signing.0
 ---
 
 # Installing the app

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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.
@@ -53,7 +53,7 @@ const publishedPosts = defineQuery({
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }`: everyone, signed out included. `customGroups` narrows only the signed-in half.
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS'] }`: signed-out visitors only.
   - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`. `customGroups` is added to `userGroupTypes`, never written in place of it.
-- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error.
+- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error, as it is in a route's visibility.
 - Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
 
 A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
@@ -47,9 +47,11 @@ The rules are the same four a route uses, and [routes-and-visibility](../routes-
 
 ### Where the rule is declared
 
-A region's rule is an ordinary value. It can sit beside the component, in the route file, or in a module the whole app shares so several regions read the same one.
+A region's rule is an ordinary value. It can sit beside the component, or come from a module the whole app shares so several regions read the same one. A route's rule cannot. Softr reads that one out of the route file, so it has to be declared there.
 
-It is separate from the route's own rule. That one is the `visibility` of the route's `definePage`, which `beforeLoad` applies: see [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md).
+Two files cannot hold a region's rule. Any declaration in `__root.tsx` is a build error. In the lazy half of a split route, Softr takes the first declaration as the route's own. Put the rule in the component's file or a shared module and import it.
+
+A route file may declare a region's rule alongside its own. The route's rule is the one `beforeLoad` names.
 
 ### Hiding a control is not authorization
 

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

@@ -1,22 +1,21 @@
 ---
 name: routes-and-visibility
 description: >-
-  Add a route file and declare its settings: definePage with its visibility
-  (LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups) and its title,
-  guardRoute or assertRouteAccess in beforeLoad, pageHead in head,
-  isAuthorized and checkAccess anywhere, rendering an access error, and the
-  lint rules that require the declaration.
+  Add a route file and declare who may see it: defineVisibility with
+  LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups, guardRoute and
+  assertRouteAccess in a route, isAuthorized and checkAccess anywhere, rendering
+  an access error, and the lint rule that requires the declaration.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.0
 ---
 
-**Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
+**Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
 
 # Route visibility
 
-Every route file in a Softr app declares its settings: who may see it, its title and its SEO tags. Softr reads them out of the source text without executing it and shows them in Softr Studio, where the app owner sees every route and its audience and can change them. That is why the rules below are strict: a setting Softr cannot read is a setting Studio cannot show.
+Every route file in a Softr app declares who may see it. Softr reads that declaration out of the source text without executing it and publishes it to Softr Studio, which shows the app owner every route and its audience. That is why the rules below are strict: a rule Softr cannot read is a rule Studio cannot show.
 
 ## Setup
 
@@ -24,16 +23,12 @@ Every route file, without exception, looks like this:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { definePage, guardRoute, pageHead } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
-const pageSettings = definePage({
-  visibility: { userGroupTypes: ['LOGGED_IN_USERS'] },
-  title: 'Billing',
-})
+const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(pageSettings),
-  head: pageHead(pageSettings),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
 })
 
@@ -42,31 +37,30 @@ function Billing() {
 }
 ```
 
-The route's settings are one `definePage` call at module scope, with an inline object literal as its argument. It always states `visibility`, and a page states its `title` too. `beforeLoad` applies the visibility, and `head` renders the title and the SEO tags.
+The route's rule is one `defineVisibility` call at module scope, with an inline object literal as its argument.
 
-These constraints hold, because Softr reads the file rather than running it:
+Four constraints on that shape, because Softr reads the file rather than running it:
 
 - The call must initialise a top-level `const`.
 - The import must be a direct named import from `@softr/sdk`.
-- A route file has one `definePage`. The route names it in `beforeLoad` and in `head`. A page imported from elsewhere is rejected.
-- Every value inside the literal is written there too. A group id taken from a `const`, a spread or an import still type-checks, but Studio can no longer change that setting. Repeat the id on each route, even when two routes share it.
-- A head setting that depends on the route's data is a function of its head context: `title: ({ loaderData }) => loaderData?.name`.
-- Never state `visibility` on `__root.tsx`. The root cannot carry an audience, so a rule there would gate nothing while looking like it does. Its `definePage` holds the app-wide head defaults only. Put the rule on a layout below the root instead.
+- The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
+- Every value inside the literal is written there too. A group id taken from a `const`, a spread or an import is rejected, even when two routes share it: repeat the id on each.
+- Never declare on `__root.tsx`. The root cannot carry an audience, so a declaration there would gate nothing while looking like it does. Softr rejects it. Put the rule on a layout below the root instead.
 
 `userGroupTypes` is a set, so a rule names one audience or several:
 
 ```ts
-visibility: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }  // everyone, signed in or not
-visibility: { userGroupTypes: ['NON_LOGGED_IN_USERS'] }                     // signed-out only: login, signup
-visibility: { userGroupTypes: ['LOGGED_IN_USERS'] }                         // any signed-in visitor
-visibility: {                                                               // those groups only
+defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] })  // everyone, signed in or not
+defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS'] })                     // signed-out only: login, signup
+defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })                         // any signed-in visitor
+defineVisibility({                                                                // those groups only
   userGroupTypes: ['LOGGED_IN_USERS'],
   customGroups: ['00000000-0000-0000-0000-00000000000a'],
-}
-visibility: {                                                               // signed-out visitors AND those groups
+})
+defineVisibility({                                                                // signed-out visitors AND those groups
   userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'],
   customGroups: ['00000000-0000-0000-0000-00000000000a'],
-}
+})
 ```
 
 Everyone is both audiences, as in the first line above. A set names each audience at most once and is never empty — the type and the build both reject one that does not. `customGroups` never stands alone: it narrows the `LOGGED_IN_USERS` half of the set, so the rule still names that half, and one without `userGroupTypes` is a type error. Absent or empty it means **any** signed-in visitor, not "nobody".
@@ -80,20 +74,17 @@ Take every id in `customGroups` from `docs/user-groups.md`, which lists each gro
 ```tsx
 // src/routes/_app.tsx: guards every route under /_app
 import { Outlet, createFileRoute } from '@tanstack/react-router'
-import { definePage, guardRoute, pageHead } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
-const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] } })
+const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
 
 export const Route = createFileRoute('/_app')({
-  beforeLoad: guardRoute(pageSettings),
-  head: pageHead(pageSettings),
+  beforeLoad: guardRoute(visibility),
   component: () => <Outlet />,
 })
 ```
 
-A pathless layout like this one is not a page, so it needs no `title`.
-
-The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own settings too.
+The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own rule too.
 
 A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can _throw_ — a `customGroups` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
 
@@ -102,9 +93,9 @@ A thrown error renders in place of the guarded route's component. A shell layout
 `guardRoute` takes per-reason overrides as a second argument. A bare string is shorthand for a redirect.
 
 ```ts
-beforeLoad: guardRoute(pageSettings, { unauthenticated: '/marketing/sign-up' }),
-beforeLoad: guardRoute(pageSettings, { forbidden: { strategy: 'throw' } }),
-beforeLoad: guardRoute(pageSettings, {
+beforeLoad: guardRoute(visibility, { unauthenticated: '/marketing/sign-up' }),
+beforeLoad: guardRoute(visibility, { forbidden: { strategy: 'throw' } }),
+beforeLoad: guardRoute(visibility, {
   unauthenticated: { strategy: 'redirect', to: '/marketing/sign-up' },
   forbidden: { strategy: 'throw' },
 }),
@@ -151,19 +142,15 @@ That file covers every route at once; a route's own overrides win over it. A rul
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { definePage, guardRoute, isAccessError, isForbiddenError, pageHead } from '@softr/sdk'
+import { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
 
-const pageSettings = definePage({
-  visibility: {
-    userGroupTypes: ['LOGGED_IN_USERS'],
-    customGroups: ['00000000-0000-0000-0000-00000000000a'],
-  },
-  title: 'Billing',
+const visibility = defineVisibility({
+  userGroupTypes: ['LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
 })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(pageSettings),
-  head: pageHead(pageSettings),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
   errorComponent: ({ error }: { error: unknown }) => {
     if (isForbiddenError(error)) return <UpgradePrompt />
@@ -179,53 +166,25 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### Run the check and then keep going
 
-`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(pageSettings, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
 
 It also narrows `opts.context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
 
-```tsx
-import { createFileRoute, redirect } from '@tanstack/react-router'
-import { assertRouteAccess, definePage, pageHead } from '@softr/sdk'
-
-const pageSettings = definePage({
-  visibility: { userGroupTypes: ['LOGGED_IN_USERS'] },
-  title: 'Reports',
-})
+```ts
+import { redirect } from '@tanstack/react-router'
+import { assertRouteAccess } from '@softr/sdk'
 
-export const Route = createFileRoute('/_app/reports')({
-  beforeLoad: (opts) => {
-    assertRouteAccess(pageSettings, opts)
-    if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
-  },
-  head: pageHead(pageSettings),
-  component: Reports,
-})
+beforeLoad: (opts) => {
+  assertRouteAccess(visibility, opts)
+  if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
+},
 ```
 
 Take `opts` whole. A `context` destructured in the parameter list does not narrow.
 
-`guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks.
-
-### Check a rule without a throw
-
-`isAuthorized(rule, context)` and `checkAccess(rule, context)` answer the same question and throw nothing, so they work anywhere: in a loader, a component or a server function. They take a rule from `defineVisibility`, not a page. Use `isAuthorized` for the same narrowing of `context.user` as `assertRouteAccess`, and `checkAccess` to branch on why: it returns `{ ok: true } | { ok: false, reason }`. All of them are synchronous and make no request.
-
-```tsx
-import { defineVisibility, isAuthorized, useCurrentUser } from '@softr/sdk'
-
-const staffOnly = defineVisibility({
-  userGroupTypes: ['LOGGED_IN_USERS'],
-  customGroups: ['00000000-0000-0000-0000-00000000000a'],
-})
-
-function StaffNote() {
-  const context = { user: useCurrentUser() }
-  if (!isAuthorized(staffOnly, context)) return null
-  return <p>Signed in as staff: {context.user.email}</p>
-}
-```
+Reach for `assertRouteAccess` when the route wants the error thrown for it, `isAuthorized(visibility, context)` when it wants the same narrowing without a throw, and `checkAccess(visibility, context)` when it needs to branch on why. `checkAccess` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
 
-To show or hide a part of a page, `Audience` is simpler: see [region-visibility/SKILL.md](../region-visibility/SKILL.md).
+`guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.
 
 ## References
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.88-signing.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.