@softr/sdk 0.0.87-alpha.3 → 0.0.87

package/dist/codegen/datasource-docs.js

@@ -73,15 +73,16 @@ function renderUserPropertiesDoc(users, context) {
 		"",
 		"```tsx",
 		"import { createFileRoute, redirect } from '@tanstack/react-router'",
-		"import { assertRouteAccess, defineVisibility } from '@softr/sdk'",
+		"import { assertRouteAccess, definePage, pageHead } from '@softr/sdk'",
 		"",
-		"const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })",
+		"const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] }, title: 'Example' })",
 		"",
 		"export const Route = createFileRoute('/example')({",
 		"  beforeLoad: (opts) => {",
-		"    assertRouteAccess(visibility, opts)",
+		"    assertRouteAccess(pageSettings, opts)",
 		`    if (opts.context.user.properties.${first} == null) throw redirect({ to: '/' })`,
 		"  },",
+		"  head: pageHead(pageSettings),",
 		"})",
 		"```",
 		"",
@@ -90,14 +91,19 @@ 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/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react2 from "react";
+import * as react6 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react2.JSX.Element;
+}: Props): react6.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/formatting.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import * as react3 from "react";
+import * as react0 from "react";
 import { ReactNode } from "react";
 
 //#region src/formatting.d.ts
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react3.FunctionComponentElement<react3.ProviderProps<Scope>>;
+}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react3.FunctionComponentElement<react3.FragmentProps>;
+}): react0.FunctionComponentElement<react0.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/index.d.ts

@@ -16,7 +16,5 @@ import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-import { Agent, AgentChatSummary, listAgents } from "./agent/agent-fns.js";
-import { AgentBlock, AgentChat, AgentChatOptions, AgentMessage, AgentQuestion, AgentTodo, AgentToolCall, useAgentChat } from "./agent/use-agent-chat.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, type Agent, type AgentBlock, type AgentChat, type AgentChatOptions, type AgentChatSummary, type AgentMessage, type AgentQuestion, type AgentTodo, type AgentToolCall, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, listAgents, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -12,8 +12,6 @@ import { fieldShape, formatDuration, formatField, formatValue, registerSoftrFiel
 import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-import { listAgents } from "./agent/agent-fns.js";
-import { useAgentChat } from "./agent/use-agent-chat.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, listAgents, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/mcp.js

@@ -385,10 +385,8 @@ async function rpc(request, origin, actions) {
 	const token = bearerToken(request);
 	if (token === null) return unauthorized(origin);
 	const session = await platformSession(token);
-	let sessionToken;
-	if (session.ok) sessionToken = session.sessionToken;
-	else if (session.refused && await resolveUser(token) !== null) sessionToken = token;
-	else return session.refused ? unauthorized(origin) : unavailable();
+	if (!session.ok) return session.refused ? unauthorized(origin) : unavailable();
+	const { sessionToken } = session;
 	const body = await readJson(request);
 	const message = z.object({
 		id: z.union([z.string(), z.number()]).optional(),

package/dist/package.js

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

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react4 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(): react4.FunctionComponentElement<react4.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.87-alpha.3",
+  "version": "0.0.87",
   "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-alpha.3
+  library_version: 0.0.87
 ---
 
 # 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 audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
+> **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**: 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`, `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`, `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/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -48,7 +48,6 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
-| Let visitors chat with a Softr agent | [agent-chat/SKILL.md](./agent-chat/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
 
@@ -85,9 +84,6 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
-Adding a chat with one of the app's Softr agents?
-  load softr-sdk/agent-chat
-
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 # The current user
@@ -55,12 +55,16 @@ It returns `User | null` and never suspends or fetches. It selects off root rout
 
 ```tsx
 export const Route = createFileRoute('/_app/invoices')({
-  beforeLoad: guardRoute(visibility),
-  loader: ({ context }) => fetchInvoicesFor({ data: { userId: context.user!.id } }),
+  beforeLoad: guardRoute(pageSettings),
+  loader: (opts) => {
+    assertRouteAccess(pageSettings, opts)
+    return fetchInvoicesFor({ data: { userId: opts.context.user.id } })
+  },
+  head: pageHead(pageSettings),
 })
 ```
 
-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).
+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).
 
 ### In a server function: `context`
 
@@ -94,7 +98,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): `isAuthorized` narrows `context.user` while applying the route's rule
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `assertRouteAccess` 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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 # 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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 # 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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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, as it is in a route's visibility.
+- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error.
 - 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-alpha.3
+  library_version: 0.0.87
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
@@ -47,11 +47,9 @@ 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, 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.
+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.
 
-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.
+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).
 
 ### Hiding a control is not authorization
 

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

