@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/index.js.LEGAL.txt

@@ -0,0 +1,11 @@
+Bundled license information:
+
+jexpr/lib/constants.js:
+jexpr/lib/tokenizer.js:
+jexpr/lib/parser.js:
+jexpr/lib/ast_factory.js:
+jexpr/lib/eval.js:
+  /*
+   * @license
+   * Portions Copyright (c) 2013, the Dart project authors.
+   */

package/dist/members.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A member, in the one shape a `select_member` cell and the `useMembers`
+ * roster both return. `email`, `image`, `groups`, `role` and `joined` reach
+ * only an authenticated member of the org; a public visitor sees `id`, `name`
+ * and `archived`. Absent is not empty: `image: null` is "no photo", a missing
+ * `image` is "not told".
+ */
+export interface ResolvedMember {
+    id: string;
+    /** `null` for an id outside the org (a removed member). */
+    name: string | null;
+    email?: string | null;
+    /** Presigned; `null` without a photo. */
+    image?: string | null;
+    /** Group names — the platform's "department"; `[]` when in none. */
+    groups?: string[];
+    /**
+     * The organization PERMISSION level, not a job title — "who is this person"
+     * is `groups`. Raw: translate it yourself.
+     */
+    role?: "owner" | "admin" | "member";
+    /** ISO timestamp of joining the organization. */
+    joined?: string;
+    /**
+     * `true` for a member who has left; never `false`. Feed it to `inactive` on
+     * `MemberChip` / `MemberProfileCard`. The roster never returns one, since a
+     * departed member cannot be assigned.
+     */
+    archived?: true;
+}
+/** `[]` for an empty or malformed cell; malformed entries are dropped. */
+export declare function readMembers(value: unknown): ResolvedMember[];

package/dist/mock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Design-time fixtures, active only with BOTH `mount(<App />, { fixture })`
+ * and the `?__mock=1` URL param, so demo data in a bundle never answers real
+ * traffic. A mocked workflow never runs, so it writes nothing and nothing is
+ * drawn ahead of it; a success re-reads every mounted read.
+ * `useFileUpload` is not mocked.
+ */
+import type { QueryAggregate } from "./shared_types.js";
+import type { WorkflowResult } from "./hooks.js";
+import type { QuerySortKey } from "./queries.js";
+import type { RecordingState } from "./recording_state.js";
+/** A result, or a function of the inputs — return a slow promise to review the pending state. */
+export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
+export interface MockQueryCall {
+    params: Record<string, unknown>;
+    filter?: unknown;
+    sort?: readonly QuerySortKey[];
+    limit?: number;
+    /** The groups the call asks for: a fixture answers the query's rows, and they are folded into these after it. */
+    aggregate?: QueryAggregate;
+}
+/** Rows, or a function of the call — the only way to honour `filter`/`sort`/`limit`, which the fixture path has no engine for. */
+export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>>);
+export interface AppFixture {
+    queries?: Record<string, MockQuery>;
+    workflows?: Record<string, MockWorkflow>;
+    /** `useRecording(alias)` reads as available; `start`/`stop` change nothing. */
+    recordings?: Record<string, RecordingState>;
+}
+export declare function registerMockFixture(fixture: AppFixture | undefined): void;
+/** The raw `?__mock=1` flag, fixture or not; false where `window.location` is absent. */
+export declare function hasMockFlag(): boolean;
+/** Null for an unmocked alias, which reads real data. */
+export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | null;
+/** Null for an unmocked alias, which executes for real. */
+export declare function getMockWorkflow(alias: string): MockWorkflow | null;
+export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/mount.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An app's entry: `mount(<App />)` in `src/main.tsx`. A `fixture` answers
+ * reads only under `?__mock=1`:
+ *
+ * ```tsx
+ * mount(<App />, {
+ *   fixture: {
+ *     queries: { customers: MOCK_CUSTOMERS, deals: MOCK_DEALS },
+ *   },
+ * });
+ * ```
+ */
+import type { ReactNode } from "react";
+import { type AppFixture } from "./mock.js";
+export interface MountOptions {
+    /** Under `?__mock=1`; an alias it lacks reads real data. */
+    fixture?: AppFixture;
+}
+export declare function mount(element: ReactNode, options?: MountOptions): void;

package/dist/new_record.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A record id in the platform's shape, restated because the canonical
+ * generator is unpublished; the server validates the shape on every write.
+ * Rejection-sampled, since `% 62` over bytes would bias the first 8 characters.
+ */
+export declare function newRecordId(): string;
+export interface NewRecordApi<P> {
+    /** Stable from the first render, before and after the record exists. */
+    id: string;
+    /**
+     * The first call creates, later ones update, serialised in order. Rejects as
+     * `create`/`update` did; a failed create leaves the next call to try again.
+     */
+    save: (patch: P) => Promise<void>;
+}
+/**
+ * A new record named before it exists, so a surface keyed on its id never
+ * remounts on the first save. Created on the first write, not on mount, so an
+ * abandoned surface leaves nothing. The hook owns the id and the ordering: two
+ * early saves never both create, a save mid-create waits, and a failed create
+ * does not latch.
+ *
+ * ```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>;
+    /** Once the record exists — for routing or selecting it, not refetching (the create already re-read). */
+    onCreated?: (id: string) => void;
+}): NewRecordApi<P>;

package/dist/open_app.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Land on `route` — the target app's own path — inside sibling app `appId`,
+ * same tab.
+ *
+ * ```tsx
+ * import { openApp } from "@lotics/app-sdk";
+ * await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
+ * ```
+ *
+ * Rejects standalone; gate on `isEmbedded()`.
+ */
+export declare function openApp(appId: string, route?: string): Promise<void>;

package/dist/open_external.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Open a URL in a new tab — the sandboxed iframe drops a direct `window.open`.
+ * Only `http`/`https`; anything else rejects.
+ *
+ * ```tsx
+ * import { openExternal } from "@lotics/app-sdk";
+ * await openExternal(invoiceUrl);
+ * ```
+ */
+export declare function openExternal(url: string): Promise<void>;

package/dist/overlay.d.ts

@@ -0,0 +1,25 @@
+import { type QueryAggregate } from "./shared_types.js";
+import type { TableRecordFilters } from "./shared_types.js";
+import { type Row } from "./written.js";
+export interface Overlaid<T = readonly Row[]> {
+    rows: T;
+    /** A write this app made touches this read, and not all of what it changes is drawn. */
+    pending: boolean;
+}
+type SortKeys = readonly {
+    field_key: string;
+    order: "asc" | "desc";
+    blank_position?: "top" | "bottom";
+}[] | 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.
+ */
+export declare function overlayRead(alias: string, params: Readonly<Record<string, unknown>>, narrowing: TableRecordFilters | undefined, sort: SortKeys, askedAt: number, rows: readonly Row[], adds: boolean): Overlaid;
+/** A read's rows asked for their groups at run time, with each staged write counted into them. */
+export declare function overlayGroups(alias: string, params: Readonly<Record<string, unknown>>, narrowing: TableRecordFilters | undefined, aggregate: QueryAggregate, askedAt: number, rows: readonly Row[]): Overlaid;
+/** The count of a read's rows with each staged write counted in or out. */
+export declare function overlayCount(alias: string, params: Readonly<Record<string, unknown>>, narrowing: TableRecordFilters | undefined, askedAt: number, total: number): Overlaid<number>;
+/** A count per value of `by`, keyed as a row carries it, with each staged write counted in or out. */
+export declare function overlayCounts(alias: string, params: Readonly<Record<string, unknown>>, narrowing: TableRecordFilters | undefined, by: string, askedAt: number, counts: Readonly<Record<string, number>>): Overlaid<Readonly<Record<string, number>>>;
+export {};

package/dist/queries.d.ts

@@ -0,0 +1,231 @@
+import type { QueryAggregate } from "./shared_types.js";
+import type { AppQueries, AppQueryColumns } from "./types.js";
+import type { ResolvedOption } from "./select.js";
+/**
+ * One row of a query whose columns codegen could not read (a dynamic alias, a
+ * bare `from_table`). Values stay `unknown` — the cell readers narrow them.
+ * Only the two addressing columns are typed, because they are handed raw to a
+ * `record_id` / `table_id`; every other `__*` column has a reader that owns it.
+ */
+export interface QueryRow {
+    [column: string]: unknown;
+    /** The record this row came from. Absent on a grouped/aggregated row. */
+    __source_record_id?: string;
+    /** The table that record lives in. Absent on a grouped/aggregated row. */
+    __source_table_id?: string;
+}
+/**
+ * The row type of alias `K`: its projected columns plus the two addressing
+ * columns, and no index signature — a column the query does not carry reads
+ * back `undefined` and renders blank, so it must fail `tsc` instead.
+ */
+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> {
+    field_key: C;
+    order: "asc" | "desc";
+    /** Where blank cells sit; `"bottom"` when omitted. */
+    blank_position?: "top" | "bottom";
+}
+export interface QueryFilterFieldCondition<C extends string = string> {
+    node_type: "condition";
+    field_key: C;
+    type?: string;
+    operator: string;
+    value?: unknown;
+    /** A comparison on a figure read in each row's own unit or currency: the option, by key, its value is in. */
+    unit_option?: string;
+}
+/** A condition on the row's own id — no `field_key`, since no field holds it. */
+export interface QueryFilterRecordIdCondition {
+    node_type: "condition";
+    type: "record_id";
+    operator: string;
+    value?: unknown;
+}
+export type QueryFilterCondition<C extends string = string> = QueryFilterFieldCondition<C> | QueryFilterRecordIdCondition;
+export interface QueryFilterGroup<C extends string = string> {
+    node_type: "group";
+    logic: "and" | "or";
+    children: Array<QueryFilterCondition<C> | QueryFilterGroup<C>>;
+}
+/**
+ * Runtime filter applied after the named query, bounded to its projected
+ * columns — by `C` at compile time and again on the server. Build a group with
+ * `columnFilterToConditions` (`@lotics/ui/column_filter`).
+ */
+export type QueryFilter<C extends string = string> = QueryFilterCondition<C> | QueryFilterGroup<C>;
+/** A `filter`/`sort` key on alias `K`: its projected columns, else `string`. */
+export type ColumnKeyOf<K extends string> = K extends keyof AppQueryColumns ? AppQueryColumns[K] & string : string;
+export interface QueryOptions<C extends string = string> {
+    /**
+     * `false` sends no request and leaves `rows` empty — gate a search until
+     * there is a term, since an empty-term search matches every row. Default `true`.
+     */
+    enabled?: boolean;
+    /** `false` skips a re-read on focus and reconnect. Default `true`. */
+    revalidateOnFocus?: boolean;
+    /** Part of the read's key; empty keeps the query's own order. */
+    sort?: QuerySortKey<C>[];
+    /** Part of the read's key. */
+    filter?: QueryFilter<C>;
+    /** The first `limit` rows only — a cap, not pages; the server clamps to its own maximum. */
+    limit?: number;
+    /** Numbered pages of `page` rows: `page`, `setPage`, `pageCount`, and the total they are counted from. */
+    page?: number;
+    /**
+     * The page in view where the screen keeps it — in its address, so a way back or a reload opens on it:
+     * `at` is read, `setPage` calls `onChange`, and a changed read never resets it. Absent, the read keeps its own.
+     */
+    pageAt?: {
+        at: number;
+        onChange: (page: number) => void;
+    };
+    /** A feed read `more` rows at a time: `loadMore` appends the next, and a shifting set never skips a row. */
+    more?: number;
+    /**
+     * The total the rows come to — a count of the whole set, its own read, so the rows never wait for it —
+     * or with `by` a count per value of that column from the same scan. On by default with `page`.
+     */
+    total?: boolean | {
+        by: C;
+    };
+    /** `false` reads no rows: a total alone. Default `true`. */
+    rows?: boolean;
+}
+export interface QueryState<R> {
+    rows: R[];
+    /** The cap (`limit`, else the server's) cut the rows, so anything folded from them is under-reported. */
+    truncated: boolean;
+    /** The whole set's count, where `total` is asked; `undefined` until it answers. */
+    total: number | undefined;
+    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`); a value no row holds is absent. */
+    counts: Readonly<Record<string, number>> | undefined;
+    /** Only the first read of a key with nothing to show; a re-read and a new key keep the rows on screen. */
+    loading: boolean;
+    /** Any request of this read is in flight. */
+    isValidating: boolean;
+    error: string | null;
+    /**
+     * A write this app made is in flight over these rows. They already show what it will change where that
+     * is known; the rest lands with the server's answer.
+     */
+    pending: boolean;
+    refetch: () => void;
+    /** The page shown, from 0; always 0 without `page`. */
+    page: number;
+    /** Clamped at 0. */
+    setPage: (page: number) => void;
+    /** `undefined` without `page`, and until the total answers. */
+    pageCount: number | undefined;
+    /** A next page (`page`) or more rows (`more`) are there to read. */
+    hasMore: boolean;
+    /** Appends the next rows (`more`); nothing otherwise, or while one is being read. */
+    loadMore: () => void;
+    loadingMore: boolean;
+}
+/**
+ * The (params, opts) tail for alias `K`. One conditional signature, never a
+ * typed overload beside a loose one, or a rejected filter key would fall
+ * through to the loose overload and compile.
+ */
+type QueryArgs<K extends string, O> = K extends keyof AppQueries ? AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O] : [params?: Record<string, unknown>, opts?: O];
+/**
+ * Read a declared query by alias, filling its `{{params.x}}` holes; the server holds the AST. Its rows, a
+ * page of them (`page`), a feed of them (`more`), its total (`total`), or the total alone (`rows: false`).
+ *
+ * ```tsx
+ * const { rows, loading } = useQuery("openOrders", { status: "open" });
+ * const orders = useQuery("orders", { q }, { page: 25, sort, filter });   // orders.page, setPage, pageCount
+ * const feed = useQuery("feed", {}, { more: 30 });                          // feed.loadMore, hasMore
+ * const { total, counts } = useQuery("orders", {}, { rows: false, total: { by: "stage" } });
+ * ```
+ */
+export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<RowOf<K>>;
+/**
+ * One read of `useQueries`: a declared query, the params its holes take, a runtime narrowing of its rows, the
+ * order they are read in (empty keeps the query's own) — so a cap keeps the first rows of THAT order — its
+ * total where asked, and, asked for its groups in place of its rows, the aggregate over what the narrowing keeps.
+ */
+export interface QueryCall {
+    alias: string;
+    params?: Record<string, unknown>;
+    filter?: QueryFilter;
+    sort?: readonly QuerySortKey[];
+    aggregate?: QueryAggregate;
+    /** The whole set's count, its own read. */
+    total?: boolean;
+    /** `false` reads no rows: a total alone. Default `true`. */
+    rows?: boolean;
+}
+/**
+ * Several declared queries read together, one state per call in the calls' order — for a surface whose
+ * reads are data (a spec's blocks, a count per stage) rather than a fixed call per component. Each reads as
+ * `useQuery` with no `limit` does: the whole result up to the server's cap, `truncated` past it; a call that
+ * fails carries its own `error`, the others their rows.
+ */
+export declare function useQueries(calls: readonly QueryCall[], opts?: Pick<QueryOptions, "enabled" | "revalidateOnFocus">): QueryState<QueryRow>[];
+/**
+ * Every row a declared query matches, read a page at a time to the end — for what must hold every row
+ * (a saved sheet), never for a screen, which pages. The server's rows as stored: no write is drawn over them.
+ */
+export declare function queryAll(alias: string, params?: Record<string, unknown>, opts?: {
+    filter?: QueryFilter;
+    sort?: readonly QuerySortKey[];
+}): Promise<QueryRow[]>;
+/** One select column's full option set. */
+export interface FieldOptions {
+    /** The source field's display name. */
+    label: string;
+    /** Every option, including ones no current row holds. */
+    options: ResolvedOption[];
+    /** `undefined` for an option removed after the cell was written. */
+    byKey: (key: string) => ResolvedOption | undefined;
+}
+/** The units or currencies a number column is read in, row by row: the options of the select on its row naming each row's. */
+export interface FigureUnits {
+    vocabulary: "unit" | "currency";
+    options: ResolvedOption[];
+}
+export interface FieldOptionsState<C extends string = string> {
+    /**
+     * Keyed by the alias's own output columns. Every key is optional: a non-select
+     * column, a UNION whose arms disagree, or a computed column has none.
+     */
+    fields: Partial<Record<C, FieldOptions>>;
+    /**
+     * A number column read in each row's own unit or currency, keyed the same way: a
+     * condition comparing it names one of these as its `unit_option` — pass it whole as
+     * a `FilterChip` column's `units`. A figure read in one unit for every row has none.
+     */
+    units: Partial<Record<C, FigureUnits>>;
+    loading: boolean;
+    isValidating: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+export interface FieldOptionsOptions {
+    /** Default `true`. */
+    enabled?: boolean;
+}
+/**
+ * The complete option set, with colors, of each `select` column the alias
+ * projects — a cell carries only the options its record holds — and the units
+ * of each number column read in each row's own unit.
+ *
+ * ```tsx
+ * const { fields, units } = useFieldOptions("records");
+ * // populate + color a picker:
+ * <Select variant="native" options={fields.status?.options ?? []}
+ *   renderOptionContent={(o) => <Status option={o} />} />
+ * // color a stored value:
+ * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
+ * // a range on a figure each row reads in its own unit:
+ * <FilterChip column={{ key: "weight", label: "Weight", type: "number", units: units.weight }} … />
+ * ```
+ */
+export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState<ColumnKeyOf<K>>;
+export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
+export {};

package/dist/recording.d.ts

@@ -0,0 +1,47 @@
+import { type RecordingState } from "./recording_state.js";
+import type { AppWorkflows } from "./types.js";
+/** The platform fills `recording`; the app passes the rest. */
+type ActInputsOf<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? Omit<AppWorkflows[K], "recording"> : Record<string, unknown>;
+export interface UseRecording<I> {
+    /**
+     * False standalone, in an older host, without transcription, and until the
+     * context answers. Draw a start control only when true.
+     */
+    available: boolean;
+    /** The latest recording through this alias. */
+    state: RecordingState;
+    /** Any of this app's recordings is live; the host records one at a time. */
+    busy: boolean;
+    /**
+     * Opens the host's capture dialog. `{ started: false }` when the member
+     * closes it; rejects with the host's reason. Once transcribed, the host runs
+     * the workflow with these inputs plus `recording`.
+     */
+    start: {} extends I ? (inputs?: I) => Promise<{
+        started: boolean;
+    }> : (inputs: I) => Promise<{
+        started: boolean;
+    }>;
+    /** Resolves whether or not one was live. */
+    stop: () => Promise<void>;
+}
+/**
+ * Record through the host and file it by `alias`, a workflow declaring the
+ * `recording` input, run once when the transcript is ready.
+ *
+ * ```tsx
+ * const visit = useRecording("log_visit");
+ * if (!visit.available) return null;
+ * if (visit.state.phase === "live" && visit.state.inputs.site === siteId) {
+ *   return <Button onPress={() => visit.stop()}>Stop</Button>;
+ * }
+ * return (
+ *   <Button disabled={visit.busy} onPress={() => visit.start({ site: siteId })}>
+ *     Record the visit
+ *   </Button>
+ * );
+ * ```
+ */
+export declare function useRecording<K extends keyof AppWorkflows & string>(alias: K): UseRecording<ActInputsOf<K>>;
+export declare function useRecording(alias: string): UseRecording<Record<string, unknown>>;
+export {};

package/dist/recording_state.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The latest recording per workflow alias this app started. A leaf module:
+ * `rpc.ts` applies pushes, `viewer.ts` the context snapshot, both in order on
+ * one channel, so the later arrival is newer.
+ */
+/** The `start` inputs echoed back, so a per-row act can tell which row is recording. */
+export type RecordingInputs = Record<string, unknown>;
+/**
+ * `interrupted`: the tab closed mid-call, resumable from the recording bar.
+ * `processing`: transcribing. `failed`: transcription, filing or the run
+ * failed; kept, and retried from the recording bar.
+ */
+export type RecordingState = {
+    phase: "idle";
+} | {
+    phase: "live";
+    elapsed_seconds: number;
+    inputs: RecordingInputs;
+} | {
+    phase: "interrupted";
+    elapsed_seconds: number;
+    inputs: RecordingInputs;
+} | {
+    phase: "processing";
+    inputs: RecordingInputs;
+} | {
+    phase: "filed";
+    execution_id: string;
+    inputs: RecordingInputs;
+} | {
+    phase: "failed";
+    message: string;
+    inputs: RecordingInputs;
+};
+export declare const IDLE_RECORDING: RecordingState;
+export declare function subscribeRecordings(listener: () => void): () => void;
+export declare function recordingStateOf(alias: string): RecordingState;
+export declare function anyRecordingLive(): boolean;
+export declare function applyRecordingChange(alias: string, state: RecordingState): void;
+/** The snapshot `context` carries: every alias it omits is idle. */
+export declare function replaceRecordings(snapshot: Record<string, RecordingState>): void;
+export declare function readRecordingState(raw: unknown): RecordingState | null;
+export declare function readRecordingSnapshot(raw: unknown): Record<string, RecordingState>;

package/dist/rename_file.d.ts

@@ -0,0 +1,13 @@
+import type { AppFile } from "./row.js";
+/**
+ * A file under another name: a NEW file over the same bytes, its extension kept exactly (`"scan.pdf"` →
+ * `"Invoice 9.pdf"`, never `.html`). Nothing holds it until a save puts it in the old one's place — a files field's
+ * change taking the old id out and putting this one in, which lands it where the old one stood — so the rename is
+ * refused wherever that save is, and reaches no other field holding the old file.
+ *
+ * ```tsx
+ * const renamed = await renameFile(file.id, "Invoice 9.pdf");
+ * await save({ record_id, papers_added: [renamed.id], papers_removed: [file.id] });
+ * ```
+ */
+export declare function renameFile(file_id: string, filename: string): Promise<AppFile>;

package/dist/router.d.ts

@@ -0,0 +1,10 @@
+import { type RouteObject } from "react-router";
+/** The SDK ships no locale, so a non-English app passes its own. */
+export interface NotFoundWords {
+    message: (path: string) => string;
+    firstScreen: string;
+}
+export declare function AppRouter({ routes, notFound }: {
+    routes: RouteObject[];
+    notFound?: NotFoundWords;
+}): import("react").JSX.Element;

package/dist/router.js

@@ -0,0 +1,97 @@
+import {
+  isEmbedded,
+  setUrlParams
+} from "./chunk-ARV5FAU5.js";
+
+// src/router.tsx
+import { useEffect } from "react";
+import {
+  BrowserRouter,
+  Link,
+  useLocation,
+  useRoutes
+} from "react-router";
+import { jsx, jsxs } from "react/jsx-runtime";
+var LOC_KEY = "_loc";
+var HOST_KEY = "lotics_host";
+function screenHref(loc) {
+  const search = new URLSearchParams(loc.search);
+  search.delete(HOST_KEY);
+  const qs = search.toString();
+  return loc.pathname + (qs ? `?${qs}` : "") + loc.hash;
+}
+function HostScreenMirror() {
+  const location = useLocation();
+  const href = screenHref(location);
+  useEffect(() => {
+    void setUrlParams({ [LOC_KEY]: href });
+  }, [href]);
+  return null;
+}
+function RoutedRoutes({ routes }) {
+  return useRoutes(routes);
+}
+var NOT_FOUND_ROOT = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "var(--lotics-space-8, 8px)",
+  paddingBlock: "var(--lotics-space-48, 48px)",
+  paddingInline: "var(--lotics-space-16, 16px)",
+  textAlign: "center",
+  fontFamily: "var(--font-sans, system-ui, sans-serif)"
+};
+var NOT_FOUND_MESSAGE = {
+  margin: 0,
+  fontSize: "var(--lotics-text-sm, 14px)",
+  color: "var(--lotics-ink-muted, #71717a)"
+};
+var NOT_FOUND_LINK = {
+  fontSize: "var(--lotics-text-sm, 14px)",
+  color: "var(--lotics-accent, #2563eb)"
+};
+var NOT_FOUND_ENGLISH = {
+  message: (path) => `No screen at ${path}`,
+  firstScreen: "Go to the first screen"
+};
+function NotFoundScreen({ home, words }) {
+  const { pathname } = useLocation();
+  return /* @__PURE__ */ jsxs("div", { style: NOT_FOUND_ROOT, children: [
+    /* @__PURE__ */ jsx("p", { style: NOT_FOUND_MESSAGE, children: words.message(pathname) }),
+    /* @__PURE__ */ jsx(Link, { to: home, style: NOT_FOUND_LINK, children: words.firstScreen })
+  ] });
+}
+function withNotFound(routes, element) {
+  return [
+    ...routes.map(
+      (route) => route.children === void 0 ? route : { ...route, children: withNotFound(route.children, element) }
+    ),
+    { path: "*", element }
+  ];
+}
+function firstScreenPath(routes) {
+  const first = routes.find((route) => route.path !== void 0 && route.path !== "*");
+  return first?.path ?? "/";
+}
+function AppRouter({
+  routes,
+  notFound = NOT_FOUND_ENGLISH
+}) {
+  const embedded = isEmbedded();
+  return /* @__PURE__ */ jsxs(BrowserRouter, { children: [
+    embedded ? /* @__PURE__ */ jsx(HostScreenMirror, {}) : null,
+    /* @__PURE__ */ jsx(
+      RoutedRoutes,
+      {
+        routes: withNotFound(
+          routes,
+          /* @__PURE__ */ jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })
+        )
+      }
+    )
+  ] });
+}
+export {
+  AppRouter
+};