@softr/sdk 0.0.56-alpha.0 → 0.0.56-alpha.1

package/dist/auth/isomorphic.d.ts

@@ -17,7 +17,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>], {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
 }>;

package/dist/auth/isomorphic.js

@@ -4,6 +4,7 @@ import { sessionConfig } from "./config.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
 import { makePlatform } from "./platform.js";
 import { bootErrorMiddleware } from "../boot-error.js";
+import { pwaMiddleware } from "../pwa.js";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
 import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 
@@ -21,7 +22,7 @@ import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 * }))
 */
 function softrAuthMiddleware() {
-	return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware()]).server(async ({ next }) => {
+	return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware(), pwaMiddleware()]).server(async ({ next }) => {
 		async function getSession() {
 			const token = readSessionToken();
 			const cached = readSessionData(token);

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react1 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react0.JSX.Element;
+}: Props): react1.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedErr
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.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 CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { type ActionPermissions, Audience, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, DefaultErrorOverlay, type FileAttachment, type FileItem, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -2,10 +2,11 @@ import { useFileUpload } from "./core/use-file-upload.js";
 import { defineComments, 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 { SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { Audience, DefaultErrorOverlay, SoftrPwaHead, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };

package/dist/mcp.d.ts

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

package/dist/package.js

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

package/dist/pwa.d.ts

@@ -0,0 +1,54 @@
+import * as react0 from "react";
+import "@tanstack/react-start";
+
+//#region src/pwa.d.ts
+
+/**
+ * The links that make the app installable: its manifest and its home screen
+ * icon. Render it once, in `<head>` in the root route's `RootDocument`.
+ *
+ * @example
+ * function RootDocument({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <HeadContent />
+ *         <SoftrPwaHead />
+ *       </head>
+ *       <body>
+ *         {children}
+ *         <Scripts />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ */
+declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
+type PwaPlatform = "ios" | "android" | "desktop";
+type PwaInstall = {
+  available: false;
+} | {
+  available: true;
+  /** Which steps install the app on this device. */
+  platform: PwaPlatform;
+  /** The name the home screen will show. */
+  name: string;
+  /** The icon the home screen will show. */
+  iconUrl: string;
+};
+/**
+ * Whether to offer installing the app, and on which platform. Render an
+ * install button only while this says `available`: it is unavailable while
+ * loading, when the builder has not turned the PWA on, when Softr has switched
+ * it off, and when the app already runs installed.
+ *
+ * @example
+ * function InstallButton() {
+ *   const install = usePwaInstall()
+ *   if (!install.available) return null
+ *   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
+ * }
+ */
+declare function usePwaInstall(): PwaInstall;
+//#endregion
+export { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall };

package/dist/pwa.js

@@ -0,0 +1,152 @@
+import { logger } from "./logger.js";
+import { fetch } from "./fetch.js";
+import { sessionConfig } from "./auth/config.js";
+import { platformApiUrl } from "./auth/platform.js";
+import { Fragment, createElement, useEffect, useState } from "react";
+import { createMiddleware } from "@tanstack/react-start";
+import { z } from "zod";
+
+//#region src/pwa.ts
+const MANIFEST_PATH = "/manifest.webmanifest";
+const ICON_PATH = "/apple-touch-icon.png";
+const INSTALL_PATH = "/_softr/pwa.json";
+const TTL_MS = 6e4;
+const CACHE_CONTROL = "public, max-age=60";
+const pwaSchema = z.object({
+	manifest: z.record(z.string(), z.unknown()),
+	install: z.object({
+		name: z.string(),
+		iconUrl: z.string()
+	})
+});
+let cached;
+/**
+* The app's PWA, or `null` when it is not installable right now. Never
+* rejects: a failure reads as not installable and is not remembered, so the
+* next request tries again.
+*/
+function readPwa() {
+	const now = Date.now();
+	if (cached !== void 0 && cached.expires > now) return cached.pwa;
+	const entry = {
+		expires: now + TTL_MS,
+		pwa: fetchPwa().catch((error) => {
+			logger.warn("Could not read the PWA settings:", error);
+			if (cached === entry) cached = void 0;
+			return null;
+		})
+	};
+	cached = entry;
+	return entry.pwa;
+}
+async function fetchPwa() {
+	const { applicationId } = sessionConfig();
+	const response = await fetch(`${await platformApiUrl()}/v1/vibe/applications/${applicationId}/pwa`, { headers: { accept: "application/json" } });
+	if (response.status === 404) return null;
+	if (!response.ok) throw new Error(`The platform answered ${response.status}`);
+	return pwaSchema.parse(await response.json());
+}
+/**
+* Serves the app's web app manifest, its home screen icon, and what an install
+* button needs to know, from the app's own origin. Every other request passes
+* through untouched.
+*
+* Answers 404, never an error page, when the app is not installable: a browser
+* silently drops a manifest it cannot parse, so a 500 there would be invisible.
+*/
+function pwaMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next, pathname }) => {
+		if (pathname !== MANIFEST_PATH && pathname !== ICON_PATH && pathname !== INSTALL_PATH) return next();
+		const pwa = await readPwa();
+		if (pwa === null) return new Response(null, { status: 404 });
+		if (pathname === MANIFEST_PATH) return new Response(JSON.stringify(pwa.manifest), { headers: {
+			"content-type": "application/manifest+json",
+			"cache-control": CACHE_CONTROL
+		} });
+		if (pathname === INSTALL_PATH) return Response.json(pwa.install, { headers: { "cache-control": CACHE_CONTROL } });
+		try {
+			const iconResponse = await fetch(pwa.install.iconUrl);
+			if (!iconResponse.ok) return new Response(null, { status: 404 });
+			return new Response(iconResponse.body, { headers: {
+				"content-type": "image/png",
+				"cache-control": CACHE_CONTROL
+			} });
+		} catch (error) {
+			logger.warn("Could not fetch the PWA icon:", error);
+			return new Response(null, { status: 404 });
+		}
+	});
+}
+/**
+* The links that make the app installable: its manifest and its home screen
+* icon. Render it once, in `<head>` in the root route's `RootDocument`.
+*
+* @example
+* function RootDocument({ children }: { children: React.ReactNode }) {
+*   return (
+*     <html lang="en">
+*       <head>
+*         <HeadContent />
+*         <SoftrPwaHead />
+*       </head>
+*       <body>
+*         {children}
+*         <Scripts />
+*       </body>
+*     </html>
+*   )
+* }
+*/
+function SoftrPwaHead() {
+	return createElement(Fragment, null, createElement("link", {
+		rel: "manifest",
+		href: MANIFEST_PATH
+	}), createElement("link", {
+		rel: "apple-touch-icon",
+		href: ICON_PATH
+	}));
+}
+const installSchema = pwaSchema.shape.install;
+/**
+* Whether to offer installing the app, and on which platform. Render an
+* install button only while this says `available`: it is unavailable while
+* loading, when the builder has not turned the PWA on, when Softr has switched
+* it off, and when the app already runs installed.
+*
+* @example
+* function InstallButton() {
+*   const install = usePwaInstall()
+*   if (!install.available) return null
+*   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
+* }
+*/
+function usePwaInstall() {
+	const [install, setInstall] = useState({ available: false });
+	useEffect(() => {
+		if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
+		let cancelled = false;
+		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;
+			setInstall({
+				available: true,
+				platform: detectPlatform(),
+				...parsed.data
+			});
+		}).catch(() => {});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	return install;
+}
+function detectPlatform() {
+	const userAgent = navigator.userAgent;
+	if (/iPhone|iPad|iPod/.test(userAgent) || /Macintosh/.test(userAgent) && navigator.maxTouchPoints > 1) return "ios";
+	if (/Android/.test(userAgent)) return "android";
+	return "desktop";
+}
+
+//#endregion
+export { SoftrPwaHead, pwaMiddleware, usePwaInstall };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 # Softr SDK core

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

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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/comments/SKILL.md

@@ -11,14 +11,14 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **Boundary.** `comments` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler. Importing it into a component fails the build. `useCommentComposer` lives on `@softr/sdk/client` and runs in components. `defineComments` comes from `@softr/sdk` and can be imported anywhere.
 
 # Comments on records
 
-Every record of a commented datasource has one thread. The SDK reads and writes it. The app owns everything you see: layout, copy, sort order, dates.
+Each record of a commented datasource has one thread. The SDK reads and writes it. The app owns what you see: layout, copy, order, dates.
 
 ## Setup
 
@@ -38,10 +38,10 @@ export const orderComments = defineComments({
 })
 ```
 
-- `id` is a name you choose, unique across the app. `datasourceId` is the table whose records get threads.
-- There is no `permissions`. Who may read, post and delete is set in Softr under Settings → Comments, the same settings native comment blocks use.
-- Declare it once per datasource. Two declarations on the same datasource are the **same** threads, so "internal notes" next to "customer comments" on one table is not possible.
-- Write the object inline. Passing it through a variable hides it from the build.
+- `id` is your name for it, unique in the app. `datasourceId` is the table that gets threads.
+- No `permissions`. Who can read, post and delete is set in Settings → Comments, shared with native blocks.
+- One declaration per datasource. Two on the same table are the **same** threads, so "internal notes" plus "customer comments" on one table isn't possible.
+- Write the object inline. A variable hides it from the build.
 
 ## Read a thread
 
@@ -51,26 +51,27 @@ const getThread = createServerFn({ method: 'GET' })
   .handler(({ data }) => comments.list(orderComments, { recordId: data.recordId, offset: data.offset }))
 ```
 
