@lotics/app-sdk 0.91.0 → 0.93.0

package/AGENTS.md

@@ -16,11 +16,11 @@ signature; open the file.**
 |---|---|
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate at 10,000 — `useQuery` says so with `truncated`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys typed against the query's own projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*` — `row.num` answers `null` for an EMPTY cell, so none is distinguishable from zero — `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, and `readCreatedAt`/`readUpdatedAt` for the record timestamps every row-level result carries), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate at 10,000 — `useQuery` says so with `truncated`), the ROW type (`RowOf` — the alias's projected columns and nothing else, values `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys AND the `useFieldOptions` map keyed against that same projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*` — `row.num` answers `null` for an EMPTY cell, so none is distinguishable from zero — `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, and `readCreatedAt`/`readUpdatedAt` for the record timestamps every row-level result carries), caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
-| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions` (keyed by the alias's OWN columns, every key optional), `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
@@ -44,6 +44,9 @@ signature; open the file.**
   column, including files. → [queries](./docs/queries.md)
 - **Never hand-roll the serialization contract** — decode cells with the typed readers.
   → [data_fetching](./docs/data_fetching.md)
+- **Read only the columns the alias projects** — its option sets too, from the alias that CARRIES
+  the column. Anything else is `undefined`, which every reader draws as a blank cell, so the row
+  type and the option map are bounded to the projection. → [data_fetching](./docs/data_fetching.md)
 - **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)

package/dist/src/hooks.d.ts

@@ -7,12 +7,14 @@ import type { ResolvedOption } from "./select.js";
 export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 /**
- * One row of a query result: the projected columns, plus the platform's
- * ADDRESSING columns.
+ * One row of a query result whose COLUMNS are not known: a dynamic alias, or a
+ * query whose AST names no projection (a bare `from_table`). Where codegen could
+ * read them, `RowOf` states them instead and there is no index signature — see
+ * that type, which is where the reason lives.
  *
- * The projected values stay `unknown` — which columns a row carries is fixed by
- * the query's manifest declaration, not by this type, so the cell readers
- * (`row.text`, `readLinks`, `readFiles`, …) are what narrow them.
+ * The projected values stay `unknown` either way: a column's TYPE is the field's
+ * and the manifest does not carry it, so the cell readers (`row.text`,
+ * `readLinks`, `readFiles`, …) are what narrow them.
  *
  * The `__source_*` columns are different in kind: the compiler injects them at
  * every layer, and they are the only way to address the RECORD a row came from
@@ -41,6 +43,27 @@ export interface QueryRow {
     /** The table that record lives in. Absent on a grouped/aggregated row. */
     __source_table_id?: string;
 }
+/**
+ * The row type of alias `K`: the columns that alias PROJECTS, plus the two
+ * addressing columns, and nothing else.
+ *
+ * `.lotics/app_queries.d.ts` already names every projected column
+ * (`AppQueryColumns`), read off the query's AST by the same rule the server
+ * names them by. A read is bounded to that union for the same reason a
+ * `filter`/`sort` key is — except the failure is quieter. A key the query does
+ * not carry is refused by the server; a COLUMN it does not carry comes back
+ * `undefined`, which every cell reader answers with its empty value, so a
+ * misspelt column, a renamed field and a projection moved to another alias all
+ * render as a blank cell in a member's browser with no error anywhere. Removing
+ * the index signature is what turns that silence into a `tsc` error, which is
+ * what `lotics app check` refuses to ship.
+ *
+ * An alias with no `AppQueryColumns` entry keeps `QueryRow` — a union that could
+ * be wrong is worse than none, the rule `ColumnKeyOf` already follows.
+ */
+export type RowOf<K extends string> = K extends keyof AppQueryColumns ? {
+    [C in AppQueryColumns[K] & string]: unknown;
+} & Pick<QueryRow, "__source_record_id" | "__source_table_id"> : QueryRow;
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -344,9 +367,10 @@ type QueryArgs<K extends string, O> = K extends keyof AppQueries ? AppQueries[K]
  *
  * Per-app CLI codegen writes `.lotics/app_queries.d.ts` augmenting `AppQueries`
  * with the declared alias → param-type map, so an undeclared alias is a
- * compile-time error and params are typed per the manifest.
+ * compile-time error and params are typed per the manifest. The same file names
+ * the alias's projected columns, which is what bounds a ROW read — see `RowOf`.
  */
