@softr/sdk 0.0.88-signing.0 → 0.0.88

package/dist/auth/isomorphic.d.ts

@@ -14,14 +14,15 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  * to read.
  *
  * Register it once, as a global request middleware in the app's `src/start.ts`.
- * It writes nothing but the session cookie.
+ * It writes the session cookie, and in production a header that stops other
+ * sites from embedding the app.
  *
  * @example
  * export const startInstance = createStart(() => ({
  *   requestMiddleware: [softrAuthMiddleware()],
  * }))
  */
-declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
   formatting: Formatting;

package/dist/auth/isomorphic.js

@@ -9,6 +9,7 @@ import { settings } from "./methods/settings.js";
 import { bootErrorMiddleware } from "../boot-error.js";
 import { pwaMiddleware } from "../pwa.js";
 import { faviconMiddleware } from "../favicon.js";
+import { embeddingMiddleware } from "../embedding.js";
 import { createContext, useContext } from "react";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
 import { getRequestHeader } from "@tanstack/react-start/server";
@@ -22,7 +23,8 @@ import { jsx } from "react/jsx-runtime";
 * to read.
 *
 * Register it once, as a global request middleware in the app's `src/start.ts`.
-* It writes nothing but the session cookie.
+* It writes the session cookie, and in production a header that stops other
+* sites from embedding the app.
 *
 * @example
 * export const startInstance = createStart(() => ({
@@ -31,6 +33,7 @@ import { jsx } from "react/jsx-runtime";
 */
 function softrAuthMiddleware() {
 	return createMiddleware({ type: "request" }).middleware([
+		embeddingMiddleware(),
 		bootErrorMiddleware(),
 		pwaMiddleware(),
 		faviconMiddleware()

package/dist/auth/methods/authenticator.js

@@ -46,7 +46,7 @@ async function confirmAuthenticatorSetup(details) {
 		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
 	}
 	const { session, backupCodes } = result.data;
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);
@@ -75,7 +75,7 @@ async function skipAuthenticatorSetup() {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from skipping setup, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);
@@ -101,7 +101,7 @@ async function verifyAuthenticator(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from verification, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/code.js

@@ -56,7 +56,7 @@ async function signInWithCode(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-in, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/magicLink.js

@@ -36,7 +36,7 @@ async function signInWithMagicLink(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from magic-link sign-in, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/password.js

@@ -35,7 +35,7 @@ async function signIn(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-in, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/passwordLink.js

@@ -68,7 +68,7 @@ async function setPasswordWithLink(details) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from setting a password, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/signup.js

@@ -66,7 +66,7 @@ async function confirmSignUp(details) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-up, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/social.js

@@ -41,7 +41,7 @@ async function signInWithGoogle(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from Google sign-in, but got none");
-	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/platform.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../assertions.js";
-import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
-import { permissionsSchema } from "./permissions.js";
 import { softrConfig } from "../softr-config.js";
+import { permissionsSchema } from "./permissions.js";
+import { softrApiUrl } from "../softr-api.js";
 import { z } from "zod";
 
 //#region src/auth/platform.ts

package/dist/auth/session.js

@@ -1,4 +1,4 @@
-import { readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
+import { expireCookie, expireOtherCopy, readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
 import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
@@ -65,12 +65,16 @@ function readSessionData(sessionToken) {
 		permissions: payload.permissions
 	};
 }
+/**
+* The token cookie, after a deletion of any copy from before `allowEmbedding`
+* changed. Both would be sent, and the old one could be read instead.
+*/
 function makeSessionTokenCookie(token) {
 	const { name, secure } = sessionCookie(SESSION_TOKEN);
-	return serializeCookie(name, sealEnvelope(token, SESSION_TOKEN), {
+	return [...expireOtherCopy(name, secure), serializeCookie(name, sealEnvelope(token, SESSION_TOKEN), {
 		maxAge: sessionConfig().sessionMaxAge,
 		secure
-	});
+	})];
 }
 function makeSessionDataCookie(session, sessionToken) {
 	const { name, secure } = sessionCookie(SESSION_DATA);
@@ -141,10 +145,7 @@ const sessionDataSchema = z.object({
 */
 function clearCookies(bases) {
 	const secure = requestIsSecure();
-	writeCookies(bases.flatMap((base) => secure ? [sessionCookieName(base, secure), base] : [base]).map((name) => serializeCookie(name, "", {
-		maxAge: 0,
-		secure
-	})));
+	writeCookies(bases.flatMap((base) => secure ? [sessionCookieName(base, secure), base] : [base]).flatMap((name) => expireCookie(name, secure)));
 }
 /**
 * Over the plaintext token, never the cookie value: that is resealed with a

package/dist/codegen/datasource-docs.js

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

package/dist/cookies.js

@@ -1,4 +1,5 @@
 import { softAssert } from "./assertions.js";
+import { softrConfig } from "./softr-config.js";
 import { getRequestHeader, getResponseHeaders, setResponseHeader } from "@tanstack/react-start/server";
 
 //#region src/cookies.ts
@@ -36,8 +37,33 @@ function serializeCookie(name, value, { maxAge, secure }) {
 	return parts.join("; ");
 }
 function sameSiteAttributes(secure) {
-	if (secure && process.env.NODE_ENV !== "production") return ["SameSite=None", "Partitioned"];
-	return ["SameSite=Lax"];
+	return partitions(secure) ? ["SameSite=None", "Partitioned"] : ["SameSite=Lax"];
+}
+function partitions(secure) {
+	return secure && (process.env.NODE_ENV !== "production" || (softrConfig().allowEmbedding ?? []).length > 0);
+}
+function expired(name, partitioned) {
+	return partitioned ? `${name}=; Path=/; HttpOnly; Secure; SameSite=None; Partitioned; Max-Age=0` : `${name}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;
+}
+/**
+* The deletions for one cookie. A browser keeps a partitioned and a plain
+* cookie of one name apart, and sends both. Which one the app wrote can change
+* between sign-in and sign-out, when `allowEmbedding` changes. So over https,
+* delete both. The one left behind would keep the visitor signed in.
+*/
+function expireCookie(name, secure) {
+	if (!secure) return [serializeCookie(name, "", {
+		maxAge: 0,
+		secure
+	})];
+	return [expired(name, false), expired(name, true)];
+}
+/**
+* The deletion of the copy the other mode would write. Sent with a new cookie,
+* so a copy from before `allowEmbedding` changed can't be read in its place.
+*/
+function expireOtherCopy(name, secure) {
+	return secure ? [expired(name, !partitions(secure))] : [];
 }
 const USER_TIMEZONE_COOKIE = "user-timezone";
 function readUserTimezone() {
@@ -56,4 +82,4 @@ function writeCookies(cookies) {
 }
 
 //#endregion
-export { readRequestCookies, readUserTimezone, serializeCookie, writeCookies };
+export { expireCookie, expireOtherCopy, readRequestCookies, readUserTimezone, serializeCookie, writeCookies };

package/dist/core/file-upload.js

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

package/dist/core/workflow.js

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

package/dist/datasource/record.js

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

package/dist/embedding.js

@@ -0,0 +1,33 @@
+import { softrConfig } from "./softr-config.js";
+import { createMiddleware } from "@tanstack/react-start";
+
+//#region src/embedding.ts
+/**
+* Stops other sites from showing the published app in an iframe. The origins
+* softr.json lists in `allowEmbedding` still can.
+*
+* Production only. The dev server runs in the preview pod, and Studio shows
+* that preview in an iframe on another site.
+*/
+function embeddingMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next }) => {
+		const result = await next();
+		if (process.env.NODE_ENV !== "production") return result;
+		const policy = [
+			"frame-ancestors",
+			"'self'",
+			...softrConfig().allowEmbedding ?? []
+		].join(" ");
+		try {
+			result.response.headers.append("content-security-policy", policy);
+			return result;
+		} catch {
+			const response = new Response(result.response.body, result.response);
+			response.headers.append("content-security-policy", policy);
+			return response;
+		}
+	});
+}
+
+//#endregion
+export { embeddingMiddleware };

package/dist/fetch.js

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

package/dist/locale-settings.js

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

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start5 from "@tanstack/react-start";
+import * as _tanstack_react_start6 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start5.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start6.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

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

package/dist/package.js

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

package/dist/pwa.js

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

package/dist/route/route.js

@@ -1,6 +1,6 @@
 import { panic } from "../assertions.js";
-import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { softrConfig } from "../softr-config.js";
+import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { redirect } from "@tanstack/react-router";
 
 //#region src/route/route.ts

package/dist/softr-config.schema.js

@@ -21,6 +21,7 @@ const AccessBehaviour = z.union([
 	z.object({ strategy: z.literal("throw") })
 ], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
 const AppPath = z.string().refine((path$1) => path$1.startsWith("/") && !path$1.includes("?") && !path$1.includes("#") && new URL(path$1, "https://app.invalid").origin === "https://app.invalid", { error: "must be a path on this app like \"/login\", with no \"?\" or \"#\"" });
+const Origin = z.union([z.literal("*"), z.string().regex(/^https:\/\/[^/\\?#@\s;,]+$/).refine(URL.canParse).transform((origin) => new URL(origin).origin)], { error: "must be an https origin like \"https://partner.com\", with no path or trailing \"/\", or \"*\" for any site" });
 const SoftrConfigSchema = z.object({
 	auth: z.strictObject({
 		routes: z.strictObject({
@@ -47,7 +48,8 @@ const SoftrConfigSchema = z.object({
 			alreadyAuthenticated: AccessBehaviour
 		})
 	}),
-	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional()
+	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional(),
+	allowEmbedding: z.array(Origin).optional()
 });
 function loadSoftrConfig(root) {
 	const file = path.join(root, SOFTR_CONFIG_FILE);

package/package.json

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

package/schema/softr.schema.json

@@ -67,6 +67,11 @@
       },
       "required": ["properties"],
       "additionalProperties": false
+    },
+    "allowEmbedding": {
+      "type": "array",
+      "description": "Sites that may show the published app in an iframe, signed-in pages included, as https origins like \"https://partner.com\", or \"*\" for any site. Any other site is still blocked. With at least one, session cookies use SameSite=None, which drops the browser's CSRF protection. Empty by default.",
+      "items": { "type": "string", "pattern": "^(\\*|https://[^/\\\\?#@\\s;,]+)$" }
     }
   },
   "required": ["auth"],

package/skills/softr-sdk/SKILL.md

@@ -3,12 +3,13 @@ name: softr-sdk
 description: >-
   Entry point for @softr/sdk: its four entrypoints (@softr/sdk, /server,
   /client, /vite) and their client-server boundary, softrAuthMiddleware and the
-  Softr context, and which sub-skill covers each task. Load it when unsure which
-  sub-skill applies, or when touching the wiring.
+  Softr context, embedding the app in another site's iframe, and which sub-skill
+  covers each task. Load it when unsure which sub-skill applies, when touching
+  the wiring, or when the user wants the app embedded elsewhere.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 # Softr SDK core
@@ -17,7 +18,7 @@ metadata:
 
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 >
-> **CRITICAL**: Every route file must declare its audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
+> **CRITICAL**: Every route file must declare its settings with `definePage`, guard itself with them in `beforeLoad` and render them in `head`. There is no default and nothing is inherited from a sibling.
 >
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
 >
@@ -29,7 +30,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -148,3 +149,7 @@ type User = {
   userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```
+
+## Embedding the app in another site
+
+The published app refuses to load inside another site's iframe. The Studio preview is not affected. When the user asks to embed the app on their site, list that site's origin in `softr.json`: `"allowEmbedding": ["https://partner.com"]`. Ask for the exact origin if you don't have it. Only listed sites can embed the app. Use `["*"]` only when the user wants any site to embed it. Remove the list to block embedding again. Sign-in then works inside the embed. Session cookies switch from SameSite=Lax to None, so the app loses the browser's CSRF protection. Only set it when the user asks. There are two more limits to tell the user: Safari may not keep the visitor signed in, and links from emails (magic link, password reset) open the app in a new tab, not in the embed.

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

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

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

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

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

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

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 # Installing the app

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.88
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -53,7 +53,7 @@ const publishedPosts = defineQuery({
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }`: everyone, signed out included. `customGroups` narrows only the signed-in half.
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS'] }`: signed-out visitors only.
   - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`. `customGroups` is added to `userGroupTypes`, never written in place of it.
-- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error, as it is in a route's visibility.
+- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error.
 - Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
 
 A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.

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

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

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

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

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

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