@lotics/app-sdk 0.115.3 → 0.116.0

package/AGENTS.md

@@ -14,13 +14,13 @@ 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 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/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** and `answeredAt` (the server answering again what a screen drew), 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/files.md](./docs/files.md) | Files end to end — `useFileUpload` and its `fidelity` and a photo's `place`, `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`, a record's activity (`useRecordActivity`). |
 | [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. |

package/dist/activity.d.ts

@@ -0,0 +1,27 @@
+import type { ActivityEntry } from "./shared_types.js";
+export interface RecordActivityState {
+    /** Newest first. */
+    entries: ActivityEntry[];
+    /** Where the trail goes on — pass it as `after` to read the page past this one; `undefined` at its end. */
+    next: string | undefined;
+    loading: boolean;
+    error: string | null;
+    /** A signed-in member; standalone nothing is read and `entries` stays empty. */
+    available: boolean;
+    refetch: () => void;
+}
+export interface RecordActivityOptions {
+    /** A page's `next`: read the page past it. Absent, the newest page. */
+    after?: string;
+}
+/**
+ * One page of the record's activity. `entity` is the alias the app's spec names the record's entity under; `record_id`
+ * a real id. Read again when a push or this app's own write names the entity's reads, and when a comment is written.
+ *
+ * ```tsx
+ * const { entries, next } = useRecordActivity("job", recordId);
+ * // The page past it, mounted where the reader asks for more:
+ * const older = useRecordActivity("job", recordId, { after: next });
+ * ```
+ */
+export declare function useRecordActivity(entity: string, record_id: string, options?: RecordActivityOptions): RecordActivityState;

package/dist/{chunk-EWCMZCKA.js → chunk-IN4WP24U.js}

@@ -471,7 +471,8 @@ async function runUploadPipeline(file, rpc2, options = {}) {
   const { file: uploaded } = await rpc2.completeUpload({
     file_id: init.file_id,
     file_storage_key: init.file_storage_key,
-    filename: candidate.name
+    filename: candidate.name,
+    ...options.place === void 0 ? {} : { place: options.place }
   });
   return uploaded;
 }
@@ -954,7 +955,8 @@ function rpcStandalone(op, payload) {
     case "upload":
       return standaloneUpload(
         payload.file,
-        payload.fidelity
+        payload.fidelity,
+        payload.place
       );
     case "file.rename":
       return standaloneRename(payload);
@@ -988,6 +990,8 @@ function rpcStandalone(op, payload) {
     case "comments.delete":
     case "comments.counts":
       return rejectCommentsStandalone();
+    case "activity.list":
+      return Promise.reject(new Error("A record's activity is available only in embedded apps \u2014 a signed-in member is required."));
     case "recording.start":
     case "recording.stop":
       return Promise.reject(
@@ -1169,7 +1173,7 @@ async function standaloneRename(payload) {
   const { file } = await apiCall("POST", `/v1/apps/${app_id}/files/${encodeURIComponent(fileId)}/rename`, { filename }, { appId: app_id });
   return file;
 }
-async function standaloneUpload(file, fidelity) {
+async function standaloneUpload(file, fidelity, place) {
   if (!(file instanceof File)) {
     throw new Error("upload payload must include a File");
   }
@@ -1187,7 +1191,7 @@ async function standaloneUpload(file, fidelity) {
       input,
       { appId: app_id }
     )
-  }, { fidelity });
+  }, { fidelity, ...place === void 0 ? {} : { place } });
   return uploaded;
 }
 

package/dist/comments.d.ts

@@ -51,6 +51,8 @@ export interface CommentsState {
 export interface UseCommentsArgs {
     record_id: string;
 }
+/** What every read a comment changes is read under — the counts, a record's activity — so a comment written or deleted asks each again. */
+export declare const COMMENT_WRITES = "comment-counts";
 /**
  * `record_id` must be a real id — an empty string still fetches. Gate the
  * panel on a row's `__source_record_id`, which a grouped query answers as null.

package/dist/geolocation.d.ts

@@ -1,8 +1,3 @@
-/**
- * Geofenced device location, read directly (the host grants the iframe the
- * `geolocation` Permissions-Policy). Failure is a structured `reason`, so the
- * app words its own guidance.
- */
 /** Center `[latitude, longitude]`, radius in meters. */
 export interface GeofenceZone {
     coordinates: [number, number];
@@ -28,6 +23,9 @@ export type GeofenceOutcome = {
 export interface GeofenceOptions {
     /** Default 15000. */
     timeoutMs?: number;
+    /** The device's best fix (satellites where it has them), slower and costlier than its default — for a place a
+     *  record keeps, where a fix a block off reads as somewhere else. Default false. */
+    highAccuracy?: boolean;
 }
 export declare function isWithinZone(latitude: number, longitude: number, zone: GeofenceZone): boolean;
 /**

package/dist/hooks.d.ts

@@ -4,6 +4,7 @@ import { type AiContextValue } from "./rpc.js";
 import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppAgents, AppAgentResults } from "./types.js";
 import type { ResolvedMember } from "./members.js";
+import type { PhotoPlace } from "./row.js";
 export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 /**
@@ -66,6 +67,7 @@ interface FileUploadState {
      */
     upload: (file: File, options?: {
         fidelity?: ImageFidelity;
+        place?: PhotoPlace;
     }) => Promise<UploadedFile>;
     uploading: boolean;
     /** Cleared when a new upload starts. */

package/dist/index.d.ts

@@ -6,12 +6,16 @@ export type { AppErrorKind } from "./error_report.js";
 export { useWorkflow, useWorkflows, writesSettled, useFileUpload, useAttachments, useAttachmentPiles, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export type { UploadedFile, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, } from "./hooks.js";
 export { useQuery, useQueries, queryAll, exportQuery, useFieldOptions } from "./queries.js";
-export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, ExportCall, ExportFile, ExportReport, ExportTab, } from "./queries.js";
+export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFieldSortKey, QueryFirstSortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, ExportCall, ExportFile, ExportReport, ExportTab, } from "./queries.js";
 export type { ExportedFile } from "./shared_types.js";
 export type { AttachedFile, AttachmentPiles, AttachmentPilesOptions, AttachmentsOptions, AttachmentsState } from "./attachments.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
+export { useRecordActivity } from "./activity.js";
+export type { RecordActivityOptions, RecordActivityState } from "./activity.js";
+export type { ActivityActor, ActivityActorKind, ActivityChange, ActivityComment, ActivityEntry, ActivityValue, RecordActivityPage, } from "./shared_types.js";
 export { useAppContext, useViewer, useWorkspaceCurrency, useWorkspaceTimezone } from "./viewer.js";
+export type { AppAbsence } from "./shared_types.js";
 export { useRecording, useRecordings } from "./recording.js";
 export type { UseRecording, UseRecordings } from "./recording.js";
 export type { RecordingState, RecordingInputs } from "./recording_state.js";
@@ -32,7 +36,7 @@ export type { AppFixture, MockExport, MockQuery, MockQueryCall, MockWorkflow } f
 export type { MockAgent, MockAgentRun } from "./mock_agent_run.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
-export type { ResolvedLink, AppFile } from "./row.js";
+export type { ResolvedLink, AppFile, PhotoPlace } from "./row.js";
 export { useNewRecord, newRecordId } from "./new_record.js";
 export type { NewRecordApi } from "./new_record.js";
 export { useRecents } from "./use_recents.js";

package/dist/index.js

@@ -25,7 +25,7 @@ import {
   subscribeRecordings,
   subscribeUrlParams,
   urlParam
-} from "./chunk-EWCMZCKA.js";
+} from "./chunk-IN4WP24U.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -601,6 +601,9 @@ function useKey(key, fetcher, opts = {}) {
   const arrival = opts.arrival ?? true;
   const aliases = opts.aliases === void 0 ? NO_ALIASES : new Set(opts.aliases);
   const slot = key === null ? null : slotOf(key, fetcher, aliases);
+  const mounted = useRef(null);
+  if (mounted.current === null || mounted.current.key !== key) mounted.current = { key, at: clock };
+  const mountedAt = mounted.current.at;
   const seeded = useRef(null);
   if (slot !== null && key !== null && slot.askedAt === 0 && opts.known !== void 0) {
     const askedAt = tick();
@@ -663,6 +666,10 @@ function useKey(key, fetcher, opts = {}) {
       read2.add("answer");
       return kept?.askedAt ?? 0;
     },
+    get answeredAt() {
+      read2.add("answer");
+      return current !== void 0 && current.askedAt > mountedAt ? current.askedAt : 0;
+    },
     get error() {
       read2.add("error");
       return slot?.error ?? null;
@@ -20633,6 +20640,11 @@ var fileUploadResponseSchema = zod_default.object({
   files: zod_default.array(processedFileSchema).describe("Successfully uploaded files"),
   errors: zod_default.array(fileUploadErrorSchema).describe("Files that failed to upload with error details")
 });
+var filePlaceSchema = zod_default.object({
+  latitude: zod_default.number().min(-90).max(90),
+  longitude: zod_default.number().min(-180).max(180),
+  accuracy: zod_default.number().min(0)
+}).strict();
 var fileFieldValueSchema = zod_default.object({
   id: zod_default.string().describe("Unique identifier for the file"),
   /**
@@ -24096,6 +24108,7 @@ var KIT_GLYPH_NAMES = [
   "rotate-cw",
   "rows-3",
   "scan",
+  "scan-line",
   "scissors",
   "search",
   "send",
@@ -25581,15 +25594,19 @@ var LINKED_CALL = "linked";
 var GRAMMAR_NAME_SHAPE = `${LINKED_CALL}(record["fld_link"])[0] fetches one linked row`;
 var RUNTIME_KEYS = new Set(runtimeKeySchema.options);
 var CURRENT_MEMBER_IN_ANY_GROUP = "current_member_in_any_group";
+var CURRENT_MEMBER_STANDS_IN_FOR = "current_member_stands_in_for";
+var CURRENT_MEMBER_STANDS_IN_FOR_ANY_GROUP = "current_member_stands_in_for_any_group";
 var INLINE_HELPERS = [
   "formatCurrency",
   "randomNumber",
   "randomAlphaNumeric",
   "sample",
-  // Actor authorization predicate — resolves the triggering member's groups
-  // server-side (bound in the backend helper registry, not a pure shared
-  // helper).
-  CURRENT_MEMBER_IN_ANY_GROUP
+  // Actor authorization predicates — resolve the triggering member's groups and
+  // whom they stand in for server-side (bound in the backend helper registry,
+  // not pure shared helpers).
+  CURRENT_MEMBER_IN_ANY_GROUP,
+  CURRENT_MEMBER_STANDS_IN_FOR,
+  CURRENT_MEMBER_STANDS_IN_FOR_ANY_GROUP
 ];
 var HELPERS = /* @__PURE__ */ new Set([
   ...Object.keys(expression_array_exports),
@@ -25744,6 +25761,9 @@ var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 var PREFIX_CACHE_TTLS = ["5m", "1h"];
 
 // ../shared/src/schemas/apps.ts
+var QUERY_FIRST_MAX = 8;
+var queryFirstSortKeySchema = zod_default.object({ first: zod_default.array(tableRecordFiltersSchema).min(1).max(QUERY_FIRST_MAX) }).strict();
+var querySortSchema = zod_default.array(zod_default.union([tableRecordSortSchema.element, queryFirstSortKeySchema]));
 var queryColumnTypeSchema = zod_default.enum([
   "text",
   "number",
@@ -26308,6 +26328,9 @@ var appThemeSchema = zod_default.object({
 var appCapabilitiesSchema = zod_default.object({
   comments: zod_default.boolean().optional().describe(
     "Enable the members-only `useComments` primitive. When true, the app may read/write record comments \u2014 each operation under the VIEWING member's own table access, row-scope, and author identity (never the app owner's). Default off."
+  ),
+  photo_places: zod_default.boolean().optional().describe(
+    "Serve each photo's `place` \u2014 where the device stood as it took it, as its upload stated \u2014 on the file cells this app's reads return, to a member of the app's organization only; a caller outside it never receives one. Default off: no read carries a place."
   )
 });
 var appSchema = zod_default.object({
@@ -28622,8 +28645,10 @@ function clientRuntime(input) {
 async function predictWorkflowEffects(input) {
   const helpers = {
     ...createTimezoneAwareFunctions(input.timezone),
-    // Group membership is the server's to answer.
+    // Group membership and whom the caller stands in for are the server's to answer.
     current_member_in_any_group: () => unread("current_member_in_any_group"),
+    current_member_stands_in_for: () => unread("current_member_stands_in_for"),
+    current_member_stands_in_for_any_group: () => unread("current_member_stands_in_for_any_group"),
     [WITHHELD]: () => unread(WITHHELD)
   };
   const written = /* @__PURE__ */ new Map();
@@ -28889,6 +28914,8 @@ function useAppContext() {
   const { data, error: error51, refetch } = useKey(APP_CONTEXT_KEY, readContext, { focus: false, arrival: false });
   return {
     memberId: data?.member_id ?? null,
+    groupIds: data?.group_ids ?? null,
+    absences: data?.absences ?? null,
     commentsEnabled: data?.comments_enabled ?? false,
     recordingEnabled: data?.recording_enabled === true,
     timezone: data?.timezone,
@@ -28906,7 +28933,7 @@ function useWorkspaceCurrency() {
 }
 function useViewer() {
   const ctx = useAppContext();
-  return { memberId: ctx.memberId, loading: !ctx.settled };
+  return { memberId: ctx.memberId, groupIds: ctx.groupIds, loading: !ctx.settled };
 }
 
 // src/written.ts
@@ -29129,12 +29156,12 @@ function noteAnswer(key, alias, askedAt, rows, since = askedAt) {
   if (shape === void 0) return;
   noteRows(shape, rows, askedAt);
   judgePredictions(shape, rows, askedAt);
-  answered.set(JSON.stringify([key, alias]), { key, askedAt: since, tables: tablesOf(shape) });
   for (const [at2, one] of answered) if (one.key !== key && !mountedKey(one.key)) answered.delete(at2);
   const before = entries2.length;
   entries2 = entries2.filter(
     (entry) => entry.settledAt === null || [...answered.values()].some(({ askedAt: at2, tables }) => at2 <= (entry.settledAt ?? 0) && touches(entry, tables))
   );
+  answered.set(JSON.stringify([key, alias]), { key, askedAt: since, tables: tablesOf(shape) });
   if (entries2.length !== before) publish();
 }
 function comparable(field, value) {
@@ -29334,7 +29361,7 @@ function useFileUpload() {
     setInFlight((n) => n + 1);
     setError(null);
     try {
-      const uploaded = await rpc("upload", { file: file2, fidelity });
+      const uploaded = await rpc("upload", { file: file2, fidelity, ...options?.place === void 0 ? {} : { place: options.place } });
       return uploaded;
     } catch (err) {
       const message2 = err instanceof Error ? err.message : "Upload failed";
@@ -29661,6 +29688,13 @@ function readLinks(v) {
   }
   return out;
 }
+function placeOf(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const latitude = Reflect.get(value, "latitude");
+  const longitude = Reflect.get(value, "longitude");
+  const accuracy = Reflect.get(value, "accuracy");
+  return typeof latitude === "number" && typeof longitude === "number" && typeof accuracy === "number" ? { latitude, longitude, accuracy } : void 0;
+}
 function readFiles(v) {
   if (!Array.isArray(v)) return [];
   const out = [];
@@ -29679,6 +29713,7 @@ function readFiles(v) {
       const size2 = f.size;
       const created_at = f.created_at;
       const template = f.document_template_id;
+      const place = placeOf(f.place);
       out.push({
         id,
         filename: typeof filename === "string" ? filename : "",
@@ -29687,7 +29722,8 @@ function readFiles(v) {
         thumbnail_url: typeof thumb === "string" ? thumb : void 0,
         size: typeof size2 === "number" ? size2 : void 0,
         created_at: typeof created_at === "string" ? created_at : void 0,
-        document_template_id: typeof template === "string" ? template : void 0
+        document_template_id: typeof template === "string" ? template : void 0,
+        ...place === void 0 ? {} : { place }
       });
     }
   }
@@ -31520,33 +31556,37 @@ function buildDependencyGraph(formulaFields, allFields) {
   }
   return { sortedFields: result, circularDependencies };
 }
-function readsFieldsOnlyThroughEmptinessPredicates(node) {
+function readsFieldsOnlyThroughEmptinessPredicates(node, taken) {
+  const reads = (child) => readsFieldsOnlyThroughEmptinessPredicates(child, taken);
   if (node === void 0) return true;
   if (isFieldRead(node)) return false;
   switch (node.type) {
     case "Invoke": {
       const args = node.arguments ?? [];
       const predicate = node.method === void 0 && node.receiver.type === "ID" && EMPTINESS_PREDICATES.has(node.receiver.value);
-      return (predicate || readsFieldsOnlyThroughEmptinessPredicates(node.receiver)) && args.every(
-        (arg) => predicate && isFieldRead(arg) || readsFieldsOnlyThroughEmptinessPredicates(arg)
+      return (predicate || reads(node.receiver)) && args.every(
+        (arg) => predicate && isFieldRead(arg) || reads(arg)
       );
     }
     case "Unary":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.child);
+      return reads(node.child);
     case "Binary":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.left) && readsFieldsOnlyThroughEmptinessPredicates(node.right);
+      return reads(node.left) && reads(node.right);
     case "Getter":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.receiver);
+      return reads(node.receiver);
     case "Index":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.receiver) && readsFieldsOnlyThroughEmptinessPredicates(node.argument);
-    case "Ternary":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.condition) && readsFieldsOnlyThroughEmptinessPredicates(node.trueExpr) && readsFieldsOnlyThroughEmptinessPredicates(node.falseExpr);
+      return reads(node.receiver) && reads(node.argument);
+    case "Ternary": {
+      if (!reads(node.condition)) return false;
+      const decided = node.condition === void 0 || taken === void 0 ? void 0 : taken(node.condition);
+      return decided === true ? reads(node.trueExpr) : decided === false ? reads(node.falseExpr) : reads(node.trueExpr) && reads(node.falseExpr);
+    }
     case "List":
-      return (node.items ?? []).every(readsFieldsOnlyThroughEmptinessPredicates);
+      return (node.items ?? []).every((item) => reads(item));
     case "Map":
-      return Object.values(node.entries ?? {}).every(readsFieldsOnlyThroughEmptinessPredicates);
+      return Object.values(node.entries ?? {}).every((entry) => reads(entry));
     case "ArrowFunction":
-      return readsFieldsOnlyThroughEmptinessPredicates(node.body);
+      return reads(node.body);
     case "ID":
       return node.value !== "data";
     case "Literal":
@@ -31559,8 +31599,13 @@ function isFieldRead(node) {
 }
 function evaluateFormulaWithJS(preparedExpression, data, timezone, everyReferenceEmpty) {
   try {
-    if (everyReferenceEmpty && !readsFieldsOnlyThroughEmptinessPredicates(parseExpression(preparedExpression))) {
-      return null;
+    if (everyReferenceEmpty) {
+      const helpers = createTimezoneAwareFunctions(timezone);
+      const taken = (condition2) => {
+        const answer = condition2.evaluate({ ...data, ...helpers });
+        return typeof answer === "boolean" ? answer : void 0;
+      };
+      if (!readsFieldsOnlyThroughEmptinessPredicates(parseExpression(preparedExpression), taken)) return null;
     }
     const result = evaluateJsExpression(preparedExpression, data, void 0, timezone);
     if (result === null || result === void 0) {
@@ -31888,6 +31933,7 @@ function ordered(one, other) {
 }
 function orderOf(shape, tableId, sort) {
   const caller = (sort ?? []).map((key) => {
+    if ("first" in key) return null;
     const fieldKey = fieldKeyOf(shape, key.field_key, tableId);
     return fieldKey === void 0 ? null : { field_key: fieldKey, order: key.order, blanks: key.blank_position ?? "bottom" };
   });
@@ -31898,7 +31944,7 @@ function orderOf(shape, tableId, sort) {
 function isBlank(value) {
   return value === null || value === void 0 || value === "" || Array.isArray(value) && value.length === 0;
 }
-function placeOf(over, rows, cells, order) {
+function placeOf2(over, rows, cells, order) {
   if (order.length === 0) return 0;
   for (const [at2, row2] of rows.entries()) {
     const id = row2.__source_record_id;
@@ -31963,7 +32009,7 @@ function overlayRows(over, shape, admits, sort, rows, adds) {
     for (const column of Object.keys(shape.columns)) base[column] = null;
     const { row: row2, exact } = redrawn(over, base, shape, rowsTable, after.cells, new Set([...after.cells.keys()].filter((key) => !after.unknown.has(key))));
     if (!exact || after.unknown.size > 0) pending = true;
-    out.splice(placeOf(over, out, after.cells, orderOf(shape, rowsTable, sort)), 0, row2);
+    out.splice(placeOf2(over, out, after.cells, orderOf(shape, rowsTable, sort)), 0, row2);
   }
   return { rows: out, pending };
 }
@@ -32264,6 +32310,9 @@ function useQuery(alias, params = {}, opts = {}) {
     get isValidating() {
       return rows.validating || feed.validating || count.validating;
     },
+    get answeredAt() {
+      return !wantsRows ? count.answeredAt : opts.more === void 0 ? rows.answeredAt : feed.answeredAt;
+    },
     error: rows.error?.message ?? feed.error?.message ?? count.error?.message ?? null,
     pending: drawn2.pending || (counted?.pending ?? false),
     refetch,
@@ -32329,6 +32378,7 @@ function useQueries(calls, opts = {}) {
         get isValidating() {
           return answers.validating;
         },
+        answeredAt: answers.answeredAt,
         error: answer?.rows?.error ?? answer?.count?.error ?? answers.error?.message ?? null,
         pending: drawn2.pending || (counted?.pending ?? false),
         refetch: answers.refetch,
@@ -32395,7 +32445,7 @@ function toFileIds(files) {
   return (files ?? []).map((f) => f.id);
 }
 var optimisticCounter = 0;
-var COUNTS = "comment-counts";
+var COMMENT_WRITES = "comment-counts";
 function useComments(args) {
   const { record_id } = args;
   const { memberId, commentsEnabled, resolved } = useAppContext();
@@ -32430,7 +32480,7 @@ function useComments(args) {
         (current) => ({ comments: [...current?.comments ?? [], optimistic] }),
         () => rpc("comments.create", { record_id, content, file_ids: fileIds.length > 0 ? fileIds : void 0 })
       );
-      refetchReads([COUNTS]);
+      refetchReads([COMMENT_WRITES]);
     },
     [available, memberId, record_id, key]
   );
@@ -32456,7 +32506,7 @@ function useComments(args) {
         (current) => ({ comments: (current?.comments ?? []).filter((c) => c.id !== id) }),
         () => rpc("comments.delete", { record_id, comment_id: id })
       );
-      refetchReads([COUNTS]);
+      refetchReads([COMMENT_WRITES]);
     },
     [available, record_id, key]
   );
@@ -32477,9 +32527,9 @@ function useCommentCounts(args) {
   const { memberId, commentsEnabled, resolved } = useAppContext();
   const available = memberId != null && commentsEnabled;
   const counted = useKey(
-    available && table_id !== void 0 ? JSON.stringify([COUNTS, table_id]) : null,
+    available && table_id !== void 0 ? JSON.stringify([COMMENT_WRITES, table_id]) : null,
     () => rpc("comments.counts", { table_id }),
-    { aliases: [COUNTS] }
+    { aliases: [COMMENT_WRITES] }
   );
   return {
     counts: counted.data ?? {},
@@ -32490,6 +32540,36 @@ function useCommentCounts(args) {
   };
 }
 
+// ../shared/src/app_compile/app_names.ts
+function listQueryAlias(entity) {
+  return `${entity}_list`;
+}
+function oneQueryAlias(entity) {
+  return `${entity}_record`;
+}
+
+// src/activity.ts
+var NO_ENTRIES = [];
+function useRecordActivity(entity, record_id, options = {}) {
+  const { after } = options;
+  const { memberId, resolved } = useAppContext();
+  const available = memberId !== null;
+  const page = useKey(
+    available ? JSON.stringify(["activity", entity, record_id, after ?? null]) : null,
+    () => rpc("activity.list", { entity, record_id, ...after === void 0 ? {} : { after } }),
+    { aliases: [oneQueryAlias(entity), listQueryAlias(entity), COMMENT_WRITES] }
+  );
+  return {
+    entries: page.data?.entries ?? NO_ENTRIES,
+    next: page.data?.next,
+    // Waiting on the context counts as loading.
+    loading: available ? page.loading : !resolved,
+    error: page.error?.message ?? null,
+    available,
+    refetch: page.refetch
+  };
+}
+
 // src/recording.ts
 import { useCallback as useCallback7, useMemo as useMemo4, useSyncExternalStore as useSyncExternalStore3 } from "react";
 var NO_MOCKS = {};
@@ -32540,20 +32620,20 @@ function useRecordings(aliases) {
   };
 }
 
-// src/geolocation.ts
+// ../shared/src/geo_distance.ts
 var EARTH_RADIUS_M = 6371e3;
-function toRadians(degrees) {
-  return degrees * Math.PI / 180;
-}
-function distanceMeters(lat1, lon1, lat2, lon2) {
-  const dLat = toRadians(lat2 - lat1);
-  const dLon = toRadians(lon2 - lon1);
-  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2);
-  return EARTH_RADIUS_M * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+var radians = (degrees) => degrees * Math.PI / 180;
+function distanceMeters(a, b) {
+  const dLat = radians(b.latitude - a.latitude);
+  const dLon = radians(b.longitude - a.longitude);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(radians(a.latitude)) * Math.cos(radians(b.latitude)) * Math.sin(dLon / 2) ** 2;
+  return EARTH_RADIUS_M * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
 }
+
+// src/geolocation.ts
 function isWithinZone(latitude, longitude, zone) {
   const [centerLat, centerLon] = zone.coordinates;
-  return distanceMeters(latitude, longitude, centerLat, centerLon) <= zone.radius;
+  return distanceMeters({ latitude, longitude }, { latitude: centerLat, longitude: centerLon }) <= zone.radius;
 }
 async function readPermissionState() {
   if (typeof navigator === "undefined" || !navigator.permissions?.query) return null;
@@ -32564,10 +32644,10 @@ async function readPermissionState() {
     return null;
   }
 }
-function getPosition(timeoutMs) {
+function getPosition(timeoutMs, highAccuracy) {
   return new Promise((resolve, reject) => {
     navigator.geolocation.getCurrentPosition(resolve, reject, {
-      enableHighAccuracy: false,
+      enableHighAccuracy: highAccuracy,
       timeout: timeoutMs,
       maximumAge: 0
     });
@@ -32583,7 +32663,7 @@ async function requestGeofencedLocation(zones, opts) {
   }
   let position;
   try {
-    position = await getPosition(timeoutMs);
+    position = await getPosition(timeoutMs, opts?.highAccuracy ?? false);
   } catch (err) {
     const code = err?.code;
     return { ok: false, reason: code === 1 ? "denied" : "unavailable" };
@@ -32849,6 +32929,7 @@ export {
   useQueries,
   useQuery,
   useRecents,
+  useRecordActivity,
   useRecording,
   useRecordings,
   useUrlState,

package/dist/overlay.d.ts

@@ -6,11 +6,13 @@ export interface Overlaid<T = readonly Row[]> {
     /** A write this app made touches this read, and not all of what it changes is drawn. */
     pending: boolean;
 }
-type SortKeys = readonly {
+type SortKeys = readonly ({
     field_key: string;
     order: "asc" | "desc";
     blank_position?: "top" | "bottom";
-}[] | undefined;
+} | {
+    first: readonly unknown[];
+})[] | undefined;
 /**
  * A read's answer with this app's writes staged over it: a row read's cells, membership and new rows (`adds`:
  * the first page only), or a declared total's counts and sums.

package/dist/queries.d.ts

@@ -25,13 +25,20 @@ export interface QueryRow {
 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;
-/** Applied after the named query, bounded to its projected columns. */
-export interface QuerySortKey<C extends string = string> {
+/** A column's order — applied after the named query, bounded to its projected columns. */
+export interface QueryFieldSortKey<C extends string = string> {
     field_key: C;
     order: "asc" | "desc";
     /** Where blank cells sit; `"bottom"` when omitted. */
     blank_position?: "top" | "bottom";
 }
+/** The rows each filter keeps, in turn, before the rest — a row with the first it meets, those meeting none last;
+ *  each part in the keys after. At most 8 filters. */
+export interface QueryFirstSortKey<C extends string = string> {
+    first: QueryFilter<C>[];
+}
+/** One key of a read's order; each breaks the ties of the ones before it. */
+export type QuerySortKey<C extends string = string> = QueryFieldSortKey<C> | QueryFirstSortKey<C>;
 export interface QueryFilterFieldCondition<C extends string = string> {
     node_type: "condition";
     field_key: C;
@@ -113,6 +120,12 @@ export interface QueryState<R> {
     loading: boolean;
     /** Any request of this read is in flight. */
     isValidating: boolean;
+    /**
+     * Moves each time the server answers again a read this screen already drew — a realtime push, a write, a refocus, a
+     * feed grown — and only then: never for a write of this app drawn over the rows. 0 while the rows shown predate the
+     * screen asking them: the last call's, kept while this one is first asked, or held ones being asked again.
+     */
+    answeredAt: number;
     error: string | null;
     /**
      * A write this app made is in flight over these rows. They already show what it will change where that

package/dist/router.js

@@ -2,7 +2,7 @@ import {
   isEmbedded,
   postHostNotification,
   setUrlParams
-} from "./chunk-EWCMZCKA.js";
+} from "./chunk-IN4WP24U.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/row.d.ts

@@ -52,6 +52,15 @@ export interface AppFile {
     created_at?: string;
     /** The document template the file was generated from (`dtl_…`); absent on a file a person brought. */
     document_template_id?: string;
+    /** Where the device that took the photo stood as it took it, as it reported; absent on a file uploaded with none, and
+     *  on every read of an app not declaring `capabilities.photo_places` or by a caller outside its organization. */
+    place?: PhotoPlace;
+}
+/** Where a device stood: degrees north and east, and how many metres off it said it may be. */
+export interface PhotoPlace {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
 }
 /**
  * The presigned files, skipping any without a `url`. A lookup arrives one

package/dist/rpc.d.ts

@@ -1,3 +1,4 @@
+import type { AppAbsence } from "./shared_types.js";
 import type { AskUserChoiceOutput } from "./agent_stream.js";
 import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
 /**
@@ -8,7 +9,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
+export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "activity.list" | "recording.start" | "recording.stop";
 export interface AgentRunPayload {
     alias: string;
     session_id: string;
@@ -57,6 +58,9 @@ export type HostNotification = {
 /** The app's identity: the host's context when bridged, `/by-subdomain` (no member) standalone. */
 export interface AppContext {
     member_id: string | null;
+    /** The member groups the viewer is in, by id — absent from an older host and for a visitor from outside the
+     *  organization. */
+    group_ids?: string[];
     /** The app declared `comments`; `useComments` also needs a signed-in member. */
     comments_enabled: boolean;
     /** The IANA zone every instant is dated in; absent from an older host, which
@@ -70,6 +74,9 @@ export interface AppContext {
     recording_enabled?: boolean;
     /** This app's recordings the host still tracks, by alias. */
     recordings?: Record<string, unknown>;
+    /** Who in the organization is away, or will be, and who stands in — absent from an older host and for a visitor from
+     *  outside the organization. */
+    absences?: AppAbsence[];
 }
 /** Whether a Lotics host embeds the app, rather than it standing alone on its own origin. */
 export declare function isEmbedded(): boolean;

package/dist/shared_types.d.ts

@@ -3,6 +3,8 @@
  * `scripts/build_sdk.mjs`, because that package is private and ships in no
  * tarball. Written at every build, never edited.
  */
+export type ActivityEntry = { changes: { field_id: string; label: string; before: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; after: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; removed?: true | undefined; }[]; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "change"; } | { comment: { id: string; body: string; mentions: { id: string; name: string; }[]; files?: { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | undefined; }; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "comment"; };
+export type AppAbsence = { member: { id: string; name: string; }; stand_in: { id: string; name: string; }; starts_on: string; ends_on: string; group_ids: string[]; };
 /** The file an app export made, as a link to download it: no workspace file, so no id, and kept a day. */
 export type ExportedFile = {
   filename: string;
@@ -25,7 +27,7 @@ export type ReportColumn = {
   key: string;
   header: string;
   /** A `date` cell is an ISO day or moment. */
-  type: "number" | "text" | "date";
+  type: "number" | "date" | "text";
   /** A select whose cells hold bare option keys, no field of the query naming them: the words each key prints as. */
   labels?: { readonly [x: string]: string; };
 };
@@ -64,7 +66,7 @@ export type ReportReadingHead = {
   /** The read behind it was cut: its figures stand, every total over them is left out (`null`). */
   truncated: boolean;
 };
-export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; lookup_field_autonumber?: boolean | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; link?: true | undefined; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
+export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "date" | "files" | "text" | "select" | "select_member" | "select_record_link" | "rollup" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; lookup_field_autonumber?: boolean | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; notation?: { style: "decimal"; } | { style: "currency"; currency: string | { per_row: string; }; } | { style: "unit"; unit: string | { per_row: string; }; } | undefined; link?: true | undefined; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "date" | "text" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;
 export type TableRecordFiltersConditionNode = { node_type: "condition"; field_key?: string | undefined; type?: string | undefined; operator: string; value?: unknown; unit_option?: string | undefined; };
 export type TableRecordFiltersGroupNode = { node_type: "group"; logic: "and" | "or"; children: (TableRecordFilters)[]; };

package/dist/store.d.ts

@@ -9,6 +9,12 @@ export interface Held<T> {
     data: T | undefined;
     /** When the answer shown was asked; 0 for a staged value or none. */
     askedAt: number;
+    /**
+     * When the answer shown was asked, where this mount asked it; 0 while what is shown predates the mount — the last
+     * key's answer, or this key's held one being asked again. A value that moves is the server answering again what this
+     * mount already drew.
+     */
+    answeredAt: number;
     error: Error | null;
     /** A first answer is awaited, and none is shown. */
     loading: boolean;

package/dist/upload/pipeline.d.ts

@@ -1,5 +1,6 @@
 /** Upload: optimize (images) → presigned URL → PUT with retry → complete. */
 import { type ImageFidelity } from "./optimize.js";
+import type { PhotoPlace } from "../row.js";
 interface UploadInitResponse {
     upload_url: string;
     file_id: string;
@@ -24,6 +25,7 @@ export interface UploadRpc {
         file_id: string;
         file_storage_key: string;
         filename: string;
+        place?: PhotoPlace;
     }): Promise<{
         file: CompleteResponseFile;
     }>;
@@ -31,6 +33,8 @@ export interface UploadRpc {
 export interface RunUploadPipelineOptions {
     signal?: AbortSignal;
     fidelity?: ImageFidelity;
+    /** A photo's: where the device that took it stood, kept with the file. */
+    place?: PhotoPlace;
 }
 export declare function runUploadPipeline(file: File, rpc: UploadRpc, options?: RunUploadPipelineOptions): Promise<CompleteResponseFile>;
 export {};

package/dist/viewer.d.ts

@@ -1,3 +1,4 @@
+import type { AppAbsence } from "./shared_types.js";
 import { type AppContext } from "./rpc.js";
 /** The store key the host's context is held under, read by every screen and by the write model alike. */
 export declare const APP_CONTEXT_KEY = "app-context";
@@ -9,6 +10,10 @@ export declare function readContext(): Promise<AppContext>;
  */
 export declare function useAppContext(): {
     memberId: string | null;
+    /** The viewer's member groups, by id; `null` where the host did not say. */
+    groupIds: readonly string[] | null;
+    /** Who in the organization is away, or will be, and who stands in; `null` where the host did not say. */
+    absences: readonly AppAbsence[] | null;
     commentsEnabled: boolean;
     recordingEnabled: boolean;
     timezone: string | undefined;
@@ -32,10 +37,12 @@ export declare function useWorkspaceTimezone(): string | undefined;
 export declare function useWorkspaceCurrency(): string | undefined;
 /**
  * The viewing member — the view-as target under "View as" — or `null` for a
- * public visitor, while `loading`, or on failure. Row scoping needs no viewer:
- * use an `is_current_member` query filter.
+ * public visitor, while `loading`, or on failure; and the member groups they
+ * are in (`groupIds`, `null` where the host did not say). Row scoping needs no
+ * viewer: use an `is_current_member` query filter.
  */
 export declare function useViewer(): {
     memberId: string | null;
+    groupIds: readonly string[] | null;
     loading: boolean;
 };

package/docs/data_fetching.md

@@ -27,7 +27,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | 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, labels? }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; `labels` the words each bare option key of a `select` column no field names prints as, refused on any other column and for a key it lacks; 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 has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so open it with `openExternal` when the promise resolves; the server deletes the file a day after it is made |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
-`isValidating`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
+`isValidating`, `answeredAt`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
 `loadMore`, `loadingMore`. A field the call did not ask for rests at its empty value (`page` 0,
 `total` and `pageCount` undefined, `hasMore` false; `setPage` and `loadMore` do nothing).
 
@@ -93,7 +93,7 @@ all its calls, and each call states its own `filter`, `sort`, `total` and `rows`
 |---|---|---|---|
 | `enabled` | `boolean` | `true` | `false` = no request is sent, `rows` is `[]`, `loading` is `false`. Flip to `true` to fetch. The gate for search-as-you-type and on-demand detail. Disabling also **hides** previously loaded rows (the cached answer survives; it re-renders instantly when re-enabled). |
 | `revalidateOnFocus` | `boolean` | `true` | `false` = no re-read on window focus / tab return / network reconnect (`refetch()` still works). Keep the default for dashboards; turn off for transient queries (a search bound to an ephemeral term) where a refocus re-run is wasted work and a visible reload. |
-| `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns: `[{ field_key, order: "asc" \| "desc", blank_position? }]`. An empty/omitted array leaves the query's own order intact. Part of the read's key — changing it re-queries. |
+| `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns, each key breaking the ties of the ones before: `{ field_key, order: "asc" \| "desc", blank_position? }` a column's order, or `{ first: [filter, …] }` the rows each filter keeps, in turn, before the rest ([queries](./queries.md)). An empty/omitted array leaves the query's own order intact. Part of the read's key — changing it re-queries. |
 | `filter` | `QueryFilter` | — | Runtime filter, applied server-side after the named query, over its output columns. A single condition or a recursive `{ node_type: "group", logic: "and" \| "or", children }`. Part of the read's key. |
 | `limit` | `number` | — | The first `limit` rows only — a **cap**, not pages; omit to read up to the server's row cap. |
 | `page` | `number` | — | Numbered pages of `page` rows: `page` (from 0), `setPage`, `pageCount`, `hasMore`, and `total`, counted by default. |
@@ -173,6 +173,12 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   `loading && rows.length === 0`, never `loading` alone, or every re-key swaps the list for a
   spinner. **`isValidating`** is `true` whenever any request of the read is in flight — use it for
   a subtle refresh indicator.
+- **`answeredAt`** moves each time the server answers again a read this screen already drew — a
+  realtime push, this app's own write re-read, a refocus, a feed grown — and never for this app's
+  write drawn over the rows. It is `0` while the rows shown predate the screen asking them: the
+  previous call's kept during a re-key, or the cache shown on a remount before its re-read lands.
+  To show what someone else changed, compare the rows a read drew with the rows it draws next only
+  where `answeredAt` moved and the call is the same.
 - **`error`** is a `string | null`. A failed query surfaces immediately — there is **no automatic
   retry** (no retry loop that masks the error). The last successful rows for the same key stay
   rendered. The next focus re-read or an explicit `refetch()` re-runs it.
@@ -232,7 +238,7 @@ Reads paginate two different ways, and the difference is load-bearing:
   The cursor is internal: the hook sends it and reads the next one back; you never see it. The
   server keysets a single sortable key (the runtime `sort`, else the template's own order on a
   column it projects, else the record id) and falls back to offset transparently for a multi-key
-  sort it can't seek. So an infinite feed needs **no
+  sort, or a `first` key, it can't seek. So an infinite feed needs **no
   dedupe** — key rows by `__source_record_id` for stable React keys, not to guard against repeats.
 - **`page`, `limit`, `queryAll` and manual `rpc("query", { limit, offset })` use offset
   pagination** — count `offset` rows, skip them, return the next page. Two consequences a keyset

package/docs/files.md

@@ -49,11 +49,16 @@ await submit({ ...fields, invoice_file_id: invoiceShot.id });
 
 Signature: `dist/hooks.d.ts`. Returns `{ upload, uploading, error }`:
 
-- `upload(file: File, options?: { fidelity }): Promise<UploadedFile>` — resolves to the stored file; rejects on failure
+- `upload(file: File, options?: { fidelity, place }): Promise<UploadedFile>` — resolves to the stored file; rejects on failure
   (the file is never partially stored). `UploadedFile` is
   `{ id, filename, mime_type, url?, thumbnail_url? }` — `url`/`thumbnail_url` are presigned
   (24 h) and load directly in the sandboxed iframe, so a just-uploaded image previews without a
   round-trip.
+- `place` — a photo's `{ latitude, longitude, accuracy }` (`PhotoPlace`): where the device stood as it took it, read
+  as the shot comes back (`requestGeofencedLocation`, `highAccuracy: true`) — the optimizer strips EXIF, so the photo
+  carries none of its own. Kept with the file, never echoed by the upload; refused on a file that is no image. A
+  person's whereabouts, so a read carries it only where the app declares `capabilities.photo_places` (`update_app`; a
+  JSON app stating `on_site` declares it), and only to a member of the app's organization.
 - `fidelity` — **how faithful the stored image must be**; the platform owns the pixels behind
   each step. `useAttachments().add` and `.attach` take it too.
 
@@ -228,10 +233,12 @@ file-shaped value anywhere in the result rows** at read time:
 - `size` (bytes), `created_at` (ISO upload timestamp) and `document_template_id` (the template a
   generated file was made from) — resolved from the file object at serving time, batch-loaded per
   response.
+- `place` (where a photo's device stood, as its upload stated) — only where the app declares
+  `capabilities.photo_places`, and only to a member of the app's organization.
 
 A caller outside the app's organization receives only `id`, `filename`, `mime_type`, `url`,
 `thumbnail_url`, `preview_url`, `size`, `created_at` and `document_template_id` — never the storage
-address.
+address, and never a place.
 
 Decode with `readFiles(cell)` → `AppFile[]` (`dist/row.d.ts`):
 
@@ -245,6 +252,7 @@ Decode with `readFiles(cell)` → `AppFile[]` (`dist/row.d.ts`):
 | `size` | `number?` | Byte size — **absent on older files not yet backfilled**; render only when present |
 | `created_at` | `string?` | ISO upload timestamp |
 | `document_template_id` | `string?` | The document template (`dtl_…`) the file was generated from — absent on a file a person uploaded, whatever its name |
+| `place` | `PhotoPlace?` | `{ latitude, longitude, accuracy }` — where the device stood as it took the photo, as its upload stated (never proof); absent on a file uploaded with none, and on every read of an app not declaring `capabilities.photo_places` or by a caller outside its organization |
 
 `readFiles` skips entries the server didn't presign (no `url`), so you never render an unservable
 file. It is pure and never throws.

package/docs/members_and_options.md

@@ -229,12 +229,14 @@ renders blank, fix the query projection — never widen the bindings.
 
 ## `useViewer()` — display-only identity
 
-`useViewer()` (`dist/viewer.d.ts`) → `{ memberId, loading }` — the signed-in member currently
-viewing the app. Under an admin's "View as" in the product it returns
+`useViewer()` (`dist/viewer.d.ts`) → `{ memberId, groupIds, loading }` — the signed-in member currently
+viewing the app, and the member groups they are in, by id. Under an admin's "View as" in the product it returns
 the **view-as target**. It is `null` for a standalone/public visitor, and until the context
-resolves — gate viewer-dependent UI on `loading`.
+resolves — gate viewer-dependent UI on `loading`. `groupIds` is `null` where the host did not say (a
+visitor from outside the organization, an older host).
 
-Use it to **personalize**: greet the member, default an assignment picker to them.
+Use it to **personalize**: greet the member, default an assignment picker to them, lift the work
+waiting on a group they are in. A query asks the same of the server (`current_member in_any_group`).
 
 **Never an authorization fact or a scoping mechanism** —
 [security](./security.md#useviewer-is-display-only).
@@ -250,6 +252,15 @@ states — `resolved` once it answered, `settled` once it answered OR failed, an
 `{ message, retry }`, `null` unless the read failed. Where it failed every fact is unknown, so a
 surface that dates or counts by them draws the failure rather than guessing the reader's zone.
 
+`absences` lists who in the organization is away, or will be (`AppAbsence`; one that has ended is left
+out): the member, the one standing in (`stand_in`), the first and last day (`starts_on`, `ends_on`,
+`YYYY-MM-DD` in the workspace's calendar, both counting) and the groups of the member away
+(`group_ids`). On those days a step the member owns — by a member field, or through a group — also
+waits on the one standing in, so say it on the step ("thay Trần Thị Mai đến 08/10"). `null` where the
+host did not say (a visitor from outside the organization, an older host). Both arrive with the
+context, read once as the app opens. Display only: the workflow body re-checks who may act
+(`current_member_stands_in_for(...)`).
+
 ## The workspace's zone at the root
 
 An app's root draws nothing until `useAppContext()` has `settled` — where it failed, it draws
@@ -357,6 +368,48 @@ table's id: read it off a row of the query that renders the badges (`rows[0]?.__
 rather than pasting a `tbl_` id, which a copy of the app cannot carry. Pass `undefined` while no
 row is on screen — no request is sent and `counts` is `{}`.
 
+## Record activity: `useRecordActivity`
+
+Who changed which of a record's fields, and who commented on it — one entry per save
+(`dist/activity.d.ts`). For a JSON app: `entity` is the alias the app's spec names the record's
+entity under.
+
+```tsx
+const { entries, next, loading, error, available, refetch } = useRecordActivity("job", recordId);
+// The page past it, mounted where the reader asks for more:
+const older = useRecordActivity("job", recordId, { after: next });
+```
+
+- **Authority: the app's own read of the record.** The server reaches the record through the
+  entity's read of one row — the read the record screen draws it with — so a row that read does not
+  reach (the reader's scope, another workspace's) answers not found. Only the fields that read draws
+  appear: a field the app does not read never does, and an edit of one neither shows nor splits an
+  entry. A field taken out of the app while its table keeps it stays hidden; a field gone from its
+  table appears where the version serving when it was written read it, marked `removed`. Comments
+  appear only where the app declares `comments`.
+- **Members of the app's organization only** — the trail names its people. Standalone, `available`
+  is `false` and nothing is read.
+- **One entry per save.** Edits by one actor on one record less than ten minutes apart read as one
+  entry: each field from its value before the first edit to its value after the last, a field edited
+  back to where it began dropped (and an entry left with nothing). A comment, another actor or a
+  longer pause starts another entry. `at` is the entry's first write, `until` its last.
+- **An entry** (`ActivityEntry`) is `kind: "change"` with `changes`, or `kind: "comment"` with
+  `comment: { id, body, mentions }`. `actor`: `{ kind, id, name, image? }` — `member` (a person),
+  `agent` (an AI acting for a member: the chat, an app's agent, an MCP client — named by that
+  member), `workflow` (a workflow on its own, named by the workflow) or `import` (a script over the
+  API or the CLI, named by the member whose key ran it). `name` is empty where nothing resolves it.
+- **A change** (`ActivityChange`): `{ field_id, label, removed?, before, after }`. `field_id` is a
+  spec field's `id`; `label` the app's label today, else — a removed field — its label when written.
+  Values are drawn as the record's read draws them, so the cell readers apply: a select
+  `[{ key, label }]` (`readSelect`; each option's label as it was when written), a member field
+  `[{ id, name, image? }]`, a link `[{ id, display }]` (`readLinks`), files presigned (`readFiles`),
+  `null` for empty.
+- **Pages**: newest first, about thirty entries each; `next` is where the trail goes on —
+  `undefined` at its end. A page may hold fewer entries and still say `next` where the trail it read
+  held little the reader may see.
+- **Freshness:** read again when a push or this app's own write names the entity's reads, when a
+  comment is written or deleted through `useComments`, on focus, and on `refetch()`.
+
 ## Where each hook works
 
 | Surface | Embedded (signed-in member) | Standalone / public (anonymous) |
@@ -368,3 +421,4 @@ row is on screen — no request is sent and `counts` is `{}`.
 | `useViewer` | member id (view-as target) | `null` |
 | `useWorkspaceTimezone` / `useWorkspaceCurrency` | ✓ | ✓ |
 | `useComments` / `useCommentCounts` | ✓ when capability declared | ✗ `available: false` |
+| `useRecordActivity` | ✓ the app's organization's members | ✗ `available: false` |

package/docs/queries.md

@@ -847,15 +847,20 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   text, options, people and what a row looks up finds what the reader reads. A number, a date or
   a rollup has no words; narrow it by range. Traversals / `locked` / `current_member` do not — bake those into the
   template.
-- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns — the typed
-  `QuerySortKey` the hooks accept. `blank_position` is `"top" | "bottom"`, defaulting to
-  `"bottom"` — the only way to express the ascending reading of a **multi-key** sort over
-  columns whose blankness IS the ranking (a pipeline's per-step date stamps).
+- **`sort`** — keys over output columns, each breaking the ties of the ones before — the typed
+  `QuerySortKey` the hooks accept. `{ field_key, order, blank_position? }` orders by a column:
+  `blank_position` is `"top" | "bottom"`, defaulting to `"bottom"` — the only way to express the
+  ascending reading of a **multi-key** sort over columns whose blankness IS the ranking (a
+  pipeline's per-step date stamps). `{ first: [filter, …] }` (at most 8 filters, each bounded and
+  resolved as `filter` is) puts the rows each filter keeps, in turn, before the rest — a row stands
+  with the first it meets, the rows meeting none last — and the keys after it order each part: the
+  rows overdue, then due soon, each part by its due date. A caller's alone: a template's own `sort`
+  orders by its columns.
 - **`limit` / `offset` / keyset `cursor`** — pagination. `useQuery` with `limit` or `page` reads by
   `offset` (`limit` clamped to the 10,000-row cap, §10); `useQuery` with `more` opts into **keyset
   (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next
   `next_cursor` (null on the last page). Seek stays O(page) and never skips/duplicates a row as the
-  set shifts, falling back to offset for a multi-key sort it can't seek.
+  set shifts, falling back to offset for a multi-key sort, or a `first` key, it can't seek.
 - **`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,

package/docs/runtime.md

@@ -409,7 +409,8 @@ await checkIn({ latitude: r.coords.latitude, longitude: r.coords.longitude });
 
 - An **empty `zones` array means "no geofence"** — resolves `ok` with the raw
   position; use it as a plain location read.
-- The fix is standard accuracy (high-accuracy mode is not requested) and never
+- The fix is standard accuracy unless `opts.highAccuracy` asks for the device's best
+  (satellites where it has them — slower, for a place a record keeps), and never
   served from cache.
 - **Warning — the gate is advisory, client-side UX, not security.** It prevents
   honest-user mistakes; it cannot stop a tampered client, and the server never

package/docs/security.md

@@ -10,6 +10,7 @@ Every data operation an app performs — queries, workflows, agent runs — exec
 | Workflows (`useWorkflow`) | App owner | Yes — `runtime.triggered_by_member_id` in the workflow body (`null` for anonymous) |
 | Agent runs (`useAgentRun`) | App owner | Yes — requires an authenticated member; runs are private to that member |
 | Comments (`useComments`) | App authority for **access**; the **author** is always the real member | Always — members-only, anonymous callers are rejected |
+| Record activity (`useRecordActivity`) | The app's own read of the record — the entity's read of one row, and only the fields it draws | Always — the app's organization's members only |
 
 Consequences of owner authority:
 
@@ -87,6 +88,8 @@ returns `true` when the **triggering member** belongs to any of the listed group
 
 **Model approvers as a group**, not as a hardcoded member id or a client-side check: a group survives personnel changes, is auditable, and is the unit both predicates understand — `current_member_in_any_group([...])` gates the write while `current_member in_any_group [...]` in a query template gates the matching read, so non-approvers never see the pending queue *and* can't act on it.
 
+**A member away names who stands in.** While their absence holds, `current_member_stands_in_for([record["fld_approver"]])` is `true` for the one they named, and `current_member_stands_in_for_any_group(["grp_abc123"])` for the one standing in for a member of the group — OR either beside the owner's own check where the step should not stall while its owner is away. Same fail-closed rules; the server resolves both per press.
+
 ## Public apps: anonymous reach and its bounds
 
 A publicly-shared app (its own origin, or its public link) is reachable by **anyone** — the public share grants `app:use` to anonymous visitors and to authenticated members of any other org alike. What anonymous visitors can and cannot do:
@@ -99,6 +102,7 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | Query/workflow file outputs | Yes — file cells and workflow-produced files return direct presigned URLs (24-hour TTL) that anonymous viewers can fetch; see [files](./files.md) |
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
 | Comments (`useComments`) | **No** — members-only |
+| Record activity (`useRecordActivity`) | **No** — the app's organization's members only |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 
 **Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.

package/docs/workflows.md

@@ -512,7 +512,7 @@ full menu by category, so a miss is one informed retry.
 | **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_…"])` |
+| **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])`, `current_member_stands_in_for([memberId])`, `current_member_stands_in_for_any_group(["grp_…"])` |
 
 **Emptiness on a record cell.** `isNull` is the strict check — true only for `null`/`undefined`.
 A cleared cell does not always reach a workflow that way: the platform stores a cleared date or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.115.3",
+  "version": "0.116.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": {