@lotics/app-sdk 0.49.1 → 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, 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/config.d.ts

@@ -0,0 +1,24 @@
+import type { AppConfigValue } from "./rpc.js";
+/**
+ * Read the installation's customization config — the first rung of the App
+ * Packages customization ladder (see docs/app_packages.md § The customization
+ * ladder). A package declares typed config knobs with defaults (labels, feature
+ * toggles, theme, column choices); each installation stores the customized values
+ * and the app reads them here. Updates flow: editing config in the product
+ * changes what this returns, with no re-deploy.
+ *
+ * `defaults` is the package contract's declared defaults — the canonical fallback
+ * (the codegen surface emits them so the call is fully typed). They fill any knob
+ * the installation hasn't overridden and provide a flicker-free first paint:
+ * before the context resolves the stored map is empty, so the defaults show
+ * immediately and the stored values overlay them once resolved.
+ *
+ *   const { config } = useConfig({ "deal.label": "Deal", "show_archived": false });
+ *   <Text>{config["deal.label"]}</Text>
+ *
+ * Gate on `loading` only for config-derived layout that must not flash a default.
+ */
+export declare function useConfig<T extends Record<string, AppConfigValue> = Record<string, AppConfigValue>>(defaults?: T): {
+    config: T;
+    loading: boolean;
+};

package/dist/src/config.js

@@ -0,0 +1,33 @@
+import { useMemo } from "react";
+import { useAppContext } from "./viewer.js";
+/**
+ * Read the installation's customization config — the first rung of the App
+ * Packages customization ladder (see docs/app_packages.md § The customization
+ * ladder). A package declares typed config knobs with defaults (labels, feature
+ * toggles, theme, column choices); each installation stores the customized values
+ * and the app reads them here. Updates flow: editing config in the product
+ * changes what this returns, with no re-deploy.
+ *
+ * `defaults` is the package contract's declared defaults — the canonical fallback
+ * (the codegen surface emits them so the call is fully typed). They fill any knob
+ * the installation hasn't overridden and provide a flicker-free first paint:
+ * before the context resolves the stored map is empty, so the defaults show
+ * immediately and the stored values overlay them once resolved.
+ *
+ *   const { config } = useConfig({ "deal.label": "Deal", "show_archived": false });
+ *   <Text>{config["deal.label"]}</Text>
+ *
+ * Gate on `loading` only for config-derived layout that must not flash a default.
+ */
+export function useConfig(defaults) {
+    const ctx = useAppContext();
+    const stored = ctx.config;
+    // Key the memo on the defaults CONTENT, not identity. An inline literal is a
+    // fresh reference each render, so a content hash keeps the result reference
+    // stable while values are unchanged AND recomputes when a default value changes
+    // (e.g. an i18n label after a locale switch) — which a ref-captured defaults
+    // would silently miss. Config maps are tiny, so the stringify cost is trivial.
+    const defaultsKey = JSON.stringify(defaults ?? {});
+    const config = useMemo(() => ({ ...(defaults ?? {}), ...stored }), [stored, defaultsKey]);
+    return { config, loading: !ctx.resolved };
+}

package/dist/src/index.d.ts

@@ -21,10 +21,12 @@ export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, Infini
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";
+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

@@ -18,8 +18,9 @@ export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
 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;
@@ -45,6 +45,15 @@ export interface AgentRunHandle {
  * The PostHog key/host are not here — they're the public project key, hardcoded
  * in `analytics.ts`.
  */
+/**
+ * A single installation config value. An app package declares typed config knobs
+ * (labels, toggles, theme, column choices) with defaults; an installation stores
+ * the customized values, which the SDK's `useConfig()` reads. The canonical type
+ * lives in `@lotics/shared` (`AppInstallationConfigValue`); the SDK mirrors it
+ * here so it stays a zero-internal-dependency published package (the boundary
+ * mirror, like `AppContext` itself).
+ */
+export type AppConfigValue = string | number | boolean;
 export interface AppContext {
     app_id: string;
     app_name: string;
@@ -57,6 +66,13 @@ export interface AppContext {
      * app that didn't opt in, and (vacuously) for standalone visitors.
      */
     comments_enabled: boolean;
+    /**
+     * The installation's customization values — the package's config knobs by
+     * alias (see `useConfig`). Empty for a bespoke app (no package) and until the
+     * context resolves. Read-only; an app changes config through the product, not
+     * the SDK.
+     */
+    config: Record<string, AppConfigValue>;
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its
@@ -94,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)}` : "";
@@ -529,6 +571,7 @@ async function standaloneContext() {
         // comments are unavailable regardless of the capability flag.
         member_id: null,
         comments_enabled: info.comments_enabled,
+        config: info.config ?? {},
     };
 }
 async function standaloneQuery(p) {

package/dist/src/viewer.d.ts

@@ -1,11 +1,13 @@
+import { type AppConfigValue } from "./rpc.js";
 /**
  * Read the app's context once, shared across every hook via a stable SWR key.
  * The host (the product iframe, or `lotics app dev`) supplies the signed-in
- * member and the app's declared capabilities.
+ * member, the app's declared capabilities, and the installation's config.
  */
 export declare function useAppContext(): {
     memberId: string | null;
     commentsEnabled: boolean;
+    config: Record<string, AppConfigValue>;
     resolved: boolean;
 };
 /**

package/dist/src/viewer.js

@@ -1,9 +1,14 @@
 import useSWR from "swr";
 import { rpc } from "./rpc.js";
+// Stable identity for the not-yet-resolved / bespoke-app case. An inline `{}`
+// fallback would be a fresh reference every render, defeating useConfig's
+// memo (its result would recompute — and re-render consumers — on every
+// render even with unchanged values).
+const EMPTY_CONFIG = {};
 /**
  * Read the app's context once, shared across every hook via a stable SWR key.
  * The host (the product iframe, or `lotics app dev`) supplies the signed-in
- * member and the app's declared capabilities.
+ * member, the app's declared capabilities, and the installation's config.
  */
 export function useAppContext() {
     const { data } = useSWR("app-context", () => rpc("context", {}), {
@@ -15,6 +20,7 @@ export function useAppContext() {
     return {
         memberId: data?.member_id ?? null,
         commentsEnabled: data?.comments_enabled ?? false,
+        config: data?.config ?? EMPTY_CONFIG,
         resolved: data !== undefined,
     };
 }

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 |
@@ -222,10 +222,13 @@ 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 app's identity: `{ app_id, app_name,
-workspace_id, organization_id, member_id, comments_enabled }`. `member_id` is
-the signed-in member when embedded, `null` standalone. **Limitation:** the
-context type is not exported from the package root — type the result yourself
-via the `rpc<T>` generic.
+workspace_id, organization_id, member_id, comments_enabled, config }`.
+`member_id` is the signed-in member when embedded, `null` standalone; `config`
+is the installation's customization map — read it through
+[`useConfig`](#installation-config--useconfig), not off this raw op. **Limitation:**
+the context type is not exported from the package root — type the result
+yourself via the `rpc<T>` generic (`AppConfigValue`, the config value type, *is*
+exported).
 
 ## `openExternal()` — open a link in a new tab
 
@@ -366,6 +369,74 @@ install `posthog-js` or call any analytics API from app code.
   browsers (e.g. Playwright) are never tracked, so analytics cannot be verified
   through headless automation.
 
+## Installation config — `useConfig()`
+
+**`useConfig(defaults?)`** → `{ config, loading }` — the App-Packages customization
+knobs for this installation (labels, toggles, theme, column choices), keyed by the
+alias the package contract declares. Exact signature: `dist/src/config.d.ts`.
+
+```tsx
+const { config } = useConfig({ board_title: "Tasks", show_archive: false });
+```
+
+- **Pass the contract's defaults.** They fill un-overridden knobs and paint
+  flicker-free before the context resolves; the installation's stored values
+  overlay them (a stored value always wins over the same-key default). `loading`
+  is true only until the **one-shot** context RPC settles (it never revalidates)
+  — gate on it only for config-derived layout that must not flash a default.
+- Values are `string | number | boolean` (`AppConfigValue`, exported from the
+  package root). The returned object is referentially stable across renders while
+  the values are unchanged — the merge is memoized, and the defaults are keyed by
+  their *content*, so passing a fresh inline `{…}` literal every render is fine
+  (no churn); it's safe as a `useEffect`/`useMemo` dependency.
+- **Bespoke apps** (not installed from a package) get `{}` from the host — the
+  hook resolves to just the defaults, so shared code needs no package check.
+- **A standalone (public) app behind a password never receives its stored config
+  in the client.** The knobs are gated server-side (they can carry business
+  terms), and the SDK resolves the app's identity once — before the visitor
+  authenticates — so `useConfig` returns the defaults only, even after unlock.
+  Design a public, password-gated app to be correct on its defaults alone.
+  (Embedded and standalone-*unprotected* apps both get the stored config.)
+- **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.49.1",
+  "version": "0.51.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {