@lotics/app-sdk 0.109.0 → 0.111.0

package/AGENTS.md

@@ -14,14 +14,14 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 
 | Doc | Read it for |
 |---|---|
-| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column and `total: { where }` a count per named filter, from one scan — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`, `useRecordings` over several aliases. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload` and its `fidelity`, `renameFile` (a new file over the same bytes), `useAttachments`/`useAttachmentPiles`, `readFiles` and presigned URLs (a bearer credential — never logged or persisted), workflow-generated files, naming a zip's entries, the delivery bounds. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People, select options and comments — `useMembers`, `useFieldOptions`, `useViewer`, `useWorkspaceTimezone`/`useWorkspaceCurrency`, `useAppContext`, the workspace's zone at the root, `useComments`. |
-| [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
+| [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model, the screens and `drawers` it reports to the host), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming parts, the agent's ask-back), `askAi`, `useAiContext`, and what the member's own chat agent can do with the app while it is open. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, why a per-input bound is a tenancy floor rather than an authorization check. |
 | [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1` — queries, workflows and agents, a mocked agent's run played line by line), `openExternal`/`openApp`/`downloadFile`, geofencing, the peer dependencies. |

package/dist/index.js

@@ -18911,7 +18911,7 @@ var kitGlyphSchema = zod_default.string().superRefine((name, ctx) => {
 var optionMarkSchema = zod_default.discriminatedUnion("kind", [
   zod_default.object({
     kind: zod_default.literal("brand"),
-    name: zod_default.enum(BRAND_NAMES).describe(`The channel the option IS, drawn as its logo: ${BRAND_NAMES.join(", ")}`)
+    name: zod_default.enum(BRAND_NAMES).describe("The channel the option IS, drawn as its logo")
   }).strict(),
   zod_default.object({
     kind: zod_default.literal("icon"),
@@ -20794,7 +20794,40 @@ function viReadGroup(n, leading) {
   }
   return parts.join(" ");
 }
-function numberToWords(value) {
+var EN_ONES = [
+  "zero",
+  "one",
+  "two",
+  "three",
+  "four",
+  "five",
+  "six",
+  "seven",
+  "eight",
+  "nine",
+  "ten",
+  "eleven",
+  "twelve",
+  "thirteen",
+  "fourteen",
+  "fifteen",
+  "sixteen",
+  "seventeen",
+  "eighteen",
+  "nineteen"
+];
+var EN_TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"];
+var EN_SCALES = ["", "thousand", "million", "billion", "trillion", "quadrillion", "quintillion"];
+function enReadGroup(n) {
+  const hundreds = Math.floor(n / 100);
+  const rest = n % 100;
+  const parts = [];
+  if (hundreds > 0) parts.push(EN_ONES[hundreds], "hundred");
+  if (rest >= 20) parts.push(rest % 10 === 0 ? EN_TENS[rest / 10] : `${EN_TENS[Math.floor(rest / 10)]}-${EN_ONES[rest % 10]}`);
+  else if (rest > 0) parts.push(EN_ONES[rest]);
+  return parts.join(" ");
+}
+function numberToWords(value, language = "vi") {
   if (value == null) return "";
   let n;
   if (typeof value === "number") {
@@ -20807,9 +20840,13 @@ function numberToWords(value) {
   if (!isFinite(n)) {
     throw new Error("numberToWords: value must be a finite number");
   }
+  if (language !== "vi" && language !== "en") {
+    throw new Error(`numberToWords: language must be "vi" or "en", got ${JSON.stringify(language)}`);
+  }
   n = Math.round(n);
   const negative = n < 0;
   n = Math.abs(n);
+  if (language === "en") return enNumberToWords(n, negative);
   if (n === 0) return "kh\xF4ng";
   const groups = [];
   for (let rem = n; rem > 0; rem = Math.floor(rem / 1e3)) {
@@ -20825,6 +20862,19 @@ function numberToWords(value) {
   const result = parts.join(" ");
   return negative ? "\xE2m " + result : result;
 }
+function enNumberToWords(n, negative) {
+  if (n === 0) return "zero";
+  const parts = [];
+  let group = 0;
+  for (let rem = n; rem > 0; rem = Math.floor(rem / 1e3), group++) {
+    const value = rem % 1e3;
+    if (value === 0) continue;
+    if (group >= EN_SCALES.length) throw new Error("numberToWords: value is too large to read in English");
+    parts.unshift(EN_SCALES[group] ? `${enReadGroup(value)} ${EN_SCALES[group]}` : enReadGroup(value));
+  }
+  const result = parts.join(" ");
+  return negative ? "minus " + result : result;
+}
 function formatNumber(value, decimals) {
   if (value == null) return "";
   if (typeof value !== "number" || Number.isNaN(value)) {
@@ -23112,7 +23162,23 @@ var TZDate = class _TZDate extends TZDateMini {
 
 // ../shared/src/expression_date.ts
 function hasTimezone(dateStr) {
-  return /[Zz]|[+-]\d{2}:\d{2}$/.test(dateStr);
+  return /[Zz]|[+-]\d{2}:?\d{2}$/.test(dateStr);
+}
+var LONG_FORMAT_TOKENS = /P+p+|P+|p+|''|'(''|[^'])+('|$)|./g;
+var FORMAT_TOKENS = /[yYQqMLwIdDecihHKkms]o|(\w)\1*|''|'(''|[^'])+('|$)|./g;
+var FORMAT_TOKEN_LETTERS = new Set("GyYRuQqMLwIdDEecihabBHKkmsSXxOztT");
+var PROTECTED_TOKENS = { D: "d", DD: "dd", YY: "yy", YYYY: "yyyy" };
+function datePatternProblem(pattern) {
+  const tokens = (pattern.match(LONG_FORMAT_TOKENS) ?? []).map((token2) => /^[Pp]/.test(token2) ? "" : token2).join("").match(FORMAT_TOKENS) ?? [];
+  for (const token2 of tokens) {
+    if (token2.startsWith("'")) continue;
+    const instead = PROTECTED_TOKENS[token2];
+    if (instead !== void 0) return `"${token2}" is not a day of the month or a calendar year \u2014 write "${instead}"`;
+    if (!FORMAT_TOKEN_LETTERS.has(token2.charAt(0)) && /[a-zA-Z]/.test(token2.charAt(0))) {
+      return `"${token2.charAt(0)}" is no date token \u2014 quote literal text, as in "'Ng\xE0y' dd 'th\xE1ng' MM 'n\u0103m' yyyy"`;
+    }
+  }
+  return void 0;
 }
 function parseDateStringInTimezone(dateStr, timezone) {
   const match2 = dateStr.match(
@@ -23214,13 +23280,18 @@ function getDateExpressionFunctions(defaultTimezone) {
         throw new Error("formatDate: formatStr must be a string");
       }
       validateOptionalTimezone(timezone, "formatDate");
+      const problem = datePatternProblem(formatStr);
+      if (problem !== void 0) {
+        throw new Error(`formatDate: ${problem}`);
+      }
       const tz = getTimezone(timezone);
       if (typeof date6 === "string" && !hasTimezone(date6)) {
         const testDate = new Date(date6);
         if (isNaN(testDate.getTime())) {
           throw new Error("formatDate: invalid date");
         }
-        return format(date6, formatStr);
+        const iso = parseISO(date6);
+        return format(isNaN(iso.getTime()) ? testDate : iso, formatStr);
       }
       const dateObj = date6 instanceof Date ? date6 : new Date(date6);
       if (isNaN(dateObj.getTime())) {
@@ -24500,16 +24571,16 @@ var appSchema = zod_default.object({
     "Whether a shared password gates the public binding. True \u2192 anonymous visitors must authenticate at `/v1/apps/{app_id}/public/authenticate` before any publicAppAccess endpoint resolves. The hash itself is never sent over the wire; only this flag is exposed (and only on authenticated owner-side reads \u2014 the public by-subdomain response surfaces the same fact as `requires_password`)."
   ),
   workflows: zod_default.record(zod_default.string(), appBoundWorkflowSchema).nullable().optional().describe(
-    "Alias \u2192 workflow declaration map. Each alias resolves to a workflow_id and an optional typed inputs schema, set by `set_app_workflow` / `remove_app_workflow` or a model apply; a deploy carries it forward. The iframe SDK's useWorkflow(alias) resolves through this map; when an inputs schema is declared, the server validates payloads against it before invocation. The workflow always executes under the app's IAM principal."
+    "Alias \u2192 workflow declaration map. Each alias resolves to a workflow_id and an optional typed inputs schema, set by `set_app_workflow` / `remove_app_binding` or a model apply; a deploy carries it forward. The iframe SDK's useWorkflow(alias) resolves through this map; when an inputs schema is declared, the server validates payloads against it before invocation. The workflow always executes under the app's IAM principal."
   ),
   queries: zod_default.record(zod_default.string(), appQueryDeclarationSchema).nullable().optional().describe(
-    "Alias \u2192 query declaration map. Each alias resolves to a fixed query AST template with a typed param schema, set by `set_app_query` / `set_app_queries` or a model apply; a deploy carries it forward. The iframe SDK's useQuery(alias, params) resolves through this map; custom-code apps never send a raw AST. The query runs under the app's IAM principal."
+    "Alias \u2192 query declaration map. Each alias resolves to a fixed query AST template with a typed param schema, set by `set_app_queries` or a model apply; a deploy carries it forward. The iframe SDK's useQuery(alias, params) resolves through this map; custom-code apps never send a raw AST. The query runs under the app's IAM principal."
   ),
   capabilities: appCapabilitiesSchema.nullable().optional().describe(
     "Opt-in app capabilities, set by `update_app` or a model apply; a deploy carries them forward. Capabilities are off unless declared \u2014 least ambient authority. `comments` gates the members-only `useComments` primitive: only an app that declares it can read/write record comments (each under the VIEWING member's own authority)."
   ),
   agents: zod_default.record(zod_default.string(), appAgentDeclarationSchema).nullable().optional().describe(
-    "Alias \u2192 agent declaration map. Each alias binds a streaming tool-loop agent the app runs via `useAgentRun(alias)` (an SSE stream), with declared tools, model, and typed inputs/outputs, set by `set_app_agent` / `remove_app_agent` or a model apply; a deploy carries it forward. The agent runs under the app's IAM principal; runs persist a flat history per session."
+    "Alias \u2192 agent declaration map. Each alias binds a streaming tool-loop agent the app runs via `useAgentRun(alias)` (an SSE stream), with declared tools, model, and typed inputs/outputs, set by `set_app_agent` / `remove_app_binding` or a model apply; a deploy carries it forward. The agent runs under the app's IAM principal; runs persist a flat history per session."
   ),
   theme: appThemeSchema.nullable().optional().describe("Theme settings for the app"),
   can_author: zod_default.boolean().optional().describe(
@@ -24709,8 +24780,15 @@ var cForStepSchema = zod_default.lazy(
 );
 var workflowStepsSchema = zod_default.array(workflowStepSchema).min(1);
 
+// ../shared/src/retired_tools.ts
+var RETIRED_TOOLS = /* @__PURE__ */ new Map([
+  ["generate_pdf_from_template", "generate_document"],
+  ["generate_excel_from_template", "generate_document"],
+  ["generate_word_from_template", "generate_document"]
+]);
+
 // ../shared/src/tool_input_semantics_registry.ts
-var TOOL_INPUT_SEMANTICS = {
+var CURRENT_TOOL_INPUT_SEMANTICS = {
   // ─── Bulk record mutations ─────────────────────────────────────────────
   update_records: {
     table_id: { kind: "table_ref", rows: "change" },
@@ -24935,7 +25013,7 @@ var TOOL_INPUT_SEMANTICS = {
     force: { kind: "scalar" }
   },
   // ─── Document-generation tools ────────────────────────────────────────
-  generate_pdf_from_template: {
+  generate_document: {
     data: { kind: "template_variables" },
     document_template_id: { kind: "scalar" },
     filename: { kind: "text" }
@@ -25242,6 +25320,15 @@ var TOOL_INPUT_SEMANTICS = {
     take: { kind: "scalar" }
   }
 };
+var TOOL_INPUT_SEMANTICS = {
+  ...CURRENT_TOOL_INPUT_SEMANTICS,
+  ...Object.fromEntries(
+    [...RETIRED_TOOLS].flatMap(([retired, replacement]) => {
+      const semantics = CURRENT_TOOL_INPUT_SEMANTICS[replacement];
+      return semantics ? [[retired, semantics]] : [];
+    })
+  )
+};
 
 // ../shared/src/workflow_step_helpers.ts
 function stepChildStepArrays(step) {
@@ -27134,6 +27221,7 @@ var TABLE_ID_PATTERN = new RegExp(
   `^tbl_[${ID_ALPHABET}]+$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`,
   "i"
 );
+var PREFIXED_ID_PATTERN = new RegExp(`^[a-z]{3}_[${ID_ALPHABET}]{${ID_LENGTH}}$`);
 
 // ../shared/src/table_field_keys.ts
 var nanoid4 = customAlphabet(ID_ALPHABET, 6);
@@ -30975,13 +31063,25 @@ function pageOf(mocked, call) {
 function countOf(mocked, by) {
   return { total: mocked.length, ...by === void 0 ? {} : { counts: countsOf(mocked, by) } };
 }
+function within(filter2, named) {
+  return filter2 === void 0 ? named : { node_type: "group", logic: "and", children: [filter2, named] };
+}
+function mockCount(alias, call) {
+  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
+  if (mocked === null) return null;
+  const where = Object.entries(call.where ?? {});
+  const named = where.map(([, one]) => getMockRows(alias, { params: call.params, filter: within(call.filter, one) }) ?? []);
+  const answer = (rows, each) => call.where === void 0 ? countOf(rows, call.by) : { total: rows.length, counts: Object.fromEntries(where.map(([name], at2) => [name, each[at2]?.length ?? 0])) };
+  if (Array.isArray(mocked) && named.every((one) => Array.isArray(one))) return answer(mocked, named.filter((one) => Array.isArray(one)));
+  return Promise.all([mocked, ...named]).then(([rows = [], ...each]) => answer(rows, each));
+}
 function knownRows(alias, call) {
   const mocked = getMockRows(alias, call);
   return Array.isArray(mocked) ? pageOf(mocked, call) : void 0;
 }
 function knownCount(alias, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  return Array.isArray(mocked) ? countOf(mocked, call.by) : void 0;
+  const counted = mockCount(alias, call);
+  return counted === null || counted instanceof Promise ? void 0 : counted;
 }
 async function askRows(key, alias, askedAt, call, since = askedAt) {
   const mocked = getMockRows(alias, call);
@@ -30998,18 +31098,22 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   return answer;
 }
 async function askCount(key, alias, askedAt, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  if (mocked !== null) return countOf(await mocked, call.by);
+  const mocked = mockCount(alias, call);
+  if (mocked !== null) return mocked;
   const answer = await rpc("query", {
     alias,
     params: call.params,
     count: true,
     ...call.filter === void 0 ? {} : { filter: call.filter },
-    ...call.by === void 0 ? {} : { count_by: call.by }
+    ...call.by === void 0 ? {} : { count_by: call.by },
+    ...call.where === void 0 ? {} : { count_where: call.where }
   });
   noteAnswer(key, alias, askedAt, []);
   return answer;
 }
+function namedCounts(named) {
+  return { rows: Object.fromEntries(named.map(([name, one]) => [name, one.rows])), pending: named.some(([, one]) => one.pending) };
+}
 var feedWants = /* @__PURE__ */ new Map();
 function ignore() {
 }
@@ -31022,7 +31126,8 @@ function useQuery(alias, params = {}, opts = {}) {
   const filter2 = opts.filter;
   const wantsRows = opts.rows ?? true;
   const totalAsked = opts.total ?? opts.page !== void 0;
-  const by = typeof totalAsked === "object" ? totalAsked.by : void 0;
+  const by = typeof totalAsked === "object" && "by" in totalAsked ? totalAsked.by : void 0;
+  const where = typeof totalAsked === "object" && "where" in totalAsked ? totalAsked.where : void 0;
   const call = JSON.stringify([params, filter2 ?? null, sort ?? null]);
   const mocking = hasMockFlag();
   const [paging, setPaging] = useState3({ call, page: 0 });
@@ -31077,11 +31182,12 @@ function useQuery(alias, params = {}, opts = {}) {
     feedWants.set(feedKey, heldPages + 1);
     feed.refetch();
   }, [feedKey, feedHasMore, heldPages, feed]);
-  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null]);
-  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, { params, filter: filter2, by }), {
+  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null, where ?? null]);
+  const countCall = { params, ...filter2 === void 0 ? {} : { filter: filter2 }, ...by === void 0 ? {} : { by }, ...where === void 0 ? {} : { where } };
+  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, countCall), {
     focus,
     aliases: [alias],
-    known: mocking ? () => knownCount(alias, { params, filter: filter2, by }) : void 0
+    known: mocking ? () => knownCount(alias, countCall) : void 0
   });
   const version3 = useWrittenVersion();
   const drawn2 = useMemo3(() => {
@@ -31097,9 +31203,10 @@ function useQuery(alias, params = {}, opts = {}) {
   const counted = useMemo3(() => {
     if (count.data === void 0) return void 0;
     const total2 = overlayCount(alias, params, filter2, count.askedAt, count.data.total);
-    const counts = by === void 0 || count.data.counts === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, count.data.counts);
+    const answered2 = count.data.counts;
+    const counts = answered2 === void 0 ? void 0 : where !== void 0 ? namedCounts(Object.entries(where).map(([name, one]) => [name, overlayCount(alias, params, within(filter2, one), count.askedAt, answered2[name] ?? 0)])) : by === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, answered2);
     return { total: total2.rows, counts: counts?.rows, pending: total2.pending || (counts?.pending ?? false) };
-  }, [alias, call, by, count.data, count.askedAt, version3]);
+  }, [alias, call, countKey, count.data, count.askedAt, version3]);
   const total = counted?.total;
   const pageCount = opts.page === void 0 || total === void 0 ? void 0 : Math.max(1, Math.ceil(total / opts.page));
   const pageHasMore = opts.page === void 0 ? false : total !== void 0 ? (page + 1) * opts.page < total : drawn2.rows.length === opts.page;

package/dist/queries.d.ts

@@ -89,10 +89,13 @@ export interface QueryOptions<C extends string = string> {
     more?: number;
     /**
      * The total the rows come to — a count of the whole set, its own read, so the rows never wait for it —
-     * or with `by` a count per value of that column from the same scan. On by default with `page`.
+     * with `by` a count per value of that column from the same scan, or with `where` a count per named filter
+     * of the rows it keeps within the set, every one from the same scan. On by default with `page`.
      */
     total?: boolean | {
         by: C;
+    } | {
+        where: Readonly<Record<string, QueryFilter<C>>>;
     };
     /** `false` reads no rows: a total alone. Default `true`. */
     rows?: boolean;
@@ -103,7 +106,8 @@ export interface QueryState<R> {
     truncated: boolean;
     /** The whole set's count, where `total` is asked; `undefined` until it answers. */
     total: number | undefined;
-    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`); a value no row holds is absent. */
+    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`), a value no row holds absent;
+     *  or per name of `total.where`. */
     counts: Readonly<Record<string, number>> | undefined;
     /** Only the first read of a key with nothing to show; a re-read and a new key keep the rows on screen. */
     loading: boolean;

package/dist/router.d.ts

@@ -4,7 +4,9 @@ export interface NotFoundWords {
     message: (path: string) => string;
     firstScreen: string;
 }
-export declare function AppRouter({ routes, notFound }: {
+export declare function AppRouter({ routes, notFound, drawers }: {
     routes: RouteObject[];
     notFound?: NotFoundWords;
+    /** The query keys a drawer opens at, the one drawn lowest first: each open counts as a screen over the path's. */
+    drawers?: readonly string[];
 }): import("react").JSX.Element;

package/dist/router.js

@@ -1,5 +1,6 @@
 import {
   isEmbedded,
+  postHostNotification,
   setUrlParams
 } from "./chunk-CRJQYSDI.js";
 
@@ -8,6 +9,7 @@ import { useEffect } from "react";
 import {
   BrowserRouter,
   Link,
+  matchRoutes,
   useLocation,
   useRoutes
 } from "react-router";
@@ -20,12 +22,40 @@ function screenHref(loc) {
   const qs = search.toString();
   return loc.pathname + (qs ? `?${qs}` : "") + loc.hash;
 }
-function HostScreenMirror() {
+function routePattern(matches, pathname) {
+  const concrete = pathname.split("/").filter((segment) => segment !== "");
+  let shape = [];
+  for (const { route, params } of matches) {
+    const path = route.path ?? "";
+    if (path.startsWith("/")) shape = [];
+    for (const segment of path.split("/")) {
+      if (segment === "") continue;
+      if (!segment.endsWith("?")) {
+        shape.push(segment);
+        continue;
+      }
+      const base = segment.slice(0, -1);
+      const present = base.startsWith(":") ? params[base.slice(1)] !== void 0 : concrete[shape.length]?.toLowerCase() === base.toLowerCase();
+      if (present) shape.push(base);
+    }
+  }
+  return `/${shape.join("/")}`;
+}
+function HostScreenMirror({ routes, drawers }) {
   const location = useLocation();
   const href = screenHref(location);
   useEffect(() => {
     void setUrlParams({ [LOC_KEY]: href });
   }, [href]);
+  const { pathname, search } = location;
+  const params = new URLSearchParams(search);
+  const opened = drawers.flatMap((key) => params.getAll(key).map((value) => ({ key, value })));
+  const matches = matchRoutes(routes, pathname);
+  const route = matches === null ? null : routePattern(matches, pathname) + opened.map(({ key }) => `+${key}`).join("");
+  const openedAt = JSON.stringify(opened.map(({ value }) => value));
+  useEffect(() => {
+    if (route !== null) postHostNotification({ type: "screen_view", route });
+  }, [pathname, openedAt, route]);
   return null;
 }
 function RoutedRoutes({ routes }) {
@@ -76,20 +106,17 @@ function firstScreenPath(routes) {
 }
 function AppRouter({
   routes,
-  notFound = NOT_FOUND_ENGLISH
+  notFound = NOT_FOUND_ENGLISH,
+  drawers = []
 }) {
   const embedded = isEmbedded();
+  const claimed = withNotFound(
+    routes,
+    /* @__PURE__ */ jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })
+  );
   return /* @__PURE__ */ jsxs(BrowserRouter, { children: [
-    embedded ? /* @__PURE__ */ jsx(HostScreenMirror, {}) : null,
-    /* @__PURE__ */ jsx(
-      RoutedRoutes,
-      {
-        routes: withNotFound(
-          routes,
-          /* @__PURE__ */ jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })
-        )
-      }
-    )
+    embedded ? /* @__PURE__ */ jsx(HostScreenMirror, { routes: claimed, drawers }) : null,
+    /* @__PURE__ */ jsx(RoutedRoutes, { routes: claimed })
   ] });
 }
 export {

package/dist/rpc.d.ts

@@ -49,7 +49,11 @@ export type HostNotification = {
     type: "aiContext";
     slot: string;
     context: AiContextValue | null;
-} | AppErrorReport;
+} | AppErrorReport | {
+    type: "screen_view";
+    /** The route pattern that claims the screen (`/item/:id`), a `+<key>` per drawer open over it; never its address. */
+    route: string;
+};
 /** The app's identity: the host's context when bridged, `/by-subdomain` (no member) standalone. */
 export interface AppContext {
     member_id: string | 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`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`.
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_binding`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`.
 
 A declaration carries:
 

package/docs/data_fetching.md

@@ -7,7 +7,7 @@ every write goes through a workflow — [./mutations.md](./mutations.md). Exact
 `dist/queries.d.ts`, `dist/row.d.ts`, `dist/select.d.ts`, `dist/members.d.ts`.
 
 The read model in one paragraph: an app never sends a raw query. It invokes a **named query by
-alias** (bound with `set_app_query`) and fills the template's declared `{{params.x}}`
+alias** (bound with `set_app_queries`) and fills the template's declared `{{params.x}}`
 value holes; the server holds the canonical AST and runs it under the **app owner's** authority
 ([./security.md](./security.md)). The generated `.lotics/app_queries.d.ts` augments `AppQueries`,
 so params are typed per the binding; an alias it does not carry is accepted as a plain string,
@@ -21,7 +21,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, opts?)` | `rows` up to the server's cap, or the first `limit` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
 | `useQuery(alias, params?, { page: n })` | one numbered page of `n` rows, `total`, `pageCount`, `setPage` | numbered, jumpable pages |
 | `useQuery(alias, params?, { more: n })` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
-| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
+| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
 | `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
@@ -63,7 +63,15 @@ const { total, counts } = useQuery("orders", { q }, { rows: false, total: { by:
 // counts?.["opt_shipped"] — the rows in that stage over the whole set, however few are loaded
 ```
 
-A `useQueries` call's `total` is `true` or absent — it takes no `by`.
+Several counts of one set — a tab each, a share each — are **one read with `total: { where }`**: each
+named filter's rows within the read's `filter`, as `counts` by name, from the same scan.
+
+```tsx
+const { total, counts } = useQuery("orders", {}, { rows: false, total: { where: { late: lateFilter, mine: mineFilter } } });
+// counts?.late, counts?.mine — one scan, however many names
+```
+
+A `useQueries` call's `total` is `true` or absent — it takes no `by` or `where`.
 
 ### Why not hand-roll it
 

package/docs/mutations.md

@@ -138,8 +138,8 @@ neither, so the refusal arrives and marks no control.
 
 ### Generated files come back in `files[]`
 
-Any step in the run whose tool output carries a `file_id` (most commonly the
-`generate_*_from_template` document tools) is collected automatically into
+Any step in the run whose tool output carries a `file_id` (most commonly
+`generate_document`) is collected automatically into
 `result.files[]` — each an `UploadedFile`
 `{ id, filename, mime_type, url?, thumbnail_url? }` with a presigned `url` (24-hour TTL) the
 app can open directly:
@@ -526,7 +526,7 @@ every read before the request answers:
   leaves it; a created row it admits joins it, standing by the read's order (the call's `sort`,
   then the query's own) where its sort cells are numbers or dates, else first. A row the read does
   not hold that a write may move into it waits for the server, and `pending` says so.
-- **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
+- **Totals.** A `total`, a count per value (`total: { by }`) or per named filter (`total: { where }`), a group asked with `aggregate` or
   declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
   or takes away; a group the last row leaves is gone, and a count per value gains the value a row
   first holds. A mean, an extreme, a distinct count, a group by day, an aggregate with its own

package/docs/navigation_and_state.md

@@ -121,6 +121,25 @@ Observable details:
 to the framework. Never declare them in a `useUrlState` shape or write them
 yourself; undeclared keys are already preserved automatically (see below).
 
+### Which screens are used (embedded)
+
+Each time the path changes, `AppRouter` tells the host which route claims the
+new screen, as that route is declared: `/item/:id`, never `/item/rec_8f2…`, and
+never the query or hash. The host counts one view per change, so a
+`useUrlState` filter is not a new screen and a step to the next item is. A
+static segment is reported as written, so never build a route's `path` from
+your data: a record's id or name goes in a `:param`.
+
+A drawer the app opens at a query key rather than a path is a screen too when
+`drawers` names its key, listed from the one drawn lowest:
+
+```tsx
+<AppRouter routes={routes} drawers={["item"]} />
+```
+
+`/?item=rec_8f2…` is then counted as `/+item`, one `+<key>` per drawer open, and
+opening, stepping or closing one is a new view; the key's value is never sent.
+
 ## `useUrlState` — typed view-state in the address bar
 
 Save a declared slice of view-state into the address bar so a filtered view

package/docs/queries.md

@@ -1,7 +1,7 @@
 # Queries — the query engine authoring reference
 
 Every read an app performs is a **named query**: a fixed AST template bound to the app by alias
-(`set_app_query`), validated and compiled when it is written, and invoked by alias
+(`set_app_queries`), validated and compiled when it is written, and invoked by alias
 through the read hooks ([data_fetching.md](./data_fetching.md)). This is the authoring reference
 for the query engine itself.
 
@@ -11,11 +11,11 @@ for the query engine itself.
 
 ### Declaration
 
-Queries live on the app, as an alias → declaration map. `set_app_query` binds one alias at a time
-(`set_app_queries` several), each as a new version of the app:
+Queries live on the app, as an alias → declaration map. `set_app_queries` binds one alias or
+several, each call a new version of the app:
 
 ```jsonc
-// set_app_query { "app_id": "app_…", "alias": "openOrders", "declaration": … }
+// set_app_queries { "app_id": "app_…", "queries": { "openOrders": … } }
 {
   "ast": {
     "kind": "project",
@@ -28,7 +28,7 @@ Queries live on the app, as an alias → declaration map. `set_app_query` binds
     "columns": ["order_code", "customer", "total", "created"]
   }
 }
-// set_app_query { "app_id": "app_…", "alias": "orderByCode", "declaration": … }
+// set_app_queries { "app_id": "app_…", "queries": { "orderByCode": … } }
 {
   "ast": { /* … a filter with "{{params.code}}" … */ },
   "params": { "code": { "type": "text" } },
@@ -844,7 +844,10 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
 - **`count: true`** — returns `{ total }` only: a COUNT over the *filtered* set, ignoring
   sort/limit/offset. Drives "Page 1 of N". With **`count_by: "<column>"`** the same scan also
   returns `counts` — rows per value of that projected column (a multi-value row under each value,
-  a row holding none in `total` only); a column whose values are not plain (a link) → 400. It is a
+  a row holding none in `total` only); a column whose values are not plain (a link) → 400. With
+  **`count_where: { <name>: <filter> }`** (not beside `count_by`) the same scan returns `counts` by
+  name — the rows each filter keeps within `filter`, each filter bounded and resolved as `filter` is,
+  at most 32. It is a
   **second full execution** of the template — sent only where a read asks for its `total`, and
   one count serves every read of the same set ([data_fetching](./data_fetching.md)).
 - **`aggregate: { by?, day?, sum? }`** — the groups of the *filtered* set in place of its rows: one

package/docs/recipes.md

@@ -11,8 +11,7 @@ A button that produces a file — a quotation, a debit note, a label — and han
 **no** record.
 
 **The mechanism is the return channel.** Any workflow tool
-whose step output carries a `file_id` (`generate_pdf_from_template`, `generate_excel_from_template`,
-`generate_word_from_template`) is auto-collected by the execute endpoint and comes back in
+whose step output carries a `file_id` (`generate_document`) is auto-collected by the execute endpoint and comes back in
 **`result.files[]`**, each with a servable `url`.
 
 So the workflow only *generates*; attaching the file to a record is a separate, optional step, and
@@ -22,7 +21,7 @@ So the workflow only *generates*; attaching the file to a record is a separate,
 // workflow body — alias `genDebit`, input `record_id`
 const rid = trigger.app_workflow.inputs.record_id;
 const rec = await get_record({ table_id: "tbl_x", record_id: rid });
-await generate_excel_from_template({
+await generate_document({
   data: { /* … */ }, filename: `Debit_${code}`, document_template_id: "dtl_x",
 });
 return({ status: "success", message: `Đã tạo ${code}` });   // the file is extracted, not returned

package/docs/security.md

@@ -111,7 +111,7 @@ Listing members (`useMembers`) takes an authenticated member of the app's own or
 
 ## What runtime refinement cannot widen
 
-The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column — over the same bounded filter. Full mechanics in [queries](./queries.md).
+The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column; with `count_where`, one per named filter, each bounded as `filter` is — over the same bounded filter. Full mechanics in [queries](./queries.md).
 
 **Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead, or AND the `search` with a template `contains` OR-group over the fields that may be probed — every row that group matches also matches the search, so the pair answers only for those fields.
 

package/docs/workflows.md

@@ -506,7 +506,7 @@ full menu by category, so a miss is one informed retry.
 | **Type / null** | `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`, `isObject`, `coalesce`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson` |
 | **Array** | `size`, `first`, `requireFirst`, `last`, `nth`, `at`, `slice`, `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`, `uniqueBy`, `compact`, `flatten`, `reverse`, `concat`, `difference`, `differenceBy`, `intersection`, `intersectionBy`, `list`, `range`, `reduce` |
 | **Number** | `sum`, `sumBy`, `mean`, `meanBy`, `min`, `max`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage` |
-| **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `formatNumber(value, decimals)` (fixed-decimal, ungrouped), `formatDecimal(value, decimals, locale)` (grouped for a reader — `formatDecimal(151000, 0, "vi-VN")` → `151.000`), `numberToWords` |
+| **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `formatNumber(value, decimals)` (fixed-decimal, ungrouped), `formatDecimal(value, decimals, locale)` (grouped for a reader — `formatDecimal(151000, 0, "vi-VN")` → `151.000`), `numberToWords(x, lang?)` (`"vi"` or `"en"`) |
 | **Object** | `keys`, `values`, `entries`, `get`, `pick`, `omit`, `merge`, `nonNullKeys` |
 | **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange` |
 | **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])` |
@@ -755,7 +755,7 @@ values and put the writing after it.
   matches the same filter.
 ### Keep expensive steps off the path the caller waits on
 
-`generate_pdf_from_template` and `agent` are the two steps that dominate a body's wall clock. Ask
+`generate_document` and `agent` are the two steps that dominate a body's wall clock. Ask
 whether the person pressing the button needs that artifact **at that instant**. A document that is
 printed later belongs in the workflow that prints it — moving it there also removes the reads that
 existed only to feed it, which is usually where the round trips were hiding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.109.0",
+  "version": "0.111.0",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {