@softr/sdk 0.0.45-alpha.0 → 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/auth/session.js

@@ -3,7 +3,6 @@ import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 import { z } from "zod";
 
@@ -36,20 +35,8 @@ function sessionCookie(base) {
 		secure
 	};
 }
-/**
-* Runs `fn` with `token` standing in for the request's session cookie, so that
-* every datasource call inside it acts as that visitor.
-*
-* For requests that carry who they are somewhere other than the cookie: an MCP
-* call authenticates with a bearer token and has no cookie at all.
-*/
-function withSessionToken(token, fn) {
-	return standInToken.run(token, fn);
-}
 /** The platform token this request carries, or `null`. */
 function readSessionToken() {
-	const standIn = standInToken.getStore();
-	if (standIn !== void 0) return standIn;
 	const { name } = sessionCookie(SESSION_TOKEN);
 	return openEnvelope(readRequestCookies()[name], SESSION_TOKEN);
 }
@@ -118,7 +105,6 @@ function clearSession() {
 		PENDING_AUTH
 	]);
 }
-const standInToken = new AsyncLocalStorage();
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
 	permissions: permissionsSchema,
@@ -210,4 +196,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };
+export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken };

package/dist/index.d.ts

@@ -3,9 +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 { softrMcpMiddleware } from "./mcp.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, softrMcpMiddleware, 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,9 +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 { softrMcpMiddleware } from "./mcp.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, softrMcpMiddleware, 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.45-alpha.0";
+var version = "0.0.45";
 
 //#endregion
 export { version };

package/dist/server.js

@@ -1,6 +1,6 @@
 import { upload } from "./core/file-upload.js";
-import { ds } from "./datasource/datasource.js";
 import { auth } from "./auth/server.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

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,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.45-alpha.0",
+  "version": "0.0.45-alpha.1",
   "type": "module",
   "exports": {
     ".": {

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