@lotics/app-sdk 0.125.9 → 0.126.0

package/docs/members_and_options.md

@@ -1,7 +1,7 @@
 # Members & select options
 
-How an app renders and picks **people** and **select-field options**, the host context they are
-read from, and **record comments**. Query mechanics live in [queries](./queries.md); the authority
+How an app renders and picks **people** and **select-field options**, and the host context they are
+read from. Query mechanics live in [queries](./queries.md); the authority
 model in [security](./security.md).
 
 ## Cells vs. catalogs — the model
@@ -261,11 +261,6 @@ host did not say (a visitor from outside the organization, an older host). Both
 context, read once as the app opens. Display only: the workflow body re-checks who may act
 (`current_member_stands_in_for(...)`).
 
-`openableApps` lists the workspace's apps the viewer can open, each by its `id` and its `name`, and `table_id`, the table its register lists, where the host says — what a
-way through to a sibling app (`openApp`, `peekApp`) is offered by. `null` where the host did not say (standalone, a
-render, an older host, or a page that had not listed its apps when the app opened). Display only: the
-app opened checks the viewer itself.
-
 `hostNamesApp` is `true` where the host's own chrome already names the app on screen (the workspace's
 app page), `false` everywhere else and from an older host. Where it is `true`, a screen that titles
 itself with the app's name draws no visible title, keeping its `<h1>` for assistive technology alone
@@ -290,94 +285,6 @@ until it resolves, where it failed, and from a host that predates them.
   where the field states no code of its own. Pass it as the money's `currency`: a money format
   given no code prints a default market, which says nothing about this workspace.
 
-## Comments: `useComments` / `useCommentCounts`
-
-Record comments — member-to-member discussion attached to any record the app reaches
-(`dist/comments.d.ts`).
-
-### Enabling comments
-
-Opt in on the app — a JSON app states it in its model; a custom-code app sets it live, as a new
-version:
-
-```jsonc
-// set_app
-{ "app_id": "app_…", "capabilities": { "comments": true } }
-```
-
-Both hooks expose **`available`** — `true` only when a member is signed in **and** the app declared
-the capability. Gate the composer on it. When `false` (any standalone/public app view, or an app
-that didn't opt in) lists stay empty, `loading` settles to `false`, and every mutation rejects —
-client-side up front, and re-checked server-side.
-
-### Authority & attribution
-
-- **Access runs under the app, not the member's table IAM.** A member who can use the app (and the
-  app declares `comments`) may read/write comments on any record the app's workspace holds,
-  regardless of their own table access. The one floor: the record must live in the app's own
-  workspace — a crafted foreign `record_id` errors.
-- **The author is always the real signed-in member** — correct attribution, enforced server-side.
-  **Warning:** under "View as", comments still author as the real member (the admin), not the
-  view-as target — unlike `useViewer` and `is_current_member` scoping, which follow the target.
-- **Edit and delete are author-only**, checked server-side against the viewer. `Timeline`'s
-  `currentMemberId` prop drives the matching affordance client-side.
-
-### Reading & writing
-
-```tsx
-// In a record screen, where an id definitionally exists:
-const { comments, available, createComment } = useComments({ record_id: recordId });
-
-// From a row, gate the whole panel rather than passing a placeholder:
-{row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
-```
-
-`record_id` must be a **real** id — the fetch keys on `available` alone, so an empty string is not
-skipped, it fetches comments for nothing. When the id comes from a row's `__source_record_id`
-addressing column (see [queries](./queries.md)) narrow it first: a grouped query answers its addressing
-columns as `null`, and a hook cannot be called conditionally, so the guard belongs at the component that
-renders the panel. State: `{ comments, loading, error, available, createComment,
-updateComment, deleteComment, refetch }`.
-
-- `comments` — newest first on the wire (server order); a thread usually reads oldest-first, so
-  reverse it for display. Each `AppComment`: `{ id, record_id,
-  table_id, member_id, author, content, files, workspace_id, created_at, updated_at }`. Attachments
-  (`AppCommentFile`) carry `id` / `filename` / `mime_type` and a presigned `url` (plus
-  `thumbnail_url` for an image), valid 24 hours and refreshed by every read. A file's identity is
-  its `id`: the server reads every attachment from the file by that id, so nothing else you hold
-  about a file can affect what is stored.
-- `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
-  `useFileUpload` / `useAttachments` (see [files](./files.md)). A comment must have content or at
-  least one file (empty input is a client no-op; the server enforces the same rule). A file id
-  that names no live file in this workspace refuses the comment. Content max 10,000 characters.
-- `updateComment(id, { content, files? })` — omit `files` to keep the current attachment set (a
-  text-only edit never drops attachments); pass `files` to replace the whole set. An id the comment does not already hold must name a live
-  file in this workspace; one it holds stays even once its file is archived.
-- All three mutations apply **optimistically** with rollback on error, then repopulate from the
-  server. **Limitation:** an optimistic create renders a placeholder row (temporary id, empty
-  `table_id`/`workspace_id`, `files: null`) until the refetch lands — don't persist anything keyed
-  on it.
-- **The author names itself.** `author` carries `{ name, image? }`, resolved server-side on every
-  comment the server returns — list, create and update alike — including one written from another
-  app by someone the record references nowhere, so a thread needs no declared member access.
-  `name` is `null` when the id no longer resolves in the org (a removed member) — render a
-  fallback (`Timeline` has an `unknownMember` label for exactly this). The one comment with no
-  `author` is the optimistic row `createComment` renders locally: the SDK knows the viewer's id and
-  not their name, and it will not invent one. The server's row replaces it when the refetch lands.
-- **Freshness:** cached like a query — re-read on arrival and on focus/reconnect, so another
-  viewer's comment appears on the next arrival, focus or explicit `refetch()` — not on its own: the realtime channel carries **record**
-  changes, and a comment emits no record event. Your queries DO get pushed
-  ([data_fetching.md](./data_fetching.md)).
-
-### Counts
-
-`useCommentCounts({ table_id })` → `{ counts, loading, error, available, refetch }` where `counts`
-is `{ record_id: count }` for the whole table — row badges without shipping any comment content
-(one server-side aggregate). Same gate and authority as `useComments`. `table_id` is the source
-table's id: read it off a row of the query that renders the badges (`rows[0]?.__source_table_id`)
-rather than pasting a `tbl_` id, which a copy of the app cannot carry. Pass `undefined` while no
-row is on screen — no request is sent and `counts` is `{}`.
-
 ## Outside links: `useOutsideLinks`
 
 `useOutsideLinks(recordId)` (`dist/outside_link.d.ts`) → `{ links, loading, error, available, create, revoke }` — a
@@ -400,4 +307,3 @@ to the link made, or `null` when the member backed out; `revoke` to whether it d
 | `useMembers` | ✓ (same-org + declaration gates) | ✗ errors |
 | `useViewer` | member id (view-as target) | `null` |
 | `useWorkspaceTimezone` / `useWorkspaceCurrency` | ✓ | ✓ |
-| `useComments` / `useCommentCounts` | ✓ when capability declared | ✗ `available: false` |

package/docs/mutations.md

@@ -332,8 +332,7 @@ const onClose = async (recordId: string) => {
 Only on **success**: a refused write changed nothing. A body that names a table only at run time,
 a run whose writes could not be predicted, a run before the app's write model has loaded, a run
 by a visitor from outside your organization, and a `useAgentRun` leg that lands, re-read every
-mounted query. A comment written or deleted re-reads
-every `useCommentCounts`. Under a design-time
+mounted query. Under a design-time
 fixture every mounted read re-reads, since a fixture has no body to read tables from. The host's
 realtime push is separate: it carries changes **other** people make, and is far too slow for your
 own.

package/docs/navigation_and_state.md

@@ -54,6 +54,9 @@ routes, and splats all work. Inside the tree, use react-router normally:
   message naming the path and a link to the first route — instead of an empty
   page, and a layout route keeps its shell around that message. Declaring your
   own `{ path: "*" }` replaces it.
+- **A route that decides its own addresses draws the same screen.** `NotFoundScreen`
+  (`{ home, words }`) is exported from `@lotics/app-sdk/router` for a splat route
+  that parses the path itself and finds none of its screens at it.
 - **The not-found screen speaks the app's language.** Its two strings default
   to English; an app whose reader reads another language passes them as
   `notFound`, next to `routes`:
@@ -130,6 +133,10 @@ never the query or hash. The host counts one view per change, so a
 static segment is reported as written, so never build a route's `path` from
 your data: a record's id or name goes in a `:param`.
 
+A splat route (`path: "/*"`) stands for many screens, so it states each one's
+shape itself, from the path alone and with no id or text in it:
+`handle: { shape: (pathname) => "/:view/:row" }`.
+
 A drawer the app opens at a query key rather than a path is a screen too when
 `drawers` names its key, listed from the one drawn lowest:
 

package/docs/runtime.md

@@ -3,7 +3,7 @@
 How an app boots and talks to the platform: **`mount()`** (with the design-time mock harness),
 the **two transports** the SDK switches between (app code never branches), the raw **`rpc()`**
 escape hatch, and the browser capabilities the sandbox would otherwise block — **`openExternal`**,
-**`openApp`** / **`peekApp`**, **`downloadFile`**, and **`requestGeofencedLocation`** / **`isWithinZone`**.
+**`downloadFile`**, and **`requestGeofencedLocation`** / **`isWithinZone`**.
 
 ## `mount()` — the entry point
 
@@ -114,7 +114,7 @@ pending state; `fixture.exportApps[key]` answers `exportApp(key, narrowing)` the
   "live", elapsed_seconds: 754, inputs: { site: "rec_1" } } }` makes
   `useRecording("log_visit")` available with that `state`; `start` and `stop`
   resolve without recording anything or moving the state.
-- **Not mocked:** uploads, `useFieldOptions`, members, comments. In mock mode
+- **Not mocked:** uploads, `useFieldOptions`, members. In mock mode
   those still hit the real transport.
 - **Analytics is disabled** whenever `?__mock=1` is present, fixture or not — a
   screenshot/design-time load emits no events.
@@ -142,7 +142,7 @@ helper works identically in both. `isEmbedded(): boolean` is exported
 | Who holds credentials | The **host** — the member's session never reaches the app | Nobody — the visitor is anonymous (an optional app password gates access, not identity) |
 | How ops travel | `postMessage` to the parent frame; the host makes the API call with its session | `fetch` to the public `/v1/apps/{id}/*` endpoints, at the API address the serving host declared in the page |
 | Which API | The host's, implicitly — it makes the call | `<meta name="lotics-api-base" content="…">` in the served document, read on the first call. **No address is compiled in**: one bundle runs on any Lotics, and a page that declares none makes the SDK refuse rather than address an instance nobody named. The app host injects it, so there is nothing for an app to set |
-| Viewer identity | The signed-in member (`useViewer`, comments, agent runs available) | `member_id` is `null`; members-only surfaces reject |
+| Viewer identity | The signed-in member (`useViewer`, agent runs available) | `member_id` is `null`; members-only surfaces reject |
 
 ### Embedded: the postMessage bridge
 
@@ -218,13 +218,10 @@ surfaces:
 | Op | Embedded (product) | Standalone |
 |---|---|---|
 | `query`, `field_options`, `workflow`, `members`, `context`, `upload`, `urlState.get/set`, `openExternal` | yes | yes |
-| `comments.*` | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
 | `agentRun` (streaming, internal to `useAgentRun`) | yes | yes |
 | `agentRun.get`, `agentRun.cancel` | yes | yes |
 | `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | rejects — a standalone caller is anonymous, and a history is its member's (`"App agent runs require an authenticated member …"`) |
 | `askAi` | yes | rejects — `"askAi is only available when the app runs inside Lotics"` |
-| `openApp` | yes — routes to the sibling in the same tab | rejects — `"openApp needs the Lotics host …"` |
-| `peekApp` | yes, when the context states `peek_app_enabled` — opens the sibling in a sheet over this app | rejects — `"peekApp needs the Lotics host …"` |
 | `recording.start`, `recording.stop` | yes, when the context states `recording_enabled` | rejects — `"Recording needs the Lotics host and a signed-in member …"` |
 
 **Limitation:** Don't build a session-log UI on `useAgentRuns`; keep the log in app
@@ -259,21 +256,18 @@ semantics are documented:
 |---|---|---|---|
 | `query` | `{ alias, params?, limit?, offset?, … }` | `{ rows }` | [queries](./queries.md), [data fetching](./data_fetching.md) |
 | `export` | `{ alias, params?, filter?, sort?, report, file }` (`exportQuery`) or `{ export: { key, … } }` (`exportApp`) | `{ file }` | [data fetching](./data_fetching.md) |
-| `spec` | `{}` | `HostSpec`: the app's compiled `app.json` itself (format 30: `lists`, `pages` by entity, `entities`, flat `acts` and `checks`; a dashboard's readings), never the route's wrapper | this doc |
+| `spec` | `{}` | `HostSpec`: the app's compiled `app.json` itself (format 31: `views`, the root Lists and Sheets in order; `pages` by entity, each with the Views its Lists draw; `entities`; flat `acts` and `checks`), never the route's wrapper | this doc |
 | `field_options` | `{ alias }` | `{ fields }` | [members & options](./members_and_options.md) |
 | `workflow` | `{ alias, inputs }` | `WorkflowResult` | [mutations](./mutations.md) |
 | `upload` | `{ file: File }` (the `File` crosses the bridge by structured clone) | uploaded-file object | [files](./files.md) |
 | `members` | `{ group? }` | `{ members }` | [members & options](./members_and_options.md) |
 | `context` | `{}` | app identity (below) | this doc |
 | `openExternal` | `{ url }` | `void` | this doc |
-| `openApp` | `{ app_id, route }` | `void` | this doc |
-| `peekApp` | `{ app_id, route }` | `void` | this doc |
 | `askAi` | prompt/files/records seed | `void` | [ai](./ai.md) |
 | `agentRuns` | `{ session_id, limit?, offset? }` | `{ runs }` | [ai](./ai.md) |
 | `agentRun.get` | `{ run_id }` | `{ run }` | [ai](./ai.md) |
 | `agentRun.cancel` | `{ run_id }` | `{ ok: true }` | [ai](./ai.md) |
 | `urlState.get` / `urlState.set` | — / `{ params }` | `UrlParams` / `void` | [navigation & state](./navigation_and_state.md) |
-| `comments.list/create/update/delete/counts` | comment ops | comment payloads | [members & options](./members_and_options.md) |
 | `recording.start` / `recording.stop` | `{ alias, inputs }` / `{ alias }` | `{ started }` / `void` | [mutations](./mutations.md#recording-into-a-workflow-userecording) |
 | `outsideLink.list/create/revoke` | `{ record_id }` / `{ record_id, outside }` / `{ record_id, link_id }` | links / link or `null` / `{ id }` or `null` | [members & options](./members_and_options.md#outside-links-useoutsidelinks) |
 
@@ -285,7 +279,7 @@ The **streaming** agent-run op is *not* reachable through `rpc()` — its
 response is a chunk stream, not a single value; it's internal to `useAgentRun`.
 
 `rpc("context", {})` resolves the viewer and the workspace:
-`{ member_id, comments_enabled, timezone, default_currency, recording_enabled?, peek_app_enabled?, recordings? }`. `member_id` is the
+`{ member_id, timezone, default_currency, recording_enabled?, recordings? }`. `member_id` is the
 signed-in member when embedded, `null` standalone; `timezone` is the workspace's
 IANA zone and `default_currency` its ISO 4217 code, from the host when embedded
 and from `/v1/apps/by-subdomain/{subdomain}` standalone. Read them through
@@ -317,9 +311,9 @@ embedded app iframe is sandboxed **without `allow-popups`**, so a direct
 host frame (embedded) or the app's own top-level
 page (standalone). Opens in a new tab with `noopener,noreferrer`.
 
-- **Scheme validation at the point of open**: only `http:` and `https:` are
-  allowed; any other scheme (`javascript:`, `data:`, …) rejects the promise with
-  `openExternal: unsupported URL scheme "<protocol>"`, and a non-string `url`
+- **Scheme validation at the point of open**: only `http:`, `https:`, `tel:`,
+  `mailto:` (the last two open in place); any other scheme (`javascript:`, `data:`)
+  rejects with `openExternal: unsupported URL scheme "<scheme>"`, a non-string `url`
   rejects with `openExternal requires a url string`. The opener re-validates on
   its own side — a URL handed across the bridge is never trusted.
 - Typical use: opening a workflow-generated file's `url` from
@@ -327,55 +321,6 @@ page (standalone). Opens in a new tab with `noopener,noreferrer`.
 - **Not a preview mechanism.** To *view* a file inline, render it in the app
   (see [files](./files.md)); `openExternal` is "leave the app".
 
-## `openApp()` — the cross-app hop
-
-```tsx
-import { openApp, isEmbedded } from "@lotics/app-sdk";
-await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
-```
-
-`openApp(appId: string, route?: string): Promise<void>` (`dist/open_app.d.ts`).
-A workspace built as several apps around one spine shows another app's record
-read-only with a way THROUGH to the app that owns it; this is the way through.
-The host owns app routing, so it lands the viewer on `route` inside `appId` in
-the **same tab**, chrome kept — `_loc` carries the screen exactly as
-`AppRouter` mirrors it, so the target boots at that record rather than at its
-root. `route` is the target app's own in-app path, exactly as its router
-declares it (`/` for its register); it is the target's to define.
-
-- **Checked at the bridge, host-side**: the id by shape (`app_…`), the route as
-  an in-app path — starts with `/`, never `//` or a scheme. An app never
-  assembles the host's URL itself.
-- **By transport**: embedded routes in place; standalone rejects (`openApp needs the Lotics host …`) — gate the
-  control on `isEmbedded()`.
-- A sibling's id is this workspace's: a copy of the suite has different ones,
-  and the portability gate refuses a concrete `app_` in `src/` and in every
-  `.md`. The id reaches the app as data — a field the model binds, a query's
-  row — never as a literal.
-- Put it on a control the person presses. A hop on mount pushes the host's
-  history without a gesture, and two apps that each do it leave Back nowhere
-  to go. A hop to the app's own id is refused — navigate inside an app with
-  its own router.
-
-## `peekApp()` — a sibling's record, over this app
-
-```tsx
-import { peekApp, useAppContext } from "@lotics/app-sdk";
-const { peekAppEnabled } = useAppContext();
-if (peekAppEnabled) await peekApp(PARTIES_APP_ID, `/${party.id}`);
-```
-
-`peekApp(appId: string, route?: string): Promise<void>` (`dist/open_app.d.ts`). The host opens `route` of `appId` in
-a side sheet over this app — a panel from the right on a desk, a full-height sheet on a phone — and this app stays as
-it was beneath. The sibling draws its own record, in its own frame, under its own workflows and permissions; this app
-never draws a second copy of it. The sheet's head carries the sibling's name, "Open in <name>" (what `openApp` does,
-closing the sheet) and a close; Escape closes it too. One sheet at a time: a `peekApp` from inside the sheet replaces it.
-
-- **Checked at the bridge**, as `openApp`'s target: the id by shape, the route as an in-app path. A hop to the app's own
-  id, and to an app the host's `openableApps` does not list, is refused.
-- **By transport**: embedded in the product host opens the sheet; standalone rejects (`peekApp needs the Lotics host …`).
-  A host that does not serve the op states no `peekAppEnabled` in `context` — gate the control on it, else offer `openApp`.
-
 ## `downloadFile()` — save browser-built bytes
 
 ```tsx
@@ -465,7 +410,7 @@ response under a `Content-Security-Policy` whose `connect-src` reaches only the
 Lotics API, so a third-party collector's requests are blocked and the only
 visible result is console noise.
 
-Most of what an app does is already recorded platform-side — a comment, an
+Most of what an app does is already recorded platform-side — an
 upload, a workflow or agent run each leave a row, and a run's outcome, including
 a user's Stop (`cancel_requested_at`), lands in `app_agent_runs`. App opens are
 counted at the serving edge. If a funnel needs something those cannot answer,

package/docs/security.md

@@ -9,7 +9,6 @@ Every data operation an app performs — queries, workflows, agent runs — exec
 | Named queries (`useQuery`, the query RPC) | App owner | Yes — bound server-side into `is_current_member` / `current_member` filter predicates |
 | Workflows (`useWorkflow`) | App owner | Yes — `runtime.triggered_by_member_id` in the workflow body (`null` for anonymous) |
 | Agent runs (`useAgentRun`) | App owner | Yes — requires an authenticated member; runs are private to that member |
-| Comments (`useComments`) | App authority for **access**; the **author** is always the real member | Always — members-only, anonymous callers are rejected |
 
 Consequences of owner authority:
 
@@ -18,8 +17,6 @@ Consequences of owner authority:
 - **The viewer never widens or narrows a data op by existing.** A member with zero table access sees whatever the app's queries project, and a member with admin table access sees no more than that. `app:use` (or the public grant, below) is the only gate on invoking the app's declared surface.
 - **The boundary is what a CALLER can do**, not what the owner can: any caller, including an anonymous public visitor, can only invoke the declared aliases with typed, per-input-constrained values. A caller gaining data or capability the aliases don't declare is a vulnerability; the sections below prevent the ones the platform cannot detect for you.
 
-Comments are the one deliberate exception: access is app-authority (any member with `app:use` + the app's declared `comments` capability may read/post on any record in the app's workspace, regardless of their own table access — a tenant floor rejects record ids outside the app's workspace), but the **author is always the real authenticated member** — never the app owner, never a "View as" subject — and edit/delete are author-only. Anonymous visitors cannot comment: the comment endpoints require an authenticated member.
-
 ## The caller boundary
 
 Callers never submit query ASTs or workflow definitions — the server holds the canonical, bind-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
@@ -100,7 +97,6 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | File upload (workflow `file` inputs) | Yes — bounded to the app's workspace |
 | Query/workflow file outputs | Yes — file cells and workflow-produced files return direct presigned URLs (24-hour TTL) that anonymous viewers can fetch; see [files](./files.md) |
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
-| Comments (`useComments`) | **No** — members-only |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 
 **Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.125.9",
+  "version": "0.126.0",
   "description": "The SDK a Lotics custom-code app reads and writes through — typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {

package/dist/open_app.d.ts

@@ -1,24 +0,0 @@
-/**
- * Land on `route` — the target app's own path — inside sibling app `appId`,
- * same tab.
- *
- * ```tsx
- * import { openApp } from "@lotics/app-sdk";
- * await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
- * ```
- *
- * Rejects standalone; gate on `isEmbedded()`.
- */
-export declare function openApp(appId: string, route?: string): Promise<void>;
-/**
- * Open sibling app `appId`'s own `route` in a sheet over this app, which stays as it was beneath. The sibling draws its
- * record itself, in its own frame, under its own workflows and permissions.
- *
- * ```tsx
- * import { peekApp } from "@lotics/app-sdk";
- * await peekApp(PARTIES_APP_ID, `/${party.id}`);
- * ```
- *
- * Rejects standalone, and on a host that does not state `useAppContext().peekAppEnabled`.
- */
-export declare function peekApp(appId: string, route?: string): Promise<void>;