@@ -1,21 +1,22 @@
 ---
 name: routes-and-visibility
 description: >-
-  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.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.3
+  library_version: 0.0.87
 ---
 
-**Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
+**Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
 
 # Route visibility
 
-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.
+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.
 
 ## Setup
 
@@ -23,12 +24,16 @@ Every route file, without exception, looks like this:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility, guardRoute } from '@softr/sdk'
+import { definePage, guardRoute, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
+const pageSettings = definePage({
+  visibility: { userGroupTypes: ['LOGGED_IN_USERS'] },
+  title: 'Billing',
+})
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: Billing,
 })
 
@@ -37,30 +42,31 @@ function Billing() {
 }
 ```
 
-The route's rule is one `defineVisibility` call at module scope, with an inline object literal as its argument.
+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.
 
-Four constraints on that shape, because Softr reads the file rather than running it:
+These constraints hold, 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`.
-- 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.
+- 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.
 
 `userGroupTypes` is a set, so a rule names one audience or several:
 
 ```ts
-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
+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
   userGroupTypes: ['LOGGED_IN_USERS'],
   customGroups: ['00000000-0000-0000-0000-00000000000a'],
-})
-defineVisibility({                                                                // signed-out visitors AND those groups
+}
+visibility: {                                                               // 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".
@@ -74,17 +80,20 @@ 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 { defineVisibility, guardRoute } from '@softr/sdk'
+import { definePage, guardRoute, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
+const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] } })
 
 export const Route = createFileRoute('/_app')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: () => <Outlet />,
 })
 ```
 
-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 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.
 
 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.
 
@@ -93,9 +102,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(visibility, { unauthenticated: '/marketing/sign-up' }),
-beforeLoad: guardRoute(visibility, { forbidden: { strategy: 'throw' } }),
-beforeLoad: guardRoute(visibility, {
+beforeLoad: guardRoute(pageSettings, { unauthenticated: '/marketing/sign-up' }),
+beforeLoad: guardRoute(pageSettings, { forbidden: { strategy: 'throw' } }),
+beforeLoad: guardRoute(pageSettings, {
   unauthenticated: { strategy: 'redirect', to: '/marketing/sign-up' },
   forbidden: { strategy: 'throw' },
 }),
@@ -142,15 +151,19 @@ 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 { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
+import { definePage, guardRoute, isAccessError, isForbiddenError, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({
-  userGroupTypes: ['LOGGED_IN_USERS'],
-  customGroups: ['00000000-0000-0000-0000-00000000000a'],
+const pageSettings = definePage({
+  visibility: {
+    userGroupTypes: ['LOGGED_IN_USERS'],
+    customGroups: ['00000000-0000-0000-0000-00000000000a'],
+  },
+  title: 'Billing',
 })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: Billing,
   errorComponent: ({ error }: { error: unknown }) => {
     if (isForbiddenError(error)) return <UpgradePrompt />
@@ -166,25 +179,53 @@ 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(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.
+`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.
 
 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.
 
-```ts
-import { redirect } from '@tanstack/react-router'
-import { assertRouteAccess } from '@softr/sdk'
+```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',
+})
 
-beforeLoad: (opts) => {
-  assertRouteAccess(visibility, opts)
-  if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
-},
+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,
+})
 ```
 
 Take `opts` whole. A `context` destructured in the parameter list does not narrow.
 
-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.
+`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>
+}
+```
 
-`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.
+To show or hide a part of a page, `Audience` is simpler: see [region-visibility/SKILL.md](../region-visibility/SKILL.md).
 
 ## 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-alpha.3
+  library_version: 0.0.87
 ---
 
 **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.

package/dist/agent/agent-fns.d.ts

@@ -1,30 +0,0 @@
-import { z } from "zod";
-import * as _tanstack_react_start7 from "@tanstack/react-start";
-
-//#region src/agent/agent-fns.d.ts
-
-declare const agentSchema: z.ZodObject<{
-  id: z.ZodString;
-  title: z.ZodString;
-  avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-  thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-/** An agent the visitor may chat with. */
-type Agent = z.infer<typeof agentSchema>;
-/**
- * The agents the visitor may chat with in this app. The builder attaches them
- * in Studio, and each one's visibility settings decide who sees it.
- */
-declare const listAgents: _tanstack_react_start7.OptionalFetcher<undefined, undefined, Promise<{
-  id: string;
-  title: string;
-  avatar?: string | null | undefined;
-  thumbnail?: string | null | undefined;
-}[]>>;
-/** One past chat with an agent. */
-type AgentChatSummary = {
-  id: string;
-  title: string;
-};
-//#endregion
-export { Agent, AgentChatSummary, listAgents };