@softr/sdk 0.0.74-alpha.0 → 0.0.75

package/dist/core/options.js

@@ -1,37 +1,9 @@
-import { assert } from "../assertions.js";
-import { fetch } from "../fetch.js";
-import { readSessionToken } from "../auth/session.js";
 import { makeChain } from "../datasource/fields.js";
-import { describeFailure, dsUrl, listRecords, refererHeader, resolveTarget } from "../datasource/record.js";
+import { listRecords } from "../datasource/record.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/core/options.ts
 /**
-* The choices a SELECT field holds right now, read from Softr on every call. A choice the
-* builder adds or renames later shows up without a new build. The field must be one the
-* action declares. Any query or mutation over the table works.
-*
-* @example
-* const loadStatuses = createServerFn().handler(() => ds.choices(listProjects, 'status'))
-*/
-async function listChoices(action, field) {
-	const { actionId, select } = resolveTarget(action, action.resource.operation);
-	const fieldId = select[field];
-	assert(fieldId, () => `action "${actionId}" declares no field "${field}"`);
-	const res = await fetch(`${dsUrl(actionId)}/metadata`, { headers: {
-		Authorization: `Bearer ${readSessionToken()}`,
-		...refererHeader()
-	} });
-	if (!res.ok) throw new Error(`datasource metadata failed for "${actionId}": ${await describeFailure(res)}`);
-	const metadataField = (await res.json()).fields.find(({ id }) => id === fieldId);
-	assert(metadataField?.type === "SELECT", () => `"${field}" on action "${actionId}" is not a SELECT field`);
-	return (metadataField.options?.choices ?? []).map(({ id, label, color }) => ({
-		id,
-		label,
-		color: color ?? null
-	}));
-}
-/**
 * The rows a linked field can point at, for a picker: each record of the query as its id and the text
 * of one field, searched on that field when a term is given, a page at a time.
 *
@@ -64,4 +36,4 @@ function labelOf(value) {
 }
 
 //#endregion
-export { listChoices, listOptions };
+export { listOptions };

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/datasource/datasource.d.ts

@@ -1,5 +1,5 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
-import { listChoices, listOptions } from "../core/options.js";
+import { listOptions } from "../core/options.js";
 import { chart, metric } from "./chart.js";
 import "@tanstack/react-start/server-only";
 
@@ -13,7 +13,6 @@ declare const ds: {
   metric: typeof metric;
   chart: typeof chart;
   options: typeof listOptions;
-  choices: typeof listChoices;
 };
 //#endregion
 export { ds };

package/dist/datasource/datasource.js

@@ -1,6 +1,6 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
 import { chart, metric } from "./chart.js";
-import { listChoices, listOptions } from "../core/options.js";
+import { listOptions } from "../core/options.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/datasource/datasource.ts
@@ -12,8 +12,7 @@ const ds = {
 	delete: deleteRecord,
 	metric,
 	chart,
-	options: listOptions,
-	choices: listChoices
+	options: listOptions
 };
 
 //#endregion

package/dist/datasource/fields.d.ts

@@ -19,21 +19,17 @@ type NumberChain = EmptyChain & {
   lte(value: number): ConstructableFilter;
   between(start: number, end: number): ConstructableFilter;
 };
-type ArrayChain = EmptyChain & {
-  is(values: Array<string>): ConstructableFilter;
-  isOneOf(values: Array<string>): ConstructableFilter;
-  isNoneOf(values: Array<string>): ConstructableFilter;
-  hasAllOf(values: Array<string>): ConstructableFilter;
+type ArrayChain<TMember$1 extends string> = EmptyChain & {
+  is(values: Array<TMember$1>): ConstructableFilter;
+  isOneOf(values: Array<TMember$1>): ConstructableFilter;
+  isNoneOf(values: Array<TMember$1>): ConstructableFilter;
+  hasAllOf(values: Array<TMember$1>): ConstructableFilter;
 };
-/**
- * Compares choice ids as plain strings. A select's choices change in Studio after the build,
- * and an id read at runtime from ds.choices has to be a valid filter value.
- */
-type ChoiceChain = EmptyChain & {
-  is(value: string): ConstructableFilter;
-  isNot(value: string): ConstructableFilter;
-  isOneOf(values: Array<string>): ConstructableFilter;
-  isNoneOf(values: Array<string>): ConstructableFilter;
+type ChoiceChain<TId$1 extends string> = EmptyChain & {
+  is(value: TId$1): ConstructableFilter;
+  isNot(value: TId$1): ConstructableFilter;
+  isOneOf(values: Array<TId$1>): ConstructableFilter;
+  isNoneOf(values: Array<TId$1>): ConstructableFilter;
 };
 /** What DSv2 filters generically: matched whole or scanned, never against a set. */
 type GenericChain = EmptyChain & {
@@ -77,20 +73,32 @@ type AnyChain = EmptyChain & {
   between(start: number | string, end: number | string): ConstructableFilter;
   isNotBetween(start: number | string, end: number | string): ConstructableFilter;
 };
+type IdOf<TValue> = TValue extends {
+  id: infer TId extends string;
+} ? TId : string;
+/**
+ * What a choice-shaped field compares against: its own ids where codegen read the choice
+ * list, and any string where it did not. A linked record is the open case, and it is the
+ * only thing distinguishing one from a select at the type level.
+ */
+type ChoiceIds<TValue> = string extends IdOf<TValue> ? string : IdOf<TValue>;
 type TextFieldType = 'SINGLE_LINE_TEXT' | 'LONG_TEXT' | 'URL' | 'EMAIL' | 'PHONE' | 'ADDRESS' | 'RECORD_ID' | 'LOCATION' | 'TIME' | 'BUTTON';
 type NumberFieldType = 'NUMBER' | 'PERCENT' | 'CURRENCY' | 'PROGRESS' | 'RATING' | 'DURATION' | 'COUNT' | 'AUTONUMBER';
 type DateFieldType = 'DATE' | 'DATETIME' | 'CREATED_AT' | 'UPDATED_AT';
 type ChoiceFieldType = 'SELECT' | 'LINKED_RECORD' | 'CREATED_BY' | 'UPDATED_BY';
 /** The types with no single value to compare: only whether the field holds one. */
 type EmptyFieldType = 'ATTACHMENT' | 'DATE_RANGE';
+type ElementOf<TValue> = TValue extends Array<infer TMember> ? TMember : TValue;
 /**
  * The operators one alias offers, chosen from the type codegen declared for the field rather
  * than from what it reads as: a `DATETIME` and a text field both read as `string`, and only
  * the declared type tells them apart.
  *
- * A field with no declared type lands on the permissive chain rather than on none.
+ * `TValue` is still needed for the literal choice ids, which live on the read type and
+ * nowhere else. A field with no declared type lands on the permissive chain rather than on
+ * none.
  */
-type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
+type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain<ChoiceIds<ElementOf<TValue>>> : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain<ChoiceIds<TValue>> : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
 type Combinators = {
   $and(...members: Array<AnyConstructable>): ConstructableFilterGroup;
   $or(...members: Array<AnyConstructable>): ConstructableFilterGroup;

package/dist/formatting.d.ts

@@ -1,4 +1,4 @@
-import * as react2 from "react";
+import * as react0 from "react";
 import { ReactNode } from "react";
 import { z } from "zod";
 
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react2.FunctionComponentElement<react2.ProviderProps<Scope>>;
+}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react2.FunctionComponentElement<react2.FragmentProps>;
+}): react0.FunctionComponentElement<react0.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { AuthSettings } from "./auth/platform.js";
@@ -17,4 +18,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -1,5 +1,5 @@
 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 "./route/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
 import { definePage, pageHead } from "./route/page.js";
@@ -14,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, 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 };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineComments, 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_start0 from "@tanstack/react-start";
+import * as _tanstack_react_start5 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start5.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react4 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
+declare function SoftrPwaHead(): react4.FunctionComponentElement<react4.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/dist/server.d.ts

@@ -1,8 +1,9 @@
 import { upload } from "./core/file-upload.js";
+import { comments } from "./comments/comments.js";
 import { auth } from "./auth/server.js";
-import { FieldChoice, RecordOption, RecordOptions } from "./core/options.js";
+import { RecordOption, RecordOptions } from "./core/options.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 { type FieldChoice, type RecordOption, type RecordOptions, auth, ds, integration, upload, workflow };
+export { type RecordOption, type RecordOptions, 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,43 +1,24 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.74-alpha.0",
+  "version": "0.0.75",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "bin": {
-    "softr-sdk": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "schema",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
+    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+  },
+  "bin": { "softr-sdk": "./dist/cli.js" },
+  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "marked": "^18.0.14",
+    "xss": "^1.0.15",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -63,9 +44,7 @@
       "optional": true
     }
   },
-  "keywords": [
-    "tanstack-intent"
-  ],
+  "keywords": ["tanstack-intent"],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.71
+  library_version: 0.0.75
 ---
 
 # Softr SDK core
@@ -30,9 +30,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`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
-| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
-| `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineComments`, `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`, `comments` |
+| `@softr/sdk/client` | Browser only | `useFileUpload`, `useCommentComposer` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
 ## Sub-Skills
@@ -51,6 +51,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | 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) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
+| Add comments to a record | [comments/SKILL.md](./comments/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -91,6 +92,9 @@ Adding an install button, or making the app installable?
 Showing a date, a time or a number on a page?
   load softr-sdk/formatting
 
+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

@@ -18,7 +18,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.71
+  library_version: 0.0.75
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -85,7 +85,8 @@ Changing the visitor's own profile:
 
 | Call | Does |
 | --- | --- |
-| `auth.updateProfile({ fullName?, avatar? })` | Changes their name, their photo, or both. `avatar: null` removes the photo |
+| `auth.updateProfile({ fullName?, avatar? })` | Changes their name, their photo, or both |
+| `auth.removeAvatar()` | Removes their photo |
 
 ## Setup
 
@@ -461,7 +462,7 @@ After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuth
 ```ts
 const result = await auth.updateProfile({ fullName: 'Ann Lee' })
 const result = await auth.updateProfile({ avatar: file })   // a File from an <input type="file">
-const result = await auth.updateProfile({ avatar: null })   // removes the photo
+const result = await auth.removeAvatar()                   // removes the photo
 ```
 
 It answers with the updated `User`. Pass the file through a server function that takes `FormData`. The photo must be a PNG, JPEG or GIF of at most 5 MB, or it answers `notAnImage` or `fileTooLarge`. A blank or unacceptable name answers `invalidName`.

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.71
+  library_version: 0.0.75
 ---
 
 **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,181 @@
+---
+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.75
+---
+
+**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
+
+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
+
+```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 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.
+- A viewer sees a thread only if a `read` action (`defineQuery`) on the same table lets them read it. Without one, `list` returns `null` for them.
+- 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
+
+```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` 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 returns:
+
+| Field | What it is |
+| --- | --- |
+| `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. Show it with `<FormattedDate value={comment.createdAt} time />`, or `useFormatting` for a title; see the `formatting` guidance.
+- `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:
+
+```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 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
+
+```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` and `mentions` as they are. Mentioned people get an email. A mention whose `@name` was edited posts as plain text.
+
+`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() === '' && done.length === 0) || isUploading}
+  onClick={async () => {
+    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>` 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 `canEdit` is true. Mount the edit box only while editing.
+
+- 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
+
+```ts
+const findPeople = createServerFn({ method: 'GET' })
+  .validator((data: { query: string }) => data)
+  .handler(({ data }) => comments.searchMentions(orderComments, data))
+```
+
+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
+
+```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 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.
+- `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.** 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.
+
+**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.
+
+**Inventing reactions.** Only `quickReactions` can be stored. `react` throws for anything else.
+
+**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's 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.71
+  library_version: 0.0.75
 ---
 
 # 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.71
+  library_version: 0.0.75
 ---
 
 **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
 }
 ```