@softr/sdk 0.0.99-alpha.1 → 0.0.99

package/dist/auth/isomorphic.d.ts

@@ -21,7 +21,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  *   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>, _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>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: {
     datasources: {};

package/dist/auth/isomorphic.js

@@ -8,7 +8,6 @@ import { makePlatform } from "./platform.js";
 import { settings } from "./methods/settings.js";
 import { bootErrorMiddleware } from "../boot-error.js";
 import { pwaMiddleware } from "../pwa.js";
-import { pushMiddleware } from "../push.js";
 import { faviconMiddleware } from "../favicon.js";
 import { embeddingMiddleware } from "../embedding.js";
 import { appIdentityMiddleware } from "../app-identity.js";
@@ -39,7 +38,6 @@ function softrAuthMiddleware() {
 		appIdentityMiddleware(),
 		bootErrorMiddleware(),
 		pwaMiddleware(),
-		pushMiddleware(),
 		faviconMiddleware()
 	]).server(async ({ next }) => {
 		async function getSession() {

package/dist/datasource/fields.js

@@ -27,10 +27,8 @@ function makeSortSet(aliases) {
 /**
 * Ands the filters of every `where` call into one, which is what an accumulated `where` needs.
 *
-* The backend takes a group inside a group and no deeper, and the docs promise the caller both levels.
-* A wrapper added here would spend one of them: a single `where` handing over an AND with an OR inside
-* would arrive three deep and be refused. So one filter goes through as it is, and a group that is itself
-* an AND contributes its members to the group built here rather than sitting inside it.
+* One filter goes through as it is. A group that is itself an AND contributes its members to the group
+* built here rather than sitting inside it. So the request is no deeper than the filters the caller wrote.
 */
 function andAll(filters) {
 	if (filters.length === 1) return filters[0];

package/dist/datasource/filter.js

@@ -5,62 +5,48 @@ const INTERNAL_KIND = Symbol("KIND");
 /**
 * Converts filter utility conditions to a format our backend supports.
 *
-* A leaf becomes a group of one, because the wire format has no way to hold a bare
-* condition and a group side by side at the same level.
+* Each group holds its conditions in `filters` and its nested groups in `filterGroups`, at any depth.
+* Both lists are always present. A single condition becomes the only member of an AND group.
 *
 * @example
 * ```tsx
-* const json = buildFilterCriteria(fields.title.contains("hello"));
+* const json = buildFilterCriteria(fields.$and(fields.title.contains("hello"), fields.$or(fields.rating.gt(3), fields.rating.isEmpty())));
 * // result
 * {
-*   "filterCriteria": {
-*     "filterConditionGroup": {
-*       "logicalOperator": "AND"
-*       "filterGroups": [{
-*         "logicalOperator": "AND",
-*         "filters": [{
-*           "subject": "title",
-*           "type": "TEXT",
-*           "operator": "CONTAINS",
-*           "value": "hello"
-*         }],
-*       }]
-*     }
+*   "filterConditionGroup": {
+*     "logicalOperator": "AND",
+*     "filters": [{ "subject": "title", "type": "TEXT", "operator": "CONTAINS", "value": "hello" }],
+*     "filterGroups": [{
+*       "logicalOperator": "OR",
+*       "filters": [
+*         { "subject": "rating", "type": "NUMERIC", "operator": "GT", "value": "3" },
+*         { "subject": "rating", "type": "TEXT", "operator": "IS_EMPTY" }
+*       ],
+*       "filterGroups": []
+*     }]
 *   }
-*  }
-*
+* }
 * ```
 */
 function buildFilterCriteria(input) {
-	assert(INTERNAL_KIND in input, "a filter must come from the callback a read hands you");
-	if (isFilter(input)) return { filterConditionGroup: {
-		logicalOperator: "AND",
-		filterGroups: [{
-			logicalOperator: "AND",
-			filters: [stripInternalKind(input)]
-		}]
-	} };
-	if (isFilterGroup(input)) {
-		if (input.filters.length === 0) return { filterConditionGroup: {
-			logicalOperator: input.logicalOperator,
-			filterGroups: []
-		} };
-		return { filterConditionGroup: {
-			logicalOperator: input.logicalOperator,
-			filterGroups: input.filters.map((inner) => {
-				if (isFilter(inner)) return {
-					logicalOperator: "AND",
-					filters: [stripInternalKind(inner)]
-				};
-				if (!inner.filters.every(isFilter)) throw new Error("Cannot nest filter groups more than three levels deep.");
-				return {
-					logicalOperator: inner.logicalOperator,
-					filters: inner.filters.map(stripInternalKind)
-				};
-			})
-		} };
+	return { filterConditionGroup: isFilterGroup(input) ? buildFilterGroup(input.logicalOperator, input.filters) : buildFilterGroup("AND", [input]) };
+}
+function buildFilterGroup(logicalOperator, members) {
+	const filters = [];
+	const filterGroups = [];
+	for (const member of members) {
+		assert(INTERNAL_KIND in member, "a filter must come from the callback a read hands you");
+		if (isFilterGroup(member)) filterGroups.push(buildFilterGroup(member.logicalOperator, member.filters));
+		else {
+			assert(isFilter(member), () => "Unknown filter kind: " + String(member[INTERNAL_KIND]));
+			filters.push(stripInternalKind(member));
+		}
 	}
-	throw new Error("Unknown filter kind: " + input[INTERNAL_KIND]);
+	return {
+		logicalOperator,
+		filters,
+		filterGroups
+	};
 }
 /**
 * Converts order-by utility conditions to a format our backend supports
@@ -115,13 +101,14 @@ function dealiasOrderBy(orderbys, aliases) {
 */
 function dealiasFilterCriteria(criteria, aliases) {
 	if (!criteria.filterConditionGroup) return criteria;
-	return { filterConditionGroup: {
-		...criteria.filterConditionGroup,
-		filterGroups: criteria.filterConditionGroup.filterGroups.map((group) => ({
+	return { filterConditionGroup: dealiasGroup(criteria.filterConditionGroup) };
+	function dealiasGroup(group) {
+		return {
 			...group,
-			filters: group.filters.map(dealiasFilter)
-		}))
-	} };
+			filters: group.filters.map(dealiasFilter),
+			filterGroups: group.filterGroups.map(dealiasGroup)
+		};
+	}
 	function dealiasFilter(filter) {
 		const subject = aliases[filter.subject];
 		assert(subject, () => `Could not find an alias for subject "${filter.subject}"`);

package/dist/index.d.ts

@@ -16,7 +16,6 @@ import { FieldShape, SoftrFieldRegistry, fieldShape, formatDuration, formatField
 import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
-import { PushNotifications, PushPrompt, usePushNotifications } from "./push.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, 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 PushNotifications, type PushPrompt, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, 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, usePushNotifications, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, 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 SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, 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

@@ -6,7 +6,6 @@ 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";
-import { usePushNotifications } from "./push.js";
 import { AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
 import { fieldShape, formatDuration, formatField, formatValue, registerSoftrFields } from "./fields/format.js";
@@ -15,4 +14,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, 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, usePushNotifications, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, 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/mcp.d.ts

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

package/dist/package.js

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

package/dist/pwa.js

@@ -149,4 +149,4 @@ function detectPlatform() {
 }
 
 //#endregion
-export { SoftrPwaHead, detectPlatform, pwaMiddleware, usePwaInstall };
+export { SoftrPwaHead, pwaMiddleware, usePwaInstall };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 # Softr SDK core
@@ -32,7 +32,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `usePushNotifications`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `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`, `ai` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -53,7 +53,6 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Call a connected third-party API (Slack, Stripe, Gmail, …), or an AI model on the user's own provider account | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
-| Let visitors turn on push notifications | [push-notifications/SKILL.md](./push-notifications/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
 
 ## Quick Decision Tree
@@ -98,9 +97,6 @@ Opening the app to an AI assistant over MCP?
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 
-Letting visitors turn on push notifications, or "notify users when …"?
-  load softr-sdk/push-notifications
-
 Showing a date, a time or a number on a page?
   load softr-sdk/formatting
 

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 **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.98
+  library_version: 0.0.99
 ---
 
 **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.98
+  library_version: 0.0.99
 ---
 
 # The current user
@@ -73,7 +73,7 @@ Never pass the visitor's id from a loader into a server function. The loader als
 ```ts
 import { createServerFn } from '@tanstack/react-start'
 import { defineQuery } from '@softr/sdk'
-import { ds } from '@softr/sdk/server'
+import { auth, ds } from '@softr/sdk/server'
 
 const myInvoices = defineQuery({
   id: 'myInvoices',
@@ -84,12 +84,14 @@ const myInvoices = defineQuery({
 })
 
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
-  if (!context.user) throw new Error('Not signed in')
-  const userId = context.user.id
-  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return { records: [], total: 0, nextOffset: null }
+  return await ds.list(myInvoices).where((q) => q.owner.isOneOf([me.id]))
 })
 ```
 
+Here `owner` links to Users, and `usersQuery` is the app's query on the Users table. `auth.currentUserRow` answers `null` when the visitor is signed out or has no row. See [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records) for the scope every read of the table takes.
+
 `context.user` is typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
 
 ### The visitor's role, in a server function

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 **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.98
+  library_version: 0.0.99
 ---
 
 # 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.98
+  library_version: 0.0.99
 ---
 
 **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.98
+  library_version: 0.0.99
 ---
 
 **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.98
+  library_version: 0.0.99
 ---
 
 # Installing the app

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 **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.
@@ -114,7 +114,7 @@ Resolves to nothing. A record that cannot be deleted throws.
 
 ### Change only the records the visitor may read
 
-When a role reads only some records of a table, it updates and deletes only those records. `permissions` decides who may run the mutation, not which record. The id comes from the browser, so it can name any record. Before the write, read the record through the same query and scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). Refuse the write when that read answers `null`, with the same error as a missing record, so the visitor cannot find out which ids exist. Keep the field that the scope filters on, such as the owner, out of the update's `fields`. If it is in `fields`, a visitor can move a record to another person.
+When a role reads only some records of a table, it updates and deletes only those records. `permissions` decides who may run the mutation, not which record. The id comes from the browser, so it can name any record. Before the write, read the record through the same query and scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). When the role changes fewer records than it reads, that read filters on the records it may change instead (see [Only the roles that change a table](#only-the-roles-that-change-a-table)). Refuse the write when that read answers `null`, with the same error as a missing record, so the visitor cannot find out which ids exist. Keep the field that the scope filters on, such as the owner, out of the update's `fields`. If it is in `fields`, a visitor can move a record to another person.
 
 Below, `bookings` is the query every read of bookings uses, and `usersQuery` is the app's query on the Users table. `updateBooking` declares `status` only, not `client`.
 
@@ -136,7 +136,7 @@ A delete takes the same read before `ds.delete`. A create into a table that take
 
 ### Only the roles that change a table
 
-Often fewer roles change a table than read it. A mutation's `customGroups` names only the roles that may change the table, also when more roles read it. In a barber app, every client reads the free hours, but only barbers open or close them. So the slot update names the barbers' group only, and a barber still changes only their own slots, through the read above:
+Often fewer roles change a table than read it. A mutation's `customGroups` names only the roles that may change the table, also when more roles read it. In a barber app, every client reads the free hours, but only barbers open or close them. So the slot update names the barbers' group only:
 
 ```ts
 const updateSlot = defineMutation({
@@ -148,6 +148,20 @@ const updateSlot = defineMutation({
 })
 ```
 
+A barber also changes only their own slots. Every client reads every slot, so the read scope does not stop one barber from changing another barber's hours. When a role changes fewer records than it reads, the read before the write filters on the records it may change. Here `slots` is the query every read of slots uses, and its `barber` field links to Users:
+
+```ts
+const setSlotOpen = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string(), open: z.boolean() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) throw new Error('Slot not found')
+    const slot = await ds.get(slots, { id: data.id }).where((q) => q.barber.isOneOf([me.id]))
+    if (slot === null) throw new Error('Slot not found')
+    await ds.update(updateSlot, { id: slot.id, data: { open: data.open } })
+  })
+```
+
 ### Edit an existing record
 
 An edit form needs both halves: a `defineQuery` to load the record and a `defineMutation` to save it. They are separate declarations over the same table, so give both the fields the form touches, and read the loaded values off the query's names.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 **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.
@@ -197,7 +197,7 @@ const getMyBooking = createServerFn()
   })
 ```
 
-The filter matches the field that holds the owner. A link to the Users table holds the visitor's row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds that row by email, or answers `null` when they are signed out or have no row. A `USER` field holds the account itself, so it filters on `context.user.id` after a check for a signed-out visitor. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+The filter matches the field that holds the owner. A link to the Users table holds the visitor's row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds that row by email, or answers `null` when they are signed out or have no row. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
 
 ### A picker over a scoped table
 
@@ -264,11 +264,13 @@ const listMessages = createServerFn()
     return await ds
       .list(messages)
       .where((q) => q.chat.isOneOf([chat.id]))
-      .orderBy((q) => q.sentAt.asc)
+      .orderBy((q) => q.sentAt.desc)
       .limit(100)
   })
 ```
 
+The read sorts newest first, so the limit keeps the newest 100 messages. Reverse them in the page to show the oldest on top.
+
 A server function that posts a message reads the chat the same way before `ds.create`.
 
 ### Other people's records show only what the role needs

package/skills/softr-sdk/record-queries/references/filters-and-sorting.md

@@ -125,7 +125,7 @@ Both take filters or nested groups:
 )
 ```
 
-Nesting goes two levels, a group inside a group. A third level throws `Cannot nest filter groups more than three levels deep.` Flatten by distributing the outer condition rather than nesting further.
+Groups nest to any depth.
 
 **An `$or` with no members matches every row.** When its members come from a list that can be empty, return no rows for an empty list instead of reading the table.
 
@@ -144,5 +144,4 @@ Each field carries `.asc` and `.desc` handles and nothing else. An array applies
 | --- | --- |
 | `a filter must come from the callback a read hands you` | A `where` value built as a plain object |
 | `a sort must come from the callback a read hands you` | An `orderBy` value not from the callback's `.asc` / `.desc` handles |
-| `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
 | A `TypeError` reading an operator off `undefined` | Filtering or sorting on a field the query does not declare |

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.98
+  library_version: 0.0.99
 ---
 
 **Boundary.** `definePage`, `pageHead`, 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.98
+  library_version: 0.0.99
 ---
 
 **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.

package/dist/push.d.ts

@@ -1,52 +0,0 @@
-import "@tanstack/react-start";
-
-//#region src/push.d.ts
-
-/** What the builder wrote in Studio for the prompt. Any of it may be missing. */
-type PushPrompt = {
-  title: string | null;
-  message: string | null;
-  enableButtonLabel: string | null;
-};
-type PushNotifications = /** Loading, signed out, push off for this app or device, or a browser without push. */
-{
-  status: "unavailable";
-}
-/** iPhone and iPad offer push only inside the installed app. */ | {
-  status: "install-first";
-  prompt: PushPrompt;
-} | {
-  status: "ask";
-  prompt: PushPrompt;
-  /** The visitor skipped the prompt recently, within the builder's skip days. Hide the prompt. */
-  dismissed: boolean;
-  /** Asks the browser for permission and subscribes. Call it from a click. */
-  subscribe: () => Promise<void>;
-  /** Hides the prompt for as long as the builder set in Studio. */
-  dismiss: () => void;
-} | {
-  status: "subscribed";
-  unsubscribe: () => Promise<void>;
-}
-/** The visitor blocked notifications in the browser. Only they can undo it, in the browser's settings. */ | {
-  status: "blocked";
-};
-/**
- * Push notifications for the signed-in visitor. Call it once, in the one
- * component that shows the prompt, rendered once in the root route's
- * `RootDocument`, so this browser stays registered and is unsubscribed on
- * sign-out. Each call keeps state of its own, so a second call does not see a
- * subscribe made through the first. Show a prompt only while `status` is `ask`
- * and the prompt is not `dismissed`.
- *
- * @example
- * function EnableNotifications() {
- *   const push = usePushNotifications()
- *   if (push.status !== "ask" || push.dismissed) return null
- *   const turnOn = () => push.subscribe().catch(() => toast.error("Notifications could not be turned on."))
- *   return <button onClick={turnOn}>{push.prompt.enableButtonLabel ?? "Turn on"}</button>
- * }
- */
-declare function usePushNotifications(): PushNotifications;
-//#endregion
-export { PushNotifications, PushPrompt, usePushNotifications };

package/dist/push.js

@@ -1,309 +0,0 @@
-import { logger } from "./logger.js";
-import { softrApiUrl } from "./softr-api.js";
-import { fetch } from "./fetch.js";
-import { sessionConfig } from "./auth/config.js";
-import { readSessionToken } from "./auth/session.js";
-import { detectPlatform } from "./pwa.js";
-import { z } from "zod";
-import { useCallback, useEffect, useState } from "react";
-import { createMiddleware } from "@tanstack/react-start";
-import { rootRouteId, useRouteContext } from "@tanstack/react-router";
-
-//#region src/push.ts
-const WORKER_PATH = "/_softr/sw.js";
-const SETTINGS_PATH = "/_softr/push.json";
-const SUBSCRIPTION_PATH = "/_softr/push";
-const TTL_MS = 6e4;
-const promptSchema = z.object({
-	title: z.string().nullable(),
-	message: z.string().nullable(),
-	enableButtonLabel: z.string().nullable(),
-	skipDays: z.number().nullable()
-});
-const settingsSchema = z.object({
-	vapidPublicKey: z.string(),
-	desktopEnabled: z.boolean(),
-	mobileEnabled: z.boolean(),
-	permissionPrompt: promptSchema.nullable()
-});
-const browserSubscriptionSchema = z.object({
-	endpoint: z.string(),
-	keys: z.object({
-		p256dh: z.string(),
-		auth: z.string()
-	})
-});
-let cachedSettings;
-let cachedWorker;
-/**
-* Reads through a one-minute cache. Never rejects: a failure reads as `null`
-* and is not remembered, so the next request tries again.
-*/
-function readCached(current, store, load) {
-	const now = Date.now();
-	const cached = current();
-	if (cached !== void 0 && cached.expires > now) return cached.value;
-	const entry = {
-		expires: now + TTL_MS,
-		value: load().catch((error) => {
-			logger.warn("Could not read push notifications from Softr:", error);
-			if (current() === entry) store(void 0);
-			return null;
-		})
-	};
-	store(entry);
-	return entry.value;
-}
-function platformPushUrl() {
-	const { applicationId } = sessionConfig();
-	return `${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${applicationId}/push`;
-}
-function readSettings() {
-	return readCached(() => cachedSettings, (entry) => cachedSettings = entry, async () => {
-		const response = await fetch(platformPushUrl(), { headers: { accept: "application/json" } });
-		if (response.status === 404) return null;
-		if (!response.ok) throw new Error(`The platform answered ${response.status}`);
-		return settingsSchema.parse(await response.json());
-	});
-}
-function readWorker() {
-	return readCached(() => cachedWorker, (entry) => cachedWorker = entry, async () => {
-		const response = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/pwa/sw.js`);
-		if (!response.ok) throw new Error(`The platform answered ${response.status}`);
-		return response.text();
-	});
-}
-/**
-* Serves push notifications from the app's own origin: the service worker, the
-* app's push settings, and saving or removing this browser's subscription for
-* the signed-in visitor. Every other request passes through untouched.
-*/
-function pushMiddleware() {
-	return createMiddleware({ type: "request" }).server(async ({ next, pathname, request }) => {
-		if (pathname === WORKER_PATH && request.method === "GET") {
-			const worker = await readWorker();
-			if (worker === null) return new Response(null, {
-				status: 503,
-				headers: { "cache-control": "no-store" }
-			});
-			return new Response(worker, { headers: {
-				"content-type": "text/javascript; charset=utf-8",
-				"cache-control": "no-cache",
-				"service-worker-allowed": "/"
-			} });
-		}
-		if (pathname === SETTINGS_PATH && request.method === "GET") {
-			const settings = await readSettings();
-			if (settings === null) return new Response(null, { status: 404 });
-			return Response.json(settings, { headers: { "cache-control": "no-store" } });
-		}
-		if (pathname === SUBSCRIPTION_PATH && (request.method === "POST" || request.method === "DELETE")) {
-			if (!request.headers.get("content-type")?.startsWith("application/json")) return new Response(null, { status: 415 });
-			const token = readSessionToken();
-			if (token === null) return new Response(null, { status: 401 });
-			const body = z.object({ subscription: browserSubscriptionSchema }).safeParse(await request.json().catch(() => null));
-			if (!body.success) return new Response(null, { status: 400 });
-			const response = request.method === "POST" ? await fetch(platformPushUrl(), {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					authorization: `Bearer ${token}`
-				},
-				body: JSON.stringify({
-					origin: new URL(request.url).origin,
-					userAgent: request.headers.get("user-agent"),
-					subscription: body.data.subscription
-				})
-			}) : await fetch(`${platformPushUrl()}?${new URLSearchParams({ endpoint: body.data.subscription.endpoint })}`, {
-				method: "DELETE",
-				headers: { authorization: `Bearer ${token}` }
-			});
-			return new Response(null, { status: response.ok ? 204 : response.status });
-		}
-		return next();
-	});
-}
-const DISMISSED_AT_KEY = "softr-push-dismissed-at";
-/**
-* Push notifications for the signed-in visitor. Call it once, in the one
-* component that shows the prompt, rendered once in the root route's
-* `RootDocument`, so this browser stays registered and is unsubscribed on
-* sign-out. Each call keeps state of its own, so a second call does not see a
-* subscribe made through the first. Show a prompt only while `status` is `ask`
-* and the prompt is not `dismissed`.
-*
-* @example
-* function EnableNotifications() {
-*   const push = usePushNotifications()
-*   if (push.status !== "ask" || push.dismissed) return null
-*   const turnOn = () => push.subscribe().catch(() => toast.error("Notifications could not be turned on."))
-*   return <button onClick={turnOn}>{push.prompt.enableButtonLabel ?? "Turn on"}</button>
-* }
-*/
-function usePushNotifications() {
-	const signedIn = useRouteContext({
-		from: rootRouteId,
-		select: (context) => context.user !== null
-	});
-	const [settings, setSettings] = useState(null);
-	const [registration, setRegistration] = useState(null);
-	const [subscribed, setSubscribed] = useState(false);
-	const [permission, setPermission] = useState("default");
-	const [dismissedAt, setDismissedAt] = useState(null);
-	useEffect(() => {
-		if (process.env.NODE_ENV !== "production" || !("serviceWorker" in navigator)) return;
-		if (!signedIn) {
-			navigator.serviceWorker.getRegistration("/").then((existing) => existing?.pushManager.getSubscription()).then((subscription) => subscription?.unsubscribe()).catch(() => {});
-			try {
-				localStorage.removeItem(DISMISSED_AT_KEY);
-			} catch {}
-			setDismissedAt(null);
-			setSettings(null);
-			setSubscribed(false);
-			return;
-		}
-		let cancelled = false;
-		(async () => {
-			const response = await globalThis.fetch(SETTINGS_PATH, { headers: { accept: "application/json" } });
-			if (!response.ok) return;
-			const parsed = settingsSchema.safeParse(await response.json());
-			if (!parsed.success || cancelled) return;
-			setDismissedAt(readDismissedAt());
-			setSettings(parsed.data);
-			if (!("PushManager" in window) || !("Notification" in window)) return;
-			setPermission(Notification.permission);
-			const registered = await navigator.serviceWorker.register(WORKER_PATH, { scope: "/" });
-			if (cancelled) return;
-			setRegistration(registered);
-			const existing = await registered.pushManager.getSubscription();
-			if (existing !== null && Notification.permission === "granted") setSubscribed(await sendSubscription("POST", existing));
-		})().catch((error) => logger.warn("Could not set up push notifications:", error));
-		return () => {
-			cancelled = true;
-		};
-	}, [signedIn]);
-	useEffect(() => {
-		if (registration === null) return;
-		return listenToWorker();
-	}, [registration]);
-	const subscribe = useCallback(async () => {
-		if (registration === null || settings === null) return;
-		const granted = await Notification.requestPermission();
-		setPermission(granted);
-		if (granted !== "granted") return;
-		const subscription = await registration.pushManager.subscribe({
-			userVisibleOnly: true,
-			applicationServerKey: decodeBase64Url(settings.vapidPublicKey)
-		});
-		if (!await sendSubscription("POST", subscription)) {
-			await subscription.unsubscribe();
-			throw new Error("Could not turn on push notifications");
-		}
-		setSubscribed(true);
-	}, [registration, settings]);
-	const unsubscribe = useCallback(async () => {
-		const subscription = await registration?.pushManager.getSubscription();
-		if (!subscription) return;
-		await sendSubscription("DELETE", subscription);
-		await subscription.unsubscribe();
-		setSubscribed(false);
-	}, [registration]);
-	const dismiss = useCallback(() => {
-		const now = Date.now();
-		try {
-			localStorage.setItem(DISMISSED_AT_KEY, String(now));
-		} catch {}
-		setDismissedAt(now);
-	}, []);
-	if (settings === null) return { status: "unavailable" };
-	const platform = detectPlatform();
-	if (platform !== "desktop" ? !settings.mobileEnabled : !settings.desktopEnabled) return { status: "unavailable" };
-	const prompt = {
-		title: settings.permissionPrompt?.title ?? null,
-		message: settings.permissionPrompt?.message ?? null,
-		enableButtonLabel: settings.permissionPrompt?.enableButtonLabel ?? null
-	};
-	if (platform === "ios" && !isStandalone()) return {
-		status: "install-first",
-		prompt
-	};
-	if (registration === null) return { status: "unavailable" };
-	if (subscribed) return {
-		status: "subscribed",
-		unsubscribe
-	};
-	if (permission === "denied") return { status: "blocked" };
-	return {
-		status: "ask",
-		prompt,
-		dismissed: isDismissed(dismissedAt, settings.permissionPrompt?.skipDays ?? null),
-		subscribe,
-		dismiss
-	};
-}
-async function sendSubscription(method, subscription) {
-	return (await globalThis.fetch(SUBSCRIPTION_PATH, {
-		method,
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify({ subscription: subscription.toJSON() })
-	})).ok;
-}
-/** A missing skip-days setting means a skipped prompt never comes back on its own. */
-function isDismissed(dismissedAt, skipDays) {
-	if (dismissedAt === null) return false;
-	if (skipDays === null) return true;
-	return Date.now() - dismissedAt < skipDays * 24 * 60 * 60 * 1e3;
-}
-function readDismissedAt() {
-	try {
-		const stored = Number(localStorage.getItem(DISMISSED_AT_KEY));
-		return Number.isFinite(stored) && stored > 0 ? stored : null;
-	} catch {
-		return null;
-	}
-}
-function isStandalone() {
-	return window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true;
-}
-/**
-* Answers the service worker, which routes a notification click to the
-* installed app when it is open, and keeps the app icon's badge right.
-*/
-function listenToWorker() {
-	const worker = navigator.serviceWorker;
-	const standalone = isStandalone();
-	if (standalone) worker.controller?.postMessage({ type: "pwa-standalone-opened" });
-	const onMessage = (event) => {
-		if (event.data === "is-this-standalone") {
-			event.ports[0]?.postMessage(standalone ? "yes" : "no");
-			return;
-		}
-		if (event.data?.type === "softr-pwa-redirect" && typeof event.data.url === "string") {
-			const target = new URL(event.data.url, window.location.href);
-			if (target.origin === window.location.origin) window.location.assign(target.href);
-		}
-	};
-	const onVisible = () => {
-		if (document.visibilityState === "visible") worker.controller?.postMessage("reset-badge-count");
-	};
-	const onInstallOffered = () => worker.controller?.postMessage({ type: "pwa-uninstalled" });
-	worker.addEventListener("message", onMessage);
-	document.addEventListener("visibilitychange", onVisible);
-	window.addEventListener("beforeinstallprompt", onInstallOffered);
-	onVisible();
-	return () => {
-		worker.removeEventListener("message", onMessage);
-		document.removeEventListener("visibilitychange", onVisible);
-		window.removeEventListener("beforeinstallprompt", onInstallOffered);
-	};
-}
-function decodeBase64Url(value) {
-	const base64 = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
-	const binary = atob(base64);
-	const bytes = new Uint8Array(binary.length);
-	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
-	return bytes;
-}
-
-//#endregion
-export { pushMiddleware, usePushNotifications };

package/skills/softr-sdk/push-notifications/SKILL.md

@@ -1,140 +0,0 @@
----
-name: push-notifications
-description: >-
-  Let signed-in visitors turn on push notifications: usePushNotifications for
-  the prompt, its states and the Studio texts, the PushNotifications and
-  PushPrompt types, and how to check that push is on for the app. Notifications
-  are sent by Softr Workflows, never by app code; the service worker is already
-  served, never write one.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.97
----
-
-# Push notifications
-
-The builder turns push on in Studio, under Users → Notifications, for desktop, mobile or both, and writes the prompt's texts there. Notifications are sent by a Softr Workflow's "Send notification" action, which the builder sets up in Studio. What the app adds is one thing: a prompt that lets the signed-in visitor turn notifications on in this browser.
-
-> **CRITICAL**: Never write a service worker, a `public/sw.js`, or any `navigator.serviceWorker`, `PushManager` or `Notification` code of your own. The app already serves its service worker, and `usePushNotifications()` registers it, subscribes and unsubscribes.
->
-> **CRITICAL**: Never send a push from app code. Sending is a Softr Workflow's "Send notification" action. When the builder asks for "notify X when Y", point them to that workflow; when Y is something the app does, the app triggers the workflow (load the Softr SDK `workflows` guidance). The app itself adds only the prompt.
-
-## Setup
-
-```ts
-import { usePushNotifications } from '@softr/sdk'
-import type { PushNotifications, PushPrompt } from '@softr/sdk'
-```
-
-```ts
-type PushPrompt = {
-  title: string | null              // what the builder wrote in Studio; any of these may be missing
-  message: string | null
-  enableButtonLabel: string | null
-}
-
-type PushNotifications =
-  | { status: 'unavailable' }       // loading, signed out, push off, this device type off, or no browser support
-  | { status: 'install-first'; prompt: PushPrompt }   // iPhone and iPad: push works only in the installed app
-  | {
-      status: 'ask'
-      prompt: PushPrompt
-      dismissed: boolean            // skipped recently, within the builder's skip days; hide the prompt
-      subscribe: () => Promise<void>  // call from a click
-      dismiss: () => void
-    }
-  | { status: 'subscribed'; unsubscribe: () => Promise<void> }
-  | { status: 'blocked' }           // blocked in the browser; only the visitor can undo it there
-```
-
-## Is push on for the app?
-
-Ask the running app for `/_softr/push.json`: `200` means push is on, `404` means it is off in Studio or the plan does not include it. Do not build a prompt against a `404`: push has to be turned on first. A change in Studio can take up to two minutes to reach the app.
-
-Push works only on the published app. Inside the Studio preview the hook always says `unavailable`, so the prompt never shows there. That is expected, not a bug to fix.
-
-## Core Patterns
-
-### The prompt
-
-Render it once, in `RootDocument` in `src/routes/__root.tsx`, so it shows on every page and the browser stays registered for the visitor. Use the prompt component the template ships when it has one. It already handles each status.
-
-Call `usePushNotifications()` in that one component only. Each call keeps state of its own: a second call, in a header or on a settings page, does not see a subscribe made through the first, so the prompt would stay on screen after the visitor said yes.
-
-`subscribe()` rejects when the browser or Softr refuses. Catch it and tell the visitor, so the button never fails in silence.
-
-```tsx
-function EnableNotifications() {
-  const push = usePushNotifications()
-  if (push.status !== 'ask' || push.dismissed) return null
-  return (
-    <div role="dialog">
-      <p>{push.prompt.title ?? 'Turn on notifications'}</p>
-      <p>{push.prompt.message ?? 'Get notified about updates.'}</p>
-      <button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
-        {push.prompt.enableButtonLabel ?? 'Turn on'}
-      </button>
-      <button onClick={push.dismiss}>Not now</button>
-    </div>
-  )
-}
-```
-
-Fall back to your own wording only where the builder left a text empty. On `install-first`, point the visitor to installing the app (load the Softr SDK `pwa` guidance); do not ask for permission.
-
-### Signing out
-
-Nothing to add. The browser is unsubscribed when the visitor signs out, so the next person on the device gets nothing meant for them.
-
-## Common Mistakes
-
-### CRITICAL Asking for permission on page load
-
-Wrong:
-
-```tsx
-useEffect(() => { push.status === 'ask' && push.subscribe() }, [push.status])
-```
-
-Correct:
-
-```tsx
-<button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
-  {push.prompt.enableButtonLabel ?? 'Turn on'}
-</button>
-```
-
-Browsers ignore or block a permission request that no click started, and a visitor who blocks it can only undo that in the browser's settings.
-
-Source: packages/sdk/src/push.ts
-
-### HIGH Showing the prompt whatever the status
-
-Wrong:
-
-```tsx
-const push = usePushNotifications()
-return <button onClick={() => push.subscribe()}>Turn on notifications</button>
-```
-
-Correct:
-
-```tsx
-const push = usePushNotifications()
-if (push.status !== 'ask' || push.dismissed) return null
-return (
-  <button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
-    {push.prompt.enableButtonLabel ?? 'Turn on'}
-  </button>
-)
-```
-
-The hook says `unavailable` when push is off in Studio, for this device type, or for a signed-out visitor. A prompt that skips the check shows in all of those, and on iPhone it asks for something the browser cannot give.
-
-Source: packages/sdk/src/push.ts
-
-## References
-
-- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on
-- [pwa/SKILL.md](../pwa/SKILL.md): installing the app, which iPhone and iPad need before push