@softr/sdk 0.0.44 → 0.0.45-alpha.1

package/dist/auth/context.d.ts

@@ -6,7 +6,7 @@ import { Permissions } from "./permissions.js";
 type Session = {
   /** The visitor, or `null` when signed out. */
   user: User | null;
-  /** What the visitor may do, signed in or not. */
+  /** The visitor's global data restrictions. An escape hatch; the SDK already checks them. */
   permissions: Permissions;
 };
 /**

package/dist/auth/isomorphic.d.ts

@@ -1,5 +1,5 @@
 import { User } from "./user.js";
-import { DatasourcePermissions, Permissions } from "./permissions.js";
+import { Permissions } from "./permissions.js";
 import { Session, SoftrContext } from "./context.js";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 
@@ -51,22 +51,5 @@ declare function initialSoftrContext(): SoftrContext;
  * }
  */
 declare function useCurrentUser(): User | null;
-/**
- * Resolves what the current user may do with one datasource.
- *
- * A rendering hint: every request is authorized again on the server, so never
- * let this stand in for a permission check.
- *
- * Requires the root route to resolve {@link getSoftrContext}.
- *
- * @example
- * function NewRecordButton() {
- *   const { create } = usePermissions(datasourceId)
- *   return create ? <button>New record</button> : null
- * }
- *
- * @throws if the application has no such datasource.
- */
-declare function usePermissions(datasourceId: string): DatasourcePermissions;
 //#endregion
-export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser };

package/dist/auth/isomorphic.js

@@ -1,4 +1,4 @@
-import { assert, panic, requireDefined } from "../assertions.js";
+import { assert, panic } from "../assertions.js";
 import { writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
@@ -87,28 +87,6 @@ function useCurrentUser() {
 		select: (context) => context.user
 	});
 }
-/**
-* Resolves what the current user may do with one datasource.
-*
-* A rendering hint: every request is authorized again on the server, so never
-* let this stand in for a permission check.
-*
-* Requires the root route to resolve {@link getSoftrContext}.
-*
-* @example
-* function NewRecordButton() {
-*   const { create } = usePermissions(datasourceId)
-*   return create ? <button>New record</button> : null
-* }
-*
-* @throws if the application has no such datasource.
-*/
-function usePermissions(datasourceId) {
-	return useRouteContext({
-		from: rootRouteId,
-		select: (context) => requireDefined(context.permissions.datasources[datasourceId], `the application has no datasource "${datasourceId}"`)
-	});
-}
 
 //#endregion
-export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser };

package/dist/auth/permissions.d.ts

@@ -19,4 +19,4 @@ type Permissions = {
   datasources: Record<string, DatasourcePermissions>;
 };
 //#endregion
-export { DatasourcePermissions, Permissions };
+export { Permissions };

package/dist/index.d.ts

@@ -3,8 +3,10 @@ import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation,
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { SoftrContext } from "./auth/context.js";
-import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
-import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
+import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
+import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+import { Audience } from "./visibility/audience.js";
+export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -1,8 +1,10 @@
 import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
-import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
-import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
+import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
+import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
+import { Audience } from "./visibility/audience.js";
 
-export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/package.js

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

package/dist/visibility/audience.d.ts

@@ -0,0 +1,31 @@
+import { Visibility } from "./visibility.js";
+import { ReactNode } from "react";
+
+//#region src/visibility/audience.d.ts
+type Props = {
+  visibility: Visibility;
+  children: ReactNode;
+  fallback?: ReactNode;
+};
+/**
+ * Renders `children` to the visitors a rule admits, and `fallback` to the rest.
+ *
+ * Use it to hide parts of the tree. The UI for visibility is accessible by the
+ * builder in Studio.
+ *
+ * Requires the root route to resolve {@link getSoftrContext}.
+ *
+ * @example
+ * const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ *
+ * <Audience visibility={membersOnly} fallback={<Upgrade />}>
+ *   <DangerZone />
+ * </Audience>
+ */
+declare function Audience({
+  visibility,
+  children,
+  fallback
+}: Props): ReactNode;
+//#endregion
+export { Audience };

package/dist/visibility/audience.js

@@ -0,0 +1,25 @@
+import { checkAccess } from "./visibility.js";
+import { useCurrentUser } from "../auth/isomorphic.js";
+
+//#region src/visibility/audience.tsx
+/**
+* Renders `children` to the visitors a rule admits, and `fallback` to the rest.
+*
+* Use it to hide parts of the tree. The UI for visibility is accessible by the
+* builder in Studio.
+*
+* Requires the root route to resolve {@link getSoftrContext}.
+*
+* @example
+* const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+*
+* <Audience visibility={membersOnly} fallback={<Upgrade />}>
+*   <DangerZone />
+* </Audience>
+*/
+function Audience({ visibility, children, fallback = null }) {
+	return checkAccess(visibility, { user: useCurrentUser() }).ok ? children : fallback;
+}
+
+//#endregion
+export { Audience };

package/dist/visibility/route.d.ts

@@ -0,0 +1,71 @@
+import { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule } from "./visibility.js";
+
+//#region src/visibility/route.d.ts
+
+/**
+ * What a guard does when it denies a visitor: redirect to a path, or throw an
+ * {@link AccessError} for the route's `errorComponent` to render. A bare string
+ * is shorthand for redirecting there.
+ */
+type AccessBehaviour = string | {
+  strategy: "redirect";
+  to: string;
+} | {
+  strategy: "throw";
+};
+/** Per-reason overrides of the default {@link AccessBehaviour}. */
+type GuardOverrides = Partial<Record<AccessReason, AccessBehaviour>>;
+/**
+ * The access error a guard throws. It is plain data, not an `Error` subclass, so
+ * take it as `unknown` in an `errorComponent` and narrow it with
+ * {@link isAccessError}. It carries the reason and nothing else: the error is
+ * serialized into the page, so it never names the groups the route wanted.
+ *
+ * @example
+ * errorComponent: ({ error }: { error: unknown }) =>
+ *   isAccessError(error) ? <NoAccess /> : <AppError />
+ */
+type AccessError = {
+  type: "access_error";
+  reason: AccessReason;
+};
+/**
+ * True for any access error thrown by a guard, whatever its reason.
+ *
+ * An access error arrives as `unknown` — hydrated from the page, or thrown by
+ * anything else at all — so every field is checked before it is narrowed.
+ */
+declare function isAccessError(error: unknown): error is AccessError;
+/** True for an access error thrown because nobody was signed in. */
+declare function isUnauthenticatedError(error: unknown): error is AccessError;
+/** True for an access error thrown because the visitor was in none of the groups. */
+declare function isForbiddenError(error: unknown): error is AccessError;
+/** True for an access error thrown because a signed-out-only route saw a user. */
+declare function isAlreadyAuthenticatedError(error: unknown): error is AccessError;
+/**
+ * A `beforeLoad` handler that denies a visitor who fails the rule.
+ *
+ * Each reason falls back to the app's configured behaviour. Pass `overrides` to
+ * change what any one reason does.
+ *
+ * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
+ *
+ * @example
+ * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+ */
+declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides): (opts: {
+  context: AccessContext;
+}) => void;
+/**
+ * Throws what {@link guardRoute} would, for a `beforeLoad` that runs its own
+ * checks after the rule. It takes no overrides.
+ *
+ * @example
+ * beforeLoad: ({ context, params }) => {
+ *   assertRouteAccess(visibility, context)
+ *   if (params.projectId === "demo") throw redirect({ to: "/projects" })
+ * }
+ */
+declare function assertRouteAccess<R extends VisibilityRule>(visibility: Visibility<R>, context: AccessContext): asserts context is Narrowed<R>;
+//#endregion
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/visibility/route.js

@@ -0,0 +1,83 @@
+import { panic } from "../assertions.js";
+import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { redirect } from "@tanstack/react-router";
+
+//#region src/visibility/route.ts
+function isAccessReason(value) {
+	return ACCESS_REASONS.some((reason) => reason === value);
+}
+/**
+* True for any access error thrown by a guard, whatever its reason.
+*
+* An access error arrives as `unknown` — hydrated from the page, or thrown by
+* anything else at all — so every field is checked before it is narrowed.
+*/
+function isAccessError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (!("type" in error) || error.type !== "access_error") return false;
+	return "reason" in error && isAccessReason(error.reason);
+}
+function isReason(error, reason) {
+	return isAccessError(error) && error.reason === reason;
+}
+/** True for an access error thrown because nobody was signed in. */
+function isUnauthenticatedError(error) {
+	return isReason(error, "unauthenticated");
+}
+/** True for an access error thrown because the visitor was in none of the groups. */
+function isForbiddenError(error) {
+	return isReason(error, "forbidden");
+}
+/** True for an access error thrown because a signed-out-only route saw a user. */
+function isAlreadyAuthenticatedError(error) {
+	return isReason(error, "alreadyAuthenticated");
+}
+/** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
+function thrownFor(reason, overrides) {
+	const behaviour = overrides?.[reason] ?? (typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing, so no guard behaviour is configured") : __SOFTR_CONFIG__.auth.guard[reason]);
+	const resolved = typeof behaviour === "string" ? {
+		strategy: "redirect",
+		to: behaviour
+	} : behaviour;
+	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
+	return {
+		type: "access_error",
+		reason
+	};
+}
+/**
+* A `beforeLoad` handler that denies a visitor who fails the rule.
+*
+* Each reason falls back to the app's configured behaviour. Pass `overrides` to
+* change what any one reason does.
+*
+* Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
+*
+* @example
+* beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+*/
+function guardRoute(visibility, overrides) {
+	return ({ context }) => {
+		const result = checkAccess(visibility, context);
+		if (result.ok) return;
+		throw thrownFor(result.reason, overrides);
+	};
+}
+/**
+* Throws what {@link guardRoute} would, for a `beforeLoad` that runs its own
+* checks after the rule. It takes no overrides.
+*
+* @example
+* beforeLoad: ({ context, params }) => {
+*   assertRouteAccess(visibility, context)
+*   if (params.projectId === "demo") throw redirect({ to: "/projects" })
+* }
+*/
+function assertRouteAccess(visibility, context) {
+	const result = checkAccess(visibility, context);
+	if (result.ok) return;
+	throw thrownFor(result.reason, void 0);
+}
+
+//#endregion
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/visibility/visibility.d.ts

@@ -0,0 +1,76 @@
+import { SoftrUserGroupId, User } from "../auth/user.js";
+import { SoftrContext } from "../auth/context.js";
+
+//#region src/visibility/visibility.d.ts
+
+/**
+ * Who may see a route.
+ *
+ * - `ALL_USERS` — everyone, signed in or not.
+ * - `NON_LOGGED_IN_USERS` — signed-out visitors only.
+ * - `LOGGED_IN_USERS` — signed-in visitors; with `userGroupIds`, only members of
+ *   at least one of those groups.
+ */
+type VisibilityRule = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+declare const visibilityBrand: unique symbol;
+/** A rule {@link defineVisibility} has produced. */
+type Visibility<R extends VisibilityRule = VisibilityRule> = R & {
+  readonly [visibilityBrand]: "visibility";
+};
+/**
+ * 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.
+ */
+declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadyAuthenticated"];
+type AccessReason = (typeof ACCESS_REASONS)[number];
+type AccessCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reason: AccessReason;
+};
+/** The one field of {@link SoftrContext} every access check reads. */
+type AccessContext = Pick<SoftrContext, "user">;
+/** The decision and, when a visitor is denied, the reason. Throws nothing. */
+declare function checkAccess(visibility: Visibility, context: AccessContext): AccessCheck;
+type Narrowed<R extends VisibilityRule> = R extends {
+  userGroup: "LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: User;
+} : R extends {
+  userGroup: "NON_LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: null;
+} : AccessContext;
+/**
+ * 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,
+ * })
+ */
+declare function defineVisibility<const R extends VisibilityRule>(rule: R): Visibility<R>;
+/**
+ * Whether the visitor passes the rule, narrowing `context.user` where the rule
+ * allows it. Throws nothing, so it is safe in a component.
+ */
+declare function isAuthorized<R extends VisibilityRule>(visibility: Visibility<R>, context: AccessContext): context is Narrowed<R>;
+//#endregion
+export { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule, checkAccess, defineVisibility, isAuthorized };

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,16 +1,37 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.44",
+  "version": "0.0.45-alpha.1",
   "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",
