@lotics/app-sdk 0.50.0 → 0.51.0

package/AGENTS.md

@@ -22,7 +22,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 `items` → `AgentRun`) and `askAi` — plus the fields-vs-file razor for choosing between them. |
 | [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. |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), and the publish chain for package contributors. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/src/index.d.ts

@@ -25,8 +25,8 @@ export { useConfig } from "./config.js";
 export type { AppConfigValue } from "./rpc.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
-export { rpc, isEmbedded } from "./rpc.js";
-export type { RpcOp } from "./rpc.js";
+export { rpc, isEmbedded, getAppBinding } from "./rpc.js";
+export type { RpcOp, AppBinding } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";

package/dist/src/index.js

@@ -20,7 +20,7 @@ export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { useConfig } from "./config.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
-export { rpc, isEmbedded } from "./rpc.js";
+export { rpc, isEmbedded, getAppBinding } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";

package/dist/src/rpc.d.ts

@@ -19,7 +19,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" | "binding" | "openExternal" | "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;
@@ -110,3 +110,26 @@ export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: st
  * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
  */
 export declare function transportErrorMessage(status: number, parsed: unknown): string;
+/**
+ * A package installation's alias→concrete-id maps — what the generated
+ * `.lotics/app_fields.ts` of a package project resolves `F`/`OPT`/`ROLE`
+ * through at module load. Keys are fully-qualified contract aliases
+ * (`entity.field`, `entity.field:opt`, role alias); values are this
+ * installation's concrete ids. 404s for a bespoke (non-package) app.
+ */
+export interface AppBinding {
+    fields: Record<string, string>;
+    options: Record<string, string>;
+    roles: Record<string, string>;
+}
+/**
+ * Fetch the installation's binding, once per boot (module-cached — every
+ * `app_fields` import shares the same in-flight promise). Called at module
+ * load via top-level await, so it must work before `mount()` — and a failure
+ * there rejects the whole module graph (blank frame, no ErrorBoundary can
+ * catch module evaluation). Two mitigations, mirroring `boot()`:
+ * bounded retries absorb a transient transport blip, and a rejection is never
+ * cached so a remount/direct caller can retry rather than replaying the same
+ * stale failure forever.
+ */
+export declare function getAppBinding(): Promise<AppBinding>;

package/dist/src/rpc.js

@@ -452,6 +452,8 @@ function rpcStandalone(op, payload) {
             return standaloneMembers(payload);
         case "context":
             return standaloneContext();
+        case "binding":
+            return standaloneBinding();
         case "openExternal":
             return standaloneOpenExternal(payload);
         case "askAi":
@@ -482,6 +484,46 @@ function rpcStandalone(op, payload) {
 function rejectCommentsStandalone() {
     return Promise.reject(new Error("Comments are available only in embedded apps — a signed-in member is required."));
 }
+let bindingPromise;
+/**
+ * Fetch the installation's binding, once per boot (module-cached — every
+ * `app_fields` import shares the same in-flight promise). Called at module
+ * load via top-level await, so it must work before `mount()` — and a failure
+ * there rejects the whole module graph (blank frame, no ErrorBoundary can
+ * catch module evaluation). Two mitigations, mirroring `boot()`:
+ * bounded retries absorb a transient transport blip, and a rejection is never
+ * cached so a remount/direct caller can retry rather than replaying the same
+ * stale failure forever.
+ */
+export function getAppBinding() {
+    if (bindingPromise === undefined) {
+        const attempt = fetchBindingWithRetry();
+        bindingPromise = attempt;
+        attempt.catch(() => {
+            if (bindingPromise === attempt)
+                bindingPromise = undefined;
+        });
+    }
+    return bindingPromise;
+}
+async function fetchBindingWithRetry() {
+    const delays = [500, 1500];
+    for (const delay of delays) {
+        try {
+            return await rpc("binding", {});
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    return rpc("binding", {});
+}
+async function standaloneBinding() {
+    const { app_id } = await boot();
+    return (await apiCall("GET", `/v1/apps/${app_id}/binding`, undefined, {
+        appId: app_id,
+    }));
+}
 async function standaloneMembers(p) {
     const { app_id } = await boot();
     const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";

package/docs/runtime.md

@@ -166,7 +166,7 @@ surfaces:
 
 | Op | Embedded (product) | `lotics app dev` | Standalone |
 |---|---|---|---|
-| `query`, `field_options`, `workflow`, `members`, `context`, `upload`, `urlState.get/set`, `openExternal` | yes | yes | yes |
+| `query`, `field_options`, `workflow`, `members`, `context`, `binding`, `upload`, `urlState.get/set`, `openExternal` | yes | yes | yes |
 | `comments.*` | yes | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
 | `agentRun` (streaming, internal to `useAgentRun`) | yes | yes | yes |
 | `agentRuns`, `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
@@ -400,6 +400,43 @@ const { config } = useConfig({ board_title: "Tasks", show_archive: false });
 - **Read-only.** Config is edited in the product (the installation's settings),
   never written from app code — there is no setter.
 
+## Installation binding — `getAppBinding()` (package apps)
+
+**`getAppBinding()`** → `Promise<AppBinding>` — a package installation's
+alias→concrete-id maps: `{ fields, options, roles }`, keyed by fully-qualified
+contract aliases (`"tasks.title"`, `"tasks.status:to_do"`, role alias) with this
+workspace's `fld_`/`opt_`/`grp_` ids as values. Exact signature:
+`dist/src/rpc.d.ts`.
+
+You normally never call it yourself: the package project's generated
+`.lotics/app_fields.ts` (written by `lotics package new/extract/dev/sync` from
+`contract.json`) calls it once at **module load** via top-level await and
+exports plain-string `F` / `OPT` / `ROLE` maps — the same import surface as a
+bespoke app's baked codegen, but resolved per-installation at runtime:
+
+```ts
+import { OPT } from "../.lotics/app_fields";
+const STATUS_DONE = OPT.TASKS.status.done; // this installation's "opt_…"
+```
+
+- **One fetch per boot.** The promise is module-cached; every importer shares
+  it. The ESM graph awaits it before any dependent module evaluates, so the
+  values are ordinary strings everywhere — including module-top-level constants.
+  Transient failures are retried (3 attempts, short backoff) and a rejection is
+  never cached — a module-load failure rejects the whole graph (blank frame),
+  so the fetch absorbs blips rather than bricking the boot on one lost request.
+- **Requires the starter's `build.target: "es2022"`** (top-level await does not
+  exist below it). `lotics package extract` refreshes `vite.config.ts` from the
+  current starter for exactly this reason.
+- **Fails loud.** A key missing from the binding throws at boot with the alias
+  named — the binding is verified complete at install/adopt, so a miss means
+  the generated file is stale relative to the installed contract version
+  (re-run the codegen, republish).
+- **Bespoke apps 404.** A never-adopted app has no binding; bespoke projects
+  keep the baked `lotics app codegen` variant instead. Shared code should not
+  call this directly — import from `.lotics/app_fields` and let the project
+  kind pick the implementation.
+
 ## For package contributors
 
 Everything below concerns changing `@lotics/app-sdk` itself (in the Lotics

package/package.json

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