@lotics/app-sdk 0.110.0 → 0.111.0

package/AGENTS.md

@@ -21,7 +21,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 | [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);

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,

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:

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" } },

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/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.110.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": {