@@ -42,7 +63,9 @@
       "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,7 +19,7 @@ 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**: 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.
 
@@ -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,7 +39,8 @@ 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) |
@@ -53,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?
@@ -123,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
 

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
 

package/dist/routes/visibility.d.ts

@@ -1,142 +0,0 @@
-import { SoftrUserGroupId, User } from "../auth/user.js";
-import { SoftrContext } from "../auth/context.js";
-
-//#region src/routes/visibility.d.ts
-
-/**
- * Who may see a route.
- *
- * - `ALL_USERS` — everyone, signed in or not.
- * - `NON_LOGGED_IN_USERS` — signed-out visitors only.
- * - `LOGGED_IN_USERS` — signed-in visitors; with `userGroupIds`, only members of
- *   at least one of those groups.
- */
-type RouteVisibility = {
-  userGroup: "ALL_USERS";
-} | {
-  userGroup: "NON_LOGGED_IN_USERS";
-} | {
-  userGroup: "LOGGED_IN_USERS";
-  userGroupIds?: Array<SoftrUserGroupId>;
-};
-/**
- * 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.
- */
-declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadyAuthenticated"];
-type AccessReason = (typeof ACCESS_REASONS)[number];
-/**
- * What a guard does when it refuses a visitor: redirect to a path, or throw an
- * {@link AccessError} for the route's `errorComponent` to render. A bare string
- * is shorthand for redirecting there.
- */
-type AccessBehaviour = string | {
-  strategy: "redirect";
-  to: string;
-} | {
-  strategy: "throw";
-};
-/** Per-reason overrides of the default {@link AccessBehaviour}. */
-type GuardOverrides = Partial<Record<AccessReason, AccessBehaviour>>;
-/** The result of {@link VisibilityHandle.check}: passed, or denied with a reason. */
-type AccessCheck = {
-  ok: true;
-} | {
-  ok: false;
-  reason: AccessReason;
-};
-/** The one field of {@link SoftrContext} every access check reads. */
-type AccessContext = Pick<SoftrContext, "user">;
-/** Decides whether a visitor passes a visibility rule, without throwing. */
-
-/**
- * The access error a guard throws. It is plain data, not an `Error` subclass, so
- * take it as `unknown` in an `errorComponent` and narrow it with
- * {@link isAccessError}. It carries the reason and nothing else: the error is
- * serialized into the page, so it never names the groups the route wanted.
- *
- * @example
- * errorComponent: ({ error }: { error: unknown }) =>
- *   isAccessError(error) ? <NoAccess /> : <AppError />
- */
-type AccessError = {
-  type: "access_error";
-  reason: AccessReason;
-};
-/**
- * True for any access error thrown by a guard, whatever its reason.
- *
- * An access error arrives as `unknown` — hydrated from the page, or thrown by
- * anything else at all — so every field is checked before it is narrowed.
- */
-declare function isAccessError(error: unknown): error is AccessError;
-/** True for an access error thrown because nobody was signed in. */
-declare function isUnauthenticatedError(error: unknown): error is AccessError;
-/** True for an access error thrown because the visitor was in none of the groups. */
-declare function isForbiddenError(error: unknown): error is AccessError;
-/** True for an access error thrown because a signed-out-only route saw a user. */
-declare function isAlreadyAuthenticatedError(error: unknown): error is AccessError;
-type Narrowed<R extends RouteVisibility> = R extends {
-  userGroup: "LOGGED_IN_USERS";
-} ? AccessContext & {
-  user: User;
-} : R extends {
-  userGroup: "NON_LOGGED_IN_USERS";
-} ? AccessContext & {
-  user: null;
-} : AccessContext;
-/** The four ways to apply a rule, returned by {@link defineVisibility}. */
-type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
-  /**
-   * A `beforeLoad` handler that denies a visitor who fails the rule.
-   *
-   * By default an unauthenticated visitor is redirected to `/login`, an already
-   * signed-in one to `/`, and a forbidden one gets an {@link AccessError} thrown
-   * in place, for the route's `errorComponent` to render. Pass `overrides` to
-   * change what any one reason does.
-   *
-   * @example
-   * beforeLoad: visibility.guard({ unauthenticated: "/sign-in" })
-   */
-  guard(overrides?: GuardOverrides): (opts: {
-    context: AccessContext;
-  }) => void;
-  /**
-   * Throws the same access error or redirect `guard()` would, for code that
-   * needs to run its own checks after the rule.
-   *
-   * @example
-   * beforeLoad: ({ context }) => {
-   *   visibility.assert(context)
-   *   if (context.user.trialExpired) throw redirect({ to: "/renew" })
-   * }
-   */
-  assert(context: AccessContext): void;
-  /**
-   * Whether the visitor passes the rule. Narrows `context.user` where the rule
-   * allows it.
-   */
-  isAuthorized(context: AccessContext): context is Narrowed<R>;
-  /** The decision and, when a visitor is refused, the reason. Throws nothing. */
-  check(context: AccessContext): AccessCheck;
-};
-/**
- * Declares who may see a route, and returns the handle that enforces it.
- *
- * One call per route file, at module scope: the build reads these declarations
- * to publish the app's route visibility, so the rule must be a literal.
- *
- * @example
- * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
- *
- * export const Route = createFileRoute("/about")({
- *   beforeLoad: visibility.guard(),
- *   component: About,
- * })
- */
-declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
-//#endregion
-export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/routes/visibility.js

@@ -1,115 +0,0 @@
-import { panic } from "../assertions.js";
-import { redirect } from "@tanstack/react-router";
-
-//#region src/routes/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"
-];
-/** Decides whether a visitor passes a visibility rule, without throwing. */
-function checkAccess(rule, context) {
-	const { user } = context;
-	switch (rule.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 = rule.userGroupIds ?? [];
-			if (required.length === 0) return { ok: true };
-			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
-				ok: false,
-				reason: "forbidden"
-			};
-		}
-	}
-}
-function isAccessReason(value) {
-	return ACCESS_REASONS.some((reason) => reason === value);
-}
-/**
-* True for any access error thrown by a guard, whatever its reason.
-*
-* An access error arrives as `unknown` — hydrated from the page, or thrown by
-* anything else at all — so every field is checked before it is narrowed.
-*/
-function isAccessError(error) {
-	if (typeof error !== "object" || error === null) return false;
-	const candidate = error;
-	if (candidate.type !== "access_error") return false;
-	return isAccessReason(candidate.reason);
-}
-function isReason(error, reason) {
-	return isAccessError(error) && error.reason === reason;
-}
-/** True for an access error thrown because nobody was signed in. */
-function isUnauthenticatedError(error) {
-	return isReason(error, "unauthenticated");
-}
-/** True for an access error thrown because the visitor was in none of the groups. */
-function isForbiddenError(error) {
-	return isReason(error, "forbidden");
-}
-/** True for an access error thrown because a signed-out-only route saw a user. */
-function isAlreadyAuthenticatedError(error) {
-	return isReason(error, "alreadyAuthenticated");
-}
-/** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
-function thrownFor(reason, overrides) {
-	const behaviour = overrides?.[reason] ?? (typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing, so no guard behaviour is configured") : __SOFTR_CONFIG__.auth.guard[reason]);
-	const resolved = typeof behaviour === "string" ? {
-		strategy: "redirect",
-		to: behaviour
-	} : behaviour;
-	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
-	return {
-		type: "access_error",
-		reason
-	};
-}
-/**
-* Declares who may see a route, and returns the handle that enforces it.
-*
-* One call per route file, at module scope: the build reads these declarations
-* to publish the app's route visibility, so the rule must be a literal.
-*
-* @example
-* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
-*
-* export const Route = createFileRoute("/about")({
-*   beforeLoad: visibility.guard(),
-*   component: About,
-* })
-*/
-function defineVisibility(rule) {
-	return {
-		guard: (overrides) => ({ context }) => {
-			const result = checkAccess(rule, context);
-			if (result.ok) return;
-			throw thrownFor(result.reason, overrides);
-		},
-		assert: (context) => {
-			const result = checkAccess(rule, context);
-			if (result.ok) return;
-			throw thrownFor(result.reason, void 0);
-		},
-		isAuthorized: (context) => checkAccess(rule, context).ok,
-		check: (context) => checkAccess(rule, context)
-	};
-}
-
-//#endregion
-export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };