@lotics/app-sdk 0.90.0 → 0.90.2

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`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, **the API address a standalone bundle reads out of its own page** (`<meta name="lotics-api-base">`, declared by whatever serves the app — no address is compiled into the SDK, so one bundle runs on any instance and a page without it refuses rather than guessing), `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`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
 
 ## Non-negotiables (each detailed in its doc)
 
@@ -47,6 +47,10 @@ signature; open the file.**
 - **Narrow `__source_record_id` / `__source_table_id` before use** — a grouped query emits neither,
   so an unchecked read hands a workflow (or an AI record ref) `undefined`.
   → [data_fetching](./docs/data_fetching.md)
+- **A standalone app takes its API address from the page it was served in**, never from a
+  constant — the serving host declares `<meta name="lotics-api-base">`, and a bundle that finds
+  none refuses instead of addressing someone else's instance. Nothing for an app to configure;
+  build against 0.90.2 or later. → [runtime](./docs/runtime.md)
 - **Errors fail loud** — no swallowed catches, no silent fallbacks.
 
 ## Keeping this reference current

package/dist/src/hooks.d.ts

@@ -383,10 +383,10 @@ export interface FieldOptionsOptions {
  * ```tsx
  * const { fields } = useFieldOptions("records");
  * // populate + color a picker:
- * <Picker options={fields.status?.options ?? []}
- *   renderOptionContent={(o) => <OptionBadge value={o} />} />
+ * <Select variant="native" options={fields.status?.options ?? []}
+ *   renderOptionContent={(o) => <Status option={o} />} />
  * // color a stored value:
- * <OptionBadge value={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
+ * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
  * ```
  */
 export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
@@ -448,7 +448,7 @@ export declare function usePaginatedQuery<K extends string>(alias: K, ...args: Q
  *
  * ```tsx
  * const { total } = useCount("orders", { q }, { filter: unpaidFilter });
- * return <Badge label={total == null ? "…" : `${total}`} />;
+ * return <Status label={total == null ? "…" : `${total}`} />;
  * ```
  */
 export declare function useCount<K extends string>(alias: K, ...args: QueryArgs<K, CountOptions<ColumnKeyOf<K>>>): CountState;
@@ -586,7 +586,7 @@ export declare function useAttachments(): AttachmentsState;
  * });
  * ```
  *
- * No-ops with no embedding host (standalone `<slug>.lotics.app` — there is no
+ * No-ops with no embedding host (standalone on the app's own origin — there is no
  * chat surface to inform) and in mock mode. Since 0.52.
  */
 export declare function useAiContext(slot: string, context: AiContextValue | null): void;
@@ -619,7 +619,7 @@ export interface MembersOptions {
  *
  * ```tsx
  * const { members } = useMembers({ group: "grp_..." });
- * // <Picker options={members.map((m) => ({
+ * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />
  * ```

package/dist/src/hooks.js

@@ -498,7 +498,7 @@ function serializeAiContext(context) {
  * });
  * ```
  *
- * No-ops with no embedding host (standalone `<slug>.lotics.app` — there is no
+ * No-ops with no embedding host (standalone on the app's own origin — there is no
  * chat surface to inform) and in mock mode. Since 0.52.
  */
 export function useAiContext(slot, context) {
@@ -536,7 +536,7 @@ export function useAiContext(slot, context) {
  *
  * ```tsx
  * const { members } = useMembers({ group: "grp_..." });
- * // <Picker options={members.map((m) => ({
+ * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />
  * ```

package/dist/src/index.d.ts

@@ -4,15 +4,14 @@
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
  * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` components, so it ships without pulling in packages/ui's
- * React Native Web dependency tree. That is a packaging choice, NOT a
- * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
- * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
- * full setup — `@lotics/ui` + react-native + react-native-web, the
- * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
- * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
- * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
+ * `@lotics/ui` component, so an app's dependency on the kit is its own and one
+ * version answers for it. That is a packaging choice, NOT a limitation: apps
+ * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
+ * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
+ * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
+ * the whole `resolve` block. Build screens by composing kit components (Card,
+ * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
+ * & components".
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";

package/dist/src/index.js

@@ -4,15 +4,14 @@
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
  * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` components, so it ships without pulling in packages/ui's
- * React Native Web dependency tree. That is a packaging choice, NOT a
- * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
- * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
- * full setup — `@lotics/ui` + react-native + react-native-web, the
- * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
- * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
- * composing `@lotics/ui` components (Card, KpiCard, charts, Table, …),
- * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
+ * `@lotics/ui` component, so an app's dependency on the kit is its own and one
+ * version answers for it. That is a packaging choice, NOT a limitation: apps
+ * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
+ * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
+ * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
+ * the whole `resolve` block. Build screens by composing kit components (Card,
+ * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
+ * & components".
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";

package/dist/src/router.js

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * addressable URLs. The app owns its OWN url (a plain browser history) in both
  * modes; the host url only ever *mirrors* the screen, it never drives the router:
  *
- *  - **Standalone** (`<slug>.lotics.app`): the page's own browser history — real
+  *  - **Standalone** (the app's own origin): the page's own browser history — real
  *    path URLs, native browser back/forward, deep-link/refresh via the app host's
  *    SPA fallback.
  *  - **Embedded** (inside the Lotics host): the app drives the IFRAME's own url

package/dist/src/rpc.d.ts

@@ -11,10 +11,11 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *    ops over postMessage and the host makes the API call. Used by internal
  *    apps — the member's credentials must never reach the app.
  *
- *  - **Standalone** — the app is served on its own at `<slug>.lotics.app`
- *    with no host. It calls the public `/v1/apps/{id}/*` endpoints directly;
- *    those are anonymous-accessible for a publicly-shared app. The app holds
- *    no credentials, so there is nothing to protect.
+ *  - **Standalone** — the app is served on its own origin, with no host. It
+ *    calls the public `/v1/apps/{id}/*` endpoints directly, at the API address
+ *    the serving host injected into the page (`API_BASE_META`); those are
+ *    anonymous-accessible for a publicly-shared app. The app holds no
+ *    credentials, so there is nothing to protect.
  *
  * Wire protocol (bridged — must match `app_iframe_host.tsx`):
  *   app  → host: { id, op, payload }
@@ -84,7 +85,7 @@ export interface AppContext {
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its
- * own `<slug>.lotics.app`). `rpc()`, `useUrlState`, and `AppRouter` use this to
+ * own origin). `rpc()`, `useUrlState`, and `AppRouter` use this to
  * pick the transport / behaviour; an app rarely needs it directly.
  */
 export declare function isEmbedded(): boolean;
@@ -106,7 +107,7 @@ export declare function subscribeUrlParams(cb: (params: UrlParams) => void): ()
 /**
  * Push a fire-and-forget notification to the embedding host — no id, no reply.
  * Only the embedded host can receive it (it owns the chat surface), so this
- * no-ops standalone (`<slug>.lotics.app` has no host to inform) and never
+ * no-ops standalone (the app's own origin has no host to inform) and never
  * throws. Distinct from `rpc()`: this is one-way, app → host.
  */
 export declare function postHostNotification(message: HostNotification): void;

package/dist/src/rpc.js

@@ -19,7 +19,7 @@ function getHostOrigin() {
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its
- * own `<slug>.lotics.app`). `rpc()`, `useUrlState`, and `AppRouter` use this to
+ * own origin). `rpc()`, `useUrlState`, and `AppRouter` use this to
  * pick the transport / behaviour; an app rarely needs it directly.
  */
 export function isEmbedded() {
@@ -81,7 +81,7 @@ export function subscribeUrlParams(cb) {
 /**
  * Push a fire-and-forget notification to the embedding host — no id, no reply.
  * Only the embedded host can receive it (it owns the chat surface), so this
- * no-ops standalone (`<slug>.lotics.app` has no host to inform) and never
+ * no-ops standalone (the app's own origin has no host to inform) and never
  * throws. Distinct from `rpc()`: this is one-way, app → host.
  */
 export function postHostNotification(message) {
@@ -307,7 +307,7 @@ export function rpcAgentRunContinue(payload, onText) {
         const continueToken = runTokens.get(payload.run_id);
         if (continueToken)
             headers[APP_AGENT_RUN_TOKEN_HEADER] = continueToken;
-        const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
+        const res = await fetch(`${apiBase()}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
             method: "POST",
             headers,
             body: JSON.stringify({ tool_call_id: payload.tool_call_id, output: payload.output }),
@@ -344,7 +344,7 @@ function agentRunStandalone(payload, onText, onRunId) {
         const headers = { "content-type": "application/json" };
         if (sessionToken)
             headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
-        const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agents/${encodeURIComponent(payload.alias)}/runs`, {
+        const res = await fetch(`${apiBase()}/v1/apps/${app_id}/agents/${encodeURIComponent(payload.alias)}/runs`, {
             method: "POST",
             headers,
             body: JSON.stringify({ session_id: payload.session_id, input: payload.input }),
@@ -382,9 +382,33 @@ function agentRunStandalone(payload, onText, onRunId) {
     return { done, abort: () => controller.abort() };
 }
 // ── Standalone transport ────────────────────────────────────────────────────
-// Standalone apps run only at `<slug>.lotics.app` (production); dev apps are
-// always bridged by the `lotics app dev` wrapper.
-const API_BASE = "https://api.lotics.ai";
+/**
+ * Meta the host serving a standalone bundle injects into `index.html`, naming
+ * the API the app calls.
+ *
+ * It is the serving host's to state, not the SDK's to assume: the same bundle
+ * is served by whoever runs the instance, and an app that carried a compiled-in
+ * API address would call somebody else's server. A bridged app never reads it —
+ * there the host's own origin arrives on `?lotics_host=`.
+ */
+const API_BASE_META = "lotics-api-base";
+let apiBaseCache = null;
+function apiBase() {
+    if (apiBaseCache !== null)
+        return apiBaseCache;
+    const content = document
+        .querySelector(`meta[name="${API_BASE_META}"]`)
+        ?.getAttribute("content")
+        ?.trim();
+    if (!content) {
+        // No default: guessing would send this app's data to whatever address the
+        // guess named. Say what is missing and who puts it there.
+        throw new Error(`This app has no API address. A standalone app reads it from <meta name="${API_BASE_META}"> ` +
+            "in the page the app host serves, and this page carries none.");
+    }
+    apiBaseCache = content.replace(/\/+$/, "");
+    return apiBaseCache;
+}
 const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
 /**
  * Boot-time resolution result. Promise is shared so concurrent first calls
@@ -592,7 +616,7 @@ async function apiCall(method, path, body, opts) {
     }, API_TIMEOUT_MS);
     let res;
     try {
-        res = await fetch(`${API_BASE}${path}`, {
+        res = await fetch(`${apiBase()}${path}`, {
             method,
             headers,
             body: body ? JSON.stringify(body) : undefined,
@@ -708,7 +732,7 @@ async function standaloneMembers(p) {
 }
 /**
  * Open an external URL in a new tab, scheme-validated. In standalone mode the
- * app is a normal top-level page (`<slug>.lotics.app`), so `window.open` is not
+ * app is a normal top-level page on its own origin, so `window.open` is not
  * sandbox-blocked — open directly. (Bridged apps route this op to the host,
  * which opens it in the un-sandboxed parent frame; see `app_iframe_host`.)
  * The scheme is re-validated wherever the open actually happens — never trust a

package/dist/src/select.d.ts

@@ -18,7 +18,7 @@ export interface ResolvedOption {
      * Named palette color token (e.g. `"blue"`, `"emerald"`). Populated by
      * `useFieldOptions` (which reads the field config); absent on options read
      * back from a query CELL via `readSelect` — a cell carries only key + label.
-     * Pass the resolved option straight to `@lotics/ui`'s `OptionBadge`, which
+     * Pass the resolved option straight to `@lotics/ui`'s `Status`, which
      * degrades a missing/unknown token to a neutral badge.
      */
     color?: string;

package/docs/ai.md

@@ -450,7 +450,7 @@ caps above).
 
 When the ambient chat agent's turn ends and it mutated records, the host pushes every mounted query hook to re-read, so the screen the member is looking at reflects the agent's change without a manual refresh. That companion behavior is automatic — you write no code for it — and is documented with the query caching contract in [data_fetching](./data_fetching.md#caching-loading-states-and-errors).
 
-**No-ops** with no embedding host (standalone `<slug>.lotics.app` — there's no chat surface to inform) and in mock mode.
+**No-ops** with no embedding host (standalone on the app's own origin — there's no chat surface to inform) and in mock mode.
 
 ---
 

package/docs/data_fetching.md

@@ -349,7 +349,7 @@ you supply the total yourself.
 
 ## Standalone (public) transport
 
-An app served standalone at `<slug>.lotics.app` (a public share with no Lotics host — see
+An app served standalone on its own origin (a public share with no Lotics host — see
 [runtime](./runtime.md)) reaches the query endpoint through a thinner transport that forwards only
 `alias`, `params`, `limit`, and `offset`. It **silently drops** `sort`, `filter`, `count`, and the
 keyset `cursor`. Design a public app around this:
@@ -439,7 +439,7 @@ a partial as its period start.
 
 **`readSelect`.** A query **cell** carries `key` + `label` only — `color` comes from
 `useFieldOptions`, not the cell. An option deleted after the cell was written surfaces as
-`label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `OptionBadge`
+`label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `Status`
 — see [./members_and_options.md](./members_and_options.md).
 
 **`readMembers`.** `name` is `null` when the id doesn't resolve in the app's org (e.g. a removed
@@ -477,7 +477,7 @@ A query cell carries only the options a record actually holds (key + label, no c
 **complete** option list of a select column — every option including those in no current row, with
 colors — use **`useFieldOptions`**, and prefer it over deriving options from loaded rows
 (row-derived sets are incomplete until every page loads and carry no colors). Its full contract
-(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`OptionBadge`,
+(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`Status`,
 `MemberChip`, `MemberSelect`), and the member roster (`useMembers`) live in
 [./members_and_options.md](./members_and_options.md).
 
@@ -510,7 +510,7 @@ pieces. Compose these — don't hand-roll search:
 
 - **`Combobox`** (`@lotics/ui/combobox`) owns the interaction — debounced `onSearchChange`, a
   popover listbox with rich rows (`renderOptionContent`), keyboard navigation, `recentOptions`,
-  `allowCustom`. (For a known small list with no search box, `Picker`.)
+  `allowCustom`. (For a known small list with no search box, `Select`.)
 - **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the
   maintained search document: **diacritics- and case-insensitive**, trigram-indexed, and AND-ed
   with the template's `filter` (search within a scope). The full `search` contract is in
@@ -540,7 +540,7 @@ const [typed, setTyped] = useState("");          // the input's own value, every
 const [term, setTerm] = useState("");            // what the server is asked, once typing settles
 const commit = useDebouncedCallback(setTerm, 250);
 
-<SearchInput value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
+<TextInput type="search" value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
 
 const { rows, loading } = useQuery(
   "searchCustomers",
@@ -560,8 +560,8 @@ relationship exists.
 When the user doesn't know the term — "show me everything, let me narrow it" — build a modal table
 they can browse (numbered pages), search, sort, and filter:
 
-- **The screen is app-owned**, composed from `@lotics/ui`: a `Dialog` over `SearchInput` + filter
-  pills (`ColumnFilter`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
+- **The screen is app-owned**, composed from `@lotics/ui`: a `Dialog` over a search `TextInput` + filter
+  pills (`FilterChip column=`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
   UI-free), so it lives in the app (e.g. a `record_picker.tsx`) — reuse it for any table by passing
   a different `alias` + column config.
 - **`usePaginatedQuery`** drives it: the page of rows, the `total` for "Page 1 of N" (the built-in

package/docs/files.md

@@ -19,7 +19,7 @@ discipline in [data fetching](./data_fetching.md).
 | Attach to a record | a declared workflow with a `{ type: "file" }` input | the workflow writes the id(s) into a `files` field — the **only** write path |
 | Read back from records | `useQuery` + `readFiles(cell)` | `AppFile[]` — presigned `url`/`thumbnail_url` (24 h) + `size`/`created_at` |
 | Receive a generated document | `useWorkflow` → `WorkflowResult.files` | presigned files auto-extracted from the run |
-| Show it | `@lotics/ui` `FileThumbnail` / `FileGrid` / `FileGalleryModal` | map to `DisplayFile` (see below) |
+| Show it | `@lotics/ui` `FileThumbnail` / `FileThumbnailGrid` / `FileGalleryDialog` | map to `DisplayFile` (see below) |
 | Save browser-built bytes | `downloadFile(filename, data, mimeType?)` | a client-side download (see [runtime](./runtime.md)) |
 
 An uploaded file is **inert until a workflow attaches it** — it has an id and serving URLs, but
@@ -175,10 +175,10 @@ Each `AttachedFile` is `{ id, filename, mime_type, preview_url, status, file_id?
 
 Wiring to `@lotics/ui`: in a `Composer`, trigger picking from `actionsButton` (via `pickFiles`),
 render the attachment pills with `FileThumbnail` as above, and gate `sendDisabled` on `uploading`.
-For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a `FileGrid`
-`FileUpload` entry — ready → `{ status: "complete", id: file_id, file: <DisplayFile> }`, else
-`{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }` — and `FileGrid` renders
-the uploading/error/retry tiles itself.
+For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a
+`FileThumbnailGrid` `FileUpload` entry — ready → `{ status: "complete", id: file_id, file:
+<DisplayFile> }`, else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`
+— and the grid renders the uploading/error/retry tiles itself.
 
 ## File cells in query results — `readFiles` and `AppFile`
 
@@ -325,11 +325,10 @@ not viewing). Component contracts live in the `@lotics/ui` reference
 For an `AttachedFile` still uploading, map `preview_url` → `url` (there is no server URL yet).
 The app owns this data→UI adapter — the SDK deliberately never imports `@lotics/ui`.
 
-- **`FileThumbnail`** — one square tile; `uploading` overlays a spinner, images fall back from
-  `thumbnailUrl` to `url` on error.
-- **`FileGrid`** — a grid of completed files plus a live `uploads` queue (it renders
-  uploading/error/retry tiles itself).
-- **`FileGalleryModal`** — the full-screen viewer (filename · counter · actions · close, with
+- **`FileThumbnail`** — one square tile; `uploading` takes the queue status and overlays the
+  scrim, the spinner or the retry, images fall back from `previewUrl` to `thumbnailUrl` to `url`.
+- **`FileThumbnailGrid`** — a grid of stored files plus a live `uploads` queue, in one grid.
+- **`FileGalleryDialog`** — the full-screen viewer (filename · counter · actions · close, with
   prev/next + ESC), delegating per-file to **`FilePreview`**, which dispatches by MIME. Wire
   `onFilePress` → a `number | null` `activeIndex`.
 - PDF renders **inline to a canvas** (a nested PDF browsing context is blocked in the sandboxed

package/docs/members_and_options.md

@@ -4,7 +4,7 @@ How an app renders and picks **people** and **select-field options**, plus the *
 surface. Covers the two cell readers (`readSelect`, `readMembers`), the two catalog hooks
 (`useFieldOptions`, `useMembers`), the viewer identity hook (`useViewer`), comments
 (`useComments`, `useCommentCounts`), and the `@lotics/ui` components they feed. Read this before
-building an assign picker, a colored status badge, a per-viewer ("my records") screen, or a
+building an assign picker, a colored `Status` mark, a per-viewer ("my records") screen, or a
 comment thread. Query mechanics live in [queries](./queries.md); the authority model in
 [security](./security.md).
 
@@ -61,7 +61,7 @@ const { fields } = useFieldOptions("orders");   // same alias you query
 // are { value, label }, so map the option key to `value`):
 <Select
   options={(fields.status?.options ?? []).map((o) => ({ value: o.key, label: o.label }))}
-  renderOptionContent={(o) => <OptionBadge value={fields.status?.byKey(o.value)} />}
+  renderOptionContent={(o) => <Status option={fields.status?.byKey(o.value)} />}
   value={status} onValueChange={setStatus}
 />
 ```
@@ -78,7 +78,7 @@ name**, not the field key. Each `FieldOptions`:
 | `byKey(key)` | Resolve one option by key; `undefined` for an unknown key (option removed after the cell was written) |
 
 - `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to
-  `@lotics/ui`'s `OptionBadge`; a missing/unrecognized token degrades to a neutral badge.
+  `@lotics/ui`'s `Status`; a missing/unrecognized token degrades to a neutral badge.
 - **A column the server can't map to a single source select field is simply absent** from
   `fields` — a UNION output whose arms disagree on the source field, or a computed column. Read
   defensively: `fields.status?.options ?? []`.
@@ -99,7 +99,7 @@ until an edit drawer opens). State: `{ fields, loading, isValidating, error, ref
 
 ```tsx
 const opt = readSelect(row.status)[0];
-<OptionBadge value={opt ? (fields.status?.byKey(opt.key) ?? opt) : null} />
+<Status option={opt ? (fields.status?.byKey(opt.key) ?? opt) : null} />
 ```
 
 `byKey` hit → the configured color. `byKey` miss (option removed post-write) → fall back to the
@@ -128,12 +128,12 @@ projected `select_member` cell to `Array<{ id, name, email?, image?, groups?, ro
   "Admin" beside a name as rank. If the question your screen asks is "who is this person in the
   company", the answer is `groups`.
 - **`joined` is an ISO timestamp of when the membership began.** Render it at whatever precision
-  your question needs — `@lotics/ui`'s `MemberProfileCard` shows month and year, because "is this
+  your question needs — `@lotics/ui`'s `MemberPeek` shows month and year, because "is this
   the new person?" does not want a day. Absent on a public response, and on an id that did not
   resolve: there is no membership to have begun.
 - **`archived: true` marks someone who has LEFT** — omitted otherwise, never `false`. It is the one
   field that is NOT gated (a departed colleague reading as a current assignee is wrong on a public
-  app too). Feed it to `inactive` on `MemberChip` / `MemberProfileCard`.
+  app too). Feed it to `inactive` on `MemberChip` / `MemberPeek`.
 - **An id that no longer resolves** (removed member, id outside the org) comes back with
   `name: null` — an explicit missing state, never an empty string. Render a placeholder.
 - Only ids already present in the projected rows are resolved — a member cell never exposes the
@@ -256,7 +256,7 @@ client-side up front, and re-checked server-side.
 - **The author is always the real signed-in member** — correct attribution, enforced server-side.
   **Warning:** under "View as", comments still author as the real member (the admin), not the
   view-as target — unlike `useViewer` and `is_current_member` scoping, which follow the target.
-- **Edit and delete are author-only**, checked server-side against the viewer. `CommentList`'s
+- **Edit and delete are author-only**, checked server-side against the viewer. `CommentThread`'s
   `currentMemberId` prop drives the matching affordance client-side.
 
 ### Reading & writing
@@ -277,13 +277,13 @@ renders the panel. State: `{ comments, loading, error, available, createComment,
 updateComment, deleteComment, refetch }`.
 
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
-  `CommentList`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
+  `CommentThread`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
   table_id, member_id, content, files, workspace_id, created_at, updated_at }`. Attachments
   (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
   the server re-reads every attachment from storage by that id, so nothing else you hold about a
   file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
   but the server does not populate them today — render attachments by name and type (what
-  `CommentList`'s default file row does), never by counting on a fetchable URL.
+  `CommentThread`'s default file row does), never by counting on a fetchable URL.
 - `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
   `useFileUpload` / `useAttachments` (see [files](./files.md)). A comment must have content or at
   least one file (empty input is a client no-op; the server enforces the same rule). Content max
@@ -296,7 +296,7 @@ updateComment, deleteComment, refetch }`.
   on it.
 - **Limitation:** a comment carries `member_id` only — resolving the author's display name needs a
   member source: the `useMembers` roster (requires the member-access declaration above) or member
-  cells in your own data. An unresolvable id should render a fallback (`CommentList` has an
+  cells in your own data. An unresolvable id should render a fallback (`CommentThread` has an
   `unknownMember` label for exactly this).
 - **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
   the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
@@ -320,10 +320,10 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 
 | Value | Component | Feed it |
 | --- | --- | --- |
-| A select value (stored or picker option) | `OptionBadge` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
+| A select value (stored or picker option) | `Status` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
 | A person, inline | `MemberChip` | `name` / `image` from a roster or a cell — both carry it; no image → initials |
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
-| A comment thread | `CommentList` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
+| A comment thread | `CommentThread` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
 
 The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter in each row above.
 

package/docs/mutations.md

@@ -70,7 +70,7 @@ Every call resolves to a `WorkflowResult<TData>` (type exported from the package
 ### The failure model: check `status`, never just try/catch
 
 **Every failure resolves — the promise (almost) never rejects.** All three transports
-(embedded product host, standalone `<slug>.lotics.app`, and the `lotics app dev` harness)
+(embedded product host, standalone on the app's own origin, and the `lotics app dev` harness)
 convert every failure into a resolved `{ status: "error", message }`:
 
 | Failure | What resolves |

package/docs/navigation_and_state.md

@@ -26,7 +26,7 @@ into a query's *server* params (see [named-query params](./queries.md) and the
 
 The embedded-vs-standalone distinction below is the runtime's: embedded means
 the app runs in an iframe inside the Lotics host, standalone means it runs on
-its own `<slug>.lotics.app` page (see [runtime](./runtime.md)). Both mechanisms
+its own app-host page (see [runtime](./runtime.md)). Both mechanisms
 expose the same API in both modes with no per-mode code (the few behavioral
 differences — embedded first-paint hydration, cross-screen persistence — are
 flagged below); mode is detected automatically (from the `lotics_host` param
@@ -74,7 +74,7 @@ routes, and splats all work. Inside the tree, use react-router normally:
 The app owns its **own** URL in both modes — the host URL only ever *mirrors*
 the screen, it never drives the router:
 
-- **Standalone** (`<slug>.lotics.app`): a normal browser router. Screens are
+- **Standalone** (the app's own origin): a normal browser router. Screens are
   real path URLs, browser Back/Forward are native, and deep-links/refresh work
   because the app host serves the entry HTML for any path the build didn't
   emit (SPA fallback).

package/docs/queries.md

@@ -836,7 +836,7 @@ Build `filter` from UI column-filters with `columnFilterToConditions` (`@lotics/
 `useFieldOptions` for a select filter's option set.
 
 **Warning (transport gaps):** the embedded product host and the `lotics app dev` forwarder pass
-`sort`/`filter`/`count` through. The **standalone public transport** (`<slug>.lotics.app`)
+`sort`/`filter`/`count` through. The **standalone public transport** (the app's own origin)
 forwards only `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter` are silently ignored
 there and a `count` never resolves ([data_fetching](./data_fetching.md) → Standalone transport).
 A standalone app must bake ordering/scoping into the template (or params) rather than rely on

package/docs/runtime.md

@@ -108,9 +108,10 @@ helper works identically in both. `isEmbedded(): boolean` is exported
 
 | | **Embedded (bridged)** | **Standalone (direct)** |
 |---|---|---|
-| Where | Iframe inside the Lotics product, or the `lotics app dev` wrapper page | The app's own top-level page at `<slug>.lotics.app` |
+| Where | Iframe inside the Lotics product, or the `lotics app dev` wrapper page | The app's own top-level page, on its own origin |
 | Who holds credentials | The **host** — the member's session never reaches the app | Nobody — the visitor is anonymous (an optional app password gates access, not identity) |
-| How ops travel | `postMessage` to the parent frame; the host makes the API call with its session | `fetch` to the public `https://api.lotics.ai/v1/apps/{id}/*` endpoints |
+| How ops travel | `postMessage` to the parent frame; the host makes the API call with its session | `fetch` to the public `/v1/apps/{id}/*` endpoints, at the API address the serving host declared in the page |
+| Which API | The host's, implicitly — it makes the call | `<meta name="lotics-api-base" content="…">` in the served document, read on the first call. **No address is compiled in**: one bundle runs on any Lotics, and a page that declares none makes the SDK refuse rather than address an instance nobody named. Every serving host injects it (the app host and `lotics app dev`), so there is nothing for an app to set |
 | Viewer identity | The signed-in member (`useViewer`, comments, agent runs available) | `member_id` is `null`; members-only surfaces reject |
 
 ### Embedded: the postMessage bridge
@@ -137,7 +138,7 @@ haven't verified exists in the host (see
 ops to the API; the bare Vite origin has no host param, so the SDK falls into
 standalone mode, tries to resolve an app from the hostname, and every data call
 fails. Dev apps are always bridged; standalone mode exists only on the deployed
-`<slug>.lotics.app` host.
+app host.
 
 ### Standalone: direct public API
 
@@ -145,7 +146,7 @@ On first data call the SDK resolves the app's identity from its own subdomain
 (one shared `GET /v1/apps/by-subdomain/{slug}` fetch — concurrent first calls
 coalesce; a transient failure isn't cached, the next call retries). If the app
 is password-protected, the visitor never reaches the app at all until they
-clear the gate: `<slug>.lotics.app` is served by the app-host Worker, which
+clear the gate: the app's own origin is served by the app host, which
 withholds every byte of the bundle and serves a password page instead. On
 success it sets `lotics_app_session` on the app's origin; the SDK reads that
 cookie and forwards it as `X-Lotics-App-Session` on data calls. The SDK owns no
@@ -266,7 +267,7 @@ page (standalone). Opens in a new tab with `noopener,noreferrer`.
 - Typical use: opening a workflow-generated file's `url` from
   `WorkflowResult.files[]` (see [mutations](./mutations.md)).
 - **Not a preview mechanism.** To *view* a file inline, use `@lotics/ui`'s
-  `FilePreview`/`FileGalleryModal` (see [files](./files.md)); `openExternal` is
+  `FilePreview`/`FileGalleryDialog` (`@lotics/ui` ≥ 48 — see [files](./files.md)); `openExternal` is
   "leave the app".
 
 ## `openApp()` — the cross-app hop
@@ -445,14 +446,11 @@ is a transport that wasn't wired.
   no dynamic `import()`, no Node built-ins. Don't touch `window` at module top
   level — resolve lazily (test environments import modules before `jsdom` is
   ready).
-- **Two bundlers in the family.** Apps build with Vite; the Lotics product
-  frontend builds with Metro (React Native Web). The SDK itself is never
-  Metro-bundled — the host frontend is forbidden from importing
-  `@lotics/app-sdk` (enforced by a dependency-direction test) — but sibling
-  packages apps share with the product (`@lotics/ui`, `@lotics/xlsx`,
-  `@lotics/docx`) build under both. When a shared package must diverge per
-  target, use platform files (`x.web.ts` / `x.ts`) plus conditional package
-  `exports` — never a runtime `require` or dynamic import.
+- **One module per entry.** A package apps share with the Lotics product
+  (`@lotics/ui`, `@lotics/xlsx`, `@lotics/docx`) ships ONE module per entry: no
+  platform twins, no per-target `exports` condition. The SDK itself is never
+  bundled by the product at all — the host frontend is forbidden from importing
+  `@lotics/app-sdk`, enforced by a dependency-direction test.
 - **Self-contained on npm.** The SDK cannot import workspace-private or
   host-only packages (`@lotics/shared`, `@lotics/ui-internal`, the frontend's
   `@/` alias) or any React Native / Expo module — also test-enforced. A helper

package/docs/security.md

@@ -89,7 +89,7 @@ returns `true` when the **triggering member** belongs to any of the listed group
 
 ## Public apps: anonymous reach and its bounds
 
-A publicly-shared app (`<slug>.lotics.app`, or its public link) is reachable by **anyone** — the public share grants `app:use` to anonymous visitors and to authenticated members of any other org alike. What anonymous visitors can and cannot do:
+A publicly-shared app (its own origin, or its public link) is reachable by **anyone** — the public share grants `app:use` to anonymous visitors and to authenticated members of any other org alike. What anonymous visitors can and cannot do:
 
 | Surface | Anonymous access |
 |---|---|

package/package.json

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