@lotics/app-sdk 0.89.0 → 0.90.0

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

@@ -26,6 +26,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

@@ -21,6 +21,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/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) |
@@ -267,6 +269,38 @@ page (standalone). Opens in a new tab with `noopener,noreferrer`.
   `FilePreview`/`FileGalleryModal` (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

package/package.json

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