-export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<QueryRow>;
+export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<RowOf<K>>;
 /** The resolved option set of one select column, plus an index for value
  *  rendering. The companion to a query row, for select fields. */
 export interface FieldOptions {
@@ -366,14 +390,20 @@ export interface FieldOptions {
      */
     byKey: (key: string) => ResolvedOption | undefined;
 }
-/** Return value of `useFieldOptions`. */
-export interface FieldOptionsState {
+/** Return value of `useFieldOptions`. `C` is the column key's type — the alias's
+ *  projected outputs, see `ColumnKeyOf`. */
+export interface FieldOptionsState<C extends string = string> {
     /**
-     * Resolved option sets keyed by the query's OUTPUT column name. A select
-     * column the server couldn't resolve to a source field (a UNION output, a
-     * computed column) is simply absent — read defensively (`fields.status?`).
+     * Resolved option sets keyed by the query's OUTPUT column name — the alias's
+     * own columns, so a key belonging to another query is a `tsc` error rather
+     * than a `[]` picker nobody can open.
+     *
+     * EVERY key is optional, and that is the shape rather than a hedge: a select
+     * column the server could not resolve to a source field (a UNION output whose
+     * arms disagree, a computed column) is genuinely absent, and a non-select
+     * column never had options. Read through it (`fields.status?.options ?? []`).
      */
-    fields: Record<string, FieldOptions>;
+    fields: Partial<Record<C, FieldOptions>>;
     loading: boolean;
     isValidating: boolean;
     error: string | null;
@@ -395,8 +425,11 @@ export interface FieldOptionsOptions {
  * added/removed option flows through with no app change.
  *
  * Addressed by the same alias you query: the option sets resolve from the named
- * query's output columns, scoped exactly like running it. A column the server
- * can't map to a source select field (UNION output, computed column) is absent.
+ * query's output columns, scoped exactly like running it, and `fields` is keyed
+ * by that same union — the alias that CARRIES the column is the one to ask, and
+ * asking another is a compile error instead of an empty picker. A column the
+ * server can't map to a source select field (UNION output, computed column) is
+ * absent, so every key is optional.
  *
  * ```tsx
  * const { fields } = useFieldOptions("records");
@@ -407,7 +440,7 @@ export interface FieldOptionsOptions {
  * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
  * ```
  */
-export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
+export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState<ColumnKeyOf<K>>;
 export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
 /**
  * Like `useQuery` but append/load-more: the first render loads one page and
@@ -418,7 +451,7 @@ export declare function useFieldOptions(alias: string, opts?: FieldOptionsOption
  * const { rows, loadMore, hasMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
  * ```
  */
-export declare function useInfiniteQuery<K extends string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): InfiniteQueryState<QueryRow>;
+export declare function useInfiniteQuery<K extends string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): InfiniteQueryState<RowOf<K>>;
 /**
  * Page-model query with a total — the data hook behind a numbered, jumpable
  * table (pairs with `@lotics/ui/pagination`). It owns the page
@@ -433,7 +466,7 @@ export declare function useInfiniteQuery<K extends string>(alias: K, ...args: Qu
  *   usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
  * ```
  */
-export declare function usePaginatedQuery<K extends string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<QueryRow>;
+export declare function usePaginatedQuery<K extends string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<RowOf<K>>;
 /**
  * HOW MANY rows a query matches — one number, no rows fetched.
  *
@@ -617,9 +650,11 @@ interface MembersState {
 /** Options for `useMembers`. */
 export interface MembersOptions {
     /**
-     * Restrict to one member group (a group ID). The group must be declared on a
-     * `member` workflow input's `group` — listing an undeclared group errors. Omit
-     * to list the whole org roster.
+     * Restrict to one member group, as `GRP.<group>` from `.lotics/app_fields.ts`
+     * (a pasted `grp_…` id is refused by `lotics app check` — it resolves to
+     * nothing in a copy of the app). The group must be declared on a `member`
+     * workflow input's `group` — listing an undeclared group errors. Omit to list
+     * the whole org roster.
      */
     group?: string;
 }
@@ -636,7 +671,7 @@ export interface MembersOptions {
  * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers({ group: "grp_..." });
+ * const { members } = useMembers({ group: GRP.sale });
  * // <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

@@ -557,7 +557,7 @@ export function useAiContext(slot, context) {
  * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers({ group: "grp_..." });
+ * const { members } = useMembers({ group: GRP.sale });
  * // <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

@@ -16,7 +16,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export type { QueryRow, RowOf, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/dist/src/router.d.ts

@@ -1,4 +1,17 @@
 import { type RouteObject } from "react-router";
-export declare function AppRouter({ routes }: {
+/**
+ * The not-found screen's words. The SDK ships no locale, so an app whose reader
+ * does not read English passes its own — from `@lotics/ui`'s locale where the app
+ * uses the kit, from its own strings otherwise.
+ */
+export interface NotFoundWords {
+    /** Names the address that has no screen. Takes the path so the words may put
+     *  it anywhere the language needs it. */
+    message: (path: string) => string;
+    /** The label of the link back to the first screen. */
+    firstScreen: string;
+}
+export declare function AppRouter({ routes, notFound }: {
     routes: RouteObject[];
+    notFound?: NotFoundWords;
 }): import("react").JSX.Element;

package/dist/src/router.js

@@ -35,9 +35,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *       { path: "/item/:id", element: <Detail /> },
  *     ]} />;
  *   }
+ *
+ * An address none of the routes claim renders the SDK's not-found screen rather
+ * than nothing — see {@link NotFoundScreen} and {@link withNotFound}. Its words
+ * are the `notFound` prop ({@link NotFoundWords}), because an app's reader reads
+ * the app's language and the SDK ships no locale.
  */
 import { useEffect } from "react";
-import { BrowserRouter, useLocation, useRoutes, } from "react-router";
+import { BrowserRouter, Link, useLocation, useRoutes, } from "react-router";
 import { isEmbedded, setUrlParams } from "./rpc.js";
 /** Host query key carrying the app's current screen, so it's shareable and the
  *  host can restore it on refresh. */
@@ -70,10 +75,70 @@ function HostScreenMirror() {
 function RoutedRoutes({ routes }) {
     return useRoutes(routes);
 }
-export function AppRouter({ routes }) {
+/*
+ * Shaped like the kit's `RegionState` — a centred message and one destination —
+ * and written in its tokens with literal fallbacks, so it takes the app's theme
+ * where `@lotics/ui/styles.css` is loaded and stays legible where it is not. It
+ * cannot BE `RegionState`: the SDK ships no kit component.
+ */
+const NOT_FOUND_ROOT = {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "var(--lotics-space-8, 8px)",
+    paddingBlock: "var(--lotics-space-48, 48px)",
+    paddingInline: "var(--lotics-space-16, 16px)",
+    textAlign: "center",
+    fontFamily: "var(--font-sans, system-ui, sans-serif)",
+};
+const NOT_FOUND_MESSAGE = {
+    margin: 0,
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-ink-muted, #71717a)",
+};
+const NOT_FOUND_LINK = {
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-accent, #2563eb)",
+};
+const NOT_FOUND_ENGLISH = {
+    message: (path) => `No screen at ${path}`,
+    firstScreen: "Go to the first screen",
+};
+/**
+ * What an app shows at an address none of its routes claim. Without it
+ * `useRoutes` matches nothing and the page renders EMPTY — no message and no
+ * console error — so a stale link or a typo reads as a crash.
+ */
+function NotFoundScreen({ home, words }) {
+    const { pathname } = useLocation();
+    return (_jsxs("div", { style: NOT_FOUND_ROOT, children: [
+            _jsx("p", { style: NOT_FOUND_MESSAGE, children: words.message(pathname) }), _jsx(Link, { to: home, style: NOT_FOUND_LINK, children: words.firstScreen })
+        ] }));
+}
+/**
+ * The catch-all, appended at EVERY level of the tree: a route with `children`
+ * is a layout, and a catch-all among those children is what keeps that layout's
+ * shell on screen instead of swapping the whole page for the message. An app
+ * that declares its own `*` still wins — react-router ranks equal matches by
+ * declaration order and ours is appended last.
+ */
+function withNotFound(routes, element) {
+    return [
+        ...routes.map((route) => route.children === undefined
+            ? route
+            : { ...route, children: withNotFound(route.children, element) }),
+        { path: "*", element },
+    ];
+}
+/** The screen the not-found sends the reader back to — the first one declared. */
+function firstScreenPath(routes) {
+    const first = routes.find((route) => route.path !== undefined && route.path !== "*");
+    return first?.path ?? "/";
+}
+export function AppRouter({ routes, notFound = NOT_FOUND_ENGLISH, }) {
     // `isEmbedded()` reads the `?lotics_host=` the host puts on the iframe src, so
     // it's known synchronously at first render.
     const embedded = isEmbedded();
-    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: routes })
-        ] }));
+    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: withNotFound(routes, _jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })) })] }));
 }