-`comments.list` answers `null` when this visitor cannot see comments on the record: comments are off for the app, the table is not set up yet, or the visitor's group may not read them. Render nothing for `null`, not an error.
+`comments.list` returns `null` when this visitor can't see comments on the record (comments are off, the table isn't set up, or their group can't read). Render nothing for `null`, not an error.
 
-Otherwise it answers:
+Otherwise it returns:
 
 | Field | What it is |
 | --- | --- |
-| `items` | The comments for this page, newest first. Each is a `CommentView` |
-| `canPost` | Whether this visitor may post. Hide the composer when false |
-| `allowMentions` | Whether `@` opens a mention menu. Do not call `searchMentions` when false |
-| `quickReactions` | The five `{ emoji, label }` a comment can be reacted with. There are no others |
-| `total`, `nextOffset` | Paging. The first page is the newest comments; each further page, fetched by passing `nextOffset` back as `offset`, goes further back in time. `null` on the last page |
-
-A `CommentView` is `{ id, bodyHtml, attachments, author: { name, avatar, isDeactivated }, createdAt, canDelete, canEdit, edited, source, reactions }`. `createdAt` is ISO 8601. Format it with `useUserTimezone`. Each reaction is `{ emoji, label, count, isSelected }`.
-
-- `allowAttachments` (on the thread): whether the composer may attach files.
-- `attachments[].type` (per attachment): the file's content type, or `null` when the platform does not know it.
-- `notificationsEnabled` (on the thread): whether to show the notifications switch at all. Hide it when false, even for a visitor who may post.
-- `canEdit` (per comment): whether this visitor may edit it. Show Edit only then.
-- `edited` (per comment): whether it was changed since it was posted. Show "(edited)" beside its date.
-- `source` (per comment): `{ text, mentions }` to fill an edit box, or `null` when `canEdit` is false. It is the body as the visitor typed it, with each mention as its own `@name` and range, the same shape the composer works with.
+| `items` | This page's comments, newest first. Each is a `CommentView` |
+| `canPost` | Whether the visitor can post. Hide the composer when false |
+| `allowMentions` | Whether `@` opens a mention menu. Don't call `searchMentions` when false |
+| `allowAttachments` | Whether the composer can attach files |
+| `notificationsEnabled` | Whether to show the notifications switch at all |
+| `quickReactions` | The five `{ emoji, label }` reactions. There are no others |
+| `total`, `nextOffset` | Paging. Pass `nextOffset` back as `offset` to get the next, older page. `null` on the last page |
+
+A `CommentView` is `{ id, bodyHtml, attachments, author: { name, avatar, isDeactivated }, createdAt, canDelete, canEdit, edited, source, reactions }`.
+
+- `createdAt` is ISO 8601. Format it with `useUserTimezone`.
+- `attachments` are `{ url, filename, type }`. `type` is `null` when unknown.
+- `edited` is true once the comment changed after posting.
+- `source` is `{ text, mentions }` for the edit box, or `null` when `canEdit` is false.
+- Each reaction is `{ emoji, label, count, isSelected }`.
 
 `bodyHtml` is already sanitised. Render it with `dangerouslySetInnerHTML` and nothing else:
 
@@ -78,7 +79,7 @@ A `CommentView` is `{ id, bodyHtml, attachments, author: { name, avatar, isDeact
 <div className="comment-body" dangerouslySetInnerHTML={{ __html: comment.bodyHtml }} />
 ```
 
-It holds `p`, `br`, `strong`, `em`, `u`, `s`, `del`, `a`, `ul`, `ol`, `li`, `code`, `pre`, `blockquote`, `h1`–`h3` and mention `span[data-type="mention"]`. Links open in a new tab. Style those tags under the body's class, because the reset strips list bullets, link colour and spacing.
+It holds `p`, `br`, `strong`, `em`, `u`, `s`, `del`, `a`, `ul`, `ol`, `li`, `code`, `pre`, `blockquote`, `h1`–`h3` and mentions (`span[data-type="mention"]`). Links open in a new tab. Style these tags under the body's class: the reset strips bullets, link colour and spacing.
 
 ## Post a comment
 
@@ -95,43 +96,43 @@ const postComment = createServerFn({ method: 'POST' })
   .handler(({ data }) => comments.create(orderComments, data))
 ```
 
-Pass the composer's `text` as `body` and its `mentions` as they are. The SDK stores the mentions in the format native blocks read, and the people mentioned get an email. A mention whose `@name` was edited is posted as plain text.
-
-`attachments` are the files the visitor uploaded with the post, from `useFileUpload(orderComments).files.filter((f) => f.status === 'done')`. Send them only when the thread's `allowAttachments` is true.
+Pass the composer's `text` and `mentions` as they are. Mentioned people get an email. A mention whose `@name` was edited posts as plain text.
 
-`useFileUpload` takes the comments declaration as it takes a mutation. No extra declaration.
+`attachments` are the finished uploads: `useFileUpload(orderComments).files.filter((f) => f.status === 'done')`. `useFileUpload` takes the comments declaration like a mutation. Send files only when `allowAttachments` is true. A comment needs text or at least one file.
 
 ## The composer
 
 ```tsx
 const composer = useCommentComposer()
+const { files, isUploading, upload, remove } = useFileUpload(orderComments)
+const done = files.filter((f) => f.status === 'done')
 
 <textarea {...composer.textareaProps} placeholder="Write a comment" />
 {/* While composer.query is not null, list findPeople's answer for it. Picking a person calls composer.pick(person). */}
 <button
