@softr/sdk 0.0.45-alpha.0 → 0.0.45-alpha.3

package/dist/visibility/visibility.js

@@ -0,0 +1,63 @@
+//#region src/visibility/visibility.ts
+/**
+* Why a visitor was denied.
+*
+* - `unauthenticated` — the route needs a signed-in visitor and there is none.
+* - `forbidden` — signed in, but in none of the groups the route names.
+* - `alreadyAuthenticated` — the route is for signed-out visitors only.
+*/
+const ACCESS_REASONS = [
+	"unauthenticated",
+	"forbidden",
+	"alreadyAuthenticated"
+];
+/** The decision and, when a visitor is denied, the reason. Throws nothing. */
+function checkAccess(visibility, context) {
+	const { user } = context;
+	switch (visibility.userGroup) {
+		case "ALL_USERS": return { ok: true };
+		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
+			ok: false,
+			reason: "alreadyAuthenticated"
+		};
+		case "LOGGED_IN_USERS": {
+			if (user === null) return {
+				ok: false,
+				reason: "unauthenticated"
+			};
+			const required = visibility.userGroupIds ?? [];
+			if (required.length === 0) return { ok: true };
+			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
+				ok: false,
+				reason: "forbidden"
+			};
+		}
+	}
+}
+/**
+* Declares who may see a route or a region of the page.
+*
+* At module scope in a route file, with a literal rule: the build reads these
+* declarations out of the source to publish the app's route visibility.
+*
+* @example
+* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+*
+* export const Route = createFileRoute("/about")({
+*   beforeLoad: guardRoute(visibility),
+*   component: About,
+* })
+*/
+function defineVisibility(rule) {
+	return rule;
+}
+/**
+* Whether the visitor passes the rule, narrowing `context.user` where the rule
+* allows it. Throws nothing, so it is safe in a component.
+*/
+function isAuthorized(visibility, context) {
+	return checkAccess(visibility, context).ok;
+}
+
+//#endregion
+export { ACCESS_REASONS, checkAccess, defineVisibility, isAuthorized };

package/package.json

@@ -1,37 +1,16 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.45-alpha.0",
+  "version": "0.0.45-alpha.3",
   "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/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
 # Softr SDK core
@@ -19,8 +19,8 @@ metadata:
 `@softr/sdk` is how a Softr application talks to Softr. The visitor's identity, who may see a route, records in a datasource, signing in: all of it goes through this package. Everything else is an ordinary TanStack Start app. Routes, server functions, loaders and middleware are Start's, not Softr's.
 
 > **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`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
-> **CRITICAL**: The session wiring is already in place. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the visitor. 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.
+> **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 the middleware and resolve the session. Do not add a second registration.
 > **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.
@@ -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`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `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` |
@@ -39,14 +39,14 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Task | Sub-Skill |
 | --- | --- |
 | Add a route, or change who can see one | [routes-and-visibility/SKILL.md](./routes-and-visibility/SKILL.md) |
-| Read the signed-in visitor or what they may do | [current-user/SKILL.md](./current-user/SKILL.md) |
+| Show part of a page to some visitors only | [region-visibility/SKILL.md](./region-visibility/SKILL.md) |
+| Read the signed-in visitor | [current-user/SKILL.md](./current-user/SKILL.md) |
 | Fetch records from a datasource | [record-queries/SKILL.md](./record-queries/SKILL.md) |
 | Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/SKILL.md) |
 | Trigger a Softr workflow | [workflows/SKILL.md](./workflows/SKILL.md) |
 | 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) |
 
 ## Quick Decision Tree
 
@@ -54,7 +54,10 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 Adding a page, or changing who may see one?
   load softr-sdk/routes-and-visibility
 
-Showing the visitor's name, or hiding UI they cannot use?
+Hiding a region of a page from some visitors?
+  load softr-sdk/region-visibility
+
+Showing the visitor's name, email or groups?
   load softr-sdk/current-user
 
 Putting records on a page, in a table, a list or a detail view?
@@ -75,16 +78,13 @@ Wiring a login, signup, or sign-out?
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
-Opening the app to an AI assistant over MCP?
-  load softr-sdk/mcp
-
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```
 
 ## The wiring
 
-Already present in the app. Read it to understand where the visitor comes from. Do not recreate it. `softrMcpMiddleware` is the exception: it is not wired by default and is added here when the app opens itself to AI assistants.
+Already present in the app. Read it to understand where the visitor comes from. Do not recreate it.
 
 ```ts
 // src/start.ts: resolves the visitor once per request
