@lotics/app-sdk 0.83.1 → 0.86.0

package/AGENTS.md

@@ -16,15 +16,15 @@ signature; open the file.**
 |---|---|
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
-| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [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, 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. |
+| [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. |
 
 ## Non-negotiables (each detailed in its doc)
 
@@ -34,6 +34,9 @@ signature; open the file.**
   A client-supplied member id is an IDOR. → [security](./docs/security.md)
 - **Server data is never copied into `useState`** — hooks are the source of truth; derive with
   `useMemo`. → [data_fetching](./docs/data_fetching.md)
+- **A successful write re-reads the screen for you** — do not chase a `useWorkflow` call with
+  `refetch()`. Reach for it only where a write cannot have told you: a poll, a value nothing on
+  this screen wrote, a total you supplied. → [mutations](./docs/mutations.md)
 - **Update writes are diffs** — send only changed fields, and *cleared* is a change: an optional
   input clears with `null` (never `""`), which `set_skip_null` drops and `set` performs.
   → [mutations](./docs/mutations.md)

package/dist/src/hooks.js

@@ -19,7 +19,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, } from "./rpc.js";
+import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, registerQueryAlias, notifyLocalWrite, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
 import { getMockRows, getMockWorkflow, hasMockFlag } from "./mock.js";
 export { buildChoiceOutput } from "./agent_stream.js";
@@ -34,7 +34,18 @@ export function useWorkflow(alias) {
         if (mock) {
             return typeof mock === "function" ? await mock(inputs ?? {}) : mock;
         }
-        return rpc("workflow", { alias, inputs: inputs ?? {} });
+        const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
+        // A workflow is the app's only write path, so a successful one means the
+        // rows on screen are stale. Re-read now rather than waiting for the host's
+        // realtime push to say what the caller already knows — that wait is what
+        // makes a screen feel like it lagged its own button.
+        //
+        // Only on success: a refused write changed nothing, and refetching after
+        // one would replace the values the user is still looking at (and about to
+        // correct) with an identical set, for a round trip nobody asked for.
+        if (result.status !== "error")
+            notifyLocalWrite();
+        return result;
     }, [alias]);
 }
 // Shared SWR config: surface a failed query immediately, keep the last good
@@ -79,10 +90,18 @@ function useHostRefetch(alias, refetch, mockRows) {
     useEffect(() => {
         if (hasMockFlag() || mockRows)
             return;
-        return subscribeQueriesChanged((aliases) => {
+        // Registered separately from the subscription because the two answer
+        // different questions: the subscription is "tell me when MY alias moved",
+        // the registration is "I am on screen, so a local write should re-read me".
+        const unregister = registerQueryAlias(alias);
+        const unsubscribe = subscribeQueriesChanged((aliases) => {
             if (aliases.includes(alias))
                 refetch();
         });
+        return () => {
+            unregister();
+            unsubscribe();
+        };
     }, [alias, refetch, mockRows]);
 }
 /**

package/dist/src/index.d.ts

@@ -21,12 +21,10 @@ export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptio
 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, getAppBinding } from "./rpc.js";
-export type { RpcOp, AppBinding, AiContextValue, AiContextRecordRef } from "./rpc.js";
+export { rpc, isEmbedded } from "./rpc.js";
+export type { RpcOp, AiContextValue, AiContextRecordRef } 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,9 +18,8 @@ export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } 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, getAppBinding } from "./rpc.js";
+export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";

package/dist/src/mock.d.ts

@@ -59,7 +59,7 @@ export declare function registerMockFixture(fixture: AppFixture | undefined): vo
 /**
  * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
  * a malformed URL or missing `window` (SSR / jsdom without location) silently
- * returns false. Distinct from `isMockMode`: analytics keys off the raw flag
+ * returns false. Distinct from `isMockMode`: a caller may key off the raw flag
  * (a design-time / screenshot load emits no events regardless of fixtures),
  * while query mocking additionally requires a registered fixture.
  */

package/dist/src/mock.js

@@ -48,7 +48,7 @@ export function registerMockFixture(fixture) {
 /**
  * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
  * a malformed URL or missing `window` (SSR / jsdom without location) silently
- * returns false. Distinct from `isMockMode`: analytics keys off the raw flag
+ * returns false. Distinct from `isMockMode`: a caller may key off the raw flag
  * (a design-time / screenshot load emits no events regardless of fixtures),
  * while query mocking additionally requires a registered fixture.
  */

package/dist/src/mount.d.ts

@@ -27,7 +27,7 @@
  * `mount` wires up React 19's createRoot against `#root` in the iframe shell,
  * sets up window.onerror/unhandledrejection forwarding so runtime crashes
  * surface in the parent's debug pane, registers the fixture (if any), renders
- * the user's tree, and bootstraps PostHog analytics (see `./analytics.ts`).
+ * the user's tree.
  *
  * If the bundler doesn't ship #root in the user's `index.html`, we create it
  * — Vite's default scaffold provides one, but defensive creation keeps the

package/dist/src/mount.js

@@ -1,6 +1,5 @@
 import { createRoot } from "react-dom/client";
 import { registerMockFixture } from "./mock.js";
-import { bootstrapAnalytics } from "./analytics.js";
 export function mount(element, options = {}) {
     registerMockFixture(options.fixture);
     let container = document.getElementById("root");
@@ -14,11 +13,6 @@ export function mount(element, options = {}) {
     // *something* even before the parent's debug telemetry is wired up.
     installVisibleErrorHandlers(container);
     createRoot(container).render(element);
-    // Fire-and-forget: resolve the app's identity and start PostHog (explicit
-    // events — autocapture is disabled project-wide). Never awaited — analytics
-    // must not delay first paint, and is best-effort so its failure can't break
-    // the app. No-ops in mock mode and off the deployed app host.
-    void bootstrapAnalytics();
 }
 function installVisibleErrorHandlers(container) {
     const showError = (message) => {

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" | "binding" | "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" | "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;
@@ -37,24 +37,11 @@ export interface AgentRunHandle {
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:
  *
- *  - **Bridged** — the host (authenticated) supplies `member_id` so app events
- *    attach to the same PostHog person as the product, plus org/workspace/app
- *    from its own context.
+ *  - **Bridged** — the host (authenticated) supplies `member_id`, plus
+ *    org/workspace/app from its own context.
  *  - **Standalone** — the public `/by-subdomain` endpoint returns identity;
  *    `member_id` is null (anonymous visitor).
- *
- * 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;
 /** A raw reference to one record — table + record id, passed through UNRESOLVED.
  *  The member's own chat agent may act on it only where that member's IAM already
  *  allows; the app never resolves it into data here. */
@@ -87,10 +74,6 @@ export type HostNotification = {
     context: AiContextValue | null;
 };
 export interface AppContext {
-    app_id: string;
-    app_name: string;
-    workspace_id: string;
-    organization_id: string;
     member_id: string | null;
     /**
      * Whether the app declared the `comments` capability. `useComments` is
@@ -98,13 +81,6 @@ 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
@@ -149,6 +125,25 @@ export declare function postHostNotification(message: HostNotification): void;
  * stay on pull-based freshness.
  */
 export declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
+/** Register a mounted query's alias. Returns the matching unregister. */
+export declare function registerQueryAlias(alias: string): () => void;
+/**
+ * Re-read the mounted queries because THIS app just wrote.
+ *
+ * The host's `queriesChanged` push is for changes the app did not make — it
+ * travels the realtime path (a version counter, a socket the host owns, and
+ * coalescing that is deliberately lazy under load), which is right for another
+ * member's edit and far too slow for your own. A writer already knows, so it
+ * rings the same bell locally instead of waiting to be told.
+ *
+ * It names every mounted alias rather than only the ones the write touched: the
+ * app cannot know which tables a workflow wrote, and the alternative — asking
+ * every call site to declare what it invalidates — is a list that goes stale
+ * silently the first time a workflow body grows a second write. The cost is
+ * bounded by what is on screen, and it is the work the app was going to do a
+ * moment later anyway.
+ */
+export declare function notifyLocalWrite(): void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
  * (the caller parses it via `agent_stream`); `done` settles when the stream
@@ -198,26 +193,3 @@ export declare function transportErrorMessage(status: number, parsed: unknown):
  * message, and a non-JSON or 5xx body never becomes one.
  */
 export declare function streamStartError(res: Response): Promise<Error>;
-/**
- * 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

@@ -111,6 +111,50 @@ export function subscribeQueriesChanged(cb) {
         refetchSubscribers.delete(cb);
     };
 }
+/**
+ * Every alias with a mounted query hook, so a local write can name them.
+ *
+ * Registered by the hooks themselves rather than derived from the manifest: what
+ * matters is what is ON SCREEN, and a screen mounts a handful of an app's
+ * queries. Keyed by alias with a count, because two hooks can read one alias at
+ * once (a register and the drawer over it) and the first to unmount must not
+ * retract the second's registration.
+ */
+const mountedAliases = new Map();
+/** Register a mounted query's alias. Returns the matching unregister. */
+export function registerQueryAlias(alias) {
+    mountedAliases.set(alias, (mountedAliases.get(alias) ?? 0) + 1);
+    return () => {
+        const n = (mountedAliases.get(alias) ?? 1) - 1;
+        if (n > 0)
+            mountedAliases.set(alias, n);
+        else
+            mountedAliases.delete(alias);
+    };
+}
+/**
+ * Re-read the mounted queries because THIS app just wrote.
+ *
+ * The host's `queriesChanged` push is for changes the app did not make — it
+ * travels the realtime path (a version counter, a socket the host owns, and
+ * coalescing that is deliberately lazy under load), which is right for another
+ * member's edit and far too slow for your own. A writer already knows, so it
+ * rings the same bell locally instead of waiting to be told.
+ *
+ * It names every mounted alias rather than only the ones the write touched: the
+ * app cannot know which tables a workflow wrote, and the alternative — asking
+ * every call site to declare what it invalidates — is a list that goes stale
+ * silently the first time a workflow body grows a second write. The cost is
+ * bounded by what is on screen, and it is the work the app was going to do a
+ * moment later anyway.
+ */
+export function notifyLocalWrite() {
+    if (mountedAliases.size === 0)
+        return;
+    const aliases = [...mountedAliases.keys()];
+    for (const cb of refetchSubscribers)
+        cb(aliases);
+}
 const pending = new Map();
 const streaming = new Map();
 /** `useUrlState` subscribers — notified when the host broadcasts new params
@@ -413,11 +457,11 @@ function readSessionCookie() {
     return null;
 }
 /**
- * Resolve the app's identity + analytics config from its own subdomain. Shared
+ * Resolve the app's identity from its own subdomain. Shared
  * promise so the context bootstrap and the first data call coalesce into one
- * `/by-subdomain` fetch. Does NOT touch the password gate — identity is needed
- * for analytics regardless of whether the visitor has unlocked the data, so a
- * password-gated app still resolves (and tracks) before the prompt.
+ * `/by-subdomain` fetch. Does NOT touch the password gate — the app's own
+ * identity is not the gated thing, so a password-gated app still resolves it
+ * before the prompt.
  */
 function resolveAppInfo() {
     if (appInfoPromise)
@@ -609,8 +653,6 @@ function rpcStandalone(op, payload) {
             return standaloneMembers(payload);
         case "context":
             return standaloneContext();
-        case "binding":
-            return standaloneBinding();
         case "openExternal":
             return standaloneOpenExternal(payload);
         case "askAi":
@@ -641,46 +683,6 @@ 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)}` : "";
@@ -720,15 +722,10 @@ async function standaloneUrlStateSet(p) {
 async function standaloneContext() {
     const info = await resolveAppInfo();
     return {
-        app_id: info.app_id,
-        app_name: info.app_name,
-        workspace_id: info.workspace_id,
-        organization_id: info.organization_id,
         // No host session in standalone mode — the visitor is anonymous, so
         // 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,13 +1,11 @@
-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, the app's declared capabilities, and the installation's config.
+ * member and the app's declared capabilities.
  */
 export declare function useAppContext(): {
     memberId: string | null;
     commentsEnabled: boolean;
-    config: Record<string, AppConfigValue>;
     resolved: boolean;
 };
 /**

package/dist/src/viewer.js

@@ -1,14 +1,9 @@
 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, the app's declared capabilities, and the installation's config.
+ * member and the app's declared capabilities.
  */
 export function useAppContext() {
     const { data } = useSWR("app-context", () => rpc("context", {}), {
@@ -20,7 +15,6 @@ export function useAppContext() {
     return {
         memberId: data?.member_id ?? null,
         commentsEnabled: data?.comments_enabled ?? false,
-        config: data?.config ?? EMPTY_CONFIG,
         resolved: data !== undefined,
     };
 }

package/docs/data_fetching.md

@@ -116,9 +116,9 @@ server validates system conditions by `type` and never reads `field_key` on them
   renders the cached rows instantly *and* revalidates them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads dedupe to one request.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on), a **realtime push**, and explicit `refetch()`.
-  **Still call `refetch()` after a write the user is watching for**: arrival covers navigation, not a
-  mutation made on the screen you are already standing on.
+  (`revalidateOnFocus`, default on), a **realtime push**, and **this app's own successful write**,
+  which re-reads every mounted query without being asked (see
+  [./mutations.md](./mutations.md)). `refetch()` covers what none of those can know about.
 - **Realtime push keeps an already-open screen current.** When a table one of your queries reads
   changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or
   MCP — that query refetches within about a second. Nothing to wire: it follows from the query's own
@@ -153,10 +153,11 @@ server validates system conditions by `type` and never reads `field_key` on them
   number, while `error !== null`. Note a key CHANGE resets this: a new `params`/`filter`/`sort`
   is a fresh key with no prior rows, so the "last successful rows stay rendered" behaviour above
   does not save you.
-- **`refetch()`** re-runs the query. Call it after a known mutation point — a successful
-  `useWorkflow` call — to pull the latest state (see [./mutations.md](./mutations.md)).
-  `usePaginatedQuery.refetch()` refreshes the page, and the count when the hook owns it
-  (a caller-supplied `total` is the caller's to refresh).
+- **`refetch()`** re-runs the query. A successful `useWorkflow` call already re-reads the mounted
+  queries on its own (see [./mutations.md](./mutations.md)), so reach for this only where a write
+  cannot have told you: a poll, a value that changes without anything on this screen writing, or a
+  total you supplied yourself. `usePaginatedQuery.refetch()` refreshes the page, and the count when
+  the hook owns it (a caller-supplied `total` is the caller's to refresh).
 - **Ambient-chat mutations refetch automatically.** When the member's ambient chat agent (see
   [./ai.md](./ai.md#useaicontextslot-context--tell-the-ambient-chat-what-the-member-is-looking-at))
   finishes a turn that mutated records, the host pushes **every mounted query hook** to re-read —

package/docs/mutations.md

@@ -3,7 +3,7 @@
 Everything about writing data from an app: `useWorkflow` (the only write path), the
 `WorkflowResult` contract and its resolve-never-throw failure model, declaring typed workflow
 inputs (file/member/optional inputs), returning structured data with `return({ data })`,
-refetching after a mutation, the diff-before-update discipline, locked records
+the automatic re-read a successful write triggers, the diff-before-update discipline, locked records
 (`readLocked` + `request_locked_record_change`), and optimistic reconciliation
 (`useOptimistic`). Read this before building any screen that creates, updates, or deletes
 records. What may be written **inside** the workflow body — the JS subset, steps, helpers,
@@ -89,7 +89,7 @@ if (result.status === "error") {
   showError(result.message ?? "Something went wrong.");
   return;
 }
-orders.refetch();
+// Success. Mounted queries re-read themselves — see "Refetch after a mutation".
 ```
 
 **Warning:** a `try/catch` with no `status` check silently treats every workflow failure as
@@ -312,9 +312,9 @@ is [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
 
-Query hooks cache through SWR and know nothing about your workflows — a successful mutation
-does **not** invalidate any query. After a known mutation point, call the owning query hook's
-`refetch()`:
+**A successful workflow re-reads the queries that are mounted, on its own.** A workflow is the
+app's only write path, so the rows on screen are stale the moment one succeeds — the SDK
+re-reads them rather than making every call site remember to. Nothing to call:
 
 ```tsx
 const items = useQuery("items");
@@ -323,10 +323,24 @@ const closeItem = useWorkflow("closeItem");
 const onClose = async (recordId: string) => {
   const r = await closeItem({ record_id: recordId });
   if (r.status === "error") { showError(r.message); return; }
-  items.refetch();
+  // items re-reads itself — a successful write already said so.
 };
 ```
 
+Only on **success**: a refused write changed nothing, and re-reading after one would swap the
+values the user is still looking at, and about to correct, for an identical set.
+
+It names every MOUNTED alias, not the ones the write touched — an app cannot know which tables
+a workflow body wrote, and a per-call-site list of what to invalidate goes stale silently the
+first time that body grows a second write. The cost is bounded by what is on screen.
+
+This is separate from the host's realtime push, which carries changes **other** people make and
+travels a socket the host owns. That path is right for someone else's edit and far too slow for
+your own — waiting on it is what makes a screen feel like it lagged its own button.
+
+`refetch()` remains for the reads a write cannot know about: a poll, a value the user expects to
+change without writing anything, or a total you supplied yourself (below).
+
 `refetch` re-runs the query in the background while the current rows stay on screen (no
 flash to a spinner — `loading` stays false during revalidation). `usePaginatedQuery`'s
 `refetch` re-runs the current page, and the count when the hook owns it — a total you supplied
@@ -411,7 +425,13 @@ Why a full-form snapshot save is a bug, not a style choice — three independent
 3. **Snapshots clobber concurrent edits.** An update writes exactly the fields present in the
    payload; unsent fields keep their current value. A diff therefore coexists with a
    colleague's concurrent edit to a *different* field — a snapshot overwrites it with the
-   stale load-time value.
+   stale load-time value. The coexistence stops at field granularity: sending the full array
+   of a multi-value field is a snapshot *inside* that field, so two writers appending to it
+   each keep the array they read and the later one wins, both reporting success. When the
+   append is the system's rather than a person's — an upload settling, a workflow attaching a
+   generated document — name the ITEMS with `add_to` / `remove_from`
+   ([workflows](./workflows.md#writing-records)) and the write path resolves them against the
+   record as it stands.
 
 ```tsx
 // load: snapshot the editable fields from the row

package/docs/runtime.md

@@ -1,7 +1,7 @@
 # The app runtime
 
 How a custom-code app boots and talks to the platform: **`mount()`** (the entry
-point, including the design-time mock harness and automatic PostHog analytics),
+point, including the design-time mock harness),
 the **two transports** the SDK switches between (embedded postMessage bridge vs.
 standalone direct API — app code never branches), the raw **`rpc()`** escape
 hatch, and the browser capabilities the sandbox would otherwise block —
@@ -32,9 +32,6 @@ mount(<App />);
    visible in the iframe itself, even before any host telemetry is wired up.
    Banners are informational only; they are not removed automatically.
 4. **Renders the tree** with React 19's `createRoot`.
-5. **Boots analytics** fire-and-forget (see [Automatic analytics](#automatic-analytics-posthog)).
-   Never awaited — it cannot delay first paint, and any failure leaves the app
-   fully functional and untracked.
 
 ### The mock harness (`options.fixture` + `?__mock=1`)
 
@@ -239,14 +236,11 @@ semantics are documented:
 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, 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).
+`rpc("context", {})` resolves the viewer: `{ member_id, comments_enabled }`.
+`member_id` is the signed-in member when embedded, `null` standalone — read it
+through `useViewer()` rather than this op. **Limitation:** the context type is
+not exported from the package root, so type the result yourself via the `rpc<T>`
+generic.
 
 ## `openExternal()` — open a link in a new tab
 
@@ -359,106 +353,21 @@ await checkIn({ latitude: r.coords.latitude, longitude: r.coords.longitude });
   there is no workflow log to find. If field failures need diagnosing, surface
   the `reason` visibly in the UI.
 
-## Automatic analytics (PostHog)
+## Analytics
 
-`mount()` boots a PostHog instance per app — apps are a separate cross-origin
-bundle, invisible to the product's own analytics. It is entirely automatic:
-don't install `posthog-js` or call any analytics API from app code, and there is
-no hook for app-defined events. If a bespoke funnel matters, request the surface
-as a platform change.
+The SDK ships no analytics and no hook for app-defined events. Don't add
+`posthog-js` or another browser SDK to an app either: the app host serves every
+response under a `Content-Security-Policy` whose `connect-src` reaches only the
+Lotics API, so a third-party collector's requests are blocked and the only
+visible result is console noise.
 
-The SDK emits one event, `app_opened`, once PostHog finishes initializing.
-Everything an app *does* is already recorded by the platform — a comment, an
+Most of what an app does is already recorded platform-side — a comment, an
 upload, a workflow or agent run each leave a row, and a run's outcome, including
-a user's Stop (`cancel_requested_at`), lands in `app_agent_runs`.
-
-- Autocapture, pageviews, dead clicks, and session replay are all off, set at
-  init rather than relied on project-wide: the server-side setting fails open,
-  and an app screen renders the customer's own records.
-- `app_opened` carries the app identity as super-properties — `app_id`,
-  `workspace_id`, `organization_id`, ids only, since a name is the customer's
-  own words — and rolls up under the `organization` group. Embedded apps `identify` the signed-in member — app and
-  product events share one person; standalone visitors stay anonymous.
-- Uncaught exceptions are captured (PostHog error tracking) in addition to
-  `mount()`'s visible banner — the app's one error channel.
-- **Tracking is gated to the deployed app host** (`*.lotics.app`). `lotics app
-  dev` (localhost) and any `?__mock=1` load emit nothing. Best-effort
-  throughout: a failed init or a failed `context` resolution leaves the app
-  fully working and untracked.
-- **Limitation:** PostHog's default bot/user-agent filter applies — headless
-  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`.
+a user's Stop (`cancel_requested_at`), lands in `app_agent_runs`. App opens are
+counted at the serving edge. If a funnel needs something those cannot answer,
+request it as a platform change.
 
-```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: on a package installation (a published
-origin, or an install of someone's package) `lotics app codegen` emits a
-binding-form `.lotics/app_fields.ts` that 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). An app scaffolded before the starter set that target must
-  set it in `vite.config.ts` before shipping the binding form.
-- **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.** An app that is not a package installation has no
-  binding; codegen emits the baked variant for it instead. Shared code should
-  not call this directly — import from `.lotics/app_fields` and let codegen
-  pick the form.
-
-## For package contributors
+## For SDK contributors
 
 Everything below concerns changing `@lotics/app-sdk` itself (in the Lotics
 monorepo), not building apps with it.
@@ -518,7 +427,7 @@ is a transport that wasn't wired.
 - **Data + RPC only — zero UI.** Never re-export a `@lotics/ui` component; the
   SDK stays off the React-Native-Web dependency tree. Apps import `@lotics/ui`
   directly.
-- **Keep the dependency set minimal.** Runtime deps are `posthog-js` and `swr`;
+- **Keep the dependency set minimal.** Runtime deps are `ai` and `swr`;
   `react`/`react-dom` are peers. `react-router` is an **optional** peer
   pulled in only by the `@lotics/app-sdk/router` subpath export — the root entry
   must never import it. (`react-router` is the canonical package; the

package/docs/workflows.md

@@ -482,6 +482,14 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 | `add_to` / `remove_from` / `replace` | `{ fld_x: [items] }` | surgical edits on multi-value fields (files, multi select, multi member, record links) |
 | `field_edits` | `[{ field, op, value }]` | the same surgical ops with the field named by a **string expression** — the only way to target a field chosen at run time |
 
+`add_to` / `remove_from` are RELATIVE: the server resolves them against the record as it stands
+when the write lands, inside the lock it already takes. Two runs appending to one field at the
+same time therefore each keep their item — which reading the field and writing the whole array
+back through `set` does not, since both fold onto the array they read and the later write drops
+the earlier, both reporting success. Parallel runs are ordinary (a trigger firing twice, an agent
+emitting two calls in one step), so reach for the ops rather than a read-modify-write whenever
+the workflow is ADDING to a field rather than stating it.
+
 Inside `set` and `create_records.records`: `null` clears (persisted), `undefined` or an omitted
 key preserves. So passing a possibly-null read straight through is safe. Use
 `coalesce(x, fallback)` only when you want a real fallback, never to "strip" null.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.83.1",
+  "version": "0.86.0",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -27,7 +27,6 @@
   },
   "dependencies": {
     "ai": "^7.0.30",
-    "posthog-js": "^1.352.0",
     "swr": "^2.4.1"
   },
   "peerDependencies": {

package/dist/src/analytics.d.ts

@@ -1 +0,0 @@
-export declare function bootstrapAnalytics(): Promise<void>;

package/dist/src/analytics.js

@@ -1,113 +0,0 @@
-/**
- * PostHog analytics for custom-code apps.
- *
- * Apps are a separate cross-origin bundle at `<slug>.lotics.app`, invisible to
- * the product's PostHog — so `mount()` boots a PostHog instance per app.
- *
- * **Why explicit events, not autocapture:** DOM autocapture ships `$el_text` —
- * the visible text of whatever was clicked, i.e. the customer's own record
- * values — and Điều 3.2 of the service contract warrants that our telemetry
- * carries no record or document content. The flags below are what enforce
- * that; the project-level setting is NOT a backstop, since it is server-side
- * and fails open when the config fetch fails.
- *
- * **What earns an event:** who KNOWS the fact. An effect the platform performs
- * or persists is the platform's — a comment, an upload, a workflow or agent run
- * all leave rows, and a client copy would duplicate one AND keep arriving from
- * apps pinned to an old SDK long after the code is deleted. A FAILURE is not a
- * gesture either; it is system telemetry, and this bundle has no log sink to
- * carry it, so it is not an event here by default.
- *
- * That leaves exactly one: `app_opened`. Apps are a separate origin the
- * product's own analytics cannot see, and the app-host gate log records gate
- * DECISIONS rather than routine serves, so nothing else counts an app being
- * used. Everything a run does is already in `app_agent_runs` — including a
- * user's Stop, which stamps `cancel_requested_at`.
- *
- * Every event is tagged with app identity and rolls up under the existing
- * `organization` group; embedded apps `identify` the member the host passes
- * down so app + product events share one person. Exception capture is on (the
- * project opts in); session replay is off (on by default project-wide, but
- * apps — including anonymous public visitors — were never scoped for it).
- *
- * The key is the public, write-only project key (already shipped in every
- * browser), hardcoded here. Tracking is gated to the deployed app host
- * (`*.lotics.app`); `lotics app dev` runs on localhost and stays untracked.
- * Best-effort: any failure leaves the app fully functional and untracked.
- */
-import posthog from "posthog-js";
-import { rpc } from "./rpc.js";
-import { hasMockFlag } from "./mock.js";
-const POSTHOG_KEY = "phc_N1nyqSRdo9XMK3DODxrxX2Y9jG3dppybruOuMznbz62";
-const POSTHOG_HOST = "https://us.i.posthog.com";
-const APP_HOST_SUFFIX = ".lotics.app";
-function onDeployedAppHost() {
-    try {
-        return window.location.hostname.endsWith(APP_HOST_SUFFIX);
-    }
-    catch {
-        return false;
-    }
-}
-export async function bootstrapAnalytics() {
-    // Only the deployed app host tracks: a design-time/screenshot load
-    // (?__mock=1) and `lotics app dev` (localhost) emit nothing. This replaces
-    // the old "no key off-prod" gate now that the key is hardcoded.
-    if (hasMockFlag() || !onDeployedAppHost())
-        return;
-    let ctx;
-    try {
-        ctx = await rpc("context", {});
-    }
-    catch {
-        // Best-effort: a context-resolution failure must never break the app.
-        return;
-    }
-    posthog.init(POSTHOG_KEY, {
-        // Pin the modern posthog-js init contract (the product uses the same).
-        defaults: "2025-05-24",
-        api_host: POSTHOG_HOST,
-        // App analytics is explicit events — not DOM autocapture or pageviews.
-        // Set here rather than relied on project-wide: the server-side setting
-        // fails open, and an app screen renders the customer's own records.
-        autocapture: false,
-        mask_all_text: true,
-        capture_pageview: false,
-        capture_pageleave: false,
-        // Dead-click autocapture (enabled by the defaults preset) is a UX-research
-        // signal nobody consumes; explicit user actions + exception capture cover
-        // the app's monitoring needs.
-        capture_dead_clicks: false,
-        // Error tracking (the project opts in). mount() only renders a local
-        // banner, so this is the app's one exception channel.
-        capture_exceptions: true,
-        // Session replay is on by default project-wide; never on the app surface.
-        disable_session_recording: true,
-        // posthog-js keeps its default bot/user-agent filter, so headless/bot
-        // traffic is never tracked (real users are unaffected). One consequence:
-        // analytics can't be verified through headless Playwright — it's filtered.
-        //
-        // Tag + capture from `loaded` (once PostHog has initialized) — the robust
-        // point to register super-properties and emit the first event.
-        loaded: (ph) => {
-            // Ids only. A super-property rides every event and every `$exception`
-            // the session sends, and an app's NAME is the customer's own words —
-            // routinely a counterparty — which Điều 3.2 keeps out of telemetry. The
-            // id resolves to the name for anyone entitled to it.
-            ph.register({
-                app_id: ctx.app_id,
-                workspace_id: ctx.workspace_id,
-                organization_id: ctx.organization_id,
-            });
-            // Guarded: a bridged host that answered `context` before its auth member
-            // loaded sends an empty org — never group on an empty key.
-            if (ctx.organization_id)
-                ph.group("organization", ctx.organization_id);
-            // Embedded apps attach to the same person as the product; standalone
-            // visitors stay anonymous (member_id null).
-            if (ctx.member_id)
-                ph.identify(ctx.member_id);
-            ph.capture("app_opened");
-        },
-    });
-}

package/dist/src/config.d.ts

@@ -1,24 +0,0 @@
-import type { AppConfigValue } from "./rpc.js";
-/**
- * Read the installation's customization config — the first rung of the App
- * Packages customization ladder (see docs/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

@@ -1,33 +0,0 @@
-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/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 };
-}