@softr/sdk 0.0.55 → 0.0.56-alpha.0

package/dist/comments/use-comment-composer.d.ts

@@ -0,0 +1,46 @@
+import { CommentMention } from "./comments.js";
+import { ChangeEvent, RefObject, SyntheticEvent } from "react";
+
+//#region src/comments/use-comment-composer.d.ts
+
+/**
+ * The state of a comment box: the text, the people mentioned in it, and the `@` fragment being
+ * typed. Spread `textareaProps` onto a `<textarea>`. Show a mention menu while `query` is not
+ * `null`, and call `pick` with the person chosen from it.
+ *
+ * Post `text` and `mentions` as they are, then call `reset` once the post succeeds.
+ *
+ * To edit a comment, pass its source as initial, in a composer mounted only while editing.
+ * `initial` is read once, on mount.
+ *
+ * @example
+ * const composer = useCommentComposer()
+ * <textarea {...composer.textareaProps} />
+ * {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+ */
+declare function useCommentComposer(options?: {
+  /** Fills the box to edit a comment: pass its `source`. */
+  initial?: {
+    text: string;
+    mentions: ReadonlyArray<CommentMention>;
+  };
+}): {
+  text: string;
+  mentions: Array<CommentMention>;
+  /** What follows the `@` before the caret, or `null` when the caret is not in a mention. */
+  query: string | null;
+  textareaProps: {
+    ref: RefObject<HTMLTextAreaElement | null>;
+    value: string;
+    onChange: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+    onSelect: (event: SyntheticEvent<HTMLTextAreaElement>) => void;
+  };
+  /** Replaces the `@` fragment with the person's `@name`, and puts the caret after it. */
+  pick: (person: {
+    name: string;
+    email: string;
+  }) => void;
+  reset: () => void;
+};
+//#endregion
+export { useCommentComposer };

package/dist/comments/use-comment-composer.js

@@ -0,0 +1,134 @@
+import { assert } from "../assertions.js";
+import { useLayoutEffect, useRef, useState } from "react";
+
+//#region src/comments/use-comment-composer.ts
+const EMPTY = {
+	text: "",
+	mentions: [],
+	caret: 0
+};
+/**
+* The state of a comment box: the text, the people mentioned in it, and the `@` fragment being
+* typed. Spread `textareaProps` onto a `<textarea>`. Show a mention menu while `query` is not
+* `null`, and call `pick` with the person chosen from it.
+*
+* Post `text` and `mentions` as they are, then call `reset` once the post succeeds.
+*
+* To edit a comment, pass its source as initial, in a composer mounted only while editing.
+* `initial` is read once, on mount.
+*
+* @example
+* const composer = useCommentComposer()
+* <textarea {...composer.textareaProps} />
+* {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+*/
+function useCommentComposer(options) {
+	const [state, setState] = useState(() => options?.initial === void 0 ? EMPTY : {
+		text: options.initial.text,
+		mentions: [...options.initial.mentions],
+		caret: options.initial.text.length
+	});
+	const ref = useRef(null);
+	const pendingCaret = useRef(null);
+	useLayoutEffect(() => {
+		const caret = pendingCaret.current;
+		if (caret === null || ref.current === null) return;
+		pendingCaret.current = null;
+		ref.current.focus();
+		ref.current.setSelectionRange(caret, caret);
+	});
+	const fragment = findMentionQuery(state.text, state.caret, state.mentions);
+	return {
+		text: state.text,
+		mentions: state.mentions,
+		query: fragment?.query ?? null,
+		textareaProps: {
+			ref,
+			value: state.text,
+			onChange(event) {
+				const next = event.currentTarget.value;
+				const caret = event.currentTarget.selectionStart;
+				setState((previous) => ({
+					text: next,
+					mentions: remapMentions(previous.text, next, previous.mentions),
+					caret
+				}));
+			},
+			onSelect(event) {
+				const caret = event.currentTarget.selectionStart;
+				setState((previous) => previous.caret === caret ? previous : {
+					...previous,
+					caret
+				});
+			}
+		},
+		pick(person) {
+			assert(fragment, "pick needs an @ fragment under the caret");
+			const label = `@${person.name}`;
+			const text = `${state.text.slice(0, fragment.start)}${label} ${state.text.slice(state.caret)}`;
+			const added = {
+				...person,
+				start: fragment.start,
+				end: fragment.start + label.length
+			};
+			const caret = added.end + 1;
+			pendingCaret.current = caret;
+			setState({
+				text,
+				mentions: [...remapMentions(state.text, text, state.mentions), added],
+				caret
+			});
+		},
+		reset() {
+			setState(EMPTY);
+		}
+	};
+}
+/** A fragment longer than this is prose, not a name being typed. */
+const MENTION_QUERY_MAX_LENGTH = 32;
+/**
+* Moves mention ranges through an edit. A textarea reports only its new value, so the edit is the
+* span between the longest common prefix and suffix. Ranges after it shift. Ranges it reached into
+* are dropped, which is how deleting part of a name un-mentions that person.
+*/
+function remapMentions(previous, next, mentions) {
+	if (previous === next) return mentions;
+	let prefix = 0;
+	while (prefix < previous.length && prefix < next.length && previous[prefix] === next[prefix]) prefix += 1;
+	let suffix = 0;
+	while (suffix < previous.length - prefix && suffix < next.length - prefix && previous[previous.length - 1 - suffix] === next[next.length - 1 - suffix]) suffix += 1;
+	const editStart = prefix;
+	const editEnd = previous.length - suffix;
+	const delta = next.length - previous.length;
+	return mentions.flatMap((mention) => {
+		if (mention.end <= editStart) return [mention];
+		if (mention.start >= editEnd) return [{
+			...mention,
+			start: mention.start + delta,
+			end: mention.end + delta
+		}];
+		return [];
+	});
+}
+/**
+* The `@` fragment the caret sits in, or `null`. An `@` does not count when:
+* - it does not start a word, so an email address opens no menu;
+* - it belongs to a mention already made;
+* - the fragment ran past a newline or is long enough to be prose. Spaces are fine, names have them.
+*/
+function findMentionQuery(text, caret, mentions) {
+	const before = text.slice(0, caret);
+	const at = before.lastIndexOf("@");
+	if (at === -1) return null;
+	if (at > 0 && !/\s/.test(before.charAt(at - 1))) return null;
+	if (mentions.some((mention) => at >= mention.start && at < mention.end)) return null;
+	const query = before.slice(at + 1);
+	if (query.includes("\n") || query.length > MENTION_QUERY_MAX_LENGTH) return null;
+	return {
+		query,
+		start: at
+	};
+}
+
+//#endregion
+export { useCommentComposer };

package/dist/core/file-upload.d.ts

@@ -1,4 +1,4 @@
-import { DatasourceAction } from "../action.js";
+import { CommentsAction, DatasourceAction } from "../action.js";
 
 //#region src/core/file-upload.d.ts
 
@@ -10,7 +10,12 @@ type FileAttachment = {
   url: string;
   filename: string;
   id: string;
+  type?: string | null;
 };
-declare function upload(action: DatasourceAction, file: File): Promise<FileAttachment>;
+/**
+ * A COMMENTS action uploads a comment attachment.
+ * The platform checks the comment settings.
+ */
+declare function upload(action: DatasourceAction | CommentsAction, file: File): Promise<FileAttachment>;
 //#endregion
 export { FileAttachment, upload };

package/dist/core/file-upload.js

@@ -5,6 +5,10 @@ import { platformApiUrl } from "../auth/platform.js";
 import { randomUUID } from "node:crypto";
 
 //#region src/core/file-upload.ts
+/**
+* A COMMENTS action uploads a comment attachment.
+* The platform checks the comment settings.
+*/
 async function upload(action, file) {
 	const { applicationId } = sessionConfig();
 	const baseUrl = await platformApiUrl();
@@ -23,7 +27,8 @@ async function upload(action, file) {
 	return {
 		url: resultJSON.url,
 		filename: resultJSON.filename || "Untitled file",
-		id: resultJSON.id || randomUUID()
+		id: resultJSON.id || randomUUID(),
+		type: resultJSON.type ?? null
 	};
 }
 

package/dist/core/use-file-upload.d.ts

@@ -1,4 +1,4 @@
-import { DatasourceAction } from "../action.js";
+import { CommentsAction, DatasourceAction } from "../action.js";
 import { FileAttachment } from "./file-upload.js";
 
 //#region src/core/use-file-upload.d.ts
@@ -16,7 +16,7 @@ type FileItem = {
   filename: string;
   error: Error;
 };
-declare function useFileUpload(action: DatasourceAction, options?: {
+declare function useFileUpload(action: DatasourceAction | CommentsAction, options?: {
   initialAttachments?: FileAttachment[];
 }): {
   files: FileItem[];

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

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

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import { CommentAttachmentInput, CommentMention, CommentThread, CommentView } from "./comments/comments.js";
 import { SoftrContext } from "./auth/context.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { 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, DefaultErrorOverlay, type FileAttachment, type FileItem, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+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 };

package/dist/index.js

@@ -1,12 +1,11 @@
 import { useFileUpload } from "./core/use-file-upload.js";
-import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.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, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/mcp.d.ts

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

package/dist/package.js

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

package/dist/server.d.ts

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

package/dist/server.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.55",
+  "version": "0.0.56-alpha.0",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
@@ -17,6 +17,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "marked": "^18.0.14",
+    "xss": "^1.0.15",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.55
+  library_version: 0.0.56-alpha.0
 ---
 
 # Softr SDK core
@@ -29,9 +29,9 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
-| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
-| `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineComments`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration`, `comments` |
+| `@softr/sdk/client` | Browser only | `useCommentComposer` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
 ## Sub-Skills
@@ -48,7 +48,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
-| Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
+| Add comments to a record | [comments/SKILL.md](./comments/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -83,8 +83,8 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
-Adding an install button, or making the app installable?
-  load softr-sdk/pwa
+Letting visitors comment on a record?
+  load softr-sdk/comments
 
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.

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

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

@@ -0,0 +1,182 @@
+---
+name: comments
+description: >-
+  Comment threads on records: defineComments from @softr/sdk declares which
+  datasource has comments; comments.list, create, update, delete, react,
+  subscription, setSubscription and searchMentions from @softr/sdk/server read
+  and write one record's thread inside a server function; useCommentComposer
+  and useFileUpload from @softr/sdk/client keep a textarea's text, its
+  @mentions and its attachments in step. Bodies come back as sanitised
+  bodyHtml. A null thread means render nothing.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.56-alpha.0
+---
+
+**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.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineComments, type CommentMention, type CommentAttachmentInput } from '@softr/sdk'
+import { comments } from '@softr/sdk/server'
+import { useCommentComposer, useFileUpload } from '@softr/sdk/client'
+```
+
+## Declare the comments action
+
+```ts
+export const orderComments = defineComments({
+  id: 'orderComments',
+  datasourceId: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+})
+```
+
+- `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.
+
+## Read a thread
+
+```ts
+const getThread = createServerFn({ method: 'GET' })
+  .validator((data: { recordId: string; offset?: number | null }) => data)
+  .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.
+
+Otherwise it answers:
+
+| 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.
+
+`bodyHtml` is already sanitised. Render it with `dangerouslySetInnerHTML` and nothing else:
+
+```tsx
+<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.
+
+## Post a comment
+
+```ts
+const postComment = createServerFn({ method: 'POST' })
+  .validator(
+    (data: {
+      recordId: string
+      body: string
+      mentions: Array<CommentMention>
+      attachments?: Array<CommentAttachmentInput>
+    }) => data,
+  )
+  .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.
+
+`useFileUpload` takes the comments declaration as it takes a mutation. No extra declaration.
+
+## The composer
+
+```tsx
+const composer = useCommentComposer()
+
+<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() === ''}
+  onClick={async () => {
+    await postComment({ data: { recordId, body: composer.text, mentions: composer.mentions } })
+    composer.reset()
+  }}
+>
+  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.
+
+## Editing a comment
+
+Offer Edit only where the comment's `canEdit` is true.
+
+- 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.
+
+## Mentions
+
+```ts
+const findPeople = createServerFn({ method: 'GET' })
+  .validator((data: { query: string }) => data)
+  .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.
+
+## Delete, update, react, subscribe
+
+```ts
+await comments.delete(orderComments, { recordId, commentId })
+await comments.update(orderComments, { recordId, commentId, body, mentions, attachments })
+await comments.react(orderComments, { recordId, commentId, emoji: '👍', selected: !reaction.isSelected })
+const subscribed = await comments.subscription(orderComments, { recordId })
+await comments.setSubscription(orderComments, { recordId, subscribed: !subscribed })
+```
+
+Each runs inside its own server function, like `list`.
+
+- 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.
+
+## 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.
+
+**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, and a second sanitiser strips the mention markup.
+
+**Inventing reactions.** Only the five in `quickReactions` can be stored. `react` throws for any other emoji.
+
+**Calling `comments.*` from a component.** It is server only. Wrap each call in a `createServerFn`.
+
+## References
+
+- [record-queries/SKILL.md](../record-queries/SKILL.md): fetching the record whose `id` keys the thread

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.55
+  library_version: 0.0.56-alpha.0
 ---
 
 # 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.55
+  library_version: 0.0.56-alpha.0
 ---
 
 **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.
@@ -75,9 +75,10 @@ function ApplicationForm() {
 
 ```ts
 type FileAttachment = {
-  url: string      // clean URL, no internal query params
-  filename: string // original filename
-  id: string       // file id extracted from the upload response
+  url: string             // clean URL, no internal query params
+  filename: string        // original filename
+  id: string              // file id extracted from the upload response
+  type?: string | null    // content type from the upload response, or null when the platform doesn't know it
 }
 ```
 

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

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