-  disabled={composer.text.trim() === ''}
+  disabled={(composer.text.trim() === '' && done.length === 0) || isUploading}
   onClick={async () => {
-    await postComment({ data: { recordId, body: composer.text, mentions: composer.mentions } })
+    await postComment({ data: { recordId, body: composer.text, mentions: composer.mentions, attachments: done } })
     composer.reset()
+    done.forEach((f) => remove(f.id))
   }}
 >
   Post
 </button>
 ```
 
-- Spread `textareaProps` onto the `<textarea>`. It carries the `ref`, `value`, `onChange` and `onSelect` the composer needs, so do not replace them.
-- `query` is what follows `@` before the caret, or `null`. It is `""` the moment `@` is typed.
-- `pick({ name, email })` writes `@name`, records the mention and puts the caret after it.
-- `reset()` empties the box. Call it after the post succeeds, never before.
+- Spread `textareaProps` onto the `<textarea>` and don't override its handlers.
+- `query` is the text after `@` before the caret, or `null`. It's `""` right after `@` is typed.
+- `pick({ name, email })` writes `@name`, records the mention and moves the caret after it.
+- `reset()` empties the box. Call it only after the post succeeds.
 
 ## Editing a comment
 
-Offer Edit only where the comment's `canEdit` is true.
+Offer Edit only where `canEdit` is true. Mount the edit box only while editing.
 
-- Fill the edit box with `useCommentComposer({ initial: comment.source })`, mounted only while editing.
-- Seed the edit's `useFileUpload` with the comment's kept files: `useFileUpload(orderComments, { initialAttachments: comment.attachments.map((a) => ({ ...a, id: a.url })) })`. A comment's attachment has no `id` of its own, so the url stands in for one.
-- Pass `comment.attachments` (the files kept) plus any new uploads to `comments.update` as `attachments`.
-- Re-read the thread after the write. `update` answers nothing.
+- Text: `useCommentComposer({ initial: comment.source })`.
+- Files: `useFileUpload(orderComments, { initialAttachments: comment.attachments.map((a) => ({ ...a, id: a.url })) })`. Attachments have no `id`, so the url stands in.
+- Save with `comments.update`, passing the full file list: the kept files plus new uploads. With `allowAttachments` false the server keeps the old files whatever you send.
 
 ## Mentions
 
@@ -141,7 +142,7 @@ const findPeople = createServerFn({ method: 'GET' })
   .handler(({ data }) => comments.searchMentions(orderComments, data))
 ```
 
-It answers `[{ name, email, avatar }]`, the people this visitor may mention whose name or email matches. Who is mentionable is set in Settings → Comments, per user group.
+It returns `[{ name, email, avatar }]`: people the visitor can mention whose name or email matches. Who's mentionable is set per user group in Settings → Comments.
 
 ## Delete, update, react, subscribe
 
@@ -153,29 +154,26 @@ const subscribed = await comments.subscription(orderComments, { recordId })
 await comments.setSubscription(orderComments, { recordId, subscribed: !subscribed })
 ```
 
-Each runs inside its own server function, like `list`.
+Each runs in its own server function, like `list`. Writes return nothing, so re-read the thread after each one.
 
 - Offer delete only where `canDelete` is true.
-- `update` saves an edit; see "Editing a comment" above for `attachments`.
-- `react` adds the visitor's reaction when `selected` is true and removes it when false. `emoji` must be one of `quickReactions`.
-- A subscription is whether the visitor gets an email when someone comments on this record. It needs a
-  signed-in visitor. Posting subscribes the author, and a mention subscribes the person mentioned.
-- Mails go out a few minutes after a comment, never to its own author, and only while notifications are
-  on in Settings → Comments.
-
-Re-read the thread after each write. The writes answer nothing.
+- `react` adds the reaction when `selected` is true and removes it when false. `emoji` must be one of `quickReactions`.
+- A subscription means the visitor gets an email about new comments on the record. It needs a signed-in visitor. Posting subscribes the author; a mention subscribes the person mentioned.
+- Mails go out a few minutes after a comment, never to its author, and only while notifications are on in Settings → Comments.
 
 ## Failure modes
 
-**Keying the thread on the URL instead of the record.** Pass the fetched `record.id` as `recordId`, never a route param or a search param. A param can be a slug, stale, or a different record's id, and the thread then shows another record's comments.
+**Keying the thread on the URL.** Pass the fetched `record.id`, never a route or search param. A param can be a slug or stale, and the thread shows another record's comments.
+
+**Treating `null` as an error.** Render nothing. An error box shows every such visitor a broken page.
 
-**Treating `null` as an error.** A visitor who may not read comments gets `null`. Render nothing. An error box for it shows every such visitor a broken page.
+**Rendering a body as text, or sanitising it again.** Use `bodyHtml` with `dangerouslySetInnerHTML`. As text it shows raw tags; a second sanitiser strips the mentions.
 
-**Rendering a body as text, or sanitising it again.** Use `bodyHtml` with `dangerouslySetInnerHTML`. As text it shows raw tags, and a second sanitiser strips the mention markup.
+**Inventing reactions.** Only `quickReactions` can be stored. `react` throws for anything else.
 
-**Inventing reactions.** Only the five in `quickReactions` can be stored. `react` throws for any other emoji.
+**Sending only new files on edit.** `update` replaces the whole list, so kept files you leave out get deleted.
 
-**Calling `comments.*` from a component.** It is server only. Wrap each call in a `createServerFn`.
+**Calling `comments.*` from a component.** It's server only. Wrap each call in a `createServerFn`.
 
 ## References
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 # The current user

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

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

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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

@@ -0,0 +1,77 @@
+---
+name: pwa
+description: >-
+  Let visitors install the app on their home screen: SoftrPwaHead for the
+  manifest and icon links, usePwaInstall to decide whether to show an install
+  button and which platform's steps to show, the PwaInstall and PwaPlatform
+  types, and how to check that the app is installable. The manifest and icon
+  are already served; never write them.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.56-alpha.1
+---
+
+# Installing the app
+
+The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
+
+> **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
+> **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
+
+## Setup
+
+```ts
+import { SoftrPwaHead, usePwaInstall } from '@softr/sdk'
+import type { PwaInstall, PwaPlatform } from '@softr/sdk'
+```
+
+```ts
+type PwaPlatform = 'ios' | 'android' | 'desktop'
+
+type PwaInstall =
+  | { available: false }
+  | {
+      available: true
+      platform: PwaPlatform   // which steps install the app on this device
+      name: string            // what the home screen will show
+      iconUrl: string         // the icon the home screen will show
+    }
+```
+
+## Is the app installable?
+
+The builder switches installing on in Studio, and `usePwaInstall()` reads that switch at runtime. To check it before writing any code, ask the running app for `/_softr/pwa.json`: `200` means installable, `404` means installing is off or there is no icon yet. Do not build an install button against a `404`: installing has to be turned on first. A change in Studio can take up to two minutes to reach the app.
+
+## Core Patterns
+
+### The links: `<SoftrPwaHead />`
+
+Render it once, in `<head>` next to `<HeadContent />`, in `RootDocument` in `src/routes/__root.tsx`.
+
+```tsx
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+        <SoftrPwaHead />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+### Whether to show a button: `usePwaInstall()`
+
+It fetches after mount, so the first render, the server render included, always says `available: false`. It stays unavailable when the app is not installable, when the request fails, and when the app already runs installed from the home screen. Inside the Studio preview it says available, so the builder can see the button; installing itself only works on the published app.
+
+There is no `install()` to call. No browser opens its install dialog for this app on request, so the button opens steps for `platform` instead: Share, then Add to Home Screen on iOS; the browser menu's Install app on Android and desktop. `name` and `iconUrl` tell the visitor what they are adding.
+
+## References
+
+- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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.56-alpha.0
+  library_version: 0.0.56-alpha.1
 ---
 
 **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/region-visibility/SKILL.md

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