package/dist/src/row.js

@@ -87,7 +87,15 @@ function datetime(v) {
         return null;
     return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1, m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
 }
-/** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
+/**
+ * One `{ id, display }` object → ResolvedLink, or null if absent/malformed.
+ *
+ * A MISSING `display` IS NOT A LINK. Other cells carry `{ id }` without one — a
+ * member is the everyday case — and answering `display: ""` for them made every
+ * assignee read as a blank-named link wherever a reader tried links first. A
+ * link the server resolved always states its display, even as the empty string,
+ * so requiring the KEY costs a real link nothing.
+ */
 function asLink(v) {
     if (!v || typeof v !== "object")
         return null;
@@ -95,7 +103,7 @@ function asLink(v) {
     if (typeof id !== "string" || !id)
         return null;
     const display = v.display;
-    return { id, display: typeof display === "string" ? display : "" };
+    return typeof display === "string" ? { id, display } : null;
 }
 /**
  * select_record_link → the FIRST linked record as `{ id, display }` (or null).

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`). `lotics app deploy` ships code and queries only — it never binds agents. The `lotics.agents` map in `package.json` is a **read-only reflection** written by `lotics app pull`; hand-editing it does nothing. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the only verb that creates a binding, so no deploy binds an alias the app does not already have. A deploy does push an alias it has: the prose in `src/agents/<alias>.md` and the authored `inputs`/`outputs` in `package.json#lotics.agents.<alias>` go through `set_app_agent` whenever either differs from the live row, before the bundle ships. Every other key of that map is a reflection `lotics app pull` refreshes and no verb sends, so replaying a stale snapshot cannot revert a grant bound elsewhere. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
 
 A declaration carries:
 

package/docs/data_fetching.md

@@ -116,6 +116,11 @@ sort for a typed alias names its keys `ColumnKeyOf<"alias">` — `QueryFilter<Co
 `QuerySortKey<…>`; `QueryFilterCondition` and `QueryFilterGroup` take the same parameter — so the
 check reaches the helper that derives the key, not only the hook call that sends it.
 
+**The option map is keyed the same way.** `useFieldOptions(alias).fields` is keyed by that alias's
+projected columns too — ask the alias that CARRIES the column, because a picker fed from a sibling
+query's map is otherwise a control that renders empty with nothing reporting it. Every key is
+optional: [./members_and_options.md](./members_and_options.md).
+
 `@lotics/ui`'s `columnFilterToConditions` carries the same parameter (`FilterableColumn<C>` →
 `FilterConditionNode<C>`), so a per-column filter UI built over a typed alias composes without a
 cast.
@@ -411,10 +416,17 @@ workflows), `__created_at` / `__updated_at` (record timestamps), and per-project
 metadata. A grouped query collapses rows and emits none of these. Details:
 [./queries.md](./queries.md).
 
-A row is typed `QueryRow`: projected columns are `unknown` (the manifest declares them, so the
-readers below are what narrow them), while `__source_record_id` / `__source_table_id` are typed
-`string | undefined` — reachable without a cast, but only after narrowing, because "a grouped query
-emits none of these" is a fact the type states rather than one you have to remember.
+A row is typed from the alias's own projection. Codegen names the columns each query carries
+(`AppQueryColumns` in `.lotics/app_queries.d.ts`) and a row read is bounded to them, so a misspelt
+column, a renamed field and a projection moved to a sibling alias are one `tsc` error rather than a
+blank cell — the server answers an unprojected column with `undefined`, and every reader below
+answers `undefined` with its empty value, so nothing else reports it. The values stay `unknown` (a
+column's TYPE is the field's, which the manifest does not carry, so the readers are the narrowing),
+while `__source_record_id` / `__source_table_id` are typed `string | undefined` — reachable without
+a cast, but only after narrowing, because "a grouped query emits none of these" is a fact the type
+states rather than one you have to remember. Write the row type down as `RowOf<"alias">`; an alias
+whose columns cannot be read off its AST keeps the open `QueryRow`, where any column compiles and
+the server's answer is the only check — the rule the filter keys follow too.
 
 ### The readers
 
@@ -473,7 +485,10 @@ never carry avatar images — the avatar lives on the `useMembers` roster
 
 **`readLinks` / `row.link`.** `display` is the linked record's primary-field text — render it;
 use `id` to correlate, filter (link `has_any_of`), or fetch detail. `row.link` reads the first
-entry only — on a multi-link field use `readLinks`.
+entry only — on a multi-link field use `readLinks`. An entry carrying an `id` and **no
+`display` key** is not a link and is skipped: a member cell has that shape, so reading one as a
+link would otherwise render every assignee under a blank name. Read a member cell with
+`readMembers`.
 
 **`readFiles`.** Each entry's `url` (and `thumbnail_url` for images) is **presigned with a 24-hour
 TTL** — it renders directly in an `<Image>`/preview and works from the sandboxed iframe and for

package/docs/members_and_options.md

@@ -68,8 +68,11 @@ const { fields } = useFieldOptions("orders");   // same alias you query
 
 ### What comes back
 
-`fields` is a `Record<outputColumnName, FieldOptions>` — keyed by the query's **output column
-name**, not the field key. Each `FieldOptions`:
+`fields` is keyed by the query's **output column name**, not the field key — and by *that alias's*
+columns: `Partial<Record<ColumnKeyOf<"alias">, FieldOptions>>`. A key the alias does not project is
+a compile error, so a picker fed from a sibling query's option map fails at your desk instead of
+rendering with no options; and every key is optional, so the read is through `?.` and never a bare
+`.options`. Each `FieldOptions`:
 
 | Property | Meaning |
 | --- | --- |
@@ -80,8 +83,8 @@ name**, not the field key. Each `FieldOptions`:
 - `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to
   `@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 ?? []`.
+  `fields` — a UNION output whose arms disagree on the source field, or a computed column. That is
+  why the type makes every key optional: `fields.status?.options ?? []`.
 - Addressed by the same alias you query, and scoped exactly like running that query — it exposes
   nothing the query itself doesn't. Params are irrelevant (they only fill filter values, never
   change the projection), so no params argument exists.
@@ -147,7 +150,7 @@ contract as `readSelect`: `[]` for null/empty/unexpected cells, malformed entrie
 The candidate set for an "assign to a member" picker (`dist/src/hooks.d.ts`):
 
 ```tsx
-const { members, loading, error } = useMembers({ group: "grp_fulfillment" });
+const { members, loading, error } = useMembers({ group: GRP.fulfillment });
 <MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
 ```
 
@@ -175,11 +178,17 @@ three gates are observable as an `error` on the hook:
    member declaration gets: *"This app has not declared member access — listing members requires a
    declared workflow `member` input or query `member` param."* Member access is a declared,
    auditable surface, like queries and workflows.
-3. **Declared groups only.** `{ group: "grp_…" }` restricts the roster to one member group — but
+3. **Declared groups only.** `{ group }` restricts the roster to one member group — but
    only a group declared on some member input's `group` property. An undeclared group errors; an
    app can only enumerate groups it actually assigns into. A declared group with no members
    resolves to `{ members: [] }`.
 
+Name the group `GRP.<group>`, from the generated `.lotics/app_fields.ts` — `GRP` is that workspace's
+group directory keyed by slugified display name, so the same source resolves in every copy of the
+app. A pasted `grp_…` id is an id one workspace minted: it resolves to nothing anywhere else, and
+`lotics app check` refuses it. (The manifest DECLARATION below is the exception — it carries the
+concrete id, and publish inverts it.)
+
 ```jsonc
 // package.json → "lotics" — the declaration that unlocks useMembers
 "workflows": {

package/docs/mutations.md

@@ -29,10 +29,9 @@ const result = await createOrder({ customer_id, quantity: 3 });
   owner's** authority (never the viewer's — see [security](./security.md) for attribution,
   privilege gates, and public-app semantics).
 - Binding is server-side (`set_app_workflow`, or `lotics app workflow set <alias>` from the
-  app project). `lotics app deploy` ships code, queries, and capabilities — it never binds
-  workflows.
-  The `package.json#lotics.workflows` map is a *pulled reflection* of the live bindings, used
-  purely to type `useWorkflow` (below); hand-editing it changes nothing on the server.
+  app project), and `lotics app deploy` calls it: `package.json#lotics.workflows.<alias>` plus
+  `src/workflows/<alias>.ts` ARE the source of a binding, so an alias committed to the repo is
+  one the next clone ships. The declaration also types `useWorkflow` (below).
 - Invoking an alias that is not bound resolves with `status: "error"` and a message naming
   the missing binding.
 - Anonymous visitors to a publicly shared app can invoke workflows too; the triggering
@@ -82,6 +81,11 @@ convert every failure into a resolved `{ status: "error", message }`:
 | Alias not bound / workflow deleted | `status: "error"` with the explanatory message |
 | Gateway timeout (a 524 on a long run), any 5xx, a non-JSON error page | `status: "error"` with a friendly, **body-free** message — never raw gateway HTML |
 
+A workflow call is **synchronous end to end** — about 100 s at the edge, 30 s through the bridged
+host — and a timed-out call may still have committed. So model work that can run for minutes belongs
+in an agent run, which is asynchronous by construction and polls to completion, never in a workflow
+step.
+
 So the correct handling is:
 
 ```tsx
@@ -204,11 +208,13 @@ if (r.status === "success" && r.data) {
 
 ## Declaring workflow inputs
 
-An alias's declaration is `{ workflow_id, inputs?, outputs? }`. `inputs` maps each input name
-to a typed declaration; it is authored when the workflow is bound (`set_app_workflow` /
-`lotics app workflow set` reads it from `package.json#lotics.workflows.<alias>`), and the
-schema the body was verified against is canonical — the manifest reflection cannot silently
-weaken it. It drives three things at once: compile-time typing of the `useWorkflow` payload,
+An alias's declaration is `{ inputs?, outputs?, workflow_id? }` — `workflow_id` is the server's
+half, stamped by the first bind, so an alias an author has only just written carries none.
+`inputs` maps each input name to a typed declaration; it is authored beside the body and
+travels with it (`set_app_workflow` / `lotics app workflow set` reads it from
+`package.json#lotics.workflows.<alias>`, and a deploy pushes a declaration that has moved), and
+the schema the body was verified against is canonical — a manifest edit that reaches no push
+weakens nothing. It drives three things at once: compile-time typing of the `useWorkflow` payload,
 compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
 validation at the execute boundary.
 
@@ -278,7 +284,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   added after authoring is accepted, a removed one rejected
   (`select input "<path>" value "<v>" is not one of field "<key>"'s current options`) with no
   redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
-  (`lotics app workflow set` / `set_app_workflow`; `lotics app deploy` never binds workflows) with
+  (`lotics app workflow set` / `set_app_workflow`, which a deploy calls for a declaration it holds) with
   `select input references field "<key>", which does not exist in this workspace` /
   `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
   field; keep `options` for a fixed enum the app owns. Populate pickers from `useFieldOptions`

package/docs/navigation_and_state.md

@@ -63,6 +63,28 @@ routes, and splats all work. Inside the tree, use react-router normally:
   (`^7 || ^8` — the canonical package; the `react-router-dom` shim's tree also
   satisfies it) is an **optional peer dependency** — an app that imports the
   router entry must install it itself; nothing else in the SDK needs it.
+- **An address no route claims says so.** `AppRouter` appends a catch-all at
+  every level of the tree, so such a path renders a not-found screen — a
+  message naming the path and a link to the first route — instead of an empty
+  page, and a layout route keeps its shell around that message. Declaring your
+  own `{ path: "*" }` replaces it.
+- **The not-found screen speaks the app's language.** Its two strings default
+  to English; an app whose reader reads another language passes them as
+  `notFound`, next to `routes`:
+
+  ```tsx
+  <AppRouter
+    routes={routes}
+    notFound={{
+      message: (path) => `Không có màn hình ở ${path}`,
+      firstScreen: "Về màn hình đầu tiên",
+    }}
+  />
+  ```
+
+  `message` takes the path so the words may place it where the language needs
+  it. Where the app uses `@lotics/ui`, read both from the kit's locale — the
+  SDK ships none of its own.
 - **Limitation: element routing only.** `AppRouter` mounts a plain browser
   router, not a react-router *data* router — route `loader`/`action` fields
   are ignored, and `useLoaderData` **throws** ("must be used within a data

package/docs/queries.md

@@ -114,7 +114,9 @@ A result is `{ rows, columns, source_fields_by_table_id }` (`+ total` for a coun
 `columns` is the statically computed output schema — `{ name, type, nullable?,
 source_table_id?, source_field_key? }` per column. Rows are plain objects keyed by output
 column name; decode cells with the SDK readers (`row.*`, `readSelect`, `readMembers`,
-`readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)).
+`readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)). Those output names are also
+the row's TYPE: codegen writes them into `AppQueryColumns`, so reading a column this query does not
+project is a `tsc` error.
 
 **`source_fields_by_table_id` is always `{}`** — the key is part of the shape, the map is not
 filled. The server reads the source tables' field definitions to resolve option and member

package/package.json

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