@compean/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CompeanR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @compean/core
 
-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 shared core of every Compean app: controllers, services, errors, forms, feedback messages and bug reporting, plus the ESLint rules that keep apps consistent. React web (Vite + TanStack Router), React Native (Expo) and a Hono API on Node all build on it.
+
+**Read [`RULES.md`](RULES.md) before writing code in an app that uses this package.** It holds the conventions; this README only lists what the package exports.
+
+## Install
+
+```sh
+pnpm add @compean/core zod
+```
+
+Optional peers, by entry point: `react` for `/react`; `prettier` for `/prettier`; `hono` and `@hono/zod-validator` for `/server`; `@tanstack/query-core` for `changed()`; `eslint` for `/eslint`. Requires Node 22.12 or later.
+
+Bug reports from `load()` and `run()` name the controller by its class name, so production builds must keep class names: in Vite, set `esbuild: { keepNames: true }`.
+
+## Entry points
+
+| Import                   | Exports                                                                                                                                      | Used in                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `@compean/core`          | `Observable`, `Controller`, `$S`, `register`, `UserError`, `ToastService`, `Form`, `ErrorReporter`, `ConsoleReporter`, `readJson`, `changed` | everything                                                        |
+| `@compean/core/react`    | `useController`, `Toaster`                                                                                                                   | web and mobile screens                                            |
+| `@compean/core/server`   | `handleErrors`, `validator`, `loadConfig`                                                                                                    | the API                                                           |
+| `@compean/core/testing`  | `resetServices`, `RecordingReporter`, `recordingNavigation`                                                                                  | tests                                                             |
+| `@compean/core/eslint`   | `compeanRules`                                                                                                                               | each app's `eslint.config.js`                                     |
+| `@compean/core/prettier` | the shared Prettier config (4 spaces, width 130, single quotes)                                                                              | each app's `package.json`: `"prettier": "@compean/core/prettier"` |
+
+## A screen in four pieces
+
+```ts
+// packages/client: the controller
+export class NotesController extends Controller<NotesState> {
+    private notes: Note[] = [];
+    public readonly form = new Form(AddNoteSchema, { body: '' });
+
+    public initialize(): void {
+        this.track(this.form.subscribe(() => this.notify()));
+        void this.load(async () => {
+            this.notes = await $S(NotesService).list();
+        });
+    }
+
+    public get state(): NotesState {
+        return { status: this.status, loadError: this.loadError, notes: this.notes, form: this.form.view() };
+    }
+
+    public addNote(): Promise<void> {
+        return this.run(() =>
+            this.form.submit(async (input) => {
+                await $S(NotesService).add(input);
+                this.form.reset();
+                $S(ToastService).show('Note added');
+            }),
+        );
+    }
+}
+```
+
+```tsx
+// apps/web: the screen
+const { state, controller } = useController(() => new NotesController());
+```
+
+```ts
+// apps/api: errors become HTTP in one place
+app.onError(handleErrors());
+```
+
+```ts
+// eslint.config.js
+export default [...typescriptConfig, ...compeanRules()];
+```
+
+## Design notes
+
+Decisions that span several modules, with the alternatives that were rejected. Code comments point here instead of repeating them.
+
+### Controller status: `load()` and `run()`
+
+A screen is `'loading'`, `'ready'` or `'error'`. Only `load()` decides that status, and only until the screen is first ready. Several first loads are allowed: the status settles when they have all finished, as `'error'` with the first failure's message if any failed; after that a load is a refresh, so its failure shows as a toast and the data stays on screen. `run()` never touches the status. `start()` (called by `useController`) marks a screen that started no load as ready.
+
+- Rejected: one `run()` for everything, where the first run counted as the load. A form screen with nothing to load stayed `'loading'`, and its first failed submit replaced the whole screen with an error.
+- Rejected: `run(task, { load: true })`. A flag that changes behaviour is a special case every caller has to remember.
+
+### One `UserError` class
+
+Everything the user should read is a `UserError(message, status)`; everything else is a bug that is reported and shown generically. `readJson` rebuilds the same class on the client from a 4xx `{ message }`, so `load()`, `run()` and `handleErrors` share one rule.
+
+- Rejected: a subclass per status (`NotFoundError`, `ConflictError`). The client only asks "may I show this?", which the class answers; the status carries the rest.
+
+### Reporting never breaks error handling
+
+`load()`, `run()` and `handleErrors` report through one internal `reportSafely`, which falls back to the console when the registered reporter throws. A vendor outage must never turn a handled error into an unhandled one.
+
+### Defaults in the registry
+
+`$S(ToastService)` and `$S(ErrorReporter)` work without wiring (a fresh `ToastService`, a `ConsoleReporter`), so tests and local runs need no boot code. Every other service must be registered; a missing one is a wiring bug and throws.
+
+### `useController` and React StrictMode
+
+StrictMode runs an effect, disposes, then runs it again on the same controller. The hook never starts a disposed controller; it mounts a fresh one. On a key change it creates the new controller during render, so the screen never shows the new controller with the old one's state.
+
+- Rejected: `useSyncExternalStore` on `controller.state`. The getter builds a new object on every read, which makes React re-render forever.
+
+### Lint rules are core's own
+
+The four checks are small ESLint rules shipped by core, not stacked `no-restricted-imports` entries. ESLint lets a later config entry for the same rule replace an earlier one, so overlapping file globs would silently cancel each other.

package/RULES.md

@@ -0,0 +1,172 @@
+# Framework rules
+
+Conventions for every app built on `@compean/core`. They apply on top of the `code-rules` skill, which holds the design principles (from _A Philosophy of Software Design_) these rules are derived from; read that first. Each rule here is written once; the section number in brackets points to the principle behind it.
+
+A rule a tool can check is enforced by `@compean/core/eslint` and listed in [Enforced by lint](#enforced-by-lint). A new kind of file, a new dependency direction or an exception to a rule needs a design decision before code, not a local workaround.
+
+## Comments
+
+Comments follow `code-rules/comments.md`. Decisions that span modules go in the README's design notes, with a pointer from the code. [ch. 12, ch. 13]
+
+## Glossary
+
+| Term               | Meaning                                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Domain**         | The pure TypeScript that both client and server agree on: models, schemas and policies in `packages/domain`. No I/O, no runtime imports, no display text.                   |
+| **Model**          | A domain concept: its readonly Zod schema, its type, and the pure functions that define its terms (`isKept`, `isPathComplete`). File: `*.model.ts`.                         |
+| **Schema**         | A validation shape that isn't a domain concept, such as a request body or a form's input. File: `*.schema.ts`.                                                              |
+| **Policy**         | A pure behaviour decision: "what should the app do?" (`shouldPromptForReview`, `recommendNextPaths`). Never creates, changes or stores anything. File: `*.policy.ts`.       |
+| **Service**        | A class that performs operations and may hold shared state, reached through `$S`. Exists on the client and on the server. File: `*.service.ts`.                             |
+| **Controller**     | Client-only. Owns one screen's logic and state; its `state` is the screen's view model. Runs on web and mobile unchanged. File: `*.controller.ts`.                          |
+| **View model**     | The display-ready values a screen renders. Normally a controller's `state`; a `*.view-model.ts` file exists only when two or more controllers build the same display shape. |
+| **Screen**         | The component a route renders. Calls `useController` once and renders its state.                                                                                            |
+| **Routes**         | Server-only. A chained Hono definition of a feature's HTTP endpoints. File: `*.routes.ts`. The word "controller" is never used for this.                                    |
+| **Repository**     | Server-only. Holds queries only when they are deep (joins, mapping, transactions) or shared by two or more services. File: `*.repository.ts`.                               |
+| **Port / adapter** | The boundary with something we don't control (device storage, a third-party SDK) and its implementation. Files: `*.port.ts`, `*.adapter.ts`.                                |
+| **`$S`**           | The service registry. `register(Class, instance)` in `boot.ts`; `$S(Class)` everywhere else it's allowed.                                                                   |
+| **`boot.ts`**      | The composition root of each app: the one place that builds services and wires their dependencies.                                                                          |
+| **`UserError`**    | An error the user can fix or should be told about. Its message is shown verbatim. Everything else is a bug.                                                                 |
+| **Resource**       | A name for a kind of server data (`'applications'`), used to mark cached data stale. Resources are a typed union in `packages/domain`, so a typo is a compile error.        |
+
+## File roles
+
+These eleven file roles are the only ones. The folder is the feature; the suffix is the role.
+
+| Where                            | Role                                                           |
+| -------------------------------- | -------------------------------------------------------------- |
+| `packages/domain`                | `*.model.ts`, `*.schema.ts`, `*.policy.ts`                     |
+| `packages/client`                | `*.controller.ts`, `*.service.ts`, `*.view-model.ts`           |
+| `apps/api`                       | `*.routes.ts`, `*.service.ts`, `*.repository.ts`               |
+| `packages/client` and `apps/api` | `*.port.ts` (an interface a service depends on)                |
+| any app                          | `*.adapter.ts` (a platform or vendor implementation of a port) |
+| entry points                     | `boot.ts` in every app; `app.ts` and `server.ts` in `apps/api` |
+
+Tests sit next to the file they cover as `*.test.ts`.
+
+Code that seems to need another suffix goes where its knowledge lives:
+
+| Instead of                         | Put it in                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `runtime`, `engine`                | a `*.service.ts` (with `start()` if it listens to events), or a `*.policy.ts` if it's pure                                     |
+| `mapper`, `codec`                  | the module that knows the format: the adapter, repository or controller that uses it; a domain format goes in its `*.model.ts` |
+| `factory`                          | the service that owns the object, or a `*.policy.ts` if it's a pure decision                                                   |
+| `handler`                          | a method on the owning service                                                                                                 |
+| `config`                           | `loadConfig` in `boot.ts`                                                                                                      |
+| `store`                            | private state inside a service                                                                                                 |
+| `types`, `entity`, `value`         | a `*.model.ts`                                                                                                                 |
+| `sequence` (animation)             | the view                                                                                                                       |
+| `labels`, `content` (display text) | the controller, or a shared `*.view-model.ts`                                                                                  |
+
+## Layout
+
+```
+apps/web/          Vite + TanStack Router: routes/, screens/, adapters/, boot.ts
+apps/mobile/       Expo Router, same shape (added when needed)
+apps/api/          Hono on Node: features/<feature>/, migrations/, app.ts, server.ts, boot.ts
+packages/domain/   models, schemas, policies
+packages/client/   features/<feature>/: controllers, client services, shared view models
+```
+
+- Formatting comes from `@compean/core/prettier` (`"prettier": "@compean/core/prettier"` in the root `package.json`), with an `.editorconfig` for editors that don't read Prettier. No project keeps its own copy.
+- **pnpm workspaces**, pinned with `packageManager`. **Node** is the only runtime, for the server, tests and scripts.
+- Dependencies point one way: `apps → packages/client → packages/domain`, and `apps/api → packages/domain`. `packages/client` imports only `type AppType` from the API, never its code. [§9.4]
+- Folders are grouped by feature inside each app or package, never by role. [ch. 9]
+- `@compean/core`'s entry points and their exports are listed in its README.
+
+## Domain
+
+- Every domain type is a readonly Zod schema in a `*.model.ts`; its type comes from `z.infer`. [§5.3, §9.1]
+- A definition of a domain term lives with its model once two modules, or both client and server, need it. Until then it stays a private function in the module that uses it. [§9.3]
+- A policy is a pure behaviour decision in the book's sense: mechanism and policy kept apart. [§6, §8.2]
+- Display text and constants that only one screen uses stay out of the domain.
+
+## Controllers
+
+- A controller extends `Controller<TState>`. It exposes `state`, `initialize()` and its actions; the base class provides `start()`, `subscribe`, `dispose`, `notify()`, `track(cleanup)`, `load(task)` and `run(task)`.
+- `state` holds display-ready values only. Building them is private mapping inside the controller. Screens and components import only view-model types, never the functions that build them. Decisions call domain rules, not view-model fields. [§7.4, §9.1]
+- Loading the screen's data goes through `load()`: before the screen is first ready, the status settles when every load started so far has finished ('ready', or 'error' with a retry); once ready it's a refresh whose failure shows as a toast. A screen that loads nothing never calls it and starts ready. Every action goes through `run()`, which never changes the status and shows failures as toasts. Both show a `UserError`'s message, show a generic message for anything else, and report bugs. [§10.7, §18]
+- An action must add something: `run()`, a state change, or combining services. One that only forwards a call is a pass-through. [§7.1]
+- Every decision that reads app state is made in the controller, in a method called directly where the data arrives (for example at the end of `load()`). Subscribe to a service only when the change comes from outside. [§18.2]
+- Controllers import no React, React Native or router package. They hold no animation values, springs, animation timers or haptics; they expose meaningful state (`phase`, `isRevealed`) and the view animates it. Timing that is behaviour (auto-advance after 3 s) stays in the controller and never copies an animation's duration. When the flow waits for an animation, the view calls a method named by what the user saw (`planRevealed()`). [§5.2, §9.4]
+- Services come from `$S`. The constructor takes only what the screen owns, in this order: route params, then navigation, each only when needed. [§7.5]
+- Success messages: `$S(ToastService).show('Moved to Technical')` after the action succeeds; `show(message, tone)` takes `'error'` for the rare message that isn't from `run()`. Only actions announce success; loading data never does.
+- Forms: the controller holds a `Form` built from a domain schema, exposed as `public readonly`, and subscribes to it in `initialize()`. The screen binds inputs to it directly, so the controller writes no setter per field. Submit with `this.run(() => this.form.submit(async (input) => { ... }))`: invalid input shows every field's error and skips the action. Clear the form only after the action succeeds. Field errors show on blur or submit. A rule only the server can check (an email already taken) arrives as a toast through `run()`. [§19.6, §10.1]
+
+### Navigation
+
+- When the destination is knowledge the screen owns (a row's detail, a menu item, back), the screen uses `<Link>` or its router directly.
+- When it comes from a rule, a result or a flow order, the controller decides. It declares a small navigation interface named by destination (`toResumeVersion(id)`, `back()`), and the screen implements it with its platform's router and passes it in. The order of a flow lives in a policy. [§9.4, §6.2]
+- A navigation implementation only navigates. Controllers never see URLs or router APIs.
+- Every navigation interface has a one-line comment: `/** Where this screen can lead after an action. Implemented by each platform's screen. */` [§13.5]
+
+## Screens
+
+- The screen calls `useController` once and renders `state`. Its sections receive `state` and `controller` as props; avoid passing them through components that don't use them. [§7.5]
+- `useEffect`, `useFocusEffect` and `useState` are for view work only: focus, gesture timing, scroll and animation values, keyboard listeners, view-only toggles.
+- Screens show no toasts or alerts.
+- Animation, haptics and sound live in the view. `<Toaster />` at the app root owns how toasts look.
+
+## Web routes
+
+- Vite + TanStack Router with file-based routes. A route file holds the path, `validateSearch` with a domain schema, and the screen.
+- Routes never use loaders or the router cache; controllers load data through services.
+- `beforeLoad` is used only for access checks, reading `$S(AuthService)`.
+
+## Services
+
+- A service extends `Observable` only when screens must react to its changes live; otherwise it's a plain class. [§19.1]
+- Its interface speaks the domain: one named snapshot for displayed data, intent methods instead of setters, question methods only for domain rules several callers share. A getter per field is a red flag. [§19.6, §5.1]
+- A library (Zustand, query-core, Better Auth) may live inside a service, never in screens or controllers. [§5.1]
+- Dependencies come through the constructor, every argument named, no `undefined` placeholders. A default must be what production wants, so only `{ clock, random }` default (to the real ones) and a dependency never defaults. Product constants live in the module that owns the rule. [§8.2, §10.9]
+
+### Server data on the client
+
+- A client service calls the typed `hc<AppType>` client directly; there's no port around our own API. It caches with a private `QueryClient` from `@tanstack/query-core`. Query keys, cache options and request status never leave the service. [ch. 8, §7.3]
+- Queries declare what they're built from: `meta: { dependsOn: ['applications'] }`. After a write, the service calls `changed(cache, 'applications')`. A writer never knows who reads. [§5.2]
+- Temporary network failures are retried inside the cache. [§10.6]
+- `readJson` turns a 4xx `{ message }` into a `UserError` and a 5xx into a plain `Error`.
+
+## Server
+
+- A feature's routes are one chained `Hono` export: path, `validator` from `@compean/core/server` with a domain schema, one service call, an explicit status code. No route classes, no rules, no database calls. [ch. 7]
+- `app.ts` chains every feature's routes and exports `AppType`. `server.ts` mounts it under `/api` with `@hono/node-server`.
+- Services are classes with the feature's rules. They never read the HTTP context; routes pass `c.var.user.id` and validated input explicitly. [§5.1]
+- A service holds its own queries by default. A `*.repository.ts` exists only when its abstraction differs (joins, mapping rows into shapes, transactions) or two or more services share it. Writes that touch several tables run in one transaction inside the module that knows the tables. There's no interface around the database. [§9.6, ch. 8, §7.2]
+- Services return model types, never rows typed by the database schema, so the schema can't leak into `AppType`. [§5.2]
+- PostgreSQL, raw SQL through `postgres`, checked by SafeQL against the real schema, so lint needs a database locally and in CI. Migrations are plain `.sql` files run by dbmate, reviewed before merge. A local-first app with SQLite on the device picks its own tool.
+- Auth: Better Auth mounted in `app.ts`, with a `withSession` middleware that sets `c.var.user`. Its tables arrive as a reviewed migration. Who may do what is decided in services or policies; something the user may not see is reported as not found (`UserError(..., 404)`).
+
+## Errors
+
+- One class, `UserError(message, status)`, on both sides. Write the message where the cause is known. [§10.7]
+- First try to define the error away: deleting something already gone succeeds, moving to the current stage does nothing. [§10.3]
+- `app.onError` is the only place errors become HTTP: a `UserError` becomes `{ message }` with its status; an `HTTPException` below 500 (from Hono middleware) keeps its own response; anything else is reported and answered with a 500 and a generic message. Input validation errors take the `UserError` path through `validator`.
+- Unrecoverable problems at startup (missing config, no database) crash `boot.ts` immediately with a clear message. [§10.8]
+- No `try/catch` in routes, controllers or screens.
+
+### Reporting bugs
+
+- `ErrorReporter.report(error, { where, userId? })`, registered in each app's `boot.ts`: `ConsoleReporter` locally and in tests, a `SentryReporter` adapter in production. All apps report to one Sentry project. [§7.2]
+- Only `load()`, `run()` and `app.onError` call it, and never for a `UserError`.
+- A reporter may throw; core's callers then fall back to the console, so reporting never breaks error handling. [§10.6]
+
+## Tests
+
+- Vitest on Node for everything except end-to-end flows.
+- Models and policies: plain unit tests.
+- Controllers: unit tests with typed fakes registered in `$S`, no React rendering.
+- Services and repositories: integration tests against a real Postgres, a fresh database per test file cloned from a migrated template. Setup fails loudly when `TEST_DATABASE_URL` is missing.
+- Routes: a few `app.request()` tests per feature, which also exercise `app.onError`.
+- Screens: a few Playwright flows for the key journeys.
+- Every test starts with `resetServices()`; tests in one file don't run concurrently. [§7.5]
+- Test-first and bug-fix order follow `code-rules/process.md`.
+
+## Enforced by lint
+
+`@compean/core/eslint` checks:
+
+- Controllers and `packages/client` import no React, React Native, `@tanstack/react-router` or `expo-router`.
+- `packages/domain` imports nothing outside itself and Zod.
+- Route files define no `loader`.
+- Only the auth service imports `better-auth`; only client services import `@tanstack/query-core`.
+- SQL in `apps/api` passes SafeQL.

package/dist/changed.d.ts

@@ -0,0 +1,10 @@
+import type { QueryClient } from '@tanstack/query-core';
+/** Query metadata naming the resources a cached query is built from. */
+export interface DependsOnMeta<R extends string = string> {
+    dependsOn?: readonly R[];
+}
+/**
+ * Marks stale every cached query whose `meta.dependsOn` lists `resource`, so screens showing it
+ * refresh. A writer calls this after a change and never needs to know who reads.
+ */
+export declare function changed<R extends string>(cache: Pick<QueryClient, 'invalidateQueries'>, resource: R): Promise<void>;

package/dist/changed.js

@@ -0,0 +1,9 @@
+/**
+ * Marks stale every cached query whose `meta.dependsOn` lists `resource`, so screens showing it
+ * refresh. A writer calls this after a change and never needs to know who reads.
+ */
+export function changed(cache, resource) {
+    return cache.invalidateQueries({
+        predicate: (query) => query.meta?.dependsOn?.includes(resource) ?? false,
+    });
+}

package/dist/controller.d.ts

@@ -0,0 +1,57 @@
+import { Observable } from './observable.js';
+/**
+ * What the screen shows as a whole: a loading view, the content, or a full-screen error with retry.
+ * See "Controller status" in the README's design notes.
+ */
+export type ControllerStatus = 'loading' | 'ready' | 'error';
+/**
+ * One screen's logic and state. `state` is what the screen renders; actions are public methods.
+ * A controller runs unchanged on web and mobile, so it never imports React, React Native or a
+ * router. Subclasses override `initialize()` and `state`, load data with `load()` and perform
+ * actions with `run()`; neither needs a try/catch.
+ */
+export declare abstract class Controller<TState> extends Observable {
+    /** Undone on `dispose()` in reverse order, so the last thing tracked is undone first. */
+    private readonly cleanups;
+    private currentStatus;
+    /** The message for the 'error' status; null in any other status. */
+    private currentLoadError;
+    /** Loads started before the screen was first ready and not yet finished. The status settles at zero. */
+    private pendingFirstLoads;
+    /** The first failure among the pending first loads; it becomes the load error once they all finish. */
+    private firstLoadFailure;
+    /** Read by the screen after every `notify()`. Build it from fields; never fetch or do slow work here. */
+    abstract get state(): TState;
+    /**
+     * Subclass hook, called once by `start()` when the screen mounts. Start loading with `load()`
+     * and subscribe to services here, registering each unsubscribe with `track()`.
+     */
+    initialize(): void;
+    /**
+     * Mounts the controller: calls `initialize()`, then marks a screen that started no load as
+     * ready. `useController` calls this; tests call it in place of mounting a screen.
+     */
+    start(): void;
+    /** Safe to call more than once: each cleanup runs only the first time. */
+    dispose(): void;
+    protected get status(): ControllerStatus;
+    /** The message to show when status is 'error': a UserError's own words, or a generic one. */
+    protected get loadError(): string | null;
+    /** Runs `cleanup` (an unsubscribe, a clearTimeout) when the controller is disposed. */
+    protected track(cleanup: () => void): void;
+    /**
+     * Loads the screen's data. Before the screen is first ready, the status settles once every
+     * load started so far has finished: 'ready' if all succeeded, otherwise 'error' with the first
+     * failure's message (shown full screen; retry by calling `load()` again). Once ready, a load is
+     * a refresh: the data stays on screen and a failure shows as a toast. Never rejects.
+     */
+    protected load(task: () => Promise<void>): Promise<void>;
+    /**
+     * Performs an action. It never changes the screen's status: a failure shows as an error toast,
+     * with a UserError's own message or a generic one, and bugs are reported. Never rejects.
+     */
+    protected run(task: () => Promise<void>): Promise<void>;
+    /** The message the user sees for this error; reports it first unless it's a UserError. */
+    private describeAndReport;
+    private settle;
+}

package/dist/controller.js

@@ -0,0 +1,110 @@
+import { Observable } from './observable.js';
+import { $S } from './registry.js';
+import { reportSafely } from './report-safely.js';
+import { ToastService } from './toast.service.js';
+import { UserError } from './user-error.js';
+const GENERIC_MESSAGE = 'Something went wrong. Try again.';
+/**
+ * One screen's logic and state. `state` is what the screen renders; actions are public methods.
+ * A controller runs unchanged on web and mobile, so it never imports React, React Native or a
+ * router. Subclasses override `initialize()` and `state`, load data with `load()` and perform
+ * actions with `run()`; neither needs a try/catch.
+ */
+export class Controller extends Observable {
+    /** Undone on `dispose()` in reverse order, so the last thing tracked is undone first. */
+    cleanups = [];
+    currentStatus = 'loading';
+    /** The message for the 'error' status; null in any other status. */
+    currentLoadError = null;
+    /** Loads started before the screen was first ready and not yet finished. The status settles at zero. */
+    pendingFirstLoads = 0;
+    /** The first failure among the pending first loads; it becomes the load error once they all finish. */
+    firstLoadFailure = null;
+    /**
+     * Subclass hook, called once by `start()` when the screen mounts. Start loading with `load()`
+     * and subscribe to services here, registering each unsubscribe with `track()`.
+     */
+    initialize() { }
+    /**
+     * Mounts the controller: calls `initialize()`, then marks a screen that started no load as
+     * ready. `useController` calls this; tests call it in place of mounting a screen.
+     */
+    start() {
+        this.initialize();
+        if (this.pendingFirstLoads === 0 && this.currentStatus === 'loading') {
+            this.settle('ready', null);
+        }
+    }
+    /** Safe to call more than once: each cleanup runs only the first time. */
+    dispose() {
+        for (const cleanup of this.cleanups.splice(0).reverse()) {
+            cleanup();
+        }
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    /** The message to show when status is 'error': a UserError's own words, or a generic one. */
+    get loadError() {
+        return this.currentLoadError;
+    }
+    /** Runs `cleanup` (an unsubscribe, a clearTimeout) when the controller is disposed. */
+    track(cleanup) {
+        this.cleanups.push(cleanup);
+    }
+    /**
+     * Loads the screen's data. Before the screen is first ready, the status settles once every
+     * load started so far has finished: 'ready' if all succeeded, otherwise 'error' with the first
+     * failure's message (shown full screen; retry by calling `load()` again). Once ready, a load is
+     * a refresh: the data stays on screen and a failure shows as a toast. Never rejects.
+     */
+    async load(task) {
+        if (this.currentStatus === 'ready') {
+            await this.run(task);
+            return;
+        }
+        if (this.currentStatus === 'error') {
+            this.settle('loading', null);
+        }
+        this.pendingFirstLoads += 1;
+        try {
+            await task();
+        }
+        catch (error) {
+            this.firstLoadFailure ??= this.describeAndReport(error);
+        }
+        finally {
+            this.pendingFirstLoads -= 1;
+            if (this.pendingFirstLoads === 0) {
+                const failure = this.firstLoadFailure;
+                this.firstLoadFailure = null;
+                this.settle(failure ? 'error' : 'ready', failure);
+            }
+        }
+    }
+    /**
+     * Performs an action. It never changes the screen's status: a failure shows as an error toast,
+     * with a UserError's own message or a generic one, and bugs are reported. Never rejects.
+     */
+    async run(task) {
+        try {
+            await task();
+        }
+        catch (error) {
+            $S(ToastService).show(this.describeAndReport(error), 'error');
+        }
+    }
+    /** The message the user sees for this error; reports it first unless it's a UserError. */
+    describeAndReport(error) {
+        if (error instanceof UserError) {
+            return error.message;
+        }
+        reportSafely(error, { where: this.constructor.name });
+        return GENERIC_MESSAGE;
+    }
+    settle(status, loadError) {
+        this.currentStatus = status;
+        this.currentLoadError = loadError;
+        this.notify();
+    }
+}

package/dist/eslint/index.d.ts

@@ -0,0 +1,6 @@
+import type { Linter } from 'eslint';
+/**
+ * The framework rules a tool can check, as an ESLint flat config. Add it after your TypeScript
+ * parser setup: `export default [...typescriptConfig, ...compeanRules()]`.
+ */
+export declare function compeanRules(): Linter.Config[];