@trypattern/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @trypattern/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine every Pattern web app runs on. Blueprints and customer apps depend on it; they never
+copy it.
+
+```ts
+export const admins: string[] = []
+
+export const tables = defineTables({
+  issues: {
+    columns: { title: z.string().min(1), assignee: z.string().nullable() },
+    access: { read: 'signedIn', create: 'signedIn', update: 'signedIn', delete: 'signedIn' },
+    writes: 'optimistic',
+  },
+})
+
+export class Preferences extends Store({
+  state: { issueSort: z.enum(['oldest', 'title']).default('oldest') },
+  persist: ['issueSort'],
+}) {
+  public setIssueSort(issueSort: 'oldest' | 'title') {
+    this.set({ issueSort })
+  }
+}
+
+export class IssueList extends Model({ stores: ['issues', 'preferences'] }) {
+  public override onPageOpen() {
+    return this.stores.issues.load()
+  }
+
+  public get issues(): readonly Issue[] {
+    return sortIssues(this.stores.issues.state.items, this.stores.preferences.state.issueSort)
+  }
+
+  public setSort = command({ input: { sort: issuesSort } }, ({ sort }) => {
+    this.stores.preferences.setIssueSort(sort)
+  })
+}
+
+export function IssueListScreen() {
+  const issueList = useModel('issueList')
+  return issueList.issues.map((issue) => <IssueListRow key={issue.id} issue={issue} />)
+}
+
+export class App extends defineApp({
+  name: 'Issues',
+  tables,
+  admins,
+  stores: { preferences: Preferences },
+  models: { issueList: IssueList },
+  routes: defineRoutes([{ id: 'issueList', path: '/issues', Component: IssueListScreen }]),
+}) {}
+
+export default createServer({ tables, admins })
+```
+
+- Layers: the service (Pattern's table API) fetches; a **store** holds data and caches it (one per
+  table, plus `Store({ state, persist })` classes for shared browser state); a **model**
+  (`Model({ state, persist, stores })`) holds a screen's state, works out answers in public getters
+  from its state and the stores it lists, and changes things through `command()` fields; a
+  **screen** reads one model with `useModel`. Getters are pure and cached: each records which
+  store values it read and is worked out again only when one of them changes, so a toast does not
+  re-sort a list. A model publishes a frozen snapshot (state, getters and commands), rebuilt only
+  while something is subscribed or when it is read, and notifies only when it actually changed;
+  that is what `useModel` returns and what flows assert. Models never read each other: a model
+  offers what you can do with it in `get actions()`, and the built-in `actions` store gathers
+  them for the command menu and shortcuts. `app check` rejects impure getters (`pure-getters`)
+  and getters that return anything but plain JSON; at runtime a getter that tries to change state
+  or navigate throws, and in dev and flows a getter that answers twice differently throws.
+- `@trypattern/sdk`: `defineApp({ name, ... })` (routing, one store per table, snapshots, the
+  built-in `app.navigate` command, the actions store ordered by `actionGroups`, and the built-ins
+  every app gets without listing them: the `account`, `palette` and `signIn` models and the
+  `session`, `actions`, `toasts` and `page` stores, with the appearance, Log out and ⌘K actions), `defineRoutes` (route ids are the page names), `startApp` (the browser entry:
+  creates the router, with the dev tools `app send` and visual flows use), `Model`, `Store`,
+  `command`, `appPath`, `defineActions`, `action`, `rankActions` (the command menu's search),
+  `EntityStore`, `TableStore` (`create` takes the columns only), `Cache`, `Gate`, and the types
+  `AppStores`, `AppSnapshot`, `AppCommand`, `AppPath`, `AppAction`, `AppActionGroup`,
+  `Interaction`, `PublishedOf`, `MessagesOf`.
+- `@trypattern/sdk/schema`: `defineTables` and the types `Row`, `PublicRow` and `Seed`. Every row gets an
+  `id` and `createdAt` that Pattern sets. Every table declares `access` (`anyone`, `signedIn`,
+  `owner`, `admin` or `server` for read, create, update and delete) and `writes` (`optimistic` or
+  `confirmed`), and may add `owned: true` (an `ownerId` the server fills), `public` columns (a
+  read-only `public<Table>` store) and `unique` column sets (a 409 `conflict`). `src/access.ts` is
+  the one rule engine; the Worker and the flow runner's memory API both use it, and
+  `accessFlows({ App })` from `@trypattern/sdk/flows` checks every table's rules against the seed.
+  Store writes return `'saved' | 'conflict' | 'forbidden' | 'missing' | 'failed'`. Safe to import
+  on the server.
+- `@trypattern/sdk/server`: `createServer({ tables, admins })`, the whole Worker: sign-in through
+  auth.trypattern.ai (Google, and emailed 6-digit codes; locally the code prints in the dev log),
+  dev sign-in, sessions, `/api/me` and every table under `/api/tables`. A deployed app holds one
+  `AUTH_SECRET` that Pattern's deploy sets, and no Google secrets. Also `users`, `sessions`,
+  `sqlTables`, `seedSql`, the sign-in wire schemas (`verifiedIdentity`, `exchangeRequest`,
+  `exchangeReply`, `sendCodeRequest`, `sendCodeReply`, `verifyCodeRequest`, `verifyCodeReply`) and
+  the Worker type `D1Database`.
+- `@trypattern/sdk/react`: `AppProvider` and `useModel`, and the primitives every app draws
+  with. The frame: `AppFrame`, `Screen`, `SignInScreen`, `CommandPalette`, `Toaster`,
+  `CommandMenu`. Layout:
+  `Content`, `Stack`, `Row`, `Card`, `Divider`, `SettingsRow`, `PropertyRow`, `ListRow`, `LoadingRows`, `EmptyState`, `Form`.
+  Words: `Text` and `Link`. Controls: `Button` (or a link to a page with `to`), `AppearancePicker`, `IconButton`, `TextField`, `Select`, `Switch`,
+  `SegmentedControl`, `Menu`, `ContextMenu`, `Dialog`, `Tooltip`, `Kbd`, `ScrollArea`, `Avatar`,
+  `Badge`, `Skeleton`, `Spinner`, `Icon`. Types: `IconName`, `MenuEntry`, `SidebarLink`,
+  `Toast`, `SelectOption`, `SegmentedOption`, `CommandMenuItem`, `SpaceName` and `Placement`.
+  Everything takes closed choices (`variant`, `tone`, `size`, `gap`, `width`) and a `style`
+  limited to placement, and every interactive primitive reports to `startApp`'s `onInteraction`.
+  App screens have no styles; `app check` holds them to that.
+- `@trypattern/sdk/tokens.stylex`: the design tokens the primitives read. An app re-values
+  `colors`, `radii`, `fonts`, `shadows`, `space`, `fontSizes`, `lineHeights`, `controls`,
+  `iconSizes`, `borders` and `widths` with `stylex.createTheme` and passes them to
+  `startApp(App, { theme, icons, onInteraction })`, which also renders the app; `defineIcons` and `appearance`
+  (system, light or dark) come from `@trypattern/sdk`.
+- Every export above is typed for the app with nothing to declare: `presets/register.d.ts`, which
+  the app tsconfig preset loads, fills `Register` from `src/App.ts`, `schema.ts`,
+  `src/stores/index.ts` and `src/routes.tsx`. `Model`, `AppStores`, `AppSnapshot`, `AppCommand` and `AppPath` come from `@trypattern/sdk`.
+
+- `@trypattern/sdk/flows`: `defineFlow({ App })`; the `flow()` it returns fakes the server
+  from the app's tables and the seed in `vite.config.ts`, and runs headless in Node or in Chrome with `app test --visual`.
+- `@trypattern/sdk/vite`: `pattern({ tables, admins, seed })`, the whole Vite and Vitest setup, including the
+  `@/` alias for the project root. The seed fills the local database and flows; it never ships.
+  A build also writes `dist/design.json` (beside, not inside, what is served): the SDK version,
+  every token with the app's overrides marked, each primitive with the literal `variant`, `tone`,
+  `size` and layout choices it is used with, the app's own drawn pieces and the tokens they read,
+  and its icons. Pattern's dashboard renders the design system from it.
+- `@trypattern/sdk/tsconfig/app.json` and `/tsconfig/server.json`: the presets project tsconfigs extend.
+- The `app` command: start, check, fix, reset, migration, build, send, screenshot, test, sign-in,
+  setup.
+
+Published to npm as `@trypattern/sdk`, compiled to `dist/`; in this repo the blueprint runs the
+source directly. Still to come: payments, workflows and blocks.

package/dist/access.d.ts

@@ -0,0 +1,31 @@
+import type { Table } from './table.ts';
+export type Viewer = {
+    userId: string;
+    isAdmin: boolean;
+};
+export type WriteOutcome = 'saved' | 'conflict' | 'forbidden' | 'missing' | 'failed';
+export type Refusal = 'signedOut' | 'forbidden' | 'missing';
+export type ReadScope = 'all' | {
+    ownerId: string;
+} | 'none';
+type Owned = {
+    ownerId?: unknown;
+};
+export declare function adminEmails(admins: readonly string[]): ReadonlySet<string>;
+export declare function viewerOf(user: {
+    id: string;
+    isAdmin: boolean;
+} | null | undefined): Viewer | null;
+export declare function viewerByEmail(user: {
+    id: string;
+    email: string;
+} | null | undefined, admins: ReadonlySet<string>): Viewer | null;
+export declare function readScope(table: Table, viewer: Viewer | null): ReadScope;
+export declare function listRefusal(table: Table, viewer: Viewer | null): Refusal | undefined;
+export declare function canSee(table: Table, viewer: Viewer | null, row: Owned): boolean;
+export declare function createRefusal(table: Table, viewer: Viewer | null): Refusal | undefined;
+export declare function changeRefusal(table: Table, operation: 'update' | 'delete', viewer: Viewer | null, existing: Owned | undefined): Refusal | undefined;
+export declare function refusalOutcome(refusal: Refusal): 'forbidden' | 'missing';
+export declare function publicRow(table: Table, row: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function clashesWith(table: Table, rows: readonly Readonly<Record<string, unknown>>[], row: Readonly<Record<string, unknown>>): boolean;
+export {};

package/dist/access.js

@@ -0,0 +1,72 @@
+export function adminEmails(admins) {
+    return new Set(admins.map((email) => email.trim().toLowerCase()));
+}
+export function viewerOf(user) {
+    if (user === null || user === undefined)
+        return null;
+    return { userId: user.id, isAdmin: user.isAdmin };
+}
+export function viewerByEmail(user, admins) {
+    if (user === null || user === undefined)
+        return null;
+    return { userId: user.id, isAdmin: admins.has(user.email.toLowerCase()) };
+}
+function mayUse(level, viewer) {
+    if (level === 'server')
+        return false;
+    if (level === 'anyone' || viewer?.isAdmin === true)
+        return true;
+    if (viewer === null)
+        return false;
+    return level === 'signedIn' || level === 'owner';
+}
+function allows(level, viewer, row) {
+    if (!mayUse(level, viewer))
+        return false;
+    if (level !== 'owner' || viewer?.isAdmin === true)
+        return true;
+    return viewer !== null && row.ownerId === viewer.userId;
+}
+function refusalFor(viewer) {
+    return viewer === null ? 'signedOut' : 'forbidden';
+}
+export function readScope(table, viewer) {
+    const level = table.access.read;
+    if (!mayUse(level, viewer))
+        return 'none';
+    if (level === 'owner' && viewer !== null && !viewer.isAdmin) {
+        return { ownerId: viewer.userId };
+    }
+    return 'all';
+}
+export function listRefusal(table, viewer) {
+    return readScope(table, viewer) === 'none' ? refusalFor(viewer) : undefined;
+}
+export function canSee(table, viewer, row) {
+    const scope = readScope(table, viewer);
+    if (scope === 'none')
+        return false;
+    return scope === 'all' || row.ownerId === scope.ownerId;
+}
+export function createRefusal(table, viewer) {
+    return mayUse(table.access.create, viewer) ? undefined : refusalFor(viewer);
+}
+export function changeRefusal(table, operation, viewer, existing) {
+    const level = table.access[operation];
+    if (!mayUse(level, viewer))
+        return refusalFor(viewer);
+    if (existing === undefined || !canSee(table, viewer, existing)) {
+        return 'missing';
+    }
+    return allows(level, viewer, existing) ? undefined : 'forbidden';
+}
+export function refusalOutcome(refusal) {
+    return refusal === 'missing' ? 'missing' : 'forbidden';
+}
+export function publicRow(table, row) {
+    return Object.fromEntries(['id', ...table.public].map((key) => [key, row[key] ?? null]));
+}
+export function clashesWith(table, rows, row) {
+    return table.unique.some((columns) => rows.some((other) => other['id'] !== row['id'] &&
+        columns.every((column) => other[column] === row[column])));
+}

package/dist/actions.d.ts

@@ -0,0 +1,57 @@
+import type { Message } from './model.ts';
+import { StoreBase } from './store.ts';
+import type { PageStore } from './page.ts';
+export type Action<Command extends Message = Message> = {
+    readonly id: string;
+    readonly label: string;
+    readonly group: string;
+    readonly icon: string;
+    readonly keys: readonly string[];
+    readonly keywords: string;
+    readonly isDanger: boolean;
+    readonly isSearchOnly: boolean;
+    readonly isHidden: boolean;
+    readonly send: readonly Command[];
+};
+export type ActionsBuilder<Context, Item extends Action> = {
+    readonly page: string | undefined;
+    readonly build: (context: Context) => readonly (Item | false)[];
+};
+type PageOf<Context> = Context extends {
+    readonly page: infer Page;
+} ? Exclude<Page, null> & string : never;
+type Entries<Seen, Item extends Action, Command extends Message> = (context: Seen) => readonly ((Item & {
+    readonly send: readonly Command[];
+}) | false)[];
+export type DefineActions<Context extends {
+    readonly page: unknown;
+}, Item extends Action, Command extends Message> = {
+    (build: Entries<Context, Item, Command>): ActionsBuilder<Context, Item>;
+    <const Page extends PageOf<Context>>(options: {
+        readonly page: Page;
+    }, build: Entries<Omit<Context, 'page'> & {
+        readonly page: Page;
+    }, Item, Command>): ActionsBuilder<Context, Item>;
+};
+export declare function bindActions<Context extends {
+    readonly page: unknown;
+}, Item extends Action, Command extends Message>(): DefineActions<Context, Item, Command>;
+type AnyBuilder = ActionsBuilder<never, Action>;
+type ReadableModel = {
+    readonly state: object;
+    readonly currentState: object;
+    readonly subscribe: (listener: () => void) => () => void;
+};
+type ActionsState<Item extends Action> = {
+    items: readonly Item[];
+};
+export declare class ActionsStore<Item extends Action = Action> extends StoreBase<ActionsState<Item>> {
+    #private;
+    constructor(page: PageStore, builders: readonly AnyBuilder[], groups: readonly string[], send: (message: Message) => Promise<void>);
+    protected initialState(): ActionsState<Item>;
+    watch(models: Readonly<Record<string, ReadableModel>>): void;
+    pressKey(key: string): Promise<void> | undefined;
+    run(action: Item): Promise<void>;
+}
+export declare function rankActions<Item extends Action>(actions: readonly Item[], query: string): Item[];
+export {};

package/dist/actions.js

@@ -0,0 +1,198 @@
+import { answerNamesOf } from "./model.js";
+import { StoreBase, isDevelopment, keepEqualParts, plainJsonProblem, readsAreCurrent, tracked, whileBuilding } from "./store.js";
+export function bindActions() {
+    function defineActions(first, second) {
+        if (typeof first === 'function')
+            return { page: undefined, build: first };
+        if (second === undefined)
+            throw new Error('defineActions() needs entries');
+        return { page: first.page, build: second };
+    }
+    return defineActions;
+}
+const NAMED_READS_ONLY = 'An actions file reads a model by naming a state field or answer, as models.issueDetail.hasNext. It cannot spread a model, list its keys or test `in`, because Pattern reruns the file only when something it named changes.';
+function readOnlyView(model) {
+    const answers = answerNamesOf(model);
+    const refuse = () => {
+        throw new Error(NAMED_READS_ONLY);
+    };
+    return new Proxy({}, {
+        get(_, key) {
+            if (typeof key !== 'string')
+                return undefined;
+            if (key in model.currentState)
+                return Reflect.get(model.state, key);
+            return answers.includes(key) ? Reflect.get(model, key) : undefined;
+        },
+        has: refuse,
+        ownKeys: refuse,
+        getOwnPropertyDescriptor: refuse
+    });
+}
+const MOST_PASSES = 4;
+const SEQUENCE_MS = 1000;
+function keysAre(keys, pressed) {
+    return (keys.length === pressed.length &&
+        pressed.every((key, index) => keys[index] === key));
+}
+function keysStartWith(keys, pressed) {
+    return (keys.length > pressed.length &&
+        pressed.every((key, index) => keys[index] === key));
+}
+export class ActionsStore extends StoreBase {
+    #page;
+    #builders;
+    #send;
+    #memos = new Map();
+    #context = {};
+    #isRebuilding = false;
+    #needsAnotherPass = false;
+    #pressed = [];
+    #pressedAt = 0;
+    #groups;
+    constructor(page, builders, groups, send) {
+        super();
+        this.#page = page;
+        this.#builders = builders;
+        this.#groups = groups;
+        this.#send = send;
+    }
+    initialState() {
+        return { items: [] };
+    }
+    watch(models) {
+        const views = Object.fromEntries(Object.entries(models).map(([name, model]) => [name, readOnlyView(model)]));
+        const page = this.#page;
+        this.#context = {
+            get page() {
+                return page.state.page;
+            },
+            models: views
+        };
+        for (const model of Object.values(models)) {
+            model.subscribe(() => this.#rebuild());
+        }
+        page.subscribe(() => this.#rebuild());
+        this.#rebuild();
+    }
+    pressKey(key) {
+        const now = Date.now();
+        const earlier = now - this.#pressedAt < SEQUENCE_MS ? this.#pressed : [];
+        const pressed = [...earlier, key.toLowerCase()];
+        this.#pressedAt = now;
+        const items = this.currentState.items;
+        const match = items.find((item) => keysAre(item.keys, pressed));
+        if (match !== undefined) {
+            this.#pressed = [];
+            return this.run(match);
+        }
+        if (items.some((item) => keysStartWith(item.keys, pressed))) {
+            this.#pressed = pressed;
+            return undefined;
+        }
+        this.#pressed = [];
+        return earlier.length > 0 ? this.pressKey(key) : undefined;
+    }
+    async run(action) {
+        for (const message of action.send)
+            await this.#send(message);
+    }
+    #rebuild() {
+        if (this.#isRebuilding) {
+            this.#needsAnotherPass = true;
+            return;
+        }
+        this.#isRebuilding = true;
+        try {
+            for (let pass = 1;; pass += 1) {
+                this.#needsAnotherPass = false;
+                this.#rebuildOnce();
+                if (!this.#needsAnotherPass)
+                    return;
+                if (pass === MOST_PASSES) {
+                    throw new Error('The actions never settle: an actions file reads something that changes whenever the actions change, such as models.palette.results. Actions files read the page and the models a person acts on, never the command menu.');
+                }
+            }
+        }
+        finally {
+            this.#isRebuilding = false;
+        }
+    }
+    #rebuildOnce() {
+        const built = this.#builders
+            .flatMap((builder) => this.#evaluate(builder))
+            .toSorted((a, b) => this.#groupRank(a) - this.#groupRank(b));
+        const items = keepEqualParts(this.currentState.items, built);
+        if (items !== this.currentState.items)
+            this.set({ items });
+    }
+    #groupRank(action) {
+        const rank = this.#groups.indexOf(action.group);
+        return rank === -1 ? this.#groups.length : rank;
+    }
+    #evaluate(builder) {
+        const memo = this.#memos.get(builder);
+        if (memo !== undefined && readsAreCurrent(memo.reads))
+            return memo.value;
+        const { value: built, reads } = whileBuilding(() => tracked(() => this.#build(builder)));
+        if (isDevelopment())
+            this.#checkPure(builder, built);
+        const value = memo === undefined ? built : keepEqualParts(memo.value, built);
+        this.#memos.set(builder, { value, reads });
+        return value;
+    }
+    #build(builder) {
+        const isElsewhere = builder.page !== undefined && this.#page.state.page !== builder.page;
+        if (isElsewhere)
+            return [];
+        return builder
+            .build(this.#context)
+            .filter((entry) => entry !== false);
+    }
+    #checkPure(builder, built) {
+        const problem = plainJsonProblem(built, 'actions');
+        if (problem !== undefined) {
+            throw new Error(`Actions must be plain JSON, because flows compare them: ${problem}`);
+        }
+        const again = whileBuilding(() => this.#build(builder));
+        if (JSON.stringify(built) !== JSON.stringify(again)) {
+            throw new Error('An actions file gave two different lists for the same page and models, so it is not pure. Actions files must not read the clock, randomness or anything outside page and models.');
+        }
+    }
+}
+function scoreOf(candidate, terms) {
+    const label = candidate.label.toLowerCase();
+    const haystack = `${label} ${candidate.keywords} ${candidate.group}`.toLowerCase();
+    if (!terms.every((term) => haystack.includes(term)))
+        return 0;
+    const phrase = terms.join(' ');
+    if (label.startsWith(phrase))
+        return 4;
+    if (` ${label}`.includes(` ${phrase}`))
+        return 3;
+    if (label.includes(phrase))
+        return 2;
+    return 1;
+}
+export function rankActions(actions, query) {
+    const offered = actions.filter((candidate) => !candidate.isHidden);
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0) {
+        return offered.filter((candidate) => !candidate.isSearchOnly);
+    }
+    const order = [...new Set(offered.map((candidate) => candidate.group))];
+    const scored = offered.flatMap((candidate) => {
+        const score = scoreOf(candidate, terms);
+        return score === 0 ? [] : [{ candidate, score }];
+    });
+    const best = new Map();
+    for (const { candidate, score } of scored) {
+        best.set(candidate.group, Math.max(best.get(candidate.group) ?? 0, score));
+    }
+    const rank = (group) => best.get(group) ?? 0;
+    return scored
+        .toSorted((a, b) => rank(b.candidate.group) - rank(a.candidate.group) ||
+        order.indexOf(a.candidate.group) - order.indexOf(b.candidate.group) ||
+        b.score - a.score)
+        .map(({ candidate }) => candidate);
+}

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+import type { SessionApi, SessionCall } from './auth/sessionApi.ts';
+import type { Gate } from './gate.ts';
+import type { Seed, Tables } from './table.ts';
+import type { TableCall, TablesApi } from './tables.ts';
+export type AppApi<Group extends Tables> = {
+    tables: TablesApi<Group>;
+    session: SessionApi;
+};
+export type ApiCall<Group extends Tables> = TableCall<Group> | `session.${SessionCall}`;
+export declare function apiCalls<Group extends Tables>(tables: Group): readonly ApiCall<Group>[];
+export declare function httpApi<Group extends Tables>(tables: Group, gate: Gate): AppApi<Group>;
+export declare function memoryApi<Group extends Tables>(tables: Group, seed: Seed<Group>, { gate, signedInAs, admins }: {
+    gate: Gate;
+    signedInAs: string | null;
+    admins: readonly string[];
+}): AppApi<Group>;
+export declare function browserApi<Group extends Tables>(tables: Group, seed: Seed<Group>, gate: Gate, { inMemory, admins }: {
+    inMemory: boolean;
+    admins: readonly string[];
+}): AppApi<Group>;

package/dist/api.js

@@ -0,0 +1,34 @@
+import { adminEmails, viewerByEmail, viewerOf } from "./access.js";
+import { HttpSessionApi, MemorySessionApi, sessionCalls } from "./auth/sessionApi.js";
+import { httpTables, memoryTables, tableCalls } from "./tables.js";
+export function apiCalls(tables) {
+    return [
+        ...tableCalls(tables),
+        ...sessionCalls.map((call) => `session.${call}`)
+    ];
+}
+export function httpApi(tables, gate) {
+    const session = new HttpSessionApi(gate);
+    return {
+        tables: httpTables(tables, gate, () => session.reportSignedOut()),
+        session
+    };
+}
+export function memoryApi(tables, seed, { gate, signedInAs, admins }) {
+    const options = { latencyMs: 0, gate };
+    const session = new MemorySessionApi(signedInAs, admins, options);
+    return {
+        tables: memoryTables(tables, seed, () => viewerOf(session.rememberedUser()), options),
+        session
+    };
+}
+export function browserApi(tables, seed, gate, { inMemory, admins }) {
+    const session = new HttpSessionApi(gate);
+    const emails = adminEmails(admins);
+    return {
+        tables: inMemory
+            ? memoryTables(tables, seed, () => viewerByEmail(session.rememberedUser(), emails), { latencyMs: 0, gate })
+            : httpTables(tables, gate, () => session.reportSignedOut()),
+        session
+    };
+}

package/dist/app.d.ts

@@ -0,0 +1,106 @@
+import type { DataRouter } from 'react-router';
+import type { AppApi } from './api.ts';
+import { SessionStore } from './auth/sessionStore.ts';
+import type { Cache } from './cache.ts';
+import type { Gate } from './gate.ts';
+import { ActionsStore } from './actions.ts';
+import type { Action, ActionsBuilder } from './actions.ts';
+import { Toasts } from './builtins/Toasts.ts';
+import { PageStore } from './page.ts';
+import type { BuiltInModels } from './registered.ts';
+import type { Snapshots } from './store.ts';
+import type { Json, Persisted } from './state.ts';
+import type { DerivedOf, Instances, MessagesOf, ModelClassLike, ModelSnapshots } from './model.ts';
+import type { PageOf, PathOf, RouteDefinition } from './routes.ts';
+import type { Tables } from './table.ts';
+import { PublicTableStore, TableStore } from './tables.ts';
+type Observed = {
+    readonly state: object;
+    readonly subscribe: (listener: () => void) => () => void;
+};
+export type { DataRouter };
+export type ModelServicesOf<Path extends string> = {
+    navigate: (to: Path) => Promise<void>;
+};
+type StaticTypeError<Text extends string> = Text;
+type NonJsonGetters<Instance> = {
+    [Key in keyof DerivedOf<Instance>]: DerivedOf<Instance>[Key] extends Json | undefined ? never : Key;
+}[keyof DerivedOf<Instance>];
+export type PlainJsonModel<Class> = Class extends abstract new (...args: never[]) => infer Instance ? [NonJsonGetters<Instance>] extends [never] ? Class : StaticTypeError<`Getter ${NonJsonGetters<Instance> & string} must return plain JSON (strings, numbers, booleans, null, and arrays and objects of those, or undefined), because flows compare the snapshot`> : Class;
+export type NavigateCommand<Path extends string> = {
+    type: 'app.navigate';
+    to: Path;
+};
+export type PressKeyCommand = {
+    type: 'app.pressKey';
+    key: string;
+};
+export type AppDependencies<Api> = {
+    api: Api;
+    cache: Cache;
+    gate: Gate;
+};
+export type RunningApp<Command, Snapshot extends {
+    readonly path: string;
+}> = {
+    readonly router: DataRouter;
+    send(command: Command): Promise<void>;
+    parse(raw: unknown): Command | {
+        error: string;
+    };
+    getSnapshot(): Snapshot;
+    whenIdle(): Promise<void>;
+};
+export type StoreClasses = Record<string, new (persisted: Persisted) => Observed>;
+export type StoreInstances<Classes extends StoreClasses> = {
+    [Key in keyof Classes]: InstanceType<Classes[Key]>;
+};
+export type TableStores<Group extends Tables> = {
+    [Key in keyof Group as Group[Key]['access']['read'] extends 'server' ? never : Key]: TableStore<Group[Key]>;
+};
+export type PublicStores<Group extends Tables> = {
+    [Key in keyof Group & string as [Group[Key]['public'][number]] extends [
+        never
+    ] ? never : `public${Capitalize<Key>}`]: PublicTableStore<Group[Key]>;
+};
+export type StoresOf<Group extends Tables, Custom, Item extends Action = Action> = {
+    session: SessionStore;
+    actions: ActionsStore<Item>;
+    toasts: Toasts;
+    page: PageStore;
+} & TableStores<Group> & PublicStores<Group> & Custom;
+export type AppDefinition<Group extends Tables, Custom extends StoreClasses, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[]> = {
+    name: string;
+    tables: Group;
+    stores?: Custom;
+    models: {
+        [Key in keyof Classes]: Key extends keyof BuiltInModels | 'app' ? StaticTypeError<`${Key & string} is a built-in model of @trypattern/sdk: its state, answers and commands come from Pattern. Name yours for what it holds.`> : PlainJsonModel<Classes[Key]>;
+    };
+    routes: Routes;
+    actions?: readonly ActionsBuilder<never, Action>[];
+    actionGroups?: readonly string[];
+};
+export type AppClass<Group extends Tables, Instance> = {
+    new (router: DataRouter, deps: AppDependencies<AppApi<Group>>): Instance;
+    readonly definition: {
+        readonly tables: Group;
+        readonly routes: readonly RouteDefinition[];
+    };
+};
+export type AppSnapshotShape<Models, Stores, Page> = {
+    page: Page | null;
+    path: string;
+    models: ModelSnapshots<Models>;
+    stores: Snapshots<Stores>;
+};
+type AppCommandOf<Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[]> = MessagesOf<Instances<BuiltInModels>> | MessagesOf<Instances<Classes>> | NavigateCommand<PathOf<Routes>> | PressKeyCommand;
+export type DefinedApp<Group extends Tables, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[], Custom extends StoreClasses> = {
+    new (router: DataRouter, dependencies: AppDependencies<AppApi<Group>>): RunningApp<AppCommandOf<Classes, Routes>, AppSnapshotShape<Instances<BuiltInModels & Classes>, StoresOf<Group, StoreInstances<Custom>>, PageOf<Routes>>> & {
+        readonly name: string;
+        readonly models: Instances<BuiltInModels & Classes>;
+        readonly stores: StoresOf<Group, StoreInstances<Custom>>;
+        pressKey(key: string): Promise<void> | undefined;
+    };
+    readonly definition: AppDefinition<Group, Custom, Classes, Routes>;
+};
+export declare function defineApp<Group extends Tables, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[], Custom extends StoreClasses = Record<never, never>>(definition: AppDefinition<Group, Custom, Classes, Routes>): DefinedApp<Group, Classes, Routes, Custom>;