lemma-sdk 0.2.34 → 0.2.35

package/README.md

@@ -1,8 +1,8 @@
 # Lemma TypeScript SDK
 
-`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk` for the core client, `lemma-sdk/react` for hooks and auth primitives, and the Lemma shadcn registry for stock UI blocks.
+`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk` for the core client and shared helpers, and use `lemma-sdk/react` as the main app-building surface for hooks and auth primitives.
 
-`AuthGuard` intentionally stays in `lemma-sdk/react`. Stock assistant, table, workflow, agent, member, and function UI lives in the registry.
+`AuthGuard` intentionally stays in `lemma-sdk/react`. The product direction is hooks-first and shell-agnostic. The registry remains available, but it is intentionally small and no longer the center of the recommended development model. See [docs/headless-first-direction.md](docs/headless-first-direction.md).
 
 ## Install
 
@@ -10,7 +10,7 @@
 npm install lemma-sdk
 ```
 
-If your app uses shadcn/ui, configure the Lemma registry with:
+If your app wants stock Lemma UI installs, configure the registry with:
 
 ```bash
 npx lemma-sdk init-shadcn
@@ -74,10 +74,10 @@ import {
 | Area | Hooks | Stability | Use when |
 | --- | --- | --- | --- |
 | Auth | `AuthGuard`, `useAuth`, `useCurrentUser`, `usePodAccess` | Stable | Gate an app, read signed-in user state, or request pod access. |
-| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords`, `useReferencingRecords` | Stable | Build custom table browsers, details views, related-record views, and relational reads. |
+| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords`, `useReferencingRecords`, `useDatastoreQuery`, `useRecordAggregates` | Stable | Build custom table browsers, details views, related-record views, raw SQL-backed reads, and chart/KPI queries. |
 | Record mutations | `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords` | Stable | Create, update, delete, or bulk-delete rows from headless UI. Function-backed mutations via `createVia`/`updateVia` options. |
 | Record forms | `useRecordSchema`, `useRecordForm`, `useForeignKeyOptions`, `useSchemaForm` | Stable | Render schema-driven record forms, enum fields, and foreign-key selectors. `useRecordForm` is the canonical table-bound form hook; `useSchemaForm` remains available for raw JSON-schema flows. |
-| Files | `useFiles`, `useFile`, `useFileSearch`, `useFileTree`, `useFilePreview` | Stable | Browse datastore folders, resolve file metadata, search indexed files, load directory trees, and preview converted or raw file content. |
+| Files | `useFiles`, `useFile`, `useUploadFile`, `useUpdateFile`, `useDeleteFile`, `useCreateFolder`, `useFileSearch`, `useFileTree`, `useFilePreview`, `useGlobalSearch` | Stable | Browse datastore folders, mutate file state, search indexed files, load directory trees, preview content, and compose multi-source desk search. |
 | Assistant | `useConversations`, `useConversation`, `useConversationMessages`, `useAssistantRun`, `useAssistantSession`, `useAssistantRuntime`, `useAssistantController` | Stable except controller/runtime | Build custom chat, conversation lists, streaming output, and final-output views. |
 | Agents | `useAgentRun`, `useAgentRuns`, `useAgentInputSchema`, `useTaskSession` | Stable except raw session | Start agent tasks, submit follow-up input, read task history, and inspect input/output schemas. |
 | Workflows | `useWorkflowStart`, `useWorkflowRun`, `useWorkflowRuns`, `useWorkflowResume` | Stable | Start, poll, resume, cancel, retry, and inspect workflow runs. |
@@ -85,6 +85,13 @@ import {
 | Functions | `useFunctionRun`, `useFunctionRuns`, `useFunctionSession` | Stable except raw session | Run functions, poll function runs, and list function history. |
 | Members and org | `useMembers`, `useAddPodMember`, `useUpdatePodMemberRole`, `useRemovePodMember`, `useOrganizationMembers` | Stable | Read pod and organization members, add existing org members into a pod, update pod roles, and remove pod access. The current checked-in client does not yet expose direct email-to-pod invites. |
 
+### Headless Helpers
+
+Alongside hooks, `lemma-sdk` exports shared headless helpers for common desk logic:
+
+- record display helpers: `formatRecordDisplayValue`, `humanizeRecordFieldName`, `detectRecordStatusColumn`
+- form/schema helpers: `buildRecordSchemaFields`, `buildSchemaFormFields`
+
 ### Common Hook Shapes
 
 For business-facing examples and a decision guide mapping "I want to..." to the right hook, see [docs/hooks-guide.md](docs/hooks-guide.md).
@@ -209,44 +216,33 @@ function WorkflowButton({ client }: { client: LemmaClient }) {
 }
 ```
 
-## Shadcn Registry
+## Registry
 
-Lemma UI lives in the registry, not in `lemma-sdk/react`.
+The registry is optional UI scaffolding, not the default product story. Most desks should be built from hooks and app-local UI.
+
+If you still want registry installs, they remain available:
 
 After running `npx lemma-sdk init-shadcn`, install blocks like:
 
 ```bash
-npx shadcn@latest add @lemma/lemma-records-view
-npx shadcn@latest add @lemma/lemma-detail-panel
-npx shadcn@latest add @lemma/lemma-record-form
-npx shadcn@latest add @lemma/lemma-global-search
-npx shadcn@latest add @lemma/lemma-file-browser
-npx shadcn@latest add @lemma/lemma-file-viewer
+npx shadcn@latest add @lemma/lemma-assistant-experience
 npx shadcn@latest add @lemma/lemma-document-workspace
-npx shadcn@latest add @lemma/lemma-document-creator
-npx shadcn@latest add @lemma/lemma-document-viewer
-npx shadcn@latest add @lemma/lemma-document-editor
+npx shadcn@latest add @lemma/lemma-global-search
 npx shadcn@latest add @lemma/lemma-members
-npx shadcn@latest add @lemma/lemma-comments
-npx shadcn@latest add @lemma/lemma-insights
-npx shadcn@latest add @lemma/lemma-assistant-experience
+npx shadcn@latest add @lemma/lemma-action-surface
 ```
 
-Those commands are representative. The registry currently ships 22 canonical blocks.
+The registry is intentionally small now. It currently ships 5 published blocks.
 
 Current registry items:
 
 | Area | Items |
 | --- | --- |
 | Assistant | `lemma-assistant-experience` |
-| Navigation | `lemma-breadcrumbs`, `lemma-global-search`, `lemma-page-tree` |
-| Records | `lemma-records-view`, `lemma-detail-panel`, `lemma-record-form`, `lemma-status-flow` |
-| Files | `lemma-file-browser`, `lemma-file-viewer` |
-| Documents | `lemma-document-workspace`, `lemma-document-creator`, `lemma-document-viewer`, `lemma-document-editor`, `lemma-markdown-editor` |
-| People | `lemma-members`, `lemma-notification-bell`, `lemma-user-menu` |
-| Analytics | `lemma-insights` |
-| Collaboration | `lemma-activity-feed`, `lemma-comments` |
-| Automation | `lemma-workflow-runner` |
+| Documents | `lemma-document-workspace` |
+| Search | `lemma-global-search` |
+| People | `lemma-members` |
+| Automation | `lemma-action-surface` |
 
 The registry is currently served from jsDelivr against this public repo:
 
@@ -255,60 +251,13 @@ The registry is currently served from jsDelivr against this public repo:
 
 For more stable installs, pin the registry URL to a tag or commit SHA instead of `@main`.
 
-Blocks that install a CSS file, such as records view, should be imported by your app's global stylesheet:
+Published blocks:
 
-```css
-@import "@/styles/lemma-records-view.css";
-```
-
-### Records Workspace Customization
-
-The records blocks are meant to be configured with props before you reach for a fork.
-
-`lemma-records-view` supports:
-
-- `preset="triage" | "issues" | "crm" | "docs"` for opinionated defaults without installing duplicate workflow blocks
-- `defaultView` and `availableViews` across `grid`, `list`, `grouped`, `kanban`, `linear`, `calendar`, `timeline`, and `matrix`
-- `tableName`, `visibleColumns`, and `hiddenFields` for schema-aware display
-- `pinnedColumns`, `columnWidths`, `columnLabels`, `primaryField`, `defaultSort`, and `paginationMode` for stronger operator-table defaults
-- `groupBy`, `calendarField`, `timelineField`, `matrixRowsBy`, and `matrixColumnsBy` for consolidated view configuration
-- `renderCell` and `renderCard` for custom record rendering
-- `foreignKeyLabels` for human-readable FK values in cards, detail views, and create/edit forms
-- `detailTabs`, `detailFieldGroups`, `detailRelatedRecords`, `detailSectionLabels`, and `detailSectionVisibility` for canonical detail composition
-- `quickActions`, `bulkActions`, `detailActions`, `quickActionMode`, and `onQuickActionSuccess` for direct, function, or workflow-backed actions
-- `onCreateOptions` and `onUpdateOptions` for function-backed mutations, including conditional field and section visibility in the create sheet
-- `createMode="sheet" | "modal" | "page"` and `detailMode="sheet" | "modal" | "page" | "inline"` for app-specific interaction patterns
-- `headerActions`, `emptyState`, `onRecordClick`, `renderFilesTab`, `renderCommentsTab`, and `renderActivityTab` for app-specific extensions
-- `appearance="default" | "minimal" | "borderless" | "contained"` and `density="compact" | "comfortable" | "spacious"` for host-level block chrome; `minimal` is the cardless mode
-
-`lemma-detail-panel` supports:
-
-- standalone record detail rendering outside the full records workspace, using the same canonical detail internals as `lemma-records-view`
-- `mode`, `variant`, and `layout` controls for embedded, sheet, modal, or full-page use
-- built-in detail tabs plus custom `tabs`, `relatedRecords`, and `renderFiles` / `renderComments` / `renderActivity` sections
-- direct, function-backed, and workflow-aware `actions`, plus `updateVia` / `updateFunctionName` for inline edits
-- shared `appearance`, `density`, and `radius` controls for use in inline, sheet, modal, or page layouts
-
-`lemma-record-form` supports:
-
-- `mode="inline" | "modal" | "sheet"`
-- `submitVia="direct" | "function"` and `submitFunctionName`
-- `submitFunctionInput` when the backing function expects a different payload shape
-- `hiddenFields`, `visibleFields`, `fieldOrder`, and `fieldGroups`
-- searchable FK inputs through the shared `record-form-fields` control layer
-- `fieldVisibility` and `sectionVisibility` for conditional forms
-- `foreignKeyLabels` for FK select labels
-- `initialValues`, `onSuccess`, and `onClose`
-- `appearance`, `density`, and `radius` using the same values as `lemma-records-view`
-
-`lemma-insights` supports:
-
-- table-backed count, sum, average, and grouped chart cards
-- bar, line, area, pie, and funnel charts with count/sum/avg aggregation
-- `aggregationMode="client" | "function"` with optional `aggregateFunctionName` for shared server-side aggregation
-- chart descriptions, value/category formatters, limits, sorting, empty states, and optional footers
-- function-backed stats and charts
-- shared `appearance`, `density`, `radius`, and card-column controls
+- `lemma-assistant-experience` for the hardest assistant/chat runtime surface
+- `lemma-document-workspace` for rich document/file create-read-edit-preview flows
+- `lemma-global-search` for a stock command-bar style omnibox
+- `lemma-members` for stock pod membership management
+- `lemma-action-surface` for long-running function/workflow/agent launches
 
 `lemma-global-search` supports:
 
@@ -318,26 +267,12 @@ The records blocks are meant to be configured with props before you reach for a
 - `minQueryLength`, `debounceMs`, `appearance`, `density`, trigger label, and placeholder customization
 - assistant handoff by `assistantName`, with optional query/results message shaping and conversation routing
 
-Navigation blocks support:
-
-- route, record, and file-path breadcrumb builders through `lemma-breadcrumbs`
-- self-referential page hierarchies through `lemma-page-tree`, with selection, expansion, and create/reorder hooks
-
-File blocks support:
-
-- datastore folder navigation and path breadcrumbs through `lemma-file-browser`
-- pod-level file browsing and search, not only record-linked attachments
-- upload, download, search, rename, move, folder creation, picker mode, and composition-friendly link actions
-- selection-aware file browsing so `lemma-file-browser` can drive a paired workspace preview
-- image, PDF, text, markdown, converted HTML, metadata, and breadcrumb-aware previews through `lemma-file-viewer`
-
 Document blocks support:
 
-- Notion/Coda-style block documents through `lemma-document-workspace`, with Tiptap JSON content, page/modal modes, title and summary chrome, file/reference/assistant blocks, save state, metadata, backlinks, and assistant-context rails
-- docstore-native creation through `lemma-document-workspace` or the simpler `lemma-document-creator`, with folder targeting, title/summary setup, pod-file metadata, and `mode="page" | "modal"`
-- long-form reading surfaces through `lemma-document-workspace` or `lemma-document-viewer`, with full-page and modal presentation, metadata, backlinks, references, and assistant-context rails
-- long-form authoring through `lemma-document-workspace` or `lemma-document-editor`, with full-page and modal presentation, title/summary chrome, save-state affordances, outline, references, and assistant-context rails
-- a clean separation between richer document UX and the lower-level pod file workspace, while keeping pod files as the primary document store and avoiding embedded-first document editing
+- Notion/Coda-style block documents through `lemma-document-workspace`, with ProseKit JSON content, page/modal modes, title and summary chrome, file/reference/assistant blocks, save state, metadata, backlinks, and assistant-context rails
+- pod-file-native creation, reading, editing, and preview through one workspace, with folder targeting, title/summary setup, pod-file metadata, and `mode="page" | "modal"`
+- non-document file previews through the same workspace, including image, PDF, text, markdown, converted HTML, and download fallback behavior
+- records and attachments should pass pod file paths into `lemma-document-workspace`; records should not own document bodies directly
 
 People blocks support:
 
@@ -348,50 +283,22 @@ People blocks support:
 
 Workflow primitives support:
 
-- lifecycle/status rendering and transitions through `lemma-status-flow`
-- read-only tracker layouts and compact step progress through `lemma-status-flow`
-- workflow run inspection through `lemma-workflow-runner`
-- reusable history and collaboration surfaces through `lemma-activity-feed` and `lemma-comments`
-- table-backed defaults with escape hatches for custom action payloads and render slots
-
-`lemma-markdown-editor` supports:
-
-- write, preview, and split modes
-- controlled and uncontrolled values
-- GitHub-flavored markdown preview via `react-markdown` and `remark-gfm`
-- a lightweight interim editing lane for plain markdown notes beside the richer block-native `lemma-document-workspace`
+- direct, function-backed, workflow-backed, and agent-backed launches through `lemma-action-surface`
+- inline, row, and panel presentation modes for long-running actions with inspectable progress
+- native workflow/file surfaces plus app-local record UIs where tables are the actual product data model
 
 Assistant blocks support:
 
 - assistant-name-first configuration through `assistantName`
 - shared `appearance` and `density` controls on the assistant experience surface
 - `chromeStyle`, `statusPlacement`, `radius`, model picker, conversation list, and render overrides for deeper customization
-
-Shell blocks support:
-
-- `lemma-notification-bell` for unread counts, popover inboxes, and mark-as-read flows
-- `lemma-user-menu` for current-user presentation, custom menu actions, and sign-out affordances
+- bounded default heights for `page` and `side-panel` modes so the message viewport scrolls instead of stretching with content; pass `className="h-full min-h-0"` inside an explicit-height parent when you want a fill-layout assistant like inbox CRM
 
 ```tsx
-import { LemmaRecordsView } from "@/components/lemma/lemma-records-view";
+import { LemmaAssistantExperience } from "@/components/lemma/assistant/assistant-experience";
+import { LemmaActionSurface } from "@/components/lemma/lemma-action-surface";
 import { LemmaGlobalSearch } from "@/components/lemma/lemma-global-search";
 
-<LemmaRecordsView
-  client={client}
-  podId={podId}
-  tableName="deals"
-  preset="crm"
-  hiddenFields={["id", "created_at", "updated_at"]}
-  foreignKeyLabels={{ company_id: "name" }}
-  appearance="minimal"
-  density="compact"
-  createMode="sheet"
-  onCreateOptions={{
-    submitVia: "function",
-    submitFunctionName: "create-deal",
-  }}
-/>;
-
 <LemmaGlobalSearch
   client={client}
   podId={podId}
@@ -416,6 +323,20 @@ import { LemmaGlobalSearch } from "@/components/lemma/lemma-global-search";
   appearance="minimal"
   density="compact"
 />;
+
+<LemmaActionSurface
+  client={client}
+  podId={podId}
+  label="Run triage"
+  kind="workflow"
+  workflowName="triage-lead"
+/>;
+
+<LemmaAssistantExperience
+  client={client}
+  assistantName="sales-copilot"
+  density="compact"
+/>;
 ```
 
 ## Auth
@@ -455,14 +376,14 @@ npm run build
 npm run registry:build
 ```
 
-To build the canonical example desk:
+To build the single local sandbox app:
 
 ```bash
 cd examples/inbox-crm
 npm run build
 ```
 
-`examples/inbox-crm` now mirrors the kept registry surface only. Its local `src/components/lemma` folder is a copied install target of the current canonical registry blocks, and `src/main.tsx` demonstrates those blocks in one routed operator desk.
+`examples/inbox-crm` is the only kept example app in this repo. It is a local sandbox for visualizing the current direction, not a promise that every copied component inside it is a published registry block.
 
 This repo includes:
 

package/dist/openapi_client/models/DatastoreDataType.d.ts

@@ -3,6 +3,7 @@
  */
 export declare enum DatastoreDataType {
     TEXT = "TEXT",
+    FILE_PATH = "FILE_PATH",
     INTEGER = "INTEGER",
     FLOAT = "FLOAT",
     BOOLEAN = "BOOLEAN",
@@ -10,6 +11,7 @@ export declare enum DatastoreDataType {
     DATE = "DATE",
     DATETIME = "DATETIME",
     UUID = "UUID",
+    USER = "USER",
     VECTOR = "VECTOR",
     SERIAL = "SERIAL",
     ENUM = "ENUM"

package/dist/openapi_client/models/DatastoreDataType.js

@@ -8,6 +8,7 @@
 export var DatastoreDataType;
 (function (DatastoreDataType) {
     DatastoreDataType["TEXT"] = "TEXT";
+    DatastoreDataType["FILE_PATH"] = "FILE_PATH";
     DatastoreDataType["INTEGER"] = "INTEGER";
     DatastoreDataType["FLOAT"] = "FLOAT";
     DatastoreDataType["BOOLEAN"] = "BOOLEAN";
@@ -15,6 +16,7 @@ export var DatastoreDataType;
     DatastoreDataType["DATE"] = "DATE";
     DatastoreDataType["DATETIME"] = "DATETIME";
     DatastoreDataType["UUID"] = "UUID";
+    DatastoreDataType["USER"] = "USER";
     DatastoreDataType["VECTOR"] = "VECTOR";
     DatastoreDataType["SERIAL"] = "SERIAL";
     DatastoreDataType["ENUM"] = "ENUM";

package/dist/react/index.d.ts

@@ -38,18 +38,32 @@ export { useFiles } from "./useFiles.js";
 export type { UseFilesOptions, UseFilesResult } from "./useFiles.js";
 export { useFile } from "./useFile.js";
 export type { UseFileOptions, UseFileResult } from "./useFile.js";
+export { useDatastoreQuery } from "./useDatastoreQuery.js";
+export type { UseDatastoreQueryOptions, UseDatastoreQueryResult, } from "./useDatastoreQuery.js";
+export { useUploadFile } from "./useUploadFile.js";
+export type { UploadFileInput, UseUploadFileOptions, UseUploadFileResult, } from "./useUploadFile.js";
+export { useUpdateFile } from "./useUpdateFile.js";
+export type { UpdateFileInput, UseUpdateFileOptions, UseUpdateFileResult, } from "./useUpdateFile.js";
+export { useDeleteFile } from "./useDeleteFile.js";
+export type { UseDeleteFileOptions, UseDeleteFileResult } from "./useDeleteFile.js";
+export { useCreateFolder } from "./useCreateFolder.js";
+export type { CreateFolderInput, UseCreateFolderOptions, UseCreateFolderResult, } from "./useCreateFolder.js";
 export { useFileSearch } from "./useFileSearch.js";
 export type { UseFileSearchOptions, UseFileSearchResult } from "./useFileSearch.js";
 export { useFileTree } from "./useFileTree.js";
 export type { UseFileTreeOptions, UseFileTreeResult } from "./useFileTree.js";
 export { useFilePreview } from "./useFilePreview.js";
 export type { FilePreviewMode, UseFilePreviewOptions, UseFilePreviewResult, } from "./useFilePreview.js";
+export { useGlobalSearch } from "./useGlobalSearch.js";
+export type { GlobalSearchFileResult, GlobalSearchFilesSource, GlobalSearchRecordResult, GlobalSearchResult, GlobalSearchTableSource, UseGlobalSearchOptions, UseGlobalSearchResult, } from "./useGlobalSearch.js";
 export { useTables } from "./useTables.js";
 export type { UseTablesOptions, UseTablesResult } from "./useTables.js";
 export { useTable } from "./useTable.js";
 export type { UseTableOptions, UseTableResult } from "./useTable.js";
 export { useRecords } from "./useRecords.js";
 export type { UseRecordsOptions, UseRecordsResult } from "./useRecords.js";
+export { useRecordAggregates } from "./useRecordAggregates.js";
+export type { RecordAggregateMetric, RecordAggregateOrderBy, UseRecordAggregatesOptions, UseRecordAggregatesResult, } from "./useRecordAggregates.js";
 export { useRecord } from "./useRecord.js";
 export type { UseRecordOptions, UseRecordResult } from "./useRecord.js";
 export { useCreateRecord } from "./useCreateRecord.js";

package/dist/react/index.js

@@ -18,12 +18,19 @@ export { useCurrentUser } from "./useCurrentUser.js";
 export { usePodAccess } from "./usePodAccess.js";
 export { useFiles } from "./useFiles.js";
 export { useFile } from "./useFile.js";
+export { useDatastoreQuery } from "./useDatastoreQuery.js";
+export { useUploadFile } from "./useUploadFile.js";
+export { useUpdateFile } from "./useUpdateFile.js";
+export { useDeleteFile } from "./useDeleteFile.js";
+export { useCreateFolder } from "./useCreateFolder.js";
 export { useFileSearch } from "./useFileSearch.js";
 export { useFileTree } from "./useFileTree.js";
 export { useFilePreview } from "./useFilePreview.js";
+export { useGlobalSearch } from "./useGlobalSearch.js";
 export { useTables } from "./useTables.js";
 export { useTable } from "./useTable.js";
 export { useRecords } from "./useRecords.js";
+export { useRecordAggregates } from "./useRecordAggregates.js";
 export { useRecord } from "./useRecord.js";
 export { useCreateRecord } from "./useCreateRecord.js";
 export { useUpdateRecord } from "./useUpdateRecord.js";

package/dist/react/sql-utils.d.ts

@@ -0,0 +1,8 @@
+import type { RecordFilter } from "../types.js";
+export declare function quoteIdentifierPath(value: string): string;
+export declare function isSimpleIdentifierPath(value: string): boolean;
+export declare function renderIdentifierPath(value: string): string;
+export declare function escapeSqlString(value: string): string;
+export declare function encodeSqlValue(value: unknown): string;
+export declare function renderRecordFilter(filter: RecordFilter): string;
+export declare function renderRecordFilters(filters?: RecordFilter[]): string;

package/dist/react/sql-utils.js

@@ -0,0 +1,62 @@
+function quoteIdentifierPart(value) {
+    return `"${value.replace(/"/g, "\"\"")}"`;
+}
+export function quoteIdentifierPath(value) {
+    return value
+        .split(".")
+        .map((part) => (part === "*" ? part : quoteIdentifierPart(part)))
+        .join(".");
+}
+export function isSimpleIdentifierPath(value) {
+    return /^[A-Za-z_][A-Za-z0-9_$]*(\.(\*|[A-Za-z_][A-Za-z0-9_$]*))*$/.test(value);
+}
+export function renderIdentifierPath(value) {
+    return isSimpleIdentifierPath(value) ? quoteIdentifierPath(value) : value;
+}
+export function escapeSqlString(value) {
+    return value.replace(/'/g, "''");
+}
+export function encodeSqlValue(value) {
+    if (value === null || typeof value === "undefined")
+        return "NULL";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("SQL values must be finite numbers.");
+        }
+        return String(value);
+    }
+    if (typeof value === "bigint")
+        return String(value);
+    if (value instanceof Date)
+        return `'${escapeSqlString(value.toISOString())}'`;
+    if (Array.isArray(value)) {
+        return `(${value.map((entry) => encodeSqlValue(entry)).join(", ")})`;
+    }
+    if (typeof value === "object") {
+        return `'${escapeSqlString(JSON.stringify(value))}'`;
+    }
+    return `'${escapeSqlString(String(value))}'`;
+}
+export function renderRecordFilter(filter) {
+    const field = filter.field?.trim();
+    if (!field) {
+        throw new Error("Record filters require a field.");
+    }
+    const operator = filter.op.trim().toUpperCase();
+    const lhs = renderIdentifierPath(field);
+    const values = Array.isArray(filter.values) ? filter.values : undefined;
+    if ((operator === "IN" || operator === "NOT IN") && values) {
+        return `${lhs} ${operator} ${encodeSqlValue(values)}`;
+    }
+    if ((operator === "IS" || operator === "IS NOT") && typeof filter.value === "undefined") {
+        return `${lhs} ${operator} NULL`;
+    }
+    return `${lhs} ${operator} ${encodeSqlValue(filter.value)}`;
+}
+export function renderRecordFilters(filters) {
+    if (!filters?.length)
+        return "";
+    return filters.map((filter) => `(${renderRecordFilter(filter)})`).join(" AND ");
+}

package/dist/react/useCreateFolder.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface CreateFolderInput {
+    directoryPath?: string;
+    parentId?: string;
+    description?: string;
+}
+export interface UseCreateFolderOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    onSuccess?: (folder: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseCreateFolderResult<TFile extends FileResponse = FileResponse> {
+    createdFolder: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    createFolder: (name: string, options?: CreateFolderInput) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useCreateFolder<TFile extends FileResponse = FileResponse>({ client, podId, enabled, onSuccess, onError, }: UseCreateFolderOptions): UseCreateFolderResult<TFile>;

package/dist/react/useCreateFolder.js

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useCreateFolder({ client, podId, enabled = true, onSuccess, onError, }) {
+    const [createdFolder, setCreatedFolder] = useState(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const createFolder = useCallback(async (name, options = {}) => {
+        const trimmedName = name.trim();
+        if (!enabled || trimmedName.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFolder = await scopedClient.files.folder.create(trimmedName, options);
+            setCreatedFolder(nextFolder);
+            onSuccessRef.current?.(nextFolder);
+            return nextFolder;
+        }
+        catch (createError) {
+            const normalized = normalizeError(createError, "Failed to create folder.");
+            setError(normalized);
+            onErrorRef.current?.(createError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, enabled, podId]);
+    const reset = useCallback(() => {
+        setCreatedFolder(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        createdFolder,
+        isSubmitting,
+        error,
+        createFolder,
+        reset,
+    }), [createFolder, createdFolder, error, isSubmitting, reset]);
+}

package/dist/react/useDatastoreQuery.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { DatastoreQueryResponse } from "../types.js";
+export interface UseDatastoreQueryOptions {
+    client: LemmaClient;
+    podId?: string;
+    query?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseDatastoreQueryResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    response: DatastoreQueryResponse | null;
+    items: TRow[];
+    total: number;
+    sql: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        query?: string | null;
+    }) => Promise<TRow[]>;
+    reset: () => void;
+}
+export declare function useDatastoreQuery<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, enabled, autoLoad, }: UseDatastoreQueryOptions): UseDatastoreQueryResult<TRow>;

package/dist/react/useDatastoreQuery.js

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useDatastoreQuery({ client, podId, query = null, enabled = true, autoLoad = true, }) {
+    const [response, setResponse] = useState(null);
+    const [sql, setSql] = useState("");
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedQuery = typeof query === "string" ? query.trim() : "";
+    const isEnabled = enabled && trimmedQuery.length > 0;
+    const reset = useCallback(() => {
+        setResponse(null);
+        setSql("");
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        const nextQuery = typeof overrides.query === "string"
+            ? overrides.query.trim()
+            : trimmedQuery;
+        if (!enabled || nextQuery.length === 0) {
+            reset();
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        setSql(nextQuery);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextResponse = await scopedClient.datastore.query(nextQuery);
+            if (signal?.aborted)
+                return [];
+            setResponse(nextResponse);
+            return (nextResponse.items ?? []);
+        }
+        catch (queryError) {
+            if (signal?.aborted)
+                return [];
+            setError(normalizeError(queryError, "Failed to execute datastore query."));
+            setResponse(null);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, podId, reset, trimmedQuery]);
+    useEffect(() => {
+        if (!isEnabled || !autoLoad) {
+            if (!isEnabled)
+                reset();
+            return;
+        }
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh, reset]);
+    return useMemo(() => ({
+        response,
+        items: (response?.items ?? []),
+        total: response?.total ?? 0,
+        sql,
+        isLoading,
+        error,
+        refresh,
+        reset,
+    }), [error, isLoading, refresh, reset, response, sql]);
+}

package/dist/react/useDeleteFile.d.ts

@@ -0,0 +1,19 @@
+import type { LemmaClient } from "../client.js";
+export interface UseDeleteFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    onSuccess?: (path: string) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseDeleteFileResult {
+    deletedPath: string | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    remove: (overrides?: {
+        path?: string | null;
+    }) => Promise<boolean>;
+    reset: () => void;
+}
+export declare function useDeleteFile({ client, podId, path, enabled, onSuccess, onError, }: UseDeleteFileOptions): UseDeleteFileResult;

package/dist/react/useDeleteFile.js

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useDeleteFile({ client, podId, path = null, enabled = true, onSuccess, onError, }) {
+    const [deletedPath, setDeletedPath] = useState(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const trimmedPath = typeof path === "string" ? path.trim() : "";
+    const isEnabled = enabled && trimmedPath.length > 0;
+    const remove = useCallback(async (overrides = {}) => {
+        const nextPath = typeof overrides.path === "string"
+            ? overrides.path.trim()
+            : trimmedPath;
+        if (!isEnabled || nextPath.length === 0) {
+            return false;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            await scopedClient.files.delete(nextPath);
+            setDeletedPath(nextPath);
+            onSuccessRef.current?.(nextPath);
+            return true;
+        }
+        catch (removeError) {
+            const normalized = normalizeError(removeError, "Failed to delete file.");
+            setError(normalized);
+            onErrorRef.current?.(removeError);
+            return false;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, podId, trimmedPath]);
+    const reset = useCallback(() => {
+        setDeletedPath(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        deletedPath,
+        isSubmitting,
+        error,
+        remove,
+        reset,
+    }), [deletedPath, error, isSubmitting, remove, reset]);
+}

package/dist/react/useGlobalSearch.d.ts

@@ -0,0 +1,62 @@
+import type { LemmaClient } from "../client.js";
+import type { FileSearchResultSchema, RecordFilter, SearchMethod } from "../types.js";
+export interface GlobalSearchTableSource {
+    key?: string;
+    tableName: string;
+    label?: string;
+    searchFields: string[];
+    displayField?: string;
+    subtitleField?: string;
+    limit?: number;
+    filters?: RecordFilter[];
+}
+export interface GlobalSearchFilesSource {
+    enabled?: boolean;
+    label?: string;
+    limit?: number;
+    searchMethod?: SearchMethod;
+}
+export interface GlobalSearchRecordResult {
+    kind: "record";
+    sourceKey: string;
+    sourceLabel: string;
+    tableName: string;
+    id: string;
+    title: string;
+    subtitle: string | null;
+    record: Record<string, unknown>;
+}
+export interface GlobalSearchFileResult {
+    kind: "file";
+    sourceKey: string;
+    sourceLabel: string;
+    path: string;
+    title: string;
+    subtitle: string | null;
+    result: FileSearchResultSchema;
+}
+export type GlobalSearchResult = GlobalSearchRecordResult | GlobalSearchFileResult;
+export interface UseGlobalSearchOptions {
+    client: LemmaClient;
+    podId?: string;
+    query?: string;
+    tables?: GlobalSearchTableSource[];
+    files?: GlobalSearchFilesSource | false;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    minQueryLength?: number;
+}
+export interface UseGlobalSearchResult {
+    results: GlobalSearchResult[];
+    recordResults: GlobalSearchRecordResult[];
+    fileResults: GlobalSearchFileResult[];
+    totalResults: number;
+    sourceErrors: Record<string, Error>;
+    isLoading: boolean;
+    error: Error | null;
+    search: (overrides?: {
+        query?: string;
+    }) => Promise<GlobalSearchResult[]>;
+    reset: () => void;
+}
+export declare function useGlobalSearch({ client, podId, query, tables, files, enabled, autoLoad, minQueryLength, }: UseGlobalSearchOptions): UseGlobalSearchResult;

package/dist/react/useGlobalSearch.js

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { escapeSqlString, quoteIdentifierPath, renderIdentifierPath, renderRecordFilters } from "./sql-utils.js";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function buildTableSearchQuery(source, query) {
+    const fields = Array.from(new Set([
+        "id",
+        ...source.searchFields,
+        source.displayField ?? "id",
+        source.subtitleField ?? "",
+    ].filter((value) => value.trim().length > 0)));
+    const searchClauses = source.searchFields.map((field) => `${renderIdentifierPath(field)} ILIKE '%${escapeSqlString(query)}%'`);
+    const filterClause = renderRecordFilters(source.filters);
+    return [
+        `SELECT ${fields.map((field) => renderIdentifierPath(field)).join(", ")}`,
+        `FROM ${quoteIdentifierPath(source.tableName)}`,
+        `WHERE (${searchClauses.join(" OR ")})${filterClause ? ` AND ${filterClause}` : ""}`,
+        `LIMIT ${source.limit ?? 8}`,
+    ].join(" ");
+}
+function readString(value) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return null;
+}
+export function useGlobalSearch({ client, podId, query = "", tables = [], files, enabled = true, autoLoad = true, minQueryLength = 1, }) {
+    const [results, setResults] = useState([]);
+    const [sourceErrors, setSourceErrors] = useState({});
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedQuery = query.trim();
+    const tablesKey = stringifyComparable(tables);
+    const filesKey = stringifyComparable(files);
+    const stableTables = useMemo(() => tables, [tablesKey]);
+    const stableFiles = useMemo(() => files, [filesKey]);
+    const reset = useCallback(() => {
+        setResults([]);
+        setSourceErrors({});
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    const search = useCallback(async (overrides = {}, signal) => {
+        const nextQuery = (overrides.query ?? trimmedQuery).trim();
+        if (!enabled || nextQuery.length < minQueryLength) {
+            reset();
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const searchTasks = [];
+            stableTables.forEach((source, index) => {
+                const sourceKey = source.key?.trim() || source.tableName;
+                searchTasks.push((async () => {
+                    try {
+                        const sql = buildTableSearchQuery(source, nextQuery);
+                        const response = await scopedClient.datastore.query(sql);
+                        const rows = response.items ?? [];
+                        const mapped = rows.map((record) => {
+                            const displayField = source.displayField ?? source.searchFields[0] ?? "id";
+                            const subtitleField = source.subtitleField;
+                            const id = readString(record.id) ?? `${source.tableName}-${index}`;
+                            return {
+                                kind: "record",
+                                sourceKey,
+                                sourceLabel: source.label ?? source.tableName,
+                                tableName: source.tableName,
+                                id,
+                                title: readString(record[displayField]) ?? id,
+                                subtitle: subtitleField ? readString(record[subtitleField]) : null,
+                                record,
+                            };
+                        });
+                        return { key: sourceKey, results: mapped };
+                    }
+                    catch (tableError) {
+                        return {
+                            key: sourceKey,
+                            results: [],
+                            error: normalizeError(tableError, `Failed to search ${source.tableName}.`),
+                        };
+                    }
+                })());
+            });
+            if (stableFiles !== false && stableFiles?.enabled !== false) {
+                searchTasks.push((async () => {
+                    const sourceKey = "files";
+                    try {
+                        const response = await scopedClient.files.search(nextQuery, {
+                            limit: stableFiles?.limit ?? 8,
+                            searchMethod: stableFiles?.searchMethod,
+                        });
+                        const mapped = (response.results ?? []).map((result) => ({
+                            kind: "file",
+                            sourceKey,
+                            sourceLabel: stableFiles?.label ?? "Files",
+                            path: result.path,
+                            title: result.path.split("/").filter(Boolean).pop() || result.path,
+                            subtitle: typeof result.content === "string" && result.content.trim().length > 0
+                                ? result.content.slice(0, 160)
+                                : null,
+                            result,
+                        }));
+                        return { key: sourceKey, results: mapped };
+                    }
+                    catch (fileError) {
+                        return {
+                            key: sourceKey,
+                            results: [],
+                            error: normalizeError(fileError, "Failed to search files."),
+                        };
+                    }
+                })());
+            }
+            const settled = await Promise.all(searchTasks);
+            if (signal?.aborted)
+                return [];
+            const nextErrors = {};
+            const nextResults = settled.flatMap((entry) => {
+                if (entry.error) {
+                    nextErrors[entry.key] = entry.error;
+                }
+                return entry.results;
+            });
+            setSourceErrors(nextErrors);
+            setResults(nextResults);
+            return nextResults;
+        }
+        catch (searchError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(searchError, "Failed to run global search.");
+            setError(normalized);
+            setResults([]);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, minQueryLength, podId, reset, stableFiles, stableTables, trimmedQuery]);
+    useEffect(() => {
+        if (!enabled || !autoLoad)
+            return;
+        if (trimmedQuery.length < minQueryLength) {
+            reset();
+            return;
+        }
+        const controller = new AbortController();
+        void search({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, enabled, minQueryLength, reset, search, trimmedQuery]);
+    return useMemo(() => {
+        const recordResults = results.filter((entry) => entry.kind === "record");
+        const fileResults = results.filter((entry) => entry.kind === "file");
+        return {
+            results,
+            recordResults,
+            fileResults,
+            totalResults: results.length,
+            sourceErrors,
+            isLoading,
+            error,
+            search,
+            reset,
+        };
+    }, [error, isLoading, reset, results, search, sourceErrors]);
+}

package/dist/react/useRecordAggregates.d.ts

@@ -0,0 +1,35 @@
+import type { LemmaClient } from "../client.js";
+import type { RecordFilter } from "../types.js";
+export interface RecordAggregateMetric {
+    key: string;
+    op: "count" | "sum" | "avg" | "min" | "max";
+    field?: string;
+    distinct?: boolean;
+}
+export interface RecordAggregateOrderBy {
+    field: string;
+    direction?: "asc" | "desc";
+}
+export interface UseRecordAggregatesOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    metrics: RecordAggregateMetric[];
+    groupBy?: string | string[];
+    filters?: RecordFilter[];
+    limit?: number;
+    offset?: number;
+    orderBy?: RecordAggregateOrderBy[];
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordAggregatesResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    rows: TRow[];
+    row: TRow | null;
+    total: number;
+    sql: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useRecordAggregates<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, metrics, groupBy, filters, limit, offset, orderBy, enabled, autoLoad, }: UseRecordAggregatesOptions): UseRecordAggregatesResult<TRow>;

package/dist/react/useRecordAggregates.js

@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { encodeSqlValue, quoteIdentifierPath, renderIdentifierPath, renderRecordFilters } from "./sql-utils.js";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function buildMetricExpression(metric) {
+    const fn = metric.op.toUpperCase();
+    if (metric.op === "count" && !metric.field) {
+        return `${fn}(*) AS ${quoteIdentifierPath(metric.key)}`;
+    }
+    if (!metric.field) {
+        throw new Error(`Aggregate metric "${metric.key}" requires a field.`);
+    }
+    const renderedField = renderIdentifierPath(metric.field);
+    const distinct = metric.distinct ? "DISTINCT " : "";
+    return `${fn}(${distinct}${renderedField}) AS ${quoteIdentifierPath(metric.key)}`;
+}
+function buildRecordAggregatesQuery({ tableName, metrics, groupBy, filters, limit, offset, orderBy, }) {
+    const groups = (Array.isArray(groupBy) ? groupBy : groupBy ? [groupBy] : [])
+        .map((field) => field.trim())
+        .filter((field) => field.length > 0);
+    const selectParts = [
+        ...groups.map((field) => `${renderIdentifierPath(field)} AS ${quoteIdentifierPath(field)}`),
+        ...metrics.map((metric) => buildMetricExpression(metric)),
+    ];
+    const whereClause = renderRecordFilters(filters);
+    const orderClause = orderBy?.length
+        ? ` ORDER BY ${orderBy.map((entry) => `${renderIdentifierPath(entry.field)} ${(entry.direction ?? "desc").toUpperCase()}`).join(", ")}`
+        : "";
+    const groupClause = groups.length
+        ? ` GROUP BY ${groups.map((field) => renderIdentifierPath(field)).join(", ")}`
+        : "";
+    const limitClause = typeof limit === "number" ? ` LIMIT ${encodeSqlValue(limit)}` : "";
+    const offsetClause = typeof offset === "number" ? ` OFFSET ${encodeSqlValue(offset)}` : "";
+    return [
+        `SELECT ${selectParts.join(", ")}`,
+        `FROM ${quoteIdentifierPath(tableName)}`,
+        whereClause ? `WHERE ${whereClause}` : "",
+        groupClause,
+        orderClause,
+        limitClause,
+        offsetClause,
+    ].filter(Boolean).join(" ");
+}
+export function useRecordAggregates({ client, podId, tableName, metrics, groupBy, filters = [], limit, offset, orderBy, enabled = true, autoLoad = true, }) {
+    const [rows, setRows] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [sql, setSql] = useState("");
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const metricsKey = stringifyComparable(metrics);
+    const filtersKey = stringifyComparable(filters);
+    const groupByKey = stringifyComparable(groupBy);
+    const orderByKey = stringifyComparable(orderBy);
+    const stableMetrics = useMemo(() => metrics, [metricsKey]);
+    const stableFilters = useMemo(() => filters, [filtersKey]);
+    const stableGroupBy = useMemo(() => groupBy, [groupByKey]);
+    const stableOrderBy = useMemo(() => orderBy, [orderByKey]);
+    const trimmedTableName = tableName.trim();
+    const isEnabled = enabled && trimmedTableName.length > 0 && stableMetrics.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setRows([]);
+            setTotal(0);
+            setSql("");
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextSql = buildRecordAggregatesQuery({
+                tableName: trimmedTableName,
+                metrics: stableMetrics,
+                groupBy: stableGroupBy,
+                filters: stableFilters,
+                limit,
+                offset,
+                orderBy: stableOrderBy,
+            });
+            setSql(nextSql);
+            const response = await scopedClient.datastore.query(nextSql);
+            if (signal?.aborted)
+                return [];
+            const nextRows = (response.items ?? []);
+            setRows(nextRows);
+            setTotal(response.total ?? nextRows.length);
+            return nextRows;
+        }
+        catch (aggregateError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(aggregateError, "Failed to load record aggregates.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, isEnabled, limit, offset, podId, stableFilters, stableGroupBy, stableMetrics, stableOrderBy, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRows([]);
+            setTotal(0);
+            setSql("");
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh(controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        rows,
+        row: rows[0] ?? null,
+        total,
+        sql,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, refresh, rows, sql, total]);
+}

package/dist/react/useTaskSession.js

@@ -30,12 +30,13 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
         }
     }, []);
     const setTaskId = useCallback((nextTaskId) => {
-        abortRef.current?.abort();
-        abortRef.current = null;
         setTaskIdState((currentTaskId) => {
             if (currentTaskId === nextTaskId) {
                 return currentTaskId;
             }
+            abortRef.current?.abort();
+            abortRef.current = null;
+            taskIdRef.current = nextTaskId;
             setError(null);
             setIsStreaming(false);
             if (!nextTaskId) {

package/dist/react/useUpdateFile.d.ts

@@ -0,0 +1,29 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UpdateFileInput {
+    file?: Blob;
+    name?: string;
+    description?: string;
+    directoryPath?: string;
+    parentId?: string;
+    newPath?: string;
+    searchEnabled?: boolean;
+}
+export interface UseUpdateFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    onSuccess?: (file: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseUpdateFileResult<TFile extends FileResponse = FileResponse> {
+    updatedFile: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    update: (input?: UpdateFileInput, overrides?: {
+        path?: string | null;
+    }) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useUpdateFile<TFile extends FileResponse = FileResponse>({ client, podId, path, enabled, onSuccess, onError, }: UseUpdateFileOptions): UseUpdateFileResult<TFile>;

package/dist/react/useUpdateFile.js

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useUpdateFile({ client, podId, path = null, enabled = true, onSuccess, onError, }) {
+    const [updatedFile, setUpdatedFile] = useState(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const trimmedPath = typeof path === "string" ? path.trim() : "";
+    const isEnabled = enabled && trimmedPath.length > 0;
+    const update = useCallback(async (input = {}, overrides = {}) => {
+        const nextPath = typeof overrides.path === "string"
+            ? overrides.path.trim()
+            : trimmedPath;
+        if (!isEnabled || nextPath.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFile = await scopedClient.files.update(nextPath, input);
+            setUpdatedFile(nextFile);
+            onSuccessRef.current?.(nextFile);
+            return nextFile;
+        }
+        catch (updateError) {
+            const normalized = normalizeError(updateError, "Failed to update file.");
+            setError(normalized);
+            onErrorRef.current?.(updateError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, podId, trimmedPath]);
+    const reset = useCallback(() => {
+        setUpdatedFile(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        updatedFile,
+        isSubmitting,
+        error,
+        update,
+        reset,
+    }), [error, isSubmitting, reset, update, updatedFile]);
+}

package/dist/react/useUploadFile.d.ts

@@ -0,0 +1,24 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UploadFileInput {
+    name?: string;
+    directoryPath?: string;
+    parentId?: string;
+    searchEnabled?: boolean;
+    description?: string;
+}
+export interface UseUploadFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    onSuccess?: (file: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseUploadFileResult<TFile extends FileResponse = FileResponse> {
+    uploadedFile: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    upload: (file: Blob, options?: UploadFileInput) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useUploadFile<TFile extends FileResponse = FileResponse>({ client, podId, enabled, onSuccess, onError, }: UseUploadFileOptions): UseUploadFileResult<TFile>;

package/dist/react/useUploadFile.js

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useUploadFile({ client, podId, enabled = true, onSuccess, onError, }) {
+    const [uploadedFile, setUploadedFile] = useState(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const upload = useCallback(async (file, options = {}) => {
+        if (!enabled) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFile = await scopedClient.files.upload(file, options);
+            setUploadedFile(nextFile);
+            onSuccessRef.current?.(nextFile);
+            return nextFile;
+        }
+        catch (uploadError) {
+            const normalized = normalizeError(uploadError, "Failed to upload file.");
+            setError(normalized);
+            onErrorRef.current?.(uploadError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, enabled, podId]);
+    const reset = useCallback(() => {
+        setUploadedFile(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        uploadedFile,
+        isSubmitting,
+        error,
+        upload,
+        reset,
+    }), [error, isSubmitting, reset, uploadedFile, upload]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "description": "Official TypeScript SDK for Lemma pod-scoped APIs",
   "type": "module",
   "main": "dist/index.js",