@contraagent/ui 0.0.0-stage → 0.1.0

package/docs/embed.md

@@ -0,0 +1,118 @@
+# Embed the monitor
+
+`<ca-monitor>` is the complete monitor: header, run switcher, tabs, filters,
+views and notifications. It holds the data (a `MonitorStore`) and the view route.
+Its attributes (`base-url`, `export`, `history`, `shortcuts`, `run`, `locale`, `theme`) are described in
+`custom-elements.json`. `history="url"` suits a page that is the monitor;
+inside an application that manages its own URL, use `history="memory"`.
+
+## What the host page keeps
+
+With `history="memory"`, the monitor leaves the page to its host:
+
+| | `history="url"` (the monitor is the page) | `history="memory"` (embedded) |
+|---|---|---|
+| View route (run, tab, filters) | the URL's query; Back and Forward | the element; the URL and the history are the host's |
+| Scroll positions, open sections | the page's history entry, under `contraagent` | the element |
+| `document.title` | `<title> monitor` | not written |
+| `<html lang>`, `<html data-ca-theme>` | follow the monitor's language and theme | not written; `lang` and `data-ca-theme` are set on `<ca-monitor>` |
+| Single-key shortcuts | anywhere in the page (`shortcuts="page"`) | only while the focus is inside the monitor (`shortcuts="element"`) |
+| The monitor's listeners on `document` and `window` | `keydown`, `popstate`, `pagehide` | none |
+
+The single-key shortcuts are 1 to 9 (the tabs), `r` (the run switcher) and `/`
+(the filter). In every scope they never take a key typed into a text field
+(`input`, `select`, `textarea`, an editable element), a key pressed with Ctrl,
+Alt or Meta, or a key a listener of the host already handled with
+`preventDefault()`. `shortcuts="off"` turns them off, and the tab bar then
+shows no key hint; `shortcuts="page"` gives an embedded monitor the whole page.
+
+While the run switcher or the theme menu is open, a click elsewhere in the page
+closes it (for the theme menu, a press of the pointer). The monitor listens on the
+document for that event only while one of them is open, and neither stops nor
+prevents it.
+
+Two monitors on one page each keep their own view route, scroll positions, open
+sections and shortcuts. They share what is one per page:
+
+- the language: Lit Localize has one locale per page, so `locale` on one
+  monitor, or its language switch, changes the other's too;
+- the reader's choices of language and theme, remembered in `localStorage`
+  (`contraagent:locale`, `contraagent:theme`), as the monitor's switches do;
+- the themes' rules, added once to the document's adopted style sheets; they
+  match only `[data-ca-theme]`, so the host's own elements are not restyled;
+- Lit Localize's `lit-localize-status` event on `window`, which every element
+  listens for to change its language.
+
+`e2e/embed.spec.ts` (in the repository's `web/`) checks this on a host page
+with its own title, text field and single-key shortcuts, and two monitors.
+
+## Connection
+
+`base-url` names the monitor server, such as `http://127.0.0.1:8787`; unset,
+it is the page's own origin. Every attribute takes effect whenever it is set,
+as an attribute or a property, before or after the element connects or the
+package loads:
+
+| Attribute | A change after connecting |
+|---|---|
+| `base-url` | closes the old server's feeds and reads the new server: the run named by `run`, else its newest run |
+| `history` | `memory` keeps the view route shown; `url` takes the address bar's |
+| `run` | opens that run |
+| `locale`, `theme`, `shortcuts` | show at once |
+
+A request to the API that gets no JSON answer is shown above the view, with
+its URL and its cause, and written to the console with `console.error`; the
+monitor then never shows "No runs yet". The causes (`ApiError.failure` in
+`@contraagent/api`):
+
+| Cause | Typical reason |
+|---|---|
+| the response is HTML, not JSON | `base-url` names a server without the API, such as a development server that answers every path with the page (`index.html`) |
+| the response is not JSON | the server at `base-url` answers with an empty body or with text |
+| the response status is 404 | `base-url` names a server, or a path on it, without the API |
+| network error, no response | the monitor server is not running, or it does not allow the page's origin (`--cors-origin`, below) |
+
+The run list (`/api/runs`) is asked for every 5 seconds, and the title and the
+custom views (`/api/info`) with it until they arrive, so a server that starts
+later is read when it answers, and the message goes.
+
+## An export, with no server
+
+`export` names an export's `data/` directory (`contraagent monitor export`) in
+place of a server: `<ca-monitor export="data/">`, relative to the page or
+absolute; set, it outranks `base-url`. The monitor then makes no request to an API
+and opens no feed: it reads the export's files, and its header shows when the
+export was written in place of the connection. An export holds no transcripts and no processes.
+
+## Without a build step
+
+::code{file="examples/embed.html"}
+
+A page on another origin can only import `/app.js` and read the API if the
+monitor names that origin: `contraagent monitor --cors-origin http://localhost:8000`.
+
+## In an application
+
+A Vite application: the page holds `<ca-monitor>` in a box, and `src/main.ts`
+imports the package and sets the monitor's `base-url`.
+
+::code{file="examples/vite/index.html"}
+
+::code{file="examples/vite/main.ts"}
+
+A page served by Vite answers an unknown path such as `/api/runs` with its own
+`index.html`: a monitor there without `base-url` shows "No monitor API at
+http://localhost:5173/api/info: the response is HTML, not JSON" (Connection,
+above).
+
+Import the package once; the elements register themselves. When it connects,
+`<ca-monitor>` sets up the languages (`configureLocales()`) and adds the
+themes' rules to its document (`adoptThemes(this.ownerDocument)`); a page
+that shows other elements without a monitor calls them itself (`adoptThemes`
+is in `@contraagent/elements/themes`). Give `<ca-monitor>` a box with a height: it fills it and scrolls inside it.
+It lays itself out by the box's width, not the window's: in a narrow box the
+header wraps and the tab list scrolls sideways. In React
+19, Vue, Svelte, Astro or plain HTML, `<ca-monitor>` is an ordinary element.
+Properties without an attribute take objects and arrays: set them from script
+(`el.rows = [...]`), or with a property binding in your framework (`.rows=${...}`
+in Lit, `rows={...}` in React 19).

package/docs/events.md

@@ -0,0 +1,38 @@
+# Events and the view route
+
+## Events
+
+An element never changes what is shown on its own. It sends an event saying
+what the reader asked for; its host decides. The monitor changes its view route;
+another page might open its own view, or ignore it. Each event crosses shadow
+roots and all but `ca-rounds` bubble, so you can listen on any ancestor, and
+each is typed in `HTMLElementEventMap`:
+
+::code{file="../src/core/events.ts" from="export interface OpenTaskDetail" to="declare global"}
+
+```ts
+document.addEventListener('ca-open-task', (e) => {
+  e.detail.key; // string: typed, no cast
+});
+```
+
+## The view route
+
+`<ca-monitor>` keeps one typed value for where the reader is, and mirrors it in
+the URL (or in memory, with `history="memory"`):
+
+::code{file="../src/core/view-route.ts" from="export interface ViewRoute" to="export type ViewRoutePatch"}
+
+Moving to another place (a tab, a task, a view, a round, a definition, a run)
+pushes a history entry, so Back returns. Changing a filter replaces the entry,
+so typing does not fill the history.
+
+## The reader's place
+
+What the URL does not say is kept in the history entry itself
+(`history.state`, under one key, merged with whatever the host keeps
+there): how far each list is scrolled and which cards are open. Back, Forward
+and a reload return to it; a new place starts at the top. Restoring waits until
+the content, which arrives over the network, is tall enough to scroll to the
+remembered position. Tool cards opened in a transcript are kept for the browser
+tab, since one transcript is shown on several entries.

package/docs/examples/embed.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<!--
+  The whole monitor inside a page of your own, with no build step.
+
+  The monitor serves its elements as an ES module (/app.js). Let this page's
+  origin use it, then open the page:
+
+    contraagent monitor --runs-dir runs --cors-origin http://localhost:8000
+    python -m http.server 8000 --directory docs/examples
+    # http://localhost:8000/embed.html
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>contraagent, embedded</title>
+    <script type="module" src="http://127.0.0.1:8787/app.js"></script>
+    <style>
+      body { margin: 0; font-family: system-ui, sans-serif; }
+      .pane { height: 70vh; border: 1px solid #93a1a1; border-radius: 8px; overflow: hidden; margin: 16px; }
+    </style>
+  </head>
+  <body>
+    <h1 style="margin: 16px">Our release pipeline</h1>
+    <!-- `memory`: the monitor keeps its view route to itself and leaves this page's URL alone.
+         The class sets a theme of your own on the monitor itself, which carries `data-ca-theme`. -->
+    <div class="pane">
+      <ca-monitor class="solarized-light" base-url="http://127.0.0.1:8787" history="memory"></ca-monitor>
+    </div>
+  </body>
+</html>

package/docs/examples/journal.ts

@@ -0,0 +1,32 @@
+// A run's journal, live, with the store doing the data work: the store folds
+// the run feed into one typed state, the element draws it.
+import { MonitorStore, isBad } from '@contraagent/api';
+import '@contraagent/ui/journal-table';
+
+export function showJournal(host: HTMLElement, run: string, openTask: (key: string) => void): () => void {
+  const store = new MonitorStore({ baseUrl: 'http://127.0.0.1:8787' });
+  const table = document.createElement('ca-journal-table');
+  host.replaceChildren(table);
+
+  // Every change: the newest state, already typed (`RunState`).
+  const unsubscribe = store.subscribe((s) => {
+    table.rows = s.state.journal;
+    table.plan = s.state.plan;
+    table.fresh = s.fresh;
+  });
+  // Rows that arrive after the replay: tasks that just finished.
+  const unwatch = store.onNewRow((row) => {
+    if (isBad(row)) console.warn(`${row.key} ended ${row.stop}: ${row.reason ?? ''}`);
+  });
+  // The element asks; the page answers.
+  table.addEventListener('ca-filter', (e) => (table.stop = e.detail.stop ?? ''));
+  table.addEventListener('ca-open-task', (e) => openTask(e.detail.key));
+
+  void store.start();
+  store.selectRun(run);
+  return () => {
+    unsubscribe();
+    unwatch();
+    store.stop();
+  };
+}

package/docs/examples/live-transcript.ts

@@ -0,0 +1,22 @@
+// One task's transcript, tailed live, in a page of your own.
+//
+// The element renders; the page decides what a reader's request means. Here a
+// round picked in the transcript is simply shown.
+import { createMonitorClient } from '@contraagent/api';
+import '@contraagent/ui/transcript';
+
+/** Where `contraagent monitor` runs (start it with `--cors-origin <this page's origin>`). */
+const MONITOR = 'http://127.0.0.1:8787';
+
+export function showTranscript(host: HTMLElement, run: string, key: string): void {
+  const t = document.createElement('ca-transcript');
+  t.client = createMonitorClient({ baseUrl: MONITOR }); // for "load earlier"
+  t.baseUrl = MONITOR; // the live feed
+  t.run = run;
+  t.stream = key;
+  t.live = true;
+  t.addEventListener('ca-navigate', (e) => {
+    if (e.detail.round !== undefined) t.round = e.detail.round;
+  });
+  host.replaceChildren(t);
+}

package/docs/examples/vite/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<!-- The application's page (index.html), with the monitor in #monitor; main.ts names its server. -->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Release dashboard</title>
+    <style>
+      body { margin: 0; font-family: system-ui, sans-serif; }
+      header { display: flex; align-items: center; gap: 16px; padding: 12px 16px; }
+      header h1 { flex: 1; margin: 0; font-size: 20px; }
+      /* The monitor fills the box it is in, and scrolls inside it: the box has a height. */
+      #monitor { height: calc(100vh - 80px); margin: 0 16px; border: 1px solid #8884; border-radius: 8px; overflow: hidden; }
+    </style>
+    <script type="module" src="/src/main.ts"></script>
+  </head>
+  <body>
+    <header>
+      <h1>Release dashboard</h1>
+      <label>Language
+        <select id="language">
+          <option value="en">English</option>
+          <option value="ja">日本語</option>
+        </select>
+      </label>
+    </header>
+    <!-- `memory`: the view route stays in the element; the page's URL, title and <html> stay the application's. -->
+    <div id="monitor"><ca-monitor history="memory" locale="en"></ca-monitor></div>
+  </body>
+</html>

package/docs/examples/vite/main.ts

@@ -0,0 +1,23 @@
+// The monitor inside a Vite application, as src/main.ts. Its dependencies:
+// @contraagent/ui, and its peers lit and @lit/localize.
+//
+// The monitor runs on another origin and lets this page read its API:
+//
+//   contraagent monitor --runs-dir runs --cors-origin http://localhost:5173
+//   pnpm vite   # http://localhost:5173
+//
+// The import registers <ca-monitor> (and every element it renders). Its
+// properties take effect whenever they are set, before or after the import.
+import '@contraagent/ui/monitor';
+import type { CaMonitor } from '@contraagent/ui/monitor';
+
+/** Where the monitor serves its API: another origin, named with `--cors-origin`. */
+const MONITOR = 'http://127.0.0.1:8787';
+
+const monitor = document.querySelector('ca-monitor')!;
+monitor.baseUrl = MONITOR; // the `base-url` attribute
+
+// `locale` changes the monitor's language in place.
+const language = document.querySelector<HTMLSelectElement>('#language')!;
+language.value = monitor.locale;
+language.addEventListener('change', () => (monitor.locale = language.value as CaMonitor['locale']));

package/docs/languages.md

@@ -0,0 +1,48 @@
+# Languages
+
+Every element speaks English and Japanese, and switches in place, without a
+reload, with Lit Localize.
+
+## How the language is chosen
+
+In the monitor, the switch in the header (`English` / `日本語`) changes the
+language and remembers it for the next visit. With no choice made yet, the
+monitor follows the browser's languages, then falls back to English.
+
+`<ca-monitor locale="ja">` fixes the language for an embedded monitor. In
+your own page, set it for every element at once:
+
+```ts
+import { setLocale, chooseLocale } from '@contraagent/ui/localize';
+
+await setLocale('ja');     // this page only
+await chooseLocale('ja');  // and remember it, as the monitor's switch does
+```
+
+## Setting up Lit Localize
+
+Importing the package does not configure Lit Localize. `configureLocales()`
+does, once per page; `<ca-monitor>` calls it when it connects, and `setLocale`
+calls it first if nothing has. Until then the elements speak English. A
+language's text is a module of its own, loaded the first time the language is
+chosen; `<ca-monitor>` draws its first view after it is loaded.
+
+Lit Localize can be configured only once per page. On a page whose own code
+configured it first, `configureLocales()` returns `false`: the elements stay
+in English and `<ca-monitor>` shows no language switch.
+
+What is translated is the monitor's own wording: labels, headings, tooltips and
+causes, and the words for a run's codes (a stop such as `completed` shows as
+"done"; a code the monitor does not know shows as `unknown (<code>)`). Dates
+and times follow the language too (`Oct 12, 10:38:40`, `10月12日 10:38:40`). What
+a run wrote stays as it is: kind and unit names, model and role names, file
+paths, failure reasons, and the transcripts.
+
+## Adding a language
+
+The English text is written in the sources, wrapped in `msg()`. Translations
+live in one XLIFF file per language (`xliff/<locale>.xlf`), and a typed module is
+generated from each. A new language is one more code in `targetLocales` of
+`lit-localize.json`, its name in `LOCALE_NAMES`, and a loader for its generated module:
+
+::code{file="../src/core/i18n.ts" from="/** Each locale's name" to="let localization"}

package/docs/live-data.md

@@ -0,0 +1,17 @@
+# Live data
+
+The elements draw what they are given; `@contraagent/api` gets it: a typed
+client, the live feeds and a store that folds a run's feed into one state.
+
+## A run's journal
+
+The store does the data work and the element draws it:
+
+::code{file="examples/journal.ts"}
+
+## One transcript, tailed
+
+`<ca-transcript>` tails a task's transcript itself when it is given `run` and
+`stream`; the page decides what a reader's request means:
+
+::code{file="examples/live-transcript.ts"}

package/docs/theming.md

@@ -0,0 +1,21 @@
+# Theming
+
+The elements take their colours, fonts, type scale and corners from the
+`--ca-*` custom properties and the built-in themes of `@contraagent/elements`:
+[its theming page](../../elements/docs/theming.md) lists them, what each colour
+means, and how to build a theme of your own. `adoptThemes(document)` adds the
+themes' rules to the page's document, so `data-ca-theme` on any ancestor picks
+a theme; `<ca-monitor>` calls it when it connects, and importing the package
+does not.
+
+## The monitor's theme
+
+In the monitor, the header's theme control changes the theme and remembers it
+in this browser. `System` follows the system's colour scheme (contraagent Dark
+or contraagent Light). With no choice made, the monitor shows contraagent Dark.
+
+`<ca-monitor theme="nord">` fixes the theme of an embedded monitor; it also
+takes `system`. The theme it shows is reflected as `data-ca-theme` on the
+element (and on `<html>`, with `history="url"`). A theme of your own (a set of
+`--ca-*` properties) goes on `<ca-monitor>` itself, which carries that
+attribute: `<ca-monitor class="solarized-light">`.

package/docs/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  // The examples are documentation: they compile against the packages as they are.
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "paths": {
+      "@contraagent/api": ["../../api/src/index.ts"],
+      "@contraagent/elements": ["../../elements/src/index.ts"],
+      "@contraagent/elements/*": ["../../elements/src/*"],
+      "@contraagent/ui": ["../src/index.ts"]
+    }
+  },
+  "include": ["examples/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "@contraagent/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Web components for the contraagent monitor: transcripts, task tables, the journal, plans, contracts. Framework-free (Lit), typed by @contraagent/api",
+  "license": "MIT",
+  "keywords": [
+    "contraagent",
+    "coding-agent",
+    "monitor",
+    "web-components",
+    "lit",
+    "custom-elements"
+  ],
+  "homepage": "https://t-tani.github.io/contraagent/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t-tani/contraagent.git",
+    "directory": "web/packages/ui"
+  },
+  "bugs": {
+    "url": "https://github.com/t-tani/contraagent/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./monitor": {
+      "types": "./dist/define/monitor.d.ts",
+      "default": "./dist/define/monitor.js"
+    },
+    "./overview": {
+      "types": "./dist/define/overview.d.ts",
+      "default": "./dist/define/overview.js"
+    },
+    "./pipeline-graph": {
+      "types": "./dist/define/pipeline-graph.d.ts",
+      "default": "./dist/define/pipeline-graph.js"
+    },
+    "./task-view": {
+      "types": "./dist/define/task-view.d.ts",
+      "default": "./dist/define/task-view.js"
+    },
+    "./transcript": {
+      "types": "./dist/define/transcript.d.ts",
+      "default": "./dist/define/transcript.js"
+    },
+    "./task-table": {
+      "types": "./dist/define/task-table.d.ts",
+      "default": "./dist/define/task-table.js"
+    },
+    "./journal-table": {
+      "types": "./dist/define/journal-table.d.ts",
+      "default": "./dist/define/journal-table.js"
+    },
+    "./contracts": {
+      "types": "./dist/define/contracts.d.ts",
+      "default": "./dist/define/contracts.js"
+    },
+    "./definitions": {
+      "types": "./dist/define/definitions.d.ts",
+      "default": "./dist/define/definitions.js"
+    },
+    "./kpis": {
+      "types": "./dist/define/kpis.d.ts",
+      "default": "./dist/define/kpis.js"
+    },
+    "./timeline": {
+      "types": "./dist/define/timeline.d.ts",
+      "default": "./dist/define/timeline.js"
+    },
+    "./procs": {
+      "types": "./dist/define/procs.d.ts",
+      "default": "./dist/define/procs.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "default": "./dist/adapters/index.js"
+    },
+    "./words": {
+      "types": "./dist/words/index.d.ts",
+      "default": "./dist/words/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./localize": {
+      "types": "./dist/core/i18n.d.ts",
+      "default": "./dist/core/i18n.js"
+    },
+    "./bundle": "./dist/contraagent-ui.js",
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "customElements": "custom-elements.json",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
+    "docs",
+    "!docs/images",
+    "custom-elements.json"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/define/*.js",
+    "./dist/elements/**"
+  ],
+  "dependencies": {
+    "@contraagent/api": "0.1.0",
+    "@contraagent/elements": "0.1.0"
+  },
+  "peerDependencies": {
+    "@lit/localize": "^0.12.2",
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
+    "@lit/localize": "^0.12.2",
+    "@lit/localize-tools": "^0.8.2",
+    "lit": "^3.3.3",
+    "terser": "^5.51.2",
+    "vite": "^8.3.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && vite build && cem analyze --litelement --globs 'src/elements/**/*.ts' --exclude 'src/elements/**/graph/**' 'src/elements/**/pipeline-graph/**' 'src/elements/**/*-model.ts'",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p docs",
+    "i18n": "lit-localize extract && lit-localize build",
+    "i18n:check": "node scripts/i18n-check.mjs"
+  }
+}

package/src/adapters/check-rows.ts

@@ -0,0 +1,78 @@
+// A checked file's fields as the rows of `<cae-check-table>`: each field of its
+// schema against what the file holds, and the fields the schema does not name.
+// Pure.
+import type { ContractSpec } from '@contraagent/api';
+import type { CheckRow, CheckTableStrings } from '@contraagent/elements/check-table';
+import { msg, str } from '@lit/localize';
+
+/** Whether a value has a schema's type; true for a type this check cannot judge (the model's own check judges it). */
+export function typeOk(t: string, v: unknown): boolean {
+  if (t.startsWith('list[') || t === 'array') return Array.isArray(v);
+  if (t === 'string') return typeof v === 'string';
+  if (t === 'integer') return Number.isInteger(v);
+  if (t === 'number') return typeof v === 'number';
+  if (t === 'boolean') return typeof v === 'boolean';
+  if (t === 'object') return v !== null && typeof v === 'object' && !Array.isArray(v);
+  return true;
+}
+
+/** A `RootModel[str]`-style schema: the model wraps one value of the given type. */
+export const rootOf = (name: string): string | null => /^RootModel\[(.+)\]$/.exec(name)?.[1] ?? null;
+
+/** The file as a JSON object, or null (no file, not JSON, or another JSON value). */
+export function contentObject(o: ContractSpec): Record<string, unknown> | null {
+  const c = o.file.content;
+  return o.file.exists && c !== null && typeof c === 'object' && !Array.isArray(c) ? (c as Record<string, unknown>) : null;
+}
+
+/**
+ * A row per field of the schema, then a row per field the file has that the
+ * schema does not name. Without a file, the fields with no values or verdicts;
+ * with a file that is not a JSON object, the fields with no verdicts. Null for
+ * a text result (a text file, or one JSON value), which has no fields to check.
+ */
+export function checkRowsFromContract(o: ContractSpec): CheckRow[] | null {
+  if (!o.fields.length && (o.schema_name === 'text' || rootOf(o.schema_name) !== null)) return null;
+  const obj = contentObject(o);
+  const rows: CheckRow[] = o.fields.map((x) => {
+    const base = { name: x.name, expected: x.type, optional: !x.required };
+    if (!obj) return { ...base, hasValue: false, verdict: 'none', verdictLabel: '' };
+    if (!(x.name in obj))
+      return x.required
+        ? { ...base, hasValue: false, verdict: 'fail', verdictLabel: msg('missing'), tip: msg('A required field that is not in the file') }
+        : { ...base, hasValue: false, verdict: 'none', verdictLabel: msg('absent (optional)') };
+    const value = obj[x.name];
+    return typeOk(x.type, value)
+      ? { ...base, hasValue: true, value, verdict: 'pass', verdictLabel: msg('passed') }
+      : { ...base, hasValue: true, value, verdict: 'fail', verdictLabel: msg('wrong type'), tip: msg(str`Expected ${x.type}`) };
+  });
+  const extra = obj ? Object.keys(obj).filter((k) => !o.fields.some((x) => x.name === k)) : [];
+  return [
+    ...rows,
+    ...extra.map(
+      (k): CheckRow => ({
+        name: k,
+        expected: msg('not in the schema'),
+        extra: true,
+        hasValue: true,
+        value: obj?.[k],
+        verdict: 'warn',
+        verdictLabel: msg('extra field'),
+        tip: msg('Not in the schema'),
+      }),
+    ),
+  ];
+}
+
+/** The check table's words. */
+export function checkTableStrings(): CheckTableStrings {
+  return {
+    name: msg('Field'),
+    expected: msg('Expected'),
+    actual: msg('In the file'),
+    verdict: msg('Check'),
+    optional: msg('optional'),
+    items: (n) => (n === 1 ? msg('1 item') : msg(str`${n} items`)),
+    object: msg('object'),
+  };
+}