@lotics/app-sdk 0.122.0 → 0.122.2

package/AGENTS.md

@@ -24,7 +24,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model, the screens and `drawers` it reports to the host), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming parts, the agent's ask-back), `askAi`, `useAiContext`, and what the member's own chat agent can do with the app while it is open. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, why a per-input bound is a tenancy floor rather than an authorization check. |
-| [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1` — queries, workflows and agents, a mocked agent's run played line by line), `openExternal`/`openApp`/`downloadFile`, geofencing, the peer dependencies. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1` — queries, workflows and agents, a mocked agent's run played line by line), `openExternal`/`openApp`/`peekApp`/`downloadFile`, geofencing, the peer dependencies. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/{chunk-MK4DBY6R.js → chunk-I2BOTPL6.js}

@@ -1635,6 +1635,10 @@ function rpcStandalone(op, payload) {
       return standalonePredictionMiss(payload);
     case "openExternal":
       return standaloneOpenExternal(payload);
+    case "peekApp":
+      return Promise.reject(
+        new Error("peekApp needs the Lotics host: a standalone app has no sibling apps to open. Gate the control on isEmbedded().")
+      );
     case "openApp":
       return Promise.reject(
         new Error("openApp needs the Lotics host: a standalone app has no sibling apps to open. Gate the control on isEmbedded().")

package/dist/index.d.ts

@@ -24,7 +24,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 { openApp, peekApp } from "./open_app.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { renameFile } from "./rename_file.js";

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   sumDecimal,
   tiersAscend,
   urlParam
-} from "./chunk-MK4DBY6R.js";
+} from "./chunk-I2BOTPL6.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -29212,6 +29212,7 @@ function useAppContext() {
     openableApps: data?.openable_apps ?? null,
     commentsEnabled: data?.comments_enabled ?? false,
     recordingEnabled: data?.recording_enabled === true,
+    peekAppEnabled: data?.peek_app_enabled === true,
     timezone: data?.timezone,
     currency: data?.default_currency,
     resolved: data !== void 0,
@@ -33031,6 +33032,9 @@ function openExternal(url2) {
 function openApp(appId, route = "/") {
   return rpc("openApp", { app_id: appId, route });
 }
+function peekApp(appId, route = "/") {
+  return rpc("peekApp", { app_id: appId, route });
+}
 
 // src/ask_ai.ts
 function askAi(args) {
@@ -33244,6 +33248,7 @@ export {
   newRecordId,
   openApp,
   openExternal,
+  peekApp,
   queryAll,
   readCreatedAt,
   readFiles,

package/dist/open_app.d.ts

@@ -10,3 +10,15 @@
  * 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>;

package/dist/router.js

@@ -2,7 +2,7 @@ import {
   isEmbedded,
   postHostNotification,
   setUrlParams
-} from "./chunk-MK4DBY6R.js";
+} from "./chunk-I2BOTPL6.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/rpc.d.ts

@@ -9,7 +9,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" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "activity.list" | "activity.undo" | "recording.start" | "recording.stop";
+export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "peekApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "activity.list" | "activity.undo" | "recording.start" | "recording.stop";
 export interface AgentRunPayload {
     alias: string;
     session_id: string;
@@ -72,6 +72,8 @@ export interface AppContext {
     /** True only from a host with `recording.*`, for a signed-in member, on an
      *  instance that transcribes; absent reads as false. */
     recording_enabled?: boolean;
+    /** True only from a host that serves `peekApp`; absent reads as false. */
+    peek_app_enabled?: boolean;
     /** This app's recordings the host still tracks, by alias. */
     recordings?: Record<string, unknown>;
     /** Who in the organization is away, or will be, and who stands in — absent from an older host and for a visitor from

package/dist/viewer.d.ts

@@ -23,6 +23,8 @@ export declare function useAppContext(): {
     }[] | null;
     commentsEnabled: boolean;
     recordingEnabled: boolean;
+    /** The host draws another app's record in a sheet over this one (`peekApp`). */
+    peekAppEnabled: boolean;
     timezone: string | undefined;
     currency: string | undefined;
     resolved: boolean;

package/docs/members_and_options.md

@@ -262,7 +262,7 @@ context, read once as the app opens. Display only: the workflow body re-checks w
 (`current_member_stands_in_for(...)`).
 
 `openableApps` lists the workspace's apps the viewer can open, each by its `id` and its `name` — what a
-way through to a sibling app (`openApp`) is offered by. `null` where the host did not say (standalone, 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.
 

package/docs/queries.md

@@ -142,7 +142,7 @@ Delivery-layer enrichment (applied to the response, per request):
   (`readSelect(cell).map((o) => o.key)`) against any alias that projects the underlying field
   DIRECTLY.
 - **`number` columns** arrive as JS numbers (Postgres `numeric` strings are coerced; a
-  high-precision decimal that would lose digits stays a string). **`date`/`datetime`** columns
+  decimal with more digits than a double holds rounds to the double). **`date`/`datetime`** columns
   arrive as canonical wall-clock strings (`YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`).
 
 ### System columns

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`**, **`downloadFile`**, and **`requestGeofencedLocation`** / **`isWithinZone`**.
+**`openApp`** / **`peekApp`**, **`downloadFile`**, and **`requestGeofencedLocation`** / **`isWithinZone`**.
 
 ## `mount()` — the entry point
 
@@ -216,6 +216,7 @@ surfaces:
 | `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
@@ -257,6 +258,7 @@ semantics are documented:
 | `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) |
@@ -269,7 +271,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?, recordings? }`. `member_id` is the
+`{ member_id, comments_enabled, timezone, default_currency, recording_enabled?, peek_app_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
@@ -341,6 +343,25 @@ declares it (`/` for its register); it is the target's to define.
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.122.0",
+  "version": "0.122.2",
   "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": {