@lotics/app-sdk 0.90.1 → 0.90.3

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

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

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) {

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/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:

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

@@ -464,7 +464,7 @@ derived surfaces share one implementation.
 | number | `number` | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` | same set | Full numeric aggregate set (§8). |
 | date / datetime | `date` / `datetime` (datetime when the field's format includes time) | `on`, `before`, `after`, `on_or_before`, `on_or_after`, `between`, `time_of_day`, `is_empty`, `is_not_empty` — values are `DateTimePoint`s (below) | same set | Day-level filters on datetime values expand to the full-day window. Sortable; bucketable in `group.by` (§8); `earliest`/`latest`/`min`/`max`/`date_range` aggregate. |
 | boolean | `boolean` | `equals` (value `true`/`false`; `false` matches NULL/missing) | same | `checked`/`unchecked`/`percent_*` aggregate (`unchecked` counts false **or** empty). |
-| select (single & multi) | `select` | `has_any_of`, `has_none_of`, `has_all_of`, `is_empty`, `is_not_empty` — values are **option keys** (`opt_*`), never labels | same | Cells are arrays even for single-selects. Sorting a select column in a query orders by raw JSON, **not** configured option order. `unnest` fans option keys. |
+| select (single & multi) | `select` | `has_any_of`, `has_none_of`, `has_all_of`, `is_empty`, `is_not_empty` — values are **option keys** (`opt_*`), never labels | the **runtime** `filter` (§9) also takes option **names**, resolving each to its key — an unknown one is refused rather than matching nothing, and the value stays an array either way; a select column the query DERIVES instead of projecting from a field carries no option set, so addressing one there is refused | Cells are arrays even for single-selects. Sorting a select column in a query orders by raw JSON, **not** configured option order. `unnest` fans option keys. |
 | select_member | `select_member` | select ops + `is_current_member`, `is_not_current_member` (field-scoped, no value) | same — `is_current_member` **works at the runtime layer** too | `unnest` fans member ids. Anonymous public request: current-member binds the app owner (§1). |
 | select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
 | files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
@@ -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

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/docs/workflows.md

@@ -16,9 +16,8 @@ engine, no `eval`, no sandbox. Four consequences shape everything below:
 
 - **Only the listed forms exist.** Anything outside them fails the save with a precise error
   naming the rule and, where one exists, the substitute. A save never partially succeeds.
-- **A successful save may still return `warnings[]`** — advisory lint that does not block
-  (a possible infinite loop, a link path more than three hops deep, a button action with no
-  `validate` guard). Read them; they are the failures that only show up in production.
+- **A successful save may still return `warnings[]`** — advisory lint that does not block.
+  Read them; they are the failures that only show up in production.
 - **One canonical form per concept.** Several JS spellings are accepted and *lowered* to one
   stored form. The stored tree renders back to source on `lotics app pull`, so a pulled body
   shows the canonical spelling, not the sugar you typed (see *Round-tripping* below).
@@ -803,8 +802,8 @@ What only the **server** can decide, so `check` stays green and `set` may still
 - **`switch` case validation** against a single-select's options, and the multi-select rejection;
 - the **literal `formatDate` format probe**;
 - **wait inside a loop**, and the `before_*` restrictions on waits and `agent` steps;
-- the **lint** — possible self-retrigger, deep link chains, a button action with no `validate`
-  guard (all warnings).
+- the **lint** — deep link chains, an input the alias declares that this body never reads, and
+  an unguarded `set` in a body that generates a document (all warnings).
 
 There is no separate verify endpoint: the loop is `set` → read the returned diagnostics → fix →
 `set`. Diagnostics arrive **batched** — independent errors across the whole body come back in one

package/package.json

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