@softr/sdk 0.0.69 → 0.0.71

package/dist/auth/methods/profile.d.ts

@@ -0,0 +1,26 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/profile.d.ts
+
+/**
+ * Changes the signed-in visitor's own name, photo, or both. A field left out
+ * stays as it is, and `avatar: null` removes the photo.
+ *
+ * The photo can change only where `user.avatarEditable` is true. Elsewhere a
+ * photo answers `avatarNotSupported`, so hide the photo controls instead.
+ *
+ * Answers with the visitor as they are now. The page keeps showing what it
+ * loaded until its route context loads again, so call `router.invalidate()`
+ * after a success.
+ *
+ * @example
+ * const result = await auth.updateProfile({ fullName: 'Ann Lee' })
+ * const result = await auth.updateProfile({ avatar: file })
+ */
+declare function updateProfile(changes: {
+  fullName?: string;
+  avatar?: File | null;
+}): Promise<Result<User, AuthError>>;
+//#endregion
+export { updateProfile };

package/dist/auth/methods/profile.js

@@ -0,0 +1,52 @@
+import { assert, panic } from "../../assertions.js";
+import { sessionConfig } from "../config.js";
+import { clearSessionData, readSessionToken } from "../session.js";
+import { makePlatform } from "../platform.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/profile.ts
+/**
+* Changes the signed-in visitor's own name, photo, or both. A field left out
+* stays as it is, and `avatar: null` removes the photo.
+*
+* The photo can change only where `user.avatarEditable` is true. Elsewhere a
+* photo answers `avatarNotSupported`, so hide the photo controls instead.
+*
+* Answers with the visitor as they are now. The page keeps showing what it
+* loaded until its route context loads again, so call `router.invalidate()`
+* after a success.
+*
+* @example
+* const result = await auth.updateProfile({ fullName: 'Ann Lee' })
+* const result = await auth.updateProfile({ avatar: file })
+*/
+async function updateProfile(changes) {
+	assert(changes.fullName !== void 0 || changes.avatar !== void 0, "updateProfile needs a name or a photo to change");
+	const token = readSessionToken();
+	if (token === null) return authError("notAuthenticated", "Nobody is signed in.");
+	const form = new FormData();
+	if (changes.fullName !== void 0) form.set("fullName", changes.fullName);
+	if (changes.avatar === null) form.set("removeAvatar", "true");
+	if (changes.avatar) form.set("avatar", changes.avatar);
+	const result = await makePlatform(sessionConfig().applicationId).updateProfile(token, form);
+	if (!result.ok) {
+		switch (result.status) {
+			case 400: return authError("invalidName", result.message);
+			case 401: return authError("notAuthenticated", result.message);
+			case 409: return authError("avatarNotSupported", result.message);
+			case 413: return authError("fileTooLarge", result.message);
+			case 415: return authError("notAnImage", result.message);
+			case 429: return authError("tooManyAttempts", result.message);
+		}
+		if (result.status >= 500) panic(`Expected the profile to update, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID.`);
+	}
+	clearSessionData();
+	return {
+		success: true,
+		data: result.data
+	};
+}
+
+//#endregion
+export { updateProfile };

package/dist/auth/methods/utils.d.ts

@@ -10,6 +10,6 @@ type AuthError = {
   code: AuthErrorCode;
   message: string;
 };
-type AuthErrorCode = "invalidCredentials" | "tooManyAttempts" | "emailTaken" | "invalidDetails" | "invalidCode" | "notAuthenticated" | "emailDomainNotAllowed" | "linkExpired";
+type AuthErrorCode = "invalidCredentials" | "tooManyAttempts" | "emailTaken" | "invalidDetails" | "invalidCode" | "notAuthenticated" | "emailDomainNotAllowed" | "linkExpired" | "invalidName" | "fileTooLarge" | "notAnImage" | "avatarNotSupported";
 //#endregion
 export { AuthError, Result };

package/dist/auth/platform.js

@@ -1,4 +1,4 @@
-import { panic } from "../assertions.js";
+import { assert, panic } from "../assertions.js";
 import { fetch } from "../fetch.js";
 import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
@@ -267,6 +267,11 @@ function makePlatform(applicationId) {
 			token,
 			json: { code }
 		}, z.null()),
+		updateProfile: (token, form) => request(`/v1/vibe/applications/${applicationId}/users/me/profile`, {
+			method: "PATCH",
+			token,
+			form
+		}, userSchema),
 		signOut: (token) => request(`/v1/applications/${applicationId}/users/sign-out`, {
 			method: "POST",
 			token
@@ -275,6 +280,7 @@ function makePlatform(applicationId) {
 }
 const errorSchema = z.object({ message: z.string() });
 async function request(path, init, schema, parse = (response$1) => response$1.json()) {
+	assert(init.json === void 0 || init.form === void 0, "A platform request carries a JSON body or a form, not both");
 	const response = await fetch(`${await platformApiUrl()}${path}`, {
 		method: init.method,
 		headers: {
@@ -282,7 +288,8 @@ async function request(path, init, schema, parse = (response$1) => response$1.js
 			...init.json === void 0 ? {} : { "content-type": "application/json" },
 			...init.token ? { authorization: `Bearer ${init.token}` } : {}
 		},
-		...init.json === void 0 ? {} : { body: JSON.stringify(init.json) }
+		...init.json === void 0 ? {} : { body: JSON.stringify(init.json) },
+		...init.form === void 0 ? {} : { body: init.form }
 	});
 	if (!response.ok) {
 		const error = errorSchema.safeParse(await response.json().catch(() => null));

package/dist/auth/server.d.ts

@@ -6,6 +6,7 @@ import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./
 import { settings } from "./methods/settings.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
 import { signInWithGoogle } from "./methods/social.js";
+import { updateProfile } from "./methods/profile.js";
 import { currentUserRow } from "./current-user-row.js";
 import "@tanstack/react-start/server-only";
 
@@ -34,6 +35,7 @@ declare const auth: {
   resetAuthenticator: typeof resetAuthenticator;
   removeAuthenticator: typeof removeAuthenticator;
   settings: typeof settings;
+  updateProfile: typeof updateProfile;
   currentUserRow: typeof currentUserRow;
 };
 //#endregion

package/dist/auth/server.js

@@ -6,6 +6,7 @@ import { signIn, signOut } from "./methods/password.js";
 import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./methods/passwordLink.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
 import { signInWithGoogle } from "./methods/social.js";
+import { updateProfile } from "./methods/profile.js";
 import { currentUserRow } from "./current-user-row.js";
 import "@tanstack/react-start/server-only";
 
@@ -33,6 +34,7 @@ const auth = {
 	resetAuthenticator,
 	removeAuthenticator,
 	settings,
+	updateProfile,
 	currentUserRow
 };
 

package/dist/auth/session.js

@@ -118,6 +118,16 @@ function clearSession() {
 		PENDING_AUTH
 	]);
 }
+/**
+* Drops the cached visitor and leaves the session signed in, so the next
+* request needing a visitor re-reads one from the platform.
+*
+* For a mutation to what the visitor's own record holds — their name, their
+* groups — which the cache would otherwise answer stale for up to five minutes.
+*/
+function clearSessionData() {
+	clearCookies([SESSION_DATA]);
+}
 const standInToken = new AsyncLocalStorage();
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
@@ -210,4 +220,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };
+export { clearPendingAuth, clearSession, clearSessionData, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };

package/dist/auth/user.d.ts

@@ -19,6 +19,10 @@ type User = {
   email: string;
   fullName: string;
   userGroupIds: Array<SoftrUserGroupId>;
+  /** Their photo, or `null` when they have none. Show their initials then. */
+  avatarUrl: string | null;
+  /** Whether `auth.updateProfile` can change their photo in this app. */
+  avatarEditable: boolean;
 };
 //#endregion
 export { SoftrUserGroupId, SoftrUserGroups, User };

package/dist/auth/user.js

@@ -5,7 +5,9 @@ const userSchema = z.object({
 	id: z.string(),
 	email: z.string(),
 	fullName: z.string(),
-	userGroupIds: z.array(z.string())
+	userGroupIds: z.array(z.string()),
+	avatarUrl: z.string().nullable().default(null),
+	avatarEditable: z.boolean().default(false)
 });
 
 //#endregion

package/dist/index.d.ts

@@ -5,8 +5,9 @@ import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { AuthSettings } from "./auth/platform.js";
-import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
-import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { checkAccess, defineVisibility, isAuthorized } from "./route/visibility.js";
+import { Page, PageSettings, definePage, pageHead } from "./route/page.js";
+import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
 import { toReturnPath } from "./auth/returnPath.js";
 import { AuthOptions, AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
@@ -15,5 +16,5 @@ import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+import { Audience } from "./route/audience.js";
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

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

package/dist/package.js

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

package/dist/{visibility → route}/audience.d.ts

@@ -1,7 +1,7 @@
 import { Visibility } from "./visibility.js";
 import { ReactNode } from "react";
 
-//#region src/visibility/audience.d.ts
+//#region src/route/audience.d.ts
 type Props = {
   visibility: Visibility;
   children: ReactNode;

package/dist/{visibility → route}/audience.js

@@ -1,7 +1,7 @@
 import { checkAccess } from "./visibility.js";
 import { useCurrentUser } from "../auth/isomorphic.js";
 
-//#region src/visibility/audience.tsx
+//#region src/route/audience.tsx
 /**
 * Renders `children` to the visitors a rule admits, and `fallback` to the rest.
 *

package/dist/route/page.d.ts

@@ -0,0 +1,72 @@
+import { VisibilityRule } from "./visibility.js";
+import { AnyRouteMatch } from "@tanstack/react-router";
+
+//#region src/route/page.d.ts
+/** The part of TanStack's `head` context a page setting can read. */
+type HeadContext = {
+  match: {
+    id: string;
+  };
+  matches: ReadonlyArray<{
+    id: string;
+  }>;
+  loaderData?: AnyRouteMatch["loaderData"];
+};
+type HeadSetting<T> = T | ((ctx: HeadContext) => T | undefined);
+type PageSettings = {
+  visibility?: VisibilityRule;
+  title?: HeadSetting<string>;
+  description?: HeadSetting<string>;
+  searchEngineIndexing?: HeadSetting<boolean>;
+  canonicalUrl?: HeadSetting<string>;
+  socialTitle?: HeadSetting<string>;
+  socialDescription?: HeadSetting<string>;
+  socialImage?: HeadSetting<string>;
+};
+declare const pageBrand: unique symbol;
+/** The settings {@link definePage} has produced. */
+type Page<S extends PageSettings = PageSettings> = S & {
+  readonly [pageBrand]: "page";
+};
+/**
+ * Declares a route's settings: who may open it, its title and its SEO tags.
+ *
+ * One call per route file, at module scope, with an object literal. Studio
+ * reads and rewrites each setting written out as a literal; a computed one is
+ * changed in the code. A head setting that depends on the route's data is a
+ * function of its head context. The route's `beforeLoad` and `head` apply it.
+ *
+ * @example
+ * const pageSettings = definePage({
+ *   visibility: { userGroupTypes: ["LOGGED_IN_USERS"] },
+ *   title: ({ loaderData }) => loaderData?.name,
+ * })
+ *
+ * export const Route = createFileRoute("/_app/projects/$projectId")({
+ *   beforeLoad: guardRoute(pageSettings),
+ *   loader: ({ params }) => loadProject({ data: params.projectId }),
+ *   head: pageHead(pageSettings),
+ *   component: Project,
+ * })
+ */
+declare function definePage<const S extends PageSettings>(settings: S & { [K in Exclude<keyof S, keyof PageSettings>]: never }): Page<S>;
+type Meta = NonNullable<AnyRouteMatch["meta"]>;
+type Links = NonNullable<AnyRouteMatch["links"]>;
+/**
+ * The router keeps the deepest route's tag for each title, name and property,
+ * so a layout's settings reach every page under it that does not state its own.
+ * A canonical URL names one page, so only the page the visitor is on renders
+ * its own.
+ *
+ * Returned rather than called with the route's context: a `head` written as
+ * `(ctx) => …` before `loader` stops TypeScript inferring the loader's types.
+ *
+ * @example
+ * head: pageHead(pageSettings)
+ */
+declare function pageHead(page: Page): (ctx: HeadContext) => {
+  meta: Meta;
+  links: Links;
+};
+//#endregion
+export { Page, PageSettings, definePage, pageHead };

package/dist/route/page.js

@@ -0,0 +1,79 @@
+//#region src/route/page.ts
+/**
+* Declares a route's settings: who may open it, its title and its SEO tags.
+*
+* One call per route file, at module scope, with an object literal. Studio
+* reads and rewrites each setting written out as a literal; a computed one is
+* changed in the code. A head setting that depends on the route's data is a
+* function of its head context. The route's `beforeLoad` and `head` apply it.
+*
+* @example
+* const pageSettings = definePage({
+*   visibility: { userGroupTypes: ["LOGGED_IN_USERS"] },
+*   title: ({ loaderData }) => loaderData?.name,
+* })
+*
+* export const Route = createFileRoute("/_app/projects/$projectId")({
+*   beforeLoad: guardRoute(pageSettings),
+*   loader: ({ params }) => loadProject({ data: params.projectId }),
+*   head: pageHead(pageSettings),
+*   component: Project,
+* })
+*/
+function definePage(settings) {
+	return settings;
+}
+/**
+* The router keeps the deepest route's tag for each title, name and property,
+* so a layout's settings reach every page under it that does not state its own.
+* A canonical URL names one page, so only the page the visitor is on renders
+* its own.
+*
+* Returned rather than called with the route's context: a `head` written as
+* `(ctx) => …` before `loader` stops TypeScript inferring the loader's types.
+*
+* @example
+* head: pageHead(pageSettings)
+*/
+function pageHead(page) {
+	return (ctx) => {
+		const resolve = (setting) => typeof setting === "function" ? setting(ctx) : setting;
+		const tag = (setting, make) => {
+			const value = resolve(setting);
+			return typeof value === "string" && value !== "" ? [make(value)] : [];
+		};
+		const indexing = resolve(page.searchEngineIndexing);
+		return {
+			meta: [
+				...tag(page.title, (title) => ({ title })),
+				...tag(page.description, (content) => ({
+					name: "description",
+					content
+				})),
+				...tag(page.socialTitle, (content) => ({
+					property: "og:title",
+					content
+				})),
+				...tag(page.socialDescription, (content) => ({
+					property: "og:description",
+					content
+				})),
+				...tag(page.socialImage, (content) => ({
+					property: "og:image",
+					content
+				})),
+				...typeof indexing === "boolean" ? [{
+					name: "robots",
+					content: indexing ? "index" : "noindex"
+				}] : []
+			],
+			links: ctx.matches.at(-1)?.id === ctx.match.id ? tag(page.canonicalUrl, (href) => ({
+				rel: "canonical",
+				href
+			})) : []
+		};
+	};
+}
+
+//#endregion
+export { definePage, pageHead };

package/dist/{visibility → route}/route.d.ts

@@ -1,6 +1,7 @@
-import { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule } from "./visibility.js";
+import { AccessContext, AccessReason, Narrowed, VisibilityRule } from "./visibility.js";
+import { Page, PageSettings } from "./page.js";
 
-//#region src/visibility/route.d.ts
+//#region src/route/route.d.ts
 
 /**
  * What a guard does when it denies a visitor: redirect to a path, or throw an
@@ -42,8 +43,11 @@ declare function isUnauthenticatedError(error: unknown): error is AccessError;
 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 GuardedPage = Page<PageSettings & {
+  visibility: VisibilityRule;
+}>;
 /**
- * A `beforeLoad` handler that denies a visitor who fails the rule.
+ * A `beforeLoad` handler that denies a visitor the page's rule does not admit.
  *
  * Each reason falls back to the app's configured behaviour. Pass `overrides` to
  * change what any one reason does. A redirected signed-out visitor carries the
@@ -52,9 +56,9 @@ declare function isAlreadyAuthenticatedError(error: unknown): error is AccessErr
  * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
  *
  * @example
- * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+ * beforeLoad: guardRoute(pageSettings, { unauthenticated: "/sign-in" })
  */
-declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides): (opts: {
+declare function guardRoute(page: GuardedPage, overrides?: GuardOverrides): (opts: {
   context: AccessContext;
   location: {
     href: string;
@@ -66,7 +70,7 @@ declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides):
  *
  * @example
  * beforeLoad: (opts) => {
- *   assertRouteAccess(visibility, opts)
+ *   assertRouteAccess(pageSettings, opts)
  *   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
  * }
  */
@@ -75,7 +79,9 @@ declare function assertRouteAccess<R extends VisibilityRule, O extends {
   location: {
     href: string;
   };
-}>(visibility: Visibility<R>, opts: O): asserts opts is O & {
+}>(page: Page<PageSettings & {
+  visibility: R;
+}>, opts: O): asserts opts is O & {
   context: Narrowed<R>;
 };
 //#endregion

package/dist/{visibility → route}/route.js

@@ -1,8 +1,9 @@
-import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { panic } from "../assertions.js";
+import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { softrConfig } from "../softr-config.js";
 import { redirect } from "@tanstack/react-router";
 
-//#region src/visibility/route.ts
+//#region src/route/route.ts
 function isAccessReason(value) {
 	return ACCESS_REASONS.some((reason) => reason === value);
 }
@@ -52,8 +53,11 @@ function thrownFor(reason, overrides, location) {
 		reason
 	};
 }
+function ruleOf(page) {
+	return page.visibility ?? panic("the page states no visibility rule to guard it with");
+}
 /**
-* A `beforeLoad` handler that denies a visitor who fails the rule.
+* A `beforeLoad` handler that denies a visitor the page's rule does not admit.
 *
 * Each reason falls back to the app's configured behaviour. Pass `overrides` to
 * change what any one reason does. A redirected signed-out visitor carries the
@@ -62,11 +66,11 @@ function thrownFor(reason, overrides, location) {
 * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
 *
 * @example
-* beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+* beforeLoad: guardRoute(pageSettings, { unauthenticated: "/sign-in" })
 */
-function guardRoute(visibility, overrides) {
+function guardRoute(page, overrides) {
 	return ({ context, location }) => {
-		const result = checkAccess(visibility, context);
+		const result = checkRule(ruleOf(page), context);
 		if (result.ok) return;
 		throw thrownFor(result.reason, overrides, location);
 	};
@@ -77,12 +81,12 @@ function guardRoute(visibility, overrides) {
 *
 * @example
 * beforeLoad: (opts) => {
-*   assertRouteAccess(visibility, opts)
+*   assertRouteAccess(pageSettings, opts)
 *   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
 * }
 */
-function assertRouteAccess(visibility, opts) {
-	const result = checkAccess(visibility, opts.context);
+function assertRouteAccess(page, opts) {
+	const result = checkRule(ruleOf(page), opts.context);
 	if (result.ok) return;
 	throw thrownFor(result.reason, void 0, opts.location);
 }

package/dist/{visibility → route}/visibility.d.ts

@@ -1,7 +1,7 @@
 import { SoftrUserGroupId, User } from "../auth/user.js";
 import { SoftrContext } from "../auth/context.js";
 
-//#region src/visibility/visibility.d.ts
+//#region src/route/visibility.d.ts
 type AudienceSet = readonly ["NON_LOGGED_IN_USERS"] | readonly ["LOGGED_IN_USERS"] | readonly ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] | readonly ["LOGGED_IN_USERS", "NON_LOGGED_IN_USERS"];
 /**
  * Who may see a route or region. `customGroups` narrows only the
@@ -48,18 +48,13 @@ type Narrowed<R extends VisibilityRule> = R["userGroupTypes"] extends ReadonlyAr
   user: null;
 } : AccessContext : 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.
+ * Declares who may see a region of the page. A route's own rule is the
+ * `visibility` of its `definePage`.
  *
  * @example
- * const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
+ * const staffOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["…"] })
  *
- * export const Route = createFileRoute("/about")({
- *   beforeLoad: guardRoute(visibility),
- *   component: About,
- * })
+ * <Audience visibility={staffOnly} fallback={null}>…</Audience>
  */
 declare function defineVisibility<const R extends VisibilityRule>(rule: R): Visibility<R>;
 /**

package/dist/{visibility → route}/visibility.js

@@ -1,4 +1,4 @@
-//#region src/visibility/visibility.ts
+//#region src/route/visibility.ts
 /**
 * Why a visitor was denied.
 *
@@ -13,8 +13,12 @@ const ACCESS_REASONS = [
 ];
 /** The decision and, when a visitor is denied, the reason. Throws nothing. */
 function checkAccess(visibility, context) {
+	return checkRule(visibility, context);
+}
+/** {@link checkAccess} for a page's rule, which {@link defineVisibility} has not produced. */
+function checkRule(rule, context) {
 	const { user } = context;
-	const audiences = visibility.userGroupTypes;
+	const audiences = rule.userGroupTypes;
 	if (user === null) return audiences.includes("NON_LOGGED_IN_USERS") ? { ok: true } : {
 		ok: false,
 		reason: "unauthenticated"
@@ -23,7 +27,7 @@ function checkAccess(visibility, context) {
 		ok: false,
 		reason: "alreadyAuthenticated"
 	};
-	const required = visibility.customGroups ?? [];
+	const required = rule.customGroups ?? [];
 	if (required.length === 0) return { ok: true };
 	return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
 		ok: false,
@@ -31,18 +35,13 @@ function checkAccess(visibility, context) {
 	};
 }
 /**
-* 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.
+* Declares who may see a region of the page. A route's own rule is the
+* `visibility` of its `definePage`.
 *
 * @example
-* const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
+* const staffOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["…"] })
 *
-* export const Route = createFileRoute("/about")({
-*   beforeLoad: guardRoute(visibility),
-*   component: About,
-* })
+* <Audience visibility={staffOnly} fallback={null}>…</Audience>
 */
 function defineVisibility(rule) {
 	return rule;
@@ -56,4 +55,4 @@ function isAuthorized(visibility, context) {
 }
 
 //#endregion
-export { ACCESS_REASONS, checkAccess, defineVisibility, isAuthorized };
+export { ACCESS_REASONS, checkAccess, checkRule, defineVisibility, isAuthorized };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 # Softr SDK core

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

@@ -7,19 +7,18 @@ description: >-
   sign-in (verifyAuthenticator, startAuthenticatorSetup,
   confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
   authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator), the emailed password links
-  (requestPasswordReset, checkPasswordLink, setPasswordWithLink), and
-  getAuthSettings, AuthSettingsProvider and useAuthSettings for which sign-in
-  and sign-up methods the app has enabled. Covers the Result shape they answer
-  with and its codes invalidCredentials, tooManyAttempts, emailTaken,
-  invalidDetails, invalidCode, notAuthenticated, emailDomainNotAllowed and
-  linkExpired, the two-step sign-up, why a successful sign-in does not always
-  mean the visitor is signed in, and toReturnPath for where to land after
-  signing in.
+  resetAuthenticator, removeAuthenticator), updateProfile for the visitor's own
+  name and photo, the emailed password links (requestPasswordReset,
+  checkPasswordLink, setPasswordWithLink), and getAuthSettings,
+  AuthSettingsProvider and useAuthSettings for which sign-in and sign-up methods
+  the app has enabled. Covers the Result shape they answer with and its error
+  codes (invalidCredentials, emailTaken, notAuthenticated, notAnImage and the
+  rest), the two-step sign-up, why a successful sign-in does not always mean the
+  visitor is signed in, and toReturnPath for where to land after signing in.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -82,6 +81,12 @@ Changing an authenticator from a settings page:
 | `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
 | `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
+Changing the visitor's own profile:
+
+| Call | Does |
+| --- | --- |
+| `auth.updateProfile({ fullName?, avatar? })` | Changes their name, their photo, or both. `avatar: null` removes the photo |
+
 ## Setup
 
 `auth` is server-only, so every call sits inside a `createServerFn` handler:
@@ -451,6 +456,20 @@ All three need a signed-in visitor and answer `notAuthenticated` when there is n
 
 After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuthenticatorSetup`, which is also where the new backup codes come from. After a removal, an app that requires an authenticator asks the visitor to set one up again on their next sign-in.
 
+### Changing the visitor's name and photo
+
+```ts
+const result = await auth.updateProfile({ fullName: 'Ann Lee' })
+const result = await auth.updateProfile({ avatar: file })   // a File from an <input type="file">
+const result = await auth.updateProfile({ avatar: null })   // removes the photo
+```
+
+It answers with the updated `User`. Pass the file through a server function that takes `FormData`. The photo must be a PNG, JPEG or GIF of at most 5 MB, or it answers `notAnImage` or `fileTooLarge`. A blank or unacceptable name answers `invalidName`.
+
+Only some apps can store a photo. Show the photo controls only when `user.avatarEditable` is true; elsewhere a photo answers `avatarNotSupported`.
+
+The page keeps showing the old name and photo until its route context loads again, so call `router.invalidate()` after a success.
+
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor these calls establish

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **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.69
+  library_version: 0.0.71
 ---
 
 # The current user
@@ -31,6 +31,8 @@ type User = {
   email: string
   fullName: string
   userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
+  avatarUrl: string | null                 // their photo; show their initials when null
+  avatarEditable: boolean                  // whether auth.updateProfile can change the photo
 }
 ```
 

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 # Dates, times and numbers

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **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.69
+  library_version: 0.0.71
 ---
 
 **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.69
+  library_version: 0.0.71
 ---
 
 # Installing the app

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.69
+  library_version: 0.0.71
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

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