@lotics/app-sdk 0.49.0 → 0.50.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), 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,6 +21,8 @@ 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";

package/dist/src/index.js

@@ -18,6 +18,7 @@ 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 { openExternal } from "./open_external.js";

package/dist/src/rpc.d.ts

@@ -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

package/dist/src/rpc.js

@@ -529,6 +529,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/queries.md

@@ -763,17 +763,26 @@ slice, and within it:
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
 - **Trigram-served:** `from_table.search` (§7).
-- **Partition scan (linear in table size):** everything else — text `contains`/`equals`,
-  number and date range predicates, negations (`has_none_of`, `is_none_of`, `not_*`),
-  emptiness, files predicates. Fine on thousands of rows; on very large tables these dominate
-  latency and are the usual timeout cause.
-
-**Filter shape drives latency.** Lead with a GIN-served membership filter or `search` where you
-can; let the scan-shaped predicates refine the already-narrowed set. Derived-layer filters run
-over the subquery result (no index), so **filter at the source layer whenever the field exists
-there** — the runtime filter is for caller-driven refinement, not for the main cut. (The engine
-pushes eligible filter-over-union predicates down automatically, but don't rely on that for
-other shapes.)
+- **B-tree-served (automatic for deployed queries):** text `equals`, number and date
+  comparisons (exact and range), and `sort` fields — for fields referenced in a **deployed
+  named query's template**. The platform provisions a partial expression index per referenced
+  field automatically: built online on `app deploy` and `app query set`, re-synced daily,
+  capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
+  A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
+  so it still gets its index. Index-seek speed at any table size once provisioned.
+- **Partition scan (linear in table size):** everything else — text `contains`, negations
+  (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
+  fields that appear **only** in the runtime `filter`/`sort` options rather than the deployed
+  template. Fine on thousands of rows; on very large tables these dominate latency and are the
+  usual timeout cause.
+
+**Filter shape drives latency.** Equality/range/sort predicates in the deployed template are
+index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
+predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
+(no index), so **filter at the source layer whenever the field exists there** — the runtime
+filter is for caller-driven refinement, not for the main cut (a runtime-only field gets no
+managed index). (The engine pushes eligible filter-over-union predicates down automatically,
+but don't rely on that for other shapes.)
 
 ### The authoring rules
 

package/docs/runtime.md

@@ -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,37 @@ 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.
+
 ## 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.0",
+  "version": "0.50.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {