@lotics/app-sdk 0.89.0 → 0.90.1

package/AGENTS.md

@@ -24,7 +24,7 @@ signature; open the file.**
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything), `openExternal`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything), `openExternal`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/src/hooks.d.ts

@@ -383,10 +383,10 @@ export interface FieldOptionsOptions {
  * ```tsx
  * const { fields } = useFieldOptions("records");
  * // populate + color a picker:
- * <Picker options={fields.status?.options ?? []}
- *   renderOptionContent={(o) => <OptionBadge value={o} />} />
+ * <Select variant="native" options={fields.status?.options ?? []}
+ *   renderOptionContent={(o) => <Status option={o} />} />
  * // color a stored value:
- * <OptionBadge value={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
+ * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
  * ```
  */
 export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
@@ -448,7 +448,7 @@ export declare function usePaginatedQuery<K extends string>(alias: K, ...args: Q
  *
  * ```tsx
  * const { total } = useCount("orders", { q }, { filter: unpaidFilter });
- * return <Badge label={total == null ? "…" : `${total}`} />;
+ * return <Status label={total == null ? "…" : `${total}`} />;
  * ```
  */
 export declare function useCount<K extends string>(alias: K, ...args: QueryArgs<K, CountOptions<ColumnKeyOf<K>>>): CountState;
@@ -619,7 +619,7 @@ export interface MembersOptions {
  *
  * ```tsx
  * const { members } = useMembers({ group: "grp_..." });
- * // <Picker options={members.map((m) => ({
+ * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />
  * ```

package/dist/src/hooks.js

@@ -536,7 +536,7 @@ export function useAiContext(slot, context) {
  *
  * ```tsx
  * const { members } = useMembers({ group: "grp_..." });
- * // <Picker options={members.map((m) => ({
+ * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />
  * ```

package/dist/src/index.d.ts

@@ -4,15 +4,14 @@
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
  * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` components, so it ships without pulling in packages/ui's
- * React Native Web dependency tree. That is a packaging choice, NOT a
- * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
- * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
- * full setup — `@lotics/ui` + react-native + react-native-web, the
- * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
- * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
- * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
+ * `@lotics/ui` component, so an app's dependency on the kit is its own and one
+ * version answers for it. That is a packaging choice, NOT a limitation: apps
+ * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
+ * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
+ * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
+ * the whole `resolve` block. Build screens by composing kit components (Card,
+ * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
+ * & components".
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
@@ -26,6 +25,7 @@ export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "
 export { rpc, isEmbedded } from "./rpc.js";
 export type { RpcOp, AiContextValue, AiContextRecordRef } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { openApp } from "./open_app.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";

package/dist/src/index.js

@@ -4,15 +4,14 @@
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
  * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` components, so it ships without pulling in packages/ui's
- * React Native Web dependency tree. That is a packaging choice, NOT a
- * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
- * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
- * full setup — `@lotics/ui` + react-native + react-native-web, the
- * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
- * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
- * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
+ * `@lotics/ui` component, so an app's dependency on the kit is its own and one
+ * version answers for it. That is a packaging choice, NOT a limitation: apps
+ * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
+ * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
+ * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
+ * the whole `resolve` block. Build screens by composing kit components (Card,
+ * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
+ * & components".
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
@@ -21,6 +20,7 @@ export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { openApp } from "./open_app.js";
 export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";

package/dist/src/open_app.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Open a record's screen in the sibling app that owns it — the cross-app hop.
+ * The host owns app routing and lands the viewer on `route` inside `appId`,
+ * same tab, chrome kept. `route` is the target app's own in-app path, exactly
+ * as its router declares it (`/` for its register).
+ *
+ * ```tsx
+ * import { openApp } from "@lotics/app-sdk";
+ * await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
+ * ```
+ *
+ * Standalone (`<slug>.lotics.app`) has no sibling apps, so the call rejects
+ * there — gate the control on `isEmbedded()`.
+ */
+export declare function openApp(appId: string, route?: string): Promise<void>;

package/dist/src/open_app.js

@@ -0,0 +1,18 @@
+import { rpc } from "./rpc.js";
+/**
+ * Open a record's screen in the sibling app that owns it — the cross-app hop.
+ * The host owns app routing and lands the viewer on `route` inside `appId`,
+ * same tab, chrome kept. `route` is the target app's own in-app path, exactly
+ * as its router declares it (`/` for its register).
+ *
+ * ```tsx
+ * import { openApp } from "@lotics/app-sdk";
+ * await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
+ * ```
+ *
+ * Standalone (`<slug>.lotics.app`) has no sibling apps, so the call rejects
+ * there — gate the control on `isEmbedded()`.
+ */
+export function openApp(appId, route = "/") {
+    return rpc("openApp", { app_id: appId, route });
+}

package/dist/src/rpc.d.ts

@@ -20,7 +20,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;

package/dist/src/rpc.js

@@ -666,6 +666,10 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "openApp":
+            // A standalone app is one page at its own address: no host routing
+            // between apps, no sibling to reach.
+            return Promise.reject(new Error("openApp needs the Lotics host: a standalone app has no sibling apps to open. Gate the control on isEmbedded()."));
         case "askAi":
             // The chat surface lives in the Lotics host — a standalone page has
             // nowhere to hand off to.

package/dist/src/select.d.ts

@@ -18,7 +18,7 @@ export interface ResolvedOption {
      * Named palette color token (e.g. `"blue"`, `"emerald"`). Populated by
      * `useFieldOptions` (which reads the field config); absent on options read
      * back from a query CELL via `readSelect` — a cell carries only key + label.
-     * Pass the resolved option straight to `@lotics/ui`'s `OptionBadge`, which
+     * Pass the resolved option straight to `@lotics/ui`'s `Status`, which
      * degrades a missing/unknown token to a neutral badge.
      */
     color?: string;

package/docs/data_fetching.md

@@ -439,7 +439,7 @@ a partial as its period start.
 
 **`readSelect`.** A query **cell** carries `key` + `label` only — `color` comes from
 `useFieldOptions`, not the cell. An option deleted after the cell was written surfaces as
-`label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `OptionBadge`
+`label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `Status`
 — see [./members_and_options.md](./members_and_options.md).
 
 **`readMembers`.** `name` is `null` when the id doesn't resolve in the app's org (e.g. a removed
@@ -477,7 +477,7 @@ A query cell carries only the options a record actually holds (key + label, no c
 **complete** option list of a select column — every option including those in no current row, with
 colors — use **`useFieldOptions`**, and prefer it over deriving options from loaded rows
 (row-derived sets are incomplete until every page loads and carry no colors). Its full contract
-(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`OptionBadge`,
+(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`Status`,
 `MemberChip`, `MemberSelect`), and the member roster (`useMembers`) live in
 [./members_and_options.md](./members_and_options.md).
 
@@ -510,7 +510,7 @@ pieces. Compose these — don't hand-roll search:
 
 - **`Combobox`** (`@lotics/ui/combobox`) owns the interaction — debounced `onSearchChange`, a
   popover listbox with rich rows (`renderOptionContent`), keyboard navigation, `recentOptions`,
-  `allowCustom`. (For a known small list with no search box, `Picker`.)
+  `allowCustom`. (For a known small list with no search box, `Select`.)
 - **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the
   maintained search document: **diacritics- and case-insensitive**, trigram-indexed, and AND-ed
   with the template's `filter` (search within a scope). The full `search` contract is in
@@ -540,7 +540,7 @@ const [typed, setTyped] = useState("");          // the input's own value, every
 const [term, setTerm] = useState("");            // what the server is asked, once typing settles
 const commit = useDebouncedCallback(setTerm, 250);
 
-<SearchInput value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
+<TextInput type="search" value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
 
 const { rows, loading } = useQuery(
   "searchCustomers",
@@ -560,8 +560,8 @@ relationship exists.
 When the user doesn't know the term — "show me everything, let me narrow it" — build a modal table
 they can browse (numbered pages), search, sort, and filter:
 
-- **The screen is app-owned**, composed from `@lotics/ui`: a `Dialog` over `SearchInput` + filter
-  pills (`ColumnFilter`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
+- **The screen is app-owned**, composed from `@lotics/ui`: a `Dialog` over a search `TextInput` + filter
+  pills (`FilterChip column=`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
   UI-free), so it lives in the app (e.g. a `record_picker.tsx`) — reuse it for any table by passing
   a different `alias` + column config.
 - **`usePaginatedQuery`** drives it: the page of rows, the `total` for "Page 1 of N" (the built-in

package/docs/files.md

@@ -19,7 +19,7 @@ discipline in [data fetching](./data_fetching.md).
 | Attach to a record | a declared workflow with a `{ type: "file" }` input | the workflow writes the id(s) into a `files` field — the **only** write path |
 | Read back from records | `useQuery` + `readFiles(cell)` | `AppFile[]` — presigned `url`/`thumbnail_url` (24 h) + `size`/`created_at` |
 | Receive a generated document | `useWorkflow` → `WorkflowResult.files` | presigned files auto-extracted from the run |
-| Show it | `@lotics/ui` `FileThumbnail` / `FileGrid` / `FileGalleryModal` | map to `DisplayFile` (see below) |
+| Show it | `@lotics/ui` `FileThumbnail` / `FileThumbnailGrid` / `FileGalleryDialog` | map to `DisplayFile` (see below) |
 | Save browser-built bytes | `downloadFile(filename, data, mimeType?)` | a client-side download (see [runtime](./runtime.md)) |
 
 An uploaded file is **inert until a workflow attaches it** — it has an id and serving URLs, but
@@ -175,10 +175,10 @@ Each `AttachedFile` is `{ id, filename, mime_type, preview_url, status, file_id?
 
 Wiring to `@lotics/ui`: in a `Composer`, trigger picking from `actionsButton` (via `pickFiles`),
 render the attachment pills with `FileThumbnail` as above, and gate `sendDisabled` on `uploading`.
-For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a `FileGrid`
-`FileUpload` entry — ready → `{ status: "complete", id: file_id, file: <DisplayFile> }`, else
-`{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }` — and `FileGrid` renders
-the uploading/error/retry tiles itself.
+For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a
+`FileThumbnailGrid` `FileUpload` entry — ready → `{ status: "complete", id: file_id, file:
+<DisplayFile> }`, else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`
+— and the grid renders the uploading/error/retry tiles itself.
 
 ## File cells in query results — `readFiles` and `AppFile`
 
@@ -325,11 +325,10 @@ not viewing). Component contracts live in the `@lotics/ui` reference
 For an `AttachedFile` still uploading, map `preview_url` → `url` (there is no server URL yet).
 The app owns this data→UI adapter — the SDK deliberately never imports `@lotics/ui`.
 
-- **`FileThumbnail`** — one square tile; `uploading` overlays a spinner, images fall back from
-  `thumbnailUrl` to `url` on error.
-- **`FileGrid`** — a grid of completed files plus a live `uploads` queue (it renders
-  uploading/error/retry tiles itself).
-- **`FileGalleryModal`** — the full-screen viewer (filename · counter · actions · close, with
+- **`FileThumbnail`** — one square tile; `uploading` takes the queue status and overlays the
+  scrim, the spinner or the retry, images fall back from `previewUrl` to `thumbnailUrl` to `url`.
+- **`FileThumbnailGrid`** — a grid of stored files plus a live `uploads` queue, in one grid.
+- **`FileGalleryDialog`** — the full-screen viewer (filename · counter · actions · close, with
   prev/next + ESC), delegating per-file to **`FilePreview`**, which dispatches by MIME. Wire
   `onFilePress` → a `number | null` `activeIndex`.
 - PDF renders **inline to a canvas** (a nested PDF browsing context is blocked in the sandboxed

package/docs/members_and_options.md

@@ -4,7 +4,7 @@ How an app renders and picks **people** and **select-field options**, plus the *
 surface. Covers the two cell readers (`readSelect`, `readMembers`), the two catalog hooks
 (`useFieldOptions`, `useMembers`), the viewer identity hook (`useViewer`), comments
 (`useComments`, `useCommentCounts`), and the `@lotics/ui` components they feed. Read this before
-building an assign picker, a colored status badge, a per-viewer ("my records") screen, or a
+building an assign picker, a colored `Status` mark, a per-viewer ("my records") screen, or a
 comment thread. Query mechanics live in [queries](./queries.md); the authority model in
 [security](./security.md).
 
@@ -61,7 +61,7 @@ const { fields } = useFieldOptions("orders");   // same alias you query
 // are { value, label }, so map the option key to `value`):
 <Select
   options={(fields.status?.options ?? []).map((o) => ({ value: o.key, label: o.label }))}
-  renderOptionContent={(o) => <OptionBadge value={fields.status?.byKey(o.value)} />}
+  renderOptionContent={(o) => <Status option={fields.status?.byKey(o.value)} />}
   value={status} onValueChange={setStatus}
 />
 ```
@@ -78,7 +78,7 @@ name**, not the field key. Each `FieldOptions`:
 | `byKey(key)` | Resolve one option by key; `undefined` for an unknown key (option removed after the cell was written) |
 
 - `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to
-  `@lotics/ui`'s `OptionBadge`; a missing/unrecognized token degrades to a neutral badge.
+  `@lotics/ui`'s `Status`; a missing/unrecognized token degrades to a neutral badge.
 - **A column the server can't map to a single source select field is simply absent** from
   `fields` — a UNION output whose arms disagree on the source field, or a computed column. Read
   defensively: `fields.status?.options ?? []`.
@@ -99,7 +99,7 @@ until an edit drawer opens). State: `{ fields, loading, isValidating, error, ref
 
 ```tsx
 const opt = readSelect(row.status)[0];
-<OptionBadge value={opt ? (fields.status?.byKey(opt.key) ?? opt) : null} />
+<Status option={opt ? (fields.status?.byKey(opt.key) ?? opt) : null} />
 ```
 
 `byKey` hit → the configured color. `byKey` miss (option removed post-write) → fall back to the
@@ -128,12 +128,12 @@ projected `select_member` cell to `Array<{ id, name, email?, image?, groups?, ro
   "Admin" beside a name as rank. If the question your screen asks is "who is this person in the
   company", the answer is `groups`.
 - **`joined` is an ISO timestamp of when the membership began.** Render it at whatever precision
-  your question needs — `@lotics/ui`'s `MemberProfileCard` shows month and year, because "is this
+  your question needs — `@lotics/ui`'s `MemberPeek` shows month and year, because "is this
   the new person?" does not want a day. Absent on a public response, and on an id that did not
   resolve: there is no membership to have begun.
 - **`archived: true` marks someone who has LEFT** — omitted otherwise, never `false`. It is the one
   field that is NOT gated (a departed colleague reading as a current assignee is wrong on a public
-  app too). Feed it to `inactive` on `MemberChip` / `MemberProfileCard`.
+  app too). Feed it to `inactive` on `MemberChip` / `MemberPeek`.
 - **An id that no longer resolves** (removed member, id outside the org) comes back with
   `name: null` — an explicit missing state, never an empty string. Render a placeholder.
 - Only ids already present in the projected rows are resolved — a member cell never exposes the
@@ -256,7 +256,7 @@ client-side up front, and re-checked server-side.
 - **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. `CommentList`'s
+- **Edit and delete are author-only**, checked server-side against the viewer. `CommentThread`'s
   `currentMemberId` prop drives the matching affordance client-side.
 
 ### Reading & writing
@@ -277,13 +277,13 @@ renders the panel. State: `{ comments, loading, error, available, createComment,
 updateComment, deleteComment, refetch }`.
 
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
-  `CommentList`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
+  `CommentThread`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
   table_id, member_id, content, files, workspace_id, created_at, updated_at }`. Attachments
   (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
   the server re-reads every attachment from storage by that id, so nothing else you hold about a
   file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
   but the server does not populate them today — render attachments by name and type (what
-  `CommentList`'s default file row does), never by counting on a fetchable URL.
+  `CommentThread`'s default file row does), never by counting on a fetchable URL.
 - `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). Content max
@@ -296,7 +296,7 @@ updateComment, deleteComment, refetch }`.
   on it.
 - **Limitation:** a comment carries `member_id` only — resolving the author's display name needs a
   member source: the `useMembers` roster (requires the member-access declaration above) or member
-  cells in your own data. An unresolvable id should render a fallback (`CommentList` has an
+  cells in your own data. An unresolvable id should render a fallback (`CommentThread` has an
   `unknownMember` label for exactly this).
 - **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
   the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
@@ -320,10 +320,10 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 
 | Value | Component | Feed it |
 | --- | --- | --- |
-| A select value (stored or picker option) | `OptionBadge` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
+| A select value (stored or picker option) | `Status` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
 | A person, inline | `MemberChip` | `name` / `image` from a roster or a cell — both carry it; no image → initials |
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
-| A comment thread | `CommentList` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
+| A comment thread | `CommentThread` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
 
 The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter in each row above.
 

package/docs/navigation_and_state.md

@@ -287,3 +287,4 @@ default `JSON.stringify`) and `max` (default **5**).
 | `urlParam`, `UrlParamCodec`, `OptionalUrlParamCodec`, `UrlParams`, `UrlParamValue` | `@lotics/app-sdk` | `dist/src/url_params.d.ts` |
 | `useRecents`, `RecentsApi`, `RecentsOptions` | `@lotics/app-sdk` | `dist/src/use_recents.d.ts` |
 | `isEmbedded` | `@lotics/app-sdk` | `dist/src/rpc.d.ts` |
+| `openApp` | `@lotics/app-sdk` | `dist/src/open_app.d.ts` |

package/docs/runtime.md

@@ -185,6 +185,7 @@ surfaces:
 | `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
 | `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | **no** | yes |
 | `askAi` | yes | **no** — `"Unknown RPC op: askAi"` | rejects — `"askAi is only available when the app runs inside Lotics"` |
+| `openApp` | yes — routes to the sibling in the same tab | yes — opens the sibling on the web app in a new tab (one app is served locally) | rejects — `"openApp needs the Lotics host …"` |
 
 **Limitation:** Don't build a session-log UI on `useAgentRuns`; keep the log in app
 state from live `useAgentRun` results (see [ai](./ai.md)). Server-side *cancel*
@@ -226,6 +227,7 @@ semantics are documented:
 | `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 |
 | `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) |
@@ -264,9 +266,41 @@ page (standalone). Opens in a new tab with `noopener,noreferrer`.
 - Typical use: opening a workflow-generated file's `url` from
   `WorkflowResult.files[]` (see [mutations](./mutations.md)).
 - **Not a preview mechanism.** To *view* a file inline, use `@lotics/ui`'s
-  `FilePreview`/`FileGalleryModal` (see [files](./files.md)); `openExternal` is
+  `FilePreview`/`FileGalleryDialog` (`@lotics/ui` ≥ 48 — 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/src/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; `lotics app dev` serves one app
+  and has no shell to route inside, so it opens the sibling on the web app in a
+  new tab; 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.
+
 ## `downloadFile()` — save browser-built bytes
 
 ```tsx
@@ -411,14 +445,11 @@ is a transport that wasn't wired.
   no dynamic `import()`, no Node built-ins. Don't touch `window` at module top
   level — resolve lazily (test environments import modules before `jsdom` is
   ready).
-- **Two bundlers in the family.** Apps build with Vite; the Lotics product
-  frontend builds with Metro (React Native Web). The SDK itself is never
-  Metro-bundled — the host frontend is forbidden from importing
-  `@lotics/app-sdk` (enforced by a dependency-direction test) — but sibling
-  packages apps share with the product (`@lotics/ui`, `@lotics/xlsx`,
-  `@lotics/docx`) build under both. When a shared package must diverge per
-  target, use platform files (`x.web.ts` / `x.ts`) plus conditional package
-  `exports` — never a runtime `require` or dynamic import.
+- **One module per entry.** A package apps share with the Lotics product
+  (`@lotics/ui`, `@lotics/xlsx`, `@lotics/docx`) ships ONE module per entry: no
+  platform twins, no per-target `exports` condition. The SDK itself is never
+  bundled by the product at all — the host frontend is forbidden from importing
+  `@lotics/app-sdk`, enforced by a dependency-direction test.
 - **Self-contained on npm.** The SDK cannot import workspace-private or
   host-only packages (`@lotics/shared`, `@lotics/ui-internal`, the frontend's
   `@/` alias) or any React Native / Expo module — also test-enforced. A helper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.89.0",
+  "version": "0.90.1",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {