@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/src/index.js

@@ -1,34 +0,0 @@
-/**
- * Lotics App SDK — the runtime + typed hooks bundled into every custom-code
- * app at build time. Apps `import { mount, useQuery, useWorkflow } from
- * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
- *
- * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` component, so an app's dependency on the kit is its own and one
- * version answers for it. That is a packaging choice, NOT a limitation: apps
- * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
- * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
- * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
- * the whole `resolve` block. Build screens by composing kit components (Card,
- * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
- * & components".
- */
-export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export { useComments, useCommentCounts } from "./comments.js";
-export { useViewer } from "./viewer.js";
-export { useRecording } from "./recording.js";
-export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
-export { rpc, isEmbedded } from "./rpc.js";
-export { openExternal } from "./open_external.js";
-export { openApp } from "./open_app.js";
-export { askAi } from "./ask_ai.js";
-export { downloadFile } from "./download.js";
-export { readMembers } from "./members.js";
-export { readSelect } from "./select.js";
-export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt } from "./row.js";
-export { useOptimistic } from "./use_optimistic.js";
-export { useNewRecord, newRecordId } from "./new_record.js";
-export { useRecents } from "./use_recents.js";
-export { useUrlState } from "./use_url_state.js";
-export { urlParam } from "./url_params.js";

package/dist/src/members.d.ts

@@ -1,105 +0,0 @@
-/**
- * Reader for `select_member` cells in `useQuery` rows.
- *
- * The server (`backend/lib/select_member_resolver.ts`) rewrites every
- * `select_member` column from its storage shape (`string[]` of bare member
- * IDs) into `ResolvedMember[]` before the row reaches the app. Apps used to
- * hardcode an id→name fallback map because the SDK didn't expose the
- * resolved shape; this helper makes the right shape the obvious one.
- *
- * If the wire format changes, the resolver and this reader move together.
- */
-/**
- * A member, in the ONE shape every door returns — a `select_member` cell in a
- * `useQuery` row and the `useMembers` roster alike.
- *
- * The two used to disagree: the roster carried an avatar, a resolved cell did
- * not, and both were typed `ResolvedMember`, so an app author holding one could
- * not tell which. That is why no register row ever rendered an avatar — the
- * data was absent and nothing said so.
- *
- * It happened a second time, and the fix is the same: the roster returned
- * neither `groups` nor `role` long after a resolved cell carried both, so an
- * app reading `m.groups` off `useMembers()` got `undefined` and drew nothing.
- * Read a field here and you may read it on either door.
- *
- * The private fields share ONE boundary, not four: an authenticated member of
- * the app's own org sees `email`, `image`, `groups` and `role`; an anonymous
- * visitor to a public app sees `id` and `name` (plus `archived`, which is not
- * private — see the field). Absent ≠ empty — `image: null` means the member has
- * no photo, `image` MISSING means you were never told, and `groups: []` means
- * they are on no team while a missing `groups` means the same "not told". Never
- * collapse the two: one is a fact about a colleague, the other is a fact about
- * your own permissions.
- *
- * The one field the doors legitimately differ on is `archived`, and it is a
- * difference of ROW SET rather than of shape: a resolved cell must keep naming
- * whoever handled a record two years ago, while the roster answers "who may I
- * assign?" and never offers a departed member at all.
- */
-export interface ResolvedMember {
-    id: string;
-    /** `null` when the id resolves outside the app's org (e.g. removed
-     *  member) — surfaces the missing state explicitly instead of an
-     *  empty string. */
-    name: string | null;
-    /** Present only on authenticated responses. Omitted on public-app
-     *  responses (no PII exposure to anonymous visitors). */
-    email?: string | null;
-    /** Avatar URL, already presigned — render it directly. `null` when the member
-     *  has no profile image (the common case: photos are opt-in). Omitted on
-     *  public-app responses. */
-    image?: string | null;
-    /** The member's group names — the platform's "department". There is no
-     *  department field; a member group is what an org uses to say Sale, Kế toán,
-     *  CSKH. `[]` when the member is in none. Omitted on public-app responses. */
-    groups?: string[];
-    /**
-     * The member's ORGANIZATION role. Omitted on public-app responses, and also
-     * when the id did not resolve — there is no member to have a level.
-     *
-     * It arrives RAW, and it is your job to translate it: the platform ships no
-     * display word for it, because a server that picked one would leak English
-     * into every localized app. Map it yourself (`admin` → "Quản trị viên") next
-     * to the rest of your vocabulary.
-     *
-     * It is a PERMISSION level and not a job title. Everyone who reads "Admin"
-     * beside a name on a sales register will read it as rank; if the question
-     * your screen answers is "who is this person in the company", the answer is
-     * `groups`, not this.
-     */
-    role?: "owner" | "admin" | "member";
-    /**
-     * ISO timestamp of when this person joined the organization. Omitted on
-     * public-app responses, and when the id did not resolve — there is no
-     * membership to have begun.
-     *
-     * Render it at whatever precision your question needs; `@lotics/ui`'s
-     * `MemberProfileCard` shows month and year, because "is this the new person?"
-     * does not want a day.
-     */
-    joined?: string;
-    /**
-     * `true` when this person has LEFT the organization — omitted otherwise,
-     * never `false`, because it rides every cell of every row and current staff
-     * are the overwhelming case.
-     *
-     * It arrives on both audiences: a departed colleague reading as a current
-     * assignee is wrong on a public app too, and it discloses less than the name
-     * already beside it. Feed it to `inactive` on `MemberChip` /
-     * `MemberProfileCard` so a record that still names them reads as history
-     * rather than as a live assignment.
-     *
-     * You will not see it on the `useMembers` roster, and that is correct rather
-     * than missing: the roster answers "who may I ASSIGN?" and departed members
-     * are not candidates, so it never returns one.
-     */
-    archived?: true;
-}
-/**
- * Parse a `useQuery` cell value into `ResolvedMember[]`. Returns `[]` for
- * null/undefined/empty cells and for any unexpected shape — callers iterate
- * uniformly without null-checks. Entries that fail the shape check are
- * dropped silently rather than corrupting the array with partial data.
- */
-export declare function readMembers(value: unknown): ResolvedMember[];

package/dist/src/members.js

@@ -1,62 +0,0 @@
-/**
- * Reader for `select_member` cells in `useQuery` rows.
- *
- * The server (`backend/lib/select_member_resolver.ts`) rewrites every
- * `select_member` column from its storage shape (`string[]` of bare member
- * IDs) into `ResolvedMember[]` before the row reaches the app. Apps used to
- * hardcode an id→name fallback map because the SDK didn't expose the
- * resolved shape; this helper makes the right shape the obvious one.
- *
- * If the wire format changes, the resolver and this reader move together.
- */
-/**
- * Parse a `useQuery` cell value into `ResolvedMember[]`. Returns `[]` for
- * null/undefined/empty cells and for any unexpected shape — callers iterate
- * uniformly without null-checks. Entries that fail the shape check are
- * dropped silently rather than corrupting the array with partial data.
- */
-export function readMembers(value) {
-    if (!Array.isArray(value))
-        return [];
-    const out = [];
-    for (const entry of value) {
-        if (!entry || typeof entry !== "object")
-            continue;
-        const obj = entry;
-        const id = obj.id;
-        if (typeof id !== "string" || id === "")
-            continue;
-        const name = typeof obj.name === "string" ? obj.name : obj.name === null ? null : null;
-        const m = { id, name };
-        // PRESENT ⇒ copy, ABSENT ⇒ leave off. The distinction is the permission
-        // boundary itself: a missing key means a public reader was never told,
-        // while `null` means the member genuinely has none. Defaulting either to
-        // null here would erase that and make a gated field look like an empty one.
-        if ("email" in obj)
-            m.email = typeof obj.email === "string" ? obj.email : null;
-        if ("image" in obj)
-            m.image = typeof obj.image === "string" ? obj.image : null;
-        if ("groups" in obj) {
-            m.groups = Array.isArray(obj.groups)
-                ? obj.groups.filter((g) => typeof g === "string")
-                : [];
-        }
-        // A CLOSED enum, so an unrecognized value is dropped rather than passed
-        // through: the field's whole worth is that a caller can switch on it, and a
-        // server that grew a fourth role must not have apps rendering the raw word
-        // in a UI that has no translation for it.
-        if (obj.role === "owner" || obj.role === "admin" || obj.role === "member")
-            m.role = obj.role;
-        // A non-empty STRING or nothing: an empty date is not a date, and letting
-        // "" through would render an empty labelled row rather than no row.
-        if (typeof obj.joined === "string" && obj.joined !== "")
-            m.joined = obj.joined;
-        // The server sends this ONLY for a departed member and only as `true`, so
-        // the truthy test is the whole contract — there is no `false` to carry, and
-        // inventing one would put the key on every current member's cell.
-        if (obj.archived === true)
-            m.archived = true;
-        out.push(m);
-    }
-    return out;
-}

package/dist/src/mock.d.ts

@@ -1,118 +0,0 @@
-/**
- * Demo / design-time fixture support for `useQuery` and `useWorkflow`.
- *
- * Activation contract:
- *
- *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: MockQuery }, workflows: { alias: MockWorkflow } }`
- *      map keyed by the same aliases the app declared in
- *      `package.json#lotics.queries` / `#lotics.workflows`.
- *   2. At runtime, the user (or a screenshot script) loads the app with the
- *      `?__mock=1` URL search param. Without that param the SDK ignores the
- *      fixture entirely and both hooks flow through the RPC bridge as usual.
- *
- * The two-step gate keeps demo data shipping in the bundle from leaking into
- * normal traffic — the param namespace (`__mock` prefix) is reserved and
- * unlikely to collide with app-side query state. Apps that don't pass a
- * fixture pay nothing: `getMockRows` / `getMockWorkflow` return `null` for
- * every alias and the hook path is unchanged.
- *
- * `workflows` exists because the side-effect argument runs the other way: a
- * mocked workflow does not RUN, so it produces no notification and no audit
- * trail — it PREVENTS them. What it cannot produce is the followup state a
- * subsequent `useQuery` would read, which is the author's call and is already
- * true of a mocked query. Without it, an app whose only AI surface is a
- * workflow that reads and calls `agent(...)` — the standard shape — had no
- * non-billing path to its own in-flight / done / error states at all, so those
- * three screens could not be reviewed without spending on a live workspace.
- *
- * A fixture entry may be the RESULT, or a FUNCTION of the call. For a workflow
- * the function form is what makes the in-flight state reachable: resolve on a
- * timer and the app renders the pending branch it otherwise never shows. It also
- * lets one alias answer differently per input, which is how an error branch is
- * reviewed beside a success one. For a query it is what reproduces a NARROWED
- * surface: the server applies `filter`/`sort`/`limit` after the named query, and
- * a static row array cannot, so a master/detail drawer under `?__mock=1` would
- * otherwise show every parent's children under every parent.
- *
- * `recordings` hands `useRecording` a canned state per alias, so each state a
- * recording act passes through can be drawn without a host that records.
- *
- * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
- * different shape from a request/response pair, and nothing has needed it.
- */
-import type { WorkflowResult } from "./hooks.js";
-import type { RecordingState } from "./recording_state.js";
-/**
- * What a mocked workflow answers with: a fixed result, or a function of the
- * inputs it was called with. Return a promise from the function to hold the
- * caller in its pending state for as long as the review needs.
- */
-export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
-/** The call a mocked query is answering: the alias's params plus the per-call
- *  refinement the screen passed. A master/detail surface narrows by `filter`,
- *  so a fixture that ignores it renders every parent's children under every
- *  parent — right-looking and wrong. */
-export interface MockQueryCall {
-    params: Record<string, unknown>;
-    filter?: unknown;
-    sort?: unknown;
-    limit?: number;
-}
-/**
- * What a mocked query answers with: fixed rows, or a function of the call.
- *
- * The function form is the one that reproduces a FILTERED surface. The server
- * applies `filter`/`sort`/`limit` after the named query; the fixture path has no
- * query engine, and re-implementing the filter grammar here would ship a second,
- * divergent copy of it — so the fixture decides, from the call it was handed,
- * which rows that call returns.
- */
-export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>>);
-export interface AppFixture {
-    /** Map of query alias → the rows the hook returns when mock mode is on, or a
-     *  function of the call for a surface that narrows per call. */
-    queries?: Record<string, MockQuery>;
-    /** Map of workflow alias → the result it resolves with when mock mode is on.
-     *  The workflow never executes, so nothing it would have written is written. */
-    workflows?: Record<string, MockWorkflow>;
-    /** Map of workflow alias → the state `useRecording(alias)` reports when mock
-     *  mode is on. It reads as available, and `start`/`stop` resolve without
-     *  recording anything or changing the state. */
-    recordings?: Record<string, RecordingState>;
-}
-/**
- * Called by `mount({ fixture })`. Module-level state because the SDK has no
- * React context boundary around the iframe — every hook resolves against the
- * same registration. Calling twice replaces (last-write-wins) which is fine
- * for HMR.
- */
-export declare function registerMockFixture(fixture: AppFixture | undefined): void;
-/**
- * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
- * a malformed URL or missing `window` (SSR / jsdom without location) silently
- * returns false. Distinct from `isMockMode`: a caller may key off the raw flag
- * (a design-time / screenshot load emits no events regardless of fixtures),
- * while query mocking additionally requires a registered fixture.
- */
-export declare function hasMockFlag(): boolean;
-/**
- * Returns the fixture rows for an alias when mock mode is active *and* the
- * fixture has an entry for that alias. Otherwise null — the hook falls
- * through to the real RPC path. The distinction matters: an app may mock
- * only some queries and let the rest flow through to real data.
- */
-export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | null;
-/**
- * The fixture entry for a workflow alias when mock mode is active *and* the
- * fixture has an entry for it. Otherwise null — the hook falls through to the
- * real RPC path, so an app may mock one workflow and let the rest execute.
- *
- * Resolved when the workflow is CALLED rather than when the hook is created, so
- * a fixture registered after mount (or replaced by HMR) is picked up, and an
- * app that never calls the workflow pays nothing.
- */
-export declare function getMockWorkflow(alias: string): MockWorkflow | null;
-/** The canned recording states when mock mode is active and the fixture names
- *  any; otherwise null, and `useRecording` reads the host. */
-export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/src/mock.js

@@ -1,124 +0,0 @@
-/**
- * Demo / design-time fixture support for `useQuery` and `useWorkflow`.
- *
- * Activation contract:
- *
- *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: MockQuery }, workflows: { alias: MockWorkflow } }`
- *      map keyed by the same aliases the app declared in
- *      `package.json#lotics.queries` / `#lotics.workflows`.
- *   2. At runtime, the user (or a screenshot script) loads the app with the
- *      `?__mock=1` URL search param. Without that param the SDK ignores the
- *      fixture entirely and both hooks flow through the RPC bridge as usual.
- *
- * The two-step gate keeps demo data shipping in the bundle from leaking into
- * normal traffic — the param namespace (`__mock` prefix) is reserved and
- * unlikely to collide with app-side query state. Apps that don't pass a
- * fixture pay nothing: `getMockRows` / `getMockWorkflow` return `null` for
- * every alias and the hook path is unchanged.
- *
- * `workflows` exists because the side-effect argument runs the other way: a
- * mocked workflow does not RUN, so it produces no notification and no audit
- * trail — it PREVENTS them. What it cannot produce is the followup state a
- * subsequent `useQuery` would read, which is the author's call and is already
- * true of a mocked query. Without it, an app whose only AI surface is a
- * workflow that reads and calls `agent(...)` — the standard shape — had no
- * non-billing path to its own in-flight / done / error states at all, so those
- * three screens could not be reviewed without spending on a live workspace.
- *
- * A fixture entry may be the RESULT, or a FUNCTION of the call. For a workflow
- * the function form is what makes the in-flight state reachable: resolve on a
- * timer and the app renders the pending branch it otherwise never shows. It also
- * lets one alias answer differently per input, which is how an error branch is
- * reviewed beside a success one. For a query it is what reproduces a NARROWED
- * surface: the server applies `filter`/`sort`/`limit` after the named query, and
- * a static row array cannot, so a master/detail drawer under `?__mock=1` would
- * otherwise show every parent's children under every parent.
- *
- * `recordings` hands `useRecording` a canned state per alias, so each state a
- * recording act passes through can be drawn without a host that records.
- *
- * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
- * different shape from a request/response pair, and nothing has needed it.
- */
-let registeredFixture;
-/** Aliases already warned about a static fixture under a filtered call. */
-const warnedStaticFilter = new Set();
-/**
- * Called by `mount({ fixture })`. Module-level state because the SDK has no
- * React context boundary around the iframe — every hook resolves against the
- * same registration. Calling twice replaces (last-write-wins) which is fine
- * for HMR.
- */
-export function registerMockFixture(fixture) {
-    registeredFixture = fixture;
-}
-/**
- * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
- * a malformed URL or missing `window` (SSR / jsdom without location) silently
- * returns false. Distinct from `isMockMode`: a caller may key off the raw flag
- * (a design-time / screenshot load emits no events regardless of fixtures),
- * while query mocking additionally requires a registered fixture.
- */
-export function hasMockFlag() {
-    try {
-        return new URLSearchParams(window.location.search).get("__mock") === "1";
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * True iff the iframe URL carries the `__mock=1` activation flag AND a
- * fixture was registered. Safe to call before mount — returns false when no
- * fixture exists.
- */
-function isMockMode() {
-    return Boolean(registeredFixture) && hasMockFlag();
-}
-/**
- * Returns the fixture rows for an alias when mock mode is active *and* the
- * fixture has an entry for that alias. Otherwise null — the hook falls
- * through to the real RPC path. The distinction matters: an app may mock
- * only some queries and let the rest flow through to real data.
- */
-export function getMockRows(alias, call) {
-    if (!isMockMode())
-        return null;
-    const fixture = registeredFixture?.queries?.[alias];
-    if (fixture === undefined)
-        return null;
-    if (typeof fixture === "function")
-        return fixture(call);
-    // A static fixture cannot honour the call's narrowing, and the divergence is
-    // otherwise invisible — a drawer showing four rows where production shows two
-    // reads as a correct render. Said once per alias, at the first call that asks.
-    if (call.filter !== undefined && !warnedStaticFilter.has(alias)) {
-        warnedStaticFilter.add(alias);
-        console.warn(`Mock fixture for query "${alias}" is a static row array, so the filter passed to this call ` +
-            `is not applied — the mocked screen shows rows production would exclude. Make ` +
-            `fixture.queries.${alias} a function of the call to narrow it.`);
-    }
-    return fixture;
-}
-/**
- * The fixture entry for a workflow alias when mock mode is active *and* the
- * fixture has an entry for it. Otherwise null — the hook falls through to the
- * real RPC path, so an app may mock one workflow and let the rest execute.
- *
- * Resolved when the workflow is CALLED rather than when the hook is created, so
- * a fixture registered after mount (or replaced by HMR) is picked up, and an
- * app that never calls the workflow pays nothing.
- */
-export function getMockWorkflow(alias) {
-    if (!isMockMode())
-        return null;
-    return registeredFixture?.workflows?.[alias] ?? null;
-}
-/** The canned recording states when mock mode is active and the fixture names
- *  any; otherwise null, and `useRecording` reads the host. */
-export function getMockRecordings() {
-    if (!isMockMode())
-        return null;
-    return registeredFixture?.recordings ?? null;
-}

package/dist/src/mount.d.ts

@@ -1,47 +0,0 @@
-/**
- * Entry point for Lotics custom-code apps.
- *
- * Usage in a user's `src/main.tsx`:
- *
- * ```tsx
- * import { mount } from "@lotics/app-sdk";
- * import App from "./App";
- *
- * mount(<App />);
- * ```
- *
- * Optional second argument registers a demo/design-time fixture. When the
- * iframe is loaded with `?__mock=1`, `useQuery` returns rows from the
- * fixture instead of hitting the RPC bridge. Without the URL flag the
- * fixture is inert — useful for taking screenshots or iterating on
- * dashboard layouts before real data exists.
- *
- * ```tsx
- * mount(<App />, {
- *   fixture: {
- *     queries: { customers: MOCK_CUSTOMERS, deals: MOCK_DEALS },
- *   },
- * });
- * ```
- *
- * `mount` wires up React 19's createRoot against `#root` in the iframe shell,
- * sets up window.onerror/unhandledrejection forwarding so runtime crashes
- * surface in the parent's debug pane, registers the fixture (if any), renders
- * the user's tree.
- *
- * If the bundler doesn't ship #root in the user's `index.html`, we create it
- * — Vite's default scaffold provides one, but defensive creation keeps the
- * mount resilient.
- */
-import type { ReactNode } from "react";
-import { type AppFixture } from "./mock.js";
-export interface MountOptions {
-    /**
-     * Optional demo fixture. When the iframe URL contains `?__mock=1`,
-     * `useQuery(alias)` returns `fixture.queries[alias]` instead of calling
-     * the RPC bridge. Aliases not present in the fixture still flow through
-     * the real path — partial mocking is supported.
-     */
-    fixture?: AppFixture;
-}
-export declare function mount(element: ReactNode, options?: MountOptions): void;

package/dist/src/mount.js

@@ -1,34 +0,0 @@
-import { createRoot } from "react-dom/client";
-import { registerMockFixture } from "./mock.js";
-export function mount(element, options = {}) {
-    registerMockFixture(options.fixture);
-    let container = document.getElementById("root");
-    if (!container) {
-        container = document.createElement("div");
-        container.id = "root";
-        document.body.appendChild(container);
-    }
-    // Surface the most common silent-failure modes (a thrown render error or an
-    // unhandled rejection) as visible text in the iframe so the developer sees
-    // *something* even before the parent's debug telemetry is wired up.
-    installVisibleErrorHandlers(container);
-    createRoot(container).render(element);
-}
-function installVisibleErrorHandlers(container) {
-    const showError = (message) => {
-        const banner = document.createElement("pre");
-        banner.style.cssText =
-            "position: fixed; top: 0; left: 0; right: 0; padding: 12px 16px; " +
-                "background: #fef2f2; color: #991b1b; font: 13px/1.4 monospace; " +
-                "white-space: pre-wrap; border-bottom: 1px solid #fecaca; margin: 0; z-index: 99999;";
-        banner.textContent = message;
-        container.parentElement?.insertBefore(banner, container);
-    };
-    window.addEventListener("error", (e) => {
-        showError(`Uncaught error: ${e.message}\n${e.error?.stack ?? ""}`);
-    });
-    window.addEventListener("unhandledrejection", (e) => {
-        const reason = e.reason instanceof Error ? `${e.reason.message}\n${e.reason.stack ?? ""}` : String(e.reason);
-        showError(`Unhandled rejection: ${reason}`);
-    });
-}

package/dist/src/new_record.d.ts

@@ -1,74 +0,0 @@
-/**
- * Mint a record id locally, in the shape the platform mints.
- *
- * The generator is restated here rather than imported because the canonical one
- * lives in a package that is not published, and this one is. The duplication is
- * safe by construction rather than by discipline: the server validates the shape on
- * every write, so a client that drifted would be rejected loudly at the first call
- * instead of quietly persisting a malformed primary key.
- *
- * Uses `crypto.getRandomValues` — available in every browser this SDK runs in — and
- * rejection-samples so each character is uniformly drawn from the alphabet. A plain
- * `% 62` over bytes would bias the first 8 characters, which is a poor property for
- * something used as a primary key.
- */
-export declare function newRecordId(): string;
-export interface NewRecordApi<P> {
-    /**
-     * The id this surface writes under, stable from the first render — before the
-     * record exists, and unchanged by its creation.
-     */
-    id: string;
-    /**
-     * Persist a patch. The first call creates the record, every later one updates it.
-     * Calls are serialised, so firing several before the first resolves is safe.
-     *
-     * Rejects with whatever `create`/`update` rejected with; a failed create leaves the
-     * record uncreated and the next call will try again.
-     */
-    save: (patch: P) => Promise<void>;
-}
-/**
- * A record that does not exist yet, named before it does.
- *
- * The problem this removes: when the server mints the id, a surface editing a new
- * record has nothing to identify it by until the first write returns. Everything
- * keyed on that id — the route, the drawer, a list selection — therefore changes
- * identity mid-edit, which React resolves by remounting the surface the user is
- * typing into. Minting the id locally makes it stable from the first render, so the
- * create stops being an event the UI has to survive.
- *
- * Creation still happens on the first write, not on mount: a surface the user opens
- * and abandons should leave nothing behind.
- *
- * The transport is the caller's. Like `useOptimistic`, this hook has no idea how the
- * app persists anything — it takes `create` and `update` thunks and owns only the id
- * and the ordering, which is the part that is easy to get wrong:
- *
- * - Two blur-saves fired before the first resolves must not both create. That is a
- *   duplicate record, and it is the failure this exists to prevent.
- * - A save arriving mid-create must wait for it, or it updates a row that is not
- *   there yet.
- * - A create that FAILS must not latch. Otherwise every later save updates a record
- *   that was never written, and the user's work goes nowhere while looking saved.
- *
- * ```tsx
- * const { id, save } = useNewRecord({
- *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
- *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
- *   onCreated: (id) => select(id),   // it exists now — the list re-reads itself
- * });
- * <InlineText onBlur={(name) => save({ name })} />
- * ```
- */
-export declare function useNewRecord<P>(opts: {
-    create: (id: string, patch: P) => Promise<unknown>;
-    update: (id: string, patch: P) => Promise<unknown>;
-    /**
-     * Runs once, after the record first exists, with its id. NOT for refetching a
-     * list — the `create` workflow's own success already re-read it. This is for
-     * what only the id can drive: routing to the record, selecting it, dropping the
-     * surface's "new" state.
-     */
-    onCreated?: (id: string) => void;
-}): NewRecordApi<P>;