@@ -127,7 +127,6 @@ export function getRouter() {
 ```ts
 type SoftrContext = {
   user: User | null                                   // null means signed out
-  permissions: { datasources: Record<string, DatasourcePermissions> }
 }
 
 type User = {

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

@@ -16,10 +16,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
 
 # Auth
 

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

@@ -12,10 +12,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Charts and metrics
 

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

@@ -1,20 +1,17 @@
 ---
 name: current-user
 description: >-
-  Read the signed-in Softr visitor and what they may do: useCurrentUser and the
-  User type, usePermissions and DatasourcePermissions, 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,
-  SoftrUserGroups module augmentation for narrowing group ids, and why
-  permissions are a rendering hint rather than an authorization check.
+  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 and the SoftrUserGroups module augmentation
+  that narrows group ids to your own.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
-
 # The current user
 
 One visitor is resolved once per request and published three ways: as a hook in components, as route context in `beforeLoad`, and on the `context` argument inside a server function. All three read the same `SoftrContext`. Which one you reach for depends only on where the code runs.
@@ -24,7 +21,7 @@ One visitor is resolved once per request and published three ways: as a hook in
 Nothing to install or register, since the app is already wired. Import from the root entrypoint:
 
 ```ts
-import { useCurrentUser, usePermissions } from '@softr/sdk'
+import { useCurrentUser } from '@softr/sdk'
 import type { User } from '@softr/sdk'
 ```
 
@@ -56,12 +53,12 @@ It returns `User | null` and never suspends or fetches. It selects off root rout
 
 ```tsx
 export const Route = createFileRoute('/_app/invoices')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   loader: ({ context }) => fetchInvoicesFor({ data: { userId: context.user!.id } }),
 })
 ```
 
-A `guard()` 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. `visibility.isAuthorized(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` 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`
 
@@ -85,24 +82,7 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 })
 ```
 
-`context.user` and `context.permissions` are typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
-
-### Hiding UI the visitor cannot use
-
-```tsx
-import { usePermissions } from '@softr/sdk'
-
-const INVOICES = '00000000-0000-0000-0000-000000000001' // the registered datasource's id
-
-function NewInvoiceButton() {
-  const { create } = usePermissions(INVOICES)
-  return create ? <button>New invoice</button> : null
-}
-```
-
-`usePermissions(datasourceId)` returns `{ read, create, update, delete }` for one datasource. The id is the opaque UUID from the table's registration on the application, the same one `ds.*` takes — not the table id, and never built from the table's name. It hides a control. It does not protect what the control does.
-
-Pass an id the visitor's session has no entry for and it throws while rendering, so a typo takes the page down rather than returning four falses.
+`context.user` is typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
 
 ### Narrowing group ids to your own
 
@@ -122,6 +102,7 @@ With this declaration, `user.userGroupIds` and every `userGroupIds` the SDK acce
 
 ## 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): `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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
 **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/integrations/SKILL.md

@@ -9,10 +9,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Integrations
 

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

@@ -11,10 +11,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Writing records
 

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

@@ -13,10 +13,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Reading records
 
@@ -179,7 +179,7 @@ ds.list(products).where((q) => q.status.is(selectedStatusId))
 
 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. 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.
+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.
 
 ## Typing
 

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

@@ -0,0 +1,63 @@
+---
+name: region-visibility
+description: >-
+  Show part of a page only to the visitors a rule admits: the Audience
+  component, its children and fallback, where a region's rule may be declared,
+  and why hiding a control is not authorization. Use when a button, a column, a
+  nav item or a panel should appear for some visitors and not others, on a page
+  everyone may open. Gating the whole route is routes-and-visibility.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.45
+---
+
+**Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
+
+# Region visibility
+
+A route's rule decides who may open the page. A region's rule decides what they see once they are on it. The two are independent: an admin panel on a page every signed-in visitor may open is a region, and so is a refund button only staff should reach for.
+
+## Setup
+
+Wrap the region in `Audience` and give it a rule:
+
+```tsx
+import { Audience, defineVisibility } from '@softr/sdk'
+
+const staffOnly = defineVisibility({
+  userGroup: 'LOGGED_IN_USERS',
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
+})
+
+function InvoiceActions({ invoice }: { invoice: Invoice }) {
+  return (
+    <Audience visibility={staffOnly} fallback={<p>Contact your account manager to refund.</p>}>
+      <RefundButton invoice={invoice} />
+    </Audience>
+  )
+}
+```
+
+`Audience` renders its children for the visitors the rule admits and `fallback` for everyone else. Without a `fallback` it renders nothing.
+
+The rules are the same four a route uses, and [routes-and-visibility](../routes-and-visibility/SKILL.md) covers them.
+
+## Core Patterns
+
+### 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.
+
+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
+
+`Audience` decides what to render and nothing else. The server function behind a hidden button is still reachable on its own, and Softr authorizes that request whatever the page rendered. If a region hides something sensitive, declare the action behind it with the permissions it should have.
+
+## References
+
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): the rule shapes, and gating a whole page
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a rule has admitted

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

@@ -3,19 +3,20 @@ name: routes-and-visibility
 description: >-
   Add a route file to a Softr app and declare who may see it: defineVisibility
   with ALL_USERS, LOGGED_IN_USERS or NON_LOGGED_IN_USERS, userGroupIds, and the
-  four ways to enforce a rule (guard, assert, isAuthorized, check). Covers
-  per-reason overrides, the redirect and throw strategies, rendering an access
-  error with isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
-  requires a declaration alongside the rules that reject a duplicate, computed
-  or root-level one.
+  ways to apply a rule: guardRoute and assertRouteAccess in a route,
+  isAuthorized and checkAccess anywhere. Covers per-reason overrides, the
+  redirect and throw strategies, rendering an access error with
+  isAccessError, isUnauthenticatedError, isForbiddenError and
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
+  declaration alongside the rules that reject a duplicate, computed or
+  root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
 
 # Route visibility
 
@@ -27,12 +28,12 @@ Every route file, without exception, looks like this:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
 const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
 })
 
@@ -41,12 +42,13 @@ function Billing() {
 }
 ```
 
-One `defineVisibility` call per file, at module scope, with an inline object literal as its argument.
+The route's rule is one `defineVisibility` call at module scope, with an inline object literal as its argument.
 
-Three rules about that shape, 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`.
+- The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
 - 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.
 
 The four rules:
@@ -70,28 +72,28 @@ Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
 ```tsx
 // src/routes/_app.tsx: guards every route under /_app
 import { Outlet, createFileRoute } from '@tanstack/react-router'
-import { defineVisibility } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
 const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
 
 export const Route = createFileRoute('/_app')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   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. Routes below a guarded layout still declare their own rule, because the declaration is what Studio reads.
+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 `userGroupIds` 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.
 
 ### Change what a denied visitor gets
 
-`guard()` takes per-reason overrides. A bare string is shorthand for a redirect.
+`guardRoute` takes per-reason overrides as a second argument. A bare string is shorthand for a redirect.
 
 ```ts
-beforeLoad: visibility.guard({ unauthenticated: '/marketing/sign-up' }),
-beforeLoad: visibility.guard({ forbidden: { strategy: 'throw' } }),
-beforeLoad: visibility.guard({
+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' },
 }),
@@ -122,13 +124,13 @@ All three reasons are required, because nothing fills in a reason the file leave
 | `forbidden` | Signed in, in none of the named groups |
 | `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route |
 
-That file covers every route at once; a route's own `guard()` overrides win over it. `ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
+That file covers every route at once; a route's own overrides win over it. `ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
 
 ### Render the error in place
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility, isAccessError, isForbiddenError } from '@softr/sdk'
+import { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
 
 const visibility = defineVisibility({
   userGroup: 'LOGGED_IN_USERS',
@@ -136,7 +138,7 @@ const visibility = defineVisibility({
 })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
   errorComponent: ({ error }: { error: unknown }) => {
     if (isForbiddenError(error)) return <UpgradePrompt />
@@ -152,24 +154,27 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### Run the check and then keep going
 
-`guard()` covers almost everything. When a route needs its own logic afterwards, `assert()` applies the same rule and throws the same access error, using `softr.json` for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, context)` applies the same rule and throws the same access error, using the default behaviour for each reason. It takes no overrides.
 
-`assert()` guarantees the visitor at runtime but does not narrow `context.user` for the compiler. `isAuthorized()` is the one that narrows. It is a type predicate, so inside its `true` branch `context.user` is `User` under `LOGGED_IN_USERS` and `null` under `NON_LOGGED_IN_USERS`.
+It also narrows `context.user` for the rest of the handler: `User` under `LOGGED_IN_USERS`, `null` under `NON_LOGGED_IN_USERS`. `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'
 
 beforeLoad: ({ context }) => {
-  if (visibility.isAuthorized(context)) {
-    if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
-  }
+  assertRouteAccess(visibility, context)
+  if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
 },
 ```
 
-Reach for `assert()` when the route wants the error thrown for it, and `check(context)` when it needs to branch on why. `check` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
+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. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.
 
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a guard has just admitted
 - [record-queries/SKILL.md](../record-queries/SKILL.md): a guard covers the page, not the server function behind it
 - [auth/SKILL.md](../auth/SKILL.md): `NON_LOGGED_IN_USERS` and the sign-in flow it fronts
+- [region-visibility/SKILL.md](../region-visibility/SKILL.md): showing part of a page to some of the visitors the route admits

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

@@ -9,10 +9,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Triggering workflows