@lotics/app-sdk 0.84.0 → 0.87.0

package/AGENTS.md

@@ -24,7 +24,7 @@ signature; open the file.**
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything), `openExternal`/`downloadFile`, geofencing, 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)
 

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

@@ -56,7 +56,7 @@ export interface NewRecordApi<P> {
  * const { id, save } = useNewRecord({
  *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
  *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
- *   onCreated: refetch,
+ *   onCreated: (id) => select(id),   // it exists now — the list re-reads itself
  * });
  * <InlineText onBlur={(name) => save({ name })} />
  * ```
@@ -64,6 +64,11 @@ export interface NewRecordApi<P> {
 export declare function useNewRecord<P>(opts: {
     create: (id: string, patch: P) => Promise<unknown>;
     update: (id: string, patch: P) => Promise<unknown>;
-    /** Runs once, after the record first exists. Pass a list `refetch` to reveal it. */
+    /**
+     * Runs once, after the record first exists, with its id. NOT for refetching a
+     * list — the `create` workflow's own success already re-read it. This is for
+     * what only the id can drive: routing to the record, selecting it, dropping the
+     * surface's "new" state.
+     */
     onCreated?: (id: string) => void;
 }): NewRecordApi<P>;

package/dist/src/new_record.js

@@ -56,7 +56,7 @@ export function newRecordId() {
  * const { id, save } = useNewRecord({
  *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
  *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
- *   onCreated: refetch,
+ *   onCreated: (id) => select(id),   // it exists now — the list re-reads itself
  * });
  * <InlineText onBlur={(name) => save({ name })} />
  * ```

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
@@ -200,11 +176,13 @@ export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
 /** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
 export declare const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message — so a raw HTML body never becomes the message.
- * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ * The error message for a non-ok response. A JSON error the API AUTHORED surfaces
+ * verbatim — a 4xx carrying a `message`, or a 5xx that also carries `code`, the
+ * discriminator every error the API emits is built with. A non-JSON body (a
+ * gateway HTML page), a 5xx from something that is not us, or a body without a
+ * `message` falls back to a body-free, status-derived message — so a raw HTML
+ * body never becomes the message. `parsed` is the JSON.parse of the body, or
+ * `null` if it wasn't JSON.
  */
 export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /**
@@ -217,26 +195,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

@@ -457,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)
@@ -519,19 +519,30 @@ function gatewayErrorMessage(status) {
     return "The service returned an unexpected response. Please try again.";
 }
 /**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message — so a raw HTML body never becomes the message.
- * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ * The error message for a non-ok response. A JSON error the API AUTHORED surfaces
+ * verbatim — a 4xx carrying a `message`, or a 5xx that also carries `code`, the
+ * discriminator every error the API emits is built with. A non-JSON body (a
+ * gateway HTML page), a 5xx from something that is not us, or a body without a
+ * `message` falls back to a body-free, status-derived message — so a raw HTML
+ * body never becomes the message. `parsed` is the JSON.parse of the body, or
+ * `null` if it wasn't JSON.
  */
 export function transportErrorMessage(status, parsed) {
     const jsonMessage = parsed && typeof parsed.message === "string"
         ? parsed.message
         : null;
-    return parsed === null || status >= 500 || jsonMessage === null
-        ? gatewayErrorMessage(status)
-        : jsonMessage;
+    if (jsonMessage === null)
+        return gatewayErrorMessage(status);
+    // Below 500 the body is ours. At 500 and above it is ours only if it carries
+    // `code` — the discriminator every error the API emits is built with. Status
+    // alone was the wrong test: it threw away the 503 our OWN backpressure gate
+    // authors and replaced it with a different English sentence, so no wording we
+    // choose for a 5xx could ever reach an app member (GAP-300). A gateway's HTML
+    // does not parse at all, and a proxy's JSON does not carry `code`, so both
+    // still get the body-free message.
+    const authored = typeof parsed.code === "string" &&
+        parsed.code.length > 0;
+    return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
 }
 /**
  * The error a stream that never started should throw.
@@ -653,8 +664,6 @@ function rpcStandalone(op, payload) {
             return standaloneMembers(payload);
         case "context":
             return standaloneContext();
-        case "binding":
-            return standaloneBinding();
         case "openExternal":
             return standaloneOpenExternal(payload);
         case "askAi":
@@ -685,46 +694,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)}` : "";
@@ -764,15 +733,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/use_optimistic.d.ts

@@ -3,9 +3,14 @@ export interface OptimisticApi<T> {
     items: T[];
     /**
      * Optimistically merge `next` into the item keyed `id`, then run `persist`.
-     * On resolve → `onSettled?.()` (pass your query's `refetch`); the patch is
-     * kept (it already matches the refetched value, so no flicker). On reject →
-     * the patch is reverted.
+     * On resolve → `onSettled?.()`; the patch is kept (it should already match
+     * what the write persisted, so the re-read lands underneath it without a
+     * flicker). On reject → the patch is reverted.
+     *
+     * `onSettled` is NOT for refetching the query this patch came from — a
+     * successful `useWorkflow` inside `persist` re-reads every mounted query on
+     * its own. Use it for what the write cannot know about: a total the app
+     * computed itself, an indicator to clear.
      */
     patch: (id: string, next: Partial<T>, persist: () => Promise<unknown>, opts?: {
         onSettled?: () => void;

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/ai.md

@@ -28,7 +28,7 @@ A declaration carries:
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
 | `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it. **Every field defaults to `required: true`**, exactly as `outputs` does — the two extend the same base — so an input the caller may legitimately omit needs `"required": false`, or the run is rejected before the agent sees it |
-| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
+| `outputs` | Optional typed output schema — the declaration vocabulary, including the two ways a `select` names its option set, is [mutations](./mutations.md#structured-results-return-data). Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
 
 **Structured vs free-text is the load-bearing split.** A structured agent's result arrives in `run.output` (the server strictly validates the submitted result against the declared schema — see the `output` typing section for the exact guarantee); a free-text agent's answer is the transcript's prose (`run.text`) and its `output` stays `undefined` — never a stray string, so a consumer reading `output.<field>` can't crash on a free-text answer.
 
@@ -145,7 +145,9 @@ The server validates the agent's submitted result strictly (unknown keys rejecte
 
 - a field declared `required: false` may be absent;
 - a `json`-typed output field is passthrough — anything goes inside it;
-- `date` / `datetime` / `email` outputs are validated only as strings, not as well-formed values;
+- a `date` / `datetime` / `email` output is checked for well-formedness (`yyyy-MM-dd`, an ISO
+  timestamp, an address shape) but not for being the *right* value — a parseable date can still
+  be the wrong date;
 - every **value** was authored by the model — a schema-valid string can still be semantically wrong;
 - one live-stream corner: the hook adopts `output` from the submit call's **arguments as they stream**, before the server-side validation runs. Normally the loud rejection makes the agent retry and the last (valid) submit overwrites it — but a run whose *final* submit was rejected ends the live stream with that invalid attempt still in `output` (the persisted run settles as an error). The review surface below is the backstop.
 

package/docs/data_fetching.md

@@ -178,6 +178,15 @@ server validates system conditions by `type` and never reads `field_key` on them
 | `query execution failed` | The query failed at the database. Deliberately generic — database internals are never sent to the client. | The app author diagnoses from the platform's server logs; the app surfaces the message. |
 | A specific validation message | e.g. an un-projected `field_key` in runtime `sort`/`filter`, invalid params, an unknown alias. An unknown column names every column the query DOES project, so the valid set is in the message. | Fix the call site — these are contract violations, not transient. |
 
+**Which message you get is decided by the ENVELOPE, not the status** (SDK 0.85.0 — before it, the
+status alone decided). A failure whose JSON body carries a `code` is one the API authored, so its
+`message` is what `error` holds — including a 5xx, which is why the shed sentence in the table above
+reaches the app at all rather than being replaced by a generic one. Everything else — a gateway's
+HTML page, a proxy's JSON with no `code`, a body with no `message` — is plumbing, and `error` holds
+a fixed sentence derived from the status instead, so a raw HTML body can never become your error
+copy. Practically: for a 5xx you are now showing a sentence the PLATFORM wrote, so treat `error` as
+copy to display, never as a string to branch on.
+
 ## Pagination — two models
 
 Reads paginate two different ways, and the difference is load-bearing:

package/docs/mutations.md

@@ -138,9 +138,23 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
   refreshes that alias's generated types in the same command, so `result.data` is typed
   immediately — no hand-copy of the echoed schema, no second `lotics app codegen`. An
   **explicitly declared** `outputs` is authoritative and never overwritten. Declare an explicit
-  `outputs` (same recursive vocabulary as inputs: scalars plus nested `object`/`array`, no
-  member/file/date_range) only to narrow beyond what's inferred; a shape the checker can't pin
-  down degrades to untyped `json`, never to a wrong schema.
+  `outputs` only to narrow beyond what's inferred; a shape the checker can't pin down degrades
+  to untyped `json`, never to a wrong schema.
+- **The output vocabulary is the input one minus the caller-only types, and `select` behaves
+  differently.** Scalars (`text`/`number`/`boolean`/`date`/`datetime`/`email`), `record_link`
+  (`table_id`, `multi?`), `select`, `json`, and nested `object` (`fields`) / `array` (`items`).
+  No `member`, `file`, or `date_range` — those describe what a caller *sends*. `select` names
+  its option set the same two ways as an input (**exactly one** of inline
+  `options: [{label, value}]` or `field: "fld_…"`, and a `field` that doesn't exist or names a
+  non-select field is rejected at bind time by the same gate, worded `select output references
+  field …`), but enforcement is **stricter than on the input side**: an output's option set is
+  enforced as *membership*, not merely key format. Inline `options` are enforced against the
+  frozen set; a `field` form is resolved to the field's **current** options at run and enforced
+  against those. So a producer — a workflow's `return({ data })`, an app agent's
+  `submit_result` — is handed the legal keys and cannot settle a label where a key belongs.
+  Prefer `field` for any select backed by a real field (the generated type tracks it, no
+  redeploy); use inline `options` for a fixed enum the app owns or a select you plan to
+  **package** (a `field` form carries a concrete field id and can't ride a package contract).
 - **Validated at run.** On a success return, the returned `data` is validated against the
   schema at the app boundary — a mismatch resolves as `status: "error"` with a field-level
   message, so a declared output is a real contract. An *error* return's `data` passes through
@@ -347,7 +361,8 @@ flash to a spinner — `loading` stays false during revalidation). `usePaginated
 yourself is yours to refresh, so a write that changes the row COUNT must also refresh whatever
 you read it from, or the page moves while "of N" does not. Focus revalidation
 (`revalidateOnFocus`, default on) eventually self-corrects stale data, but never rely on it
-in place of an explicit refetch after a write the user is watching for.
+where the staleness is one of those three — the user is looking at the number now, not the
+next time they come back to the tab.
 
 ### A read must not overtake an in-flight write
 
@@ -506,9 +521,10 @@ Contract points:
   a whole. Include every changed field in the same call; don't submit per-field requests.
 - **Nothing changes immediately.** The tool returns
   `{ approval_request_id, status: "pending" }`; the record's values update only when an
-  approver (the table's configured approvers, else org admins) accepts. A `refetch()` right
-  after submitting shows the *old* values — render a "pending approval" state from the
-  result, don't poll for the new values.
+  approver (the table's configured approvers, else org admins) accepts. The submission
+  succeeds, so the automatic re-read fires and returns the *old* values — that is correct,
+  and it is why the pending state must come from the RESULT rather than from the row. Render
+  it from `data.request_id`; don't poll the record for values no one has approved yet.
 - **Requires a member actor.** The request is attributed to the triggering member; an
   anonymous caller through a public app is rejected. Gate the affordance on a signed-in
   viewer.
@@ -523,7 +539,8 @@ const save = async () => {
     if (res.status === "success") showPending();
   } else {
     const res = await updateOrder({ record_id, ...changes });
-    if (res.status === "success") orders.refetch();
+    if (res.status === "error") { showError(res.message); return; }
+    // orders re-reads itself — a successful write already said so.
   }
 };
 ```
@@ -543,9 +560,18 @@ patch(id, next, persist, opts?);
   item's stable key. `items` is `base` with pending patches merged per key (`{ ...item,
   ...patch }`); repeated patches on the same key merge.
 - `patch(id, next, persist, { onSettled })` applies `next` immediately, then runs the
-  `persist` thunk. On **resolve**, the patch is *kept* (it should match the refetched value —
-  no flicker) and `onSettled` runs — pass the owning query's `refetch`. On **reject**, the
-  patch is *reverted*.
+  `persist` thunk. On **resolve**, the patch is *kept* and `onSettled` runs. On **reject**,
+  the patch is *reverted*.
+- **`onSettled` is not where you refetch the query the patch came from.** The `persist` thunk
+  calls `useWorkflow`, and a successful write re-reads every mounted query by itself — so the
+  re-read is already in flight before `onSettled` fires, and passing `refetch` here buys a
+  second execution of the same query. Keep it for what the write cannot know about: a total
+  you computed yourself, a "saving…" indicator to clear, an analytics call.
+- **A kept patch stays merged over `base` for the life of the view.** It is never cleared on
+  success — the design assumes it equals what the server stored, so the re-read lands
+  underneath it with no flicker. Patch the value you are SENDING, not a display form of it: if
+  the server normalizes (rounds a time, trims a string, resolves a link's label), the
+  optimistic value masks the stored one permanently and nothing reports it.
 
 **Warning — the persist thunk must throw on `status: "error"`.** `useWorkflow` resolves on
 failure (the failure model above), and a resolved promise means "kept" to `useOptimistic` —
@@ -555,6 +581,7 @@ workflow failed. Convert the status into a rejection:
 ```tsx
 const q = useQuery("events");
 const reschedule = useWorkflow("rescheduleEvent");
+const mapped = useMemo(() => q.rows.map(toCalendarEvent), [q.rows]);
 const { items, patch } = useOptimistic(mapped, (e) => e.id);
 
 const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
@@ -566,14 +593,13 @@ const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
       const r = await reschedule({ record_id: ev.recordId, new_date: toISODate(newStart) });
       if (r.status === "error") throw new Error(r.message ?? "Reschedule failed");
     },
-    { onSettled: q.refetch },
   );
 ```
 
 This is the full read → mutate → reconcile loop: `useQuery` reads, `row.*` coerces,
-`useWorkflow` mutates, `useOptimistic` bridges the gap until `refetch` converges. Declare
-one workflow per (table, field) you mutate — typed and narrow, never a generic
-`setField(any_field)` that hands the client write access to every field
+`useWorkflow` mutates, `useOptimistic` covers the round-trip until the write's own re-read
+converges. Declare one workflow per (table, field) you mutate — typed and narrow, never a
+generic `setField(any_field)` that hands the client write access to every field
 ([security](./security.md)).
 
 ## Editing a record that does not exist yet: `useNewRecord`
@@ -590,7 +616,7 @@ id is known from the first render and the create stops being an event the UI has
 const { id, save } = useNewRecord({
   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
-  onCreated: list.refetch,
+  onCreated: (id) => select(id),
 });
 
 <InlineText onBlur={(name) => save({ name })} />
@@ -605,6 +631,9 @@ const { id, save } = useNewRecord({
 - **A failed create does not latch.** The next `save` retries the create, rather than updating a
   row that was never written while the UI looks like it saved.
 - `id` and `save` are stable across renders, so `save` can be bound directly to an `onBlur`.
+- **`onCreated` is not for refetching the list.** The `create` workflow succeeded, so every
+  mounted query re-read itself already. It runs once, with the id, for what only the id can
+  drive — routing to the record, selecting it, dropping the surface's "new" state.
 
 Your `create` workflow must pass the id through to `create_records` as `ids: [record_id]`.
 Creation is creation: an id that already exists is a conflict, never an overwrite — so the

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

@@ -425,6 +425,15 @@ full menu by category, so a miss is one informed retry.
 | **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange` |
 | **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])` |
 
+**Emptiness on a record cell.** `isNull` is the strict check — true only for `null`/`undefined`.
+A cleared cell does not always reach a workflow that way: the platform stores a cleared date or
+text as `""` and a cleared select, link or files cell as `[]`, so `isNull(record.data.ngay_doi_soat)`
+is **false** on a date the user emptied. Reach for `isEmpty` for the "has the user filled this in?"
+question — it covers `null`, `undefined`, `""` and `[]`. (`isNull` stays narrow on purpose: it is
+declared as a type predicate and every `?.` in a body lowers to it, so widening it would narrow
+`""` out of a branch that still receives it.) A FORMULA field is the one surface where the two
+agree: its evaluation context normalizes every unset cell to `null` before the expression runs.
+
 A few signatures worth knowing: `requireFirst(arr, message?)` asserts non-empty and returns `T`
 rather than `T | undefined` — pair it with a `validate` on `size(x) == 0` instead of wrapping
 every read in `if (x)`. `at(arr, -1)` counts from the end. `range(end)` / `range(start, end)`.
@@ -707,7 +716,8 @@ rejects, or read a path that is null on real data. The rehearsal for that is `dr
 `app_workflow_inputs`. It walks the real step tree with the production expression evaluator and
 hands back `planned_calls` (every tool call in order, with its fully-resolved input),
 `return_value`, `validation_failures`, `evaluation_errors`, and `tool_input_errors` — inputs the
-target tool would reject, which can only surface once the values are computed. **Write tools are
+target tool would reject, which can only surface once the values are computed. Loops run for real,
+every iteration, so a fold or a per-row fan-out is rehearsed at its true size. **Write tools are
 recorded, never dispatched**, and nothing is persisted.
 
 **Add `live_reads: true` whenever the body READS.** By default the read-only tools
@@ -721,6 +731,22 @@ which supply the real record as the payload AND turn live reads on; an app workf
 record — its payload is its inputs — so it asks for the reads directly.) Do this before the first
 live run of anything that writes.
 
+**`return_value` is what the CALLER receives**, not a summary of it: `{ status, message }` always,
+plus `data` when the body returns one and `field_errors` when it returns those — the same map a
+form reads. A `validate` step that fails produces the same shape the live run does: every failing
+check's message joined with `"; "`, and one `field_errors` entry per failing check that names a
+`field_key`.
+
+**A rehearsal can stop early, and it says so in `evaluation_errors`.** Four bounds apply — 1 000
+iterations of a `while` / `do_while` / `c_for`, 10 000 steps, 50 live reads, and 20 seconds — and
+tripping any of them appends an entry naming the bound and ending "the plan below is incomplete",
+then stops. So read `evaluation_errors` before reading `planned_calls`: an entry there may be a
+truncated plan rather than a bug in your body. A `foreach` is deliberately NOT capped at 1 000 —
+its length is known before the first iteration, so the rehearsal walks every item and instead
+refuses, up front, exactly the lists a live run refuses (over 10 000 items). The 50-live-read bound
+is the one `live_reads: true` makes reachable: a loop body that reads issues one real query per
+iteration.
+
 ## A worked body
 
 An app action that creates an order after checking for a duplicate, then returns the new id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.84.0",
+  "version": "0.87.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 };
-}