@dolphy-app/extension-sdk 0.4.0 → 0.5.0

package/docs/recipe-hooks.md

@@ -0,0 +1,158 @@
+# Recipe: hooks before a session and a batch
+
+Step into the learning loop. A `before` hook runs before the engine does
+something and may change its input or cancel it. This recipe reorders the
+exercises of a session so that reviews come before new material and the most
+forgotten come first, and refuses to
+start a session in the small hours. There is no template for it; start from
+`blank` and replace the files below, which are checked as a whole project. See
+[quick-start.md](quick-start.md) for the commands. Events, which only observe,
+are in [recipe-event-storage.md](recipe-event-storage.md).
+
+## The manifest
+
+File `extension.json` (hooks):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Reviews first",
+  "description": "Puts reviews before new exercises and keeps sessions out of the small hours.",
+  "author": "your-github-login",
+  "tags": ["learning"]
+}
+```
+
+Nothing about hooks is in the manifest: `server.before` is the registration.
+
+## The code
+
+File `src/index.ts` (hooks):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+
+const REVIEW_FIRST = { review: 0, remediation: 1, new: 2 } as const;
+
+export const server = defineServer((s) => {
+  // may only cancel: throw to stop the session from starting
+  s.before('session.start', ({ now }) => {
+    if (new Date(now).getHours() < 6) {
+      throw new Error('Sessions are closed until six in the morning');
+    }
+  });
+
+  // gets the batch the engine built and returns the one to use
+  // reviews before new material, the most forgotten first within a group
+  s.before('practice.batch', ({ exerciseIds, reasons, memory }) => {
+    const items = exerciseIds
+      .map((id, index) => ({
+        id,
+        reason: reasons[index] ?? 'new',
+        // no attempts yet: nothing to forget
+        retrievability: memory[index]?.retrievability ?? 1,
+      }))
+      .sort(
+        (a, b) =>
+          REVIEW_FIRST[a.reason] - REVIEW_FIRST[b.reason] ||
+          a.retrievability - b.retrievability,
+      );
+    return {
+      exerciseIds: items.map(({ id }) => id),
+      reasons: items.map(({ reason }) => reason),
+    };
+  });
+});
+```
+
+- `server.before(name, handler)` registers a hook. The names are a closed list:
+  `session.start` and `practice.batch`; another name fails the registration.
+  One handler per name; the call returns a `Disposable`.
+- `session.start` gets `{ now }` (epoch milliseconds) and returns nothing. The
+  only way to act is to throw: the session is not created and the learner sees
+  the message of your error.
+- `practice.batch` gets `{ sessionId, exerciseIds, reasons, memory, source }`
+  (`sessionId` is `null` while the session does not exist yet, as in the daily
+  plan before it starts).
+  `reasons[i]` (`review`, `new` or `remediation`) belongs to `exerciseIds[i]`;
+  `source` is `batch` for `practice.getBatch` and `plan` for the daily plan the
+  window builds a session from. `memory[i]` is what the engine remembers of
+  `exerciseIds[i]`, read-only: `retrievability` (0..1 chance to recall now),
+  `lastAttemptAt` (epoch milliseconds), `attempts`, and the FSRS `stability`
+  (days) and `difficulty`. An exercise with no attempts has `attempts: 0` and
+  `null` in the other fields. Return `{ exerciseIds, reasons }` of the same
+  length. You may reorder, drop and add exercises; every id must exist in the
+  library, at most 500 ids.
+- Extensions with a hook run one after another in the order of their ids; each
+  gets the result of the previous one. A handler has 30 seconds.
+- An error, a timeout or an answer the engine rejects (a missing exercise,
+  unequal lengths, too many ids) cancels the whole operation: no session, no
+  batch, nothing written to the journal. The caller gets the engine error
+  `EXTENSION_HOOK_FAILED` with the extension id and your message, and the window
+  shows it like any other failure to start a session.
+
+## The test
+
+File `test/index.test.ts` (hooks):
+
+```ts
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
+import { expect, it } from 'vitest';
+import { server } from '../src/index.ts';
+
+const start = () => createTestServer(server, { extensionId: 'acme.hello' });
+
+it('puts reviews before new exercises', async () => {
+  const running = await start();
+  const batch = await running.hook('practice.batch', {
+    sessionId: 's1',
+    exerciseIds: ['c::l::a', 'c::l::b', 'c::l::c'],
+    reasons: ['new', 'review', 'remediation'],
+    memory: [
+      { retrievability: null, lastAttemptAt: null, attempts: 0, stability: null, difficulty: null },
+      { retrievability: 0.8, lastAttemptAt: 1_000, attempts: 3, stability: 9, difficulty: 4 },
+      { retrievability: 0.3, lastAttemptAt: 2_000, attempts: 1, stability: 2, difficulty: 6 },
+    ],
+    source: 'batch',
+  });
+  expect(batch).toEqual({
+    exerciseIds: ['c::l::b', 'c::l::c', 'c::l::a'],
+    reasons: ['review', 'remediation', 'new'],
+  });
+  await running.dispose();
+});
+
+it('puts the most forgotten exercises first within a group', async () => {
+  const running = await start();
+  const batch = await running.hook('practice.batch', {
+    sessionId: 's1',
+    exerciseIds: ['c::l::a', 'c::l::b', 'c::l::c'],
+    reasons: ['new', 'review', 'review'],
+    memory: [
+      { retrievability: null, lastAttemptAt: null, attempts: 0, stability: null, difficulty: null },
+      { retrievability: 0.8, lastAttemptAt: 1_000, attempts: 3, stability: 9, difficulty: 4 },
+      { retrievability: 0.3, lastAttemptAt: 2_000, attempts: 1, stability: 2, difficulty: 6 },
+    ],
+    source: 'batch',
+  });
+  expect(batch.exerciseIds).toEqual(['c::l::c', 'c::l::b', 'c::l::a']);
+  expect(batch.reasons).toEqual(['review', 'review', 'new']);
+  await running.dispose();
+});
+
+it('refuses to start a session in the small hours', async () => {
+  const running = await start();
+  const night = new Date(2026, 9, 7, 3).getTime();
+  await expect(running.hook('session.start', { now: night })).rejects.toThrow(
+    'Sessions are closed until six in the morning',
+  );
+  const morning = new Date(2026, 9, 7, 9).getTime();
+  await expect(
+    running.hook('session.start', { now: morning }),
+  ).resolves.toBeUndefined();
+  await running.dispose();
+});
+```

package/docs/recipe-import-export.md

@@ -20,34 +20,19 @@ File `extension.json` (import-export):
   "name": "Hello cards",
   "description": "Import flashcards from a CSV file and export a course back to CSV.",
   "author": "your-github-login",
-  "tags": ["content"],
-  "contributes": {
-    "importers": [
-      { "id": "acme.hello.import", "title": "Cards from CSV", "accept": [".csv"] }
-    ],
-    "exporters": [
-      { "id": "acme.hello.export", "title": "Course to CSV", "scope": "course" }
-    ]
-  }
+  "tags": ["content"]
 }
 ```
 
-- An importer has an `id`, a `title` (up to 60 characters), `accept` (1–8
-  lower-case file extensions such as `.csv`) and an optional `input`: `text`
-  (the default, the handler gets the file as a UTF-8 string) or `bytes` (a
-  `Uint8Array`). An exporter has `scope`: `course` or `progress`.
-- No permission is needed: the user choosing the file is the consent, and your
-  code never sees a path. A `progress` exporter reads `ctx.stats` and needs the
-  `learning.stats` permission.
-- The importer appears in the palette as "Import: Cards from CSV", the exporter
-  as "Export: Course to CSV", and both have buttons in Settings → Library.
+The manifest holds the identity only; the importer and the exporter are
+registered by the code.
 
 ## The code
 
 File `src/index.ts` (import-export):
 
 ```ts
-import { defineExtension } from '@dolphy-app/extension-sdk';
+import { defineServer } from '@dolphy-app/extension-sdk';
 import type {
   CourseExportInput,
   TextImportInput,
@@ -62,11 +47,15 @@ const courseIdOf = (fileName: string): string =>
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-|-$/g, '') || 'cards';
 
-export const host = defineExtension({
-  importers: {
+export const server = defineServer((s) => {
+  s.registerImporter({
+    id: 'acme.hello.import',
+    title: { en: 'Cards from CSV', ru: 'Карточки из CSV' },
+    accept: ['.csv'],
+    input: 'text',
     // one line "front,back" is one flashcard; the paths are relative to the
     // new course directory the app creates
-    'acme.hello.import': ({ name, text }: TextImportInput) => {
+    run: ({ name, text }: TextImportInput) => {
       const rows = text.split(/\r?\n/).filter((line) => line.trim() !== '');
       if (rows.length === 0) throw new Error('The file has no rows');
       const course = courseIdOf(name);
@@ -109,11 +98,15 @@ export const host = defineExtension({
       });
       return { files };
     },
-  },
-  exporters: {
+  });
+
+  s.registerExporter({
+    id: 'acme.hello.export',
+    title: { en: 'Course to CSV', ru: 'Курс в CSV' },
+    scope: 'course',
     // the snapshot holds the text files of the chosen course, paths relative
     // to the course directory
-    'acme.hello.export': ({ title, files }: CourseExportInput) => {
+    run: ({ title, files }: CourseExportInput) => {
       const cell = (text: string): string => text.trim().replace(/\s+/g, ' ');
       const fronts = Object.keys(files)
         .filter((path) => path.endsWith('/front.md'))
@@ -127,10 +120,20 @@ export const host = defineExtension({
         text: `${rows.join('\n')}\n`,
       };
     },
-  },
+  });
 });
 ```
 
+- `server.registerImporter({ id, title, accept, input, run })`: `title` (up to 60
+  characters) is a `LocalizedText`; `accept` is 1–8 unique lower-case file
+  extensions such as `.csv`; `input` is `text` (the handler gets the file as a
+  UTF-8 string) or `bytes` (a `Uint8Array`). `server.registerExporter({ id,
+  title, scope, run })` has a `scope`: `course` or `progress`. At most 8 of each
+  per extension.
+- The user choosing the file is the consent, and your code never sees a path. A
+  `progress` exporter reads `server.stats`.
+- The importer appears in the palette as "Import: Cards from CSV", the exporter
+  as "Export: Course to CSV", and both have buttons in Settings → Library.
 - An importer handler gets `{ name, text }` (or `{ name, bytes }`) and returns
   `{ files: Record<path, text> }`: the files of a new directory in the library
   (`imported/<extension id>-<file name>`). At most 5000 files, 2 MiB each and
@@ -147,30 +150,24 @@ export const host = defineExtension({
   and is at most 120 characters. The app asks the user where to save it.
 - A handler has 30 seconds. Throw an `Error` to refuse: its message reaches the
   user, and nothing is written.
-- A handler that needs `ctx` is registered in `activate` with
-  `ctx.importers.register(id, handler)` / `ctx.exporters.register(id, handler)`
-  (`inActivate` in the record, as for commands).
 
 ## The tests
 
 File `test/index.test.ts` (import-export):
 
 ```ts
-import {
-  loadExporters,
-  loadImporters,
-} from '@dolphy-app/extension-sdk/testing';
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
 import { describe, expect, it } from 'vitest';
-import { host } from '../src/index.ts';
+import { server } from '../src/index.ts';
 
 const CSV = 'hola,hello\nadiós,goodbye\n';
 
+const start = () => createTestServer(server, { extensionId: 'acme.hello' });
+
 describe('acme.hello: importer', () => {
   it('turns every row into a flashcard of one lesson', async () => {
-    const importers = await loadImporters(host, {
-      declaredImporters: [{ id: 'acme.hello.import' }],
-    });
-    const { files } = await importers.run('acme.hello.import', {
+    const running = await start();
+    const { files } = await running.importer('acme.hello.import').run({
       name: 'Spanish basics.csv',
       text: CSV,
     });
@@ -185,26 +182,24 @@ describe('acme.hello: importer', () => {
       'spanish-basics/course_manifest.json',
     ]);
     expect(files['spanish-basics/cards/c2/front.md']).toBe('adiós\n');
-    await importers.dispose();
+    await running.dispose();
   });
 
   it('refuses a row without an answer', async () => {
-    const importers = await loadImporters(host, {
-      declaredImporters: [{ id: 'acme.hello.import' }],
-    });
+    const running = await start();
     await expect(
-      importers.run('acme.hello.import', { name: 'x.csv', text: 'hola\n' }),
+      running
+        .importer('acme.hello.import')
+        .run({ name: 'x.csv', text: 'hola\n' }),
     ).rejects.toThrow('Row 1');
-    await importers.dispose();
+    await running.dispose();
   });
 });
 
 describe('acme.hello: exporter', () => {
   it('writes the cards of the snapshot back to CSV', async () => {
-    const exporters = await loadExporters(host, {
-      declaredExporters: [{ id: 'acme.hello.export', scope: 'course' }],
-    });
-    const result = await exporters.run('acme.hello.export', {
+    const running = await start();
+    const result = await running.exporter('acme.hello.export').run({
       scope: 'course',
       courseId: 'deck',
       title: 'Deck / Spanish',
@@ -221,18 +216,18 @@ describe('acme.hello: exporter', () => {
       filename: 'Deck - Spanish.csv',
       text: 'hola,hello\nadiós,goodbye\ndiez,ten\n',
     });
-    await exporters.dispose();
+    await running.dispose();
   });
 });
 ```
 
-`loadImporters` and `loadExporters` activate the module in memory and run a
-handler with the rules of the host: the `text`/`bytes` form of a declared
-importer, the `scope` of a declared exporter, the size of the input and the
+`running.importer(id).run(input)` and `running.exporter(id).run(input)` run a
+handler with the rules of the host: the `text`/`bytes` form the importer
+declares, the `scope` the exporter declares, the size of the input and the
 shape and limits of the result. A broken result rejects with
 `invalid import result: …` / `invalid export result: …`, so the test fails the
 way the app would refuse it. For a `progress` exporter pass
-`stats: createMemoryStats(…)`.
+`stats: createMemoryStats(…)` to `createTestServer`.
 
 ## Try and ship
 

package/docs/recipe-mountable.md

@@ -0,0 +1,322 @@
+# Recipe: a component of any framework
+
+The app draws a panel, an injection, an answer view or a markdown block with
+Vue, or with a `Mountable`: an object with `mount(el, ctx)` that draws into the
+element the app gives it and returns the cleanup. Nothing in a `Mountable`
+depends on Vue, so it is the base for Svelte, Solid, Lit or plain DOM. This
+recipe builds a panel on plain DOM, the smallest case, and tests it with
+`mountForTest`. React has a preset built on the same contract:
+[recipe-react.md](recipe-react.md). The command and panel basics are in
+[recipe-command-panel.md](recipe-command-panel.md); the contracts use `zod`, so
+the project lists `zod` in its `dependencies`.
+
+## The manifest
+
+File `extension.json` (mountable):
+
+```json
+{
+  "id": "acme.counter",
+  "version": "1.0.0",
+  "apiVersion": 1
+}
+```
+
+## The parts
+
+File `src/index.ts` (mountable):
+
+```ts
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
+
+File `src/shared/rpc.ts` (mountable):
+
+```ts
+import { defineRpc } from '@dolphy-app/extension-sdk';
+import { z } from 'zod';
+
+export const sayHello = defineRpc({
+  name: 'greeting.say-hello',
+  input: z.object({ name: z.string() }),
+  output: z.object({ text: z.string() }),
+});
+```
+
+File `src/server.ts` (mountable):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+import { sayHello } from './shared/rpc.ts';
+
+export const server = defineServer((s) => {
+  s.handle(sayHello, async ({ name }) => ({ text: `Hello, ${name}!` }));
+});
+```
+
+## The component
+
+File `src/hello-panel.ts` (mountable):
+
+```ts
+import { defineMountable } from '@dolphy-app/extension-sdk';
+import type { PanelHandle, PanelProps } from '@dolphy-app/extension-sdk';
+import { sayHello } from './shared/rpc.ts';
+
+// plain DOM: the element is yours, any framework mounts into it the same way
+export const HelloPanel = defineMountable<PanelProps, PanelHandle>(
+  (el, ctx) => {
+    const title = document.createElement('h2');
+    const text = document.createElement('p');
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = 'Ask the server';
+    el.append(title, text, button);
+
+    const nameOf = ({ props }: PanelProps) =>
+      typeof props === 'string' ? props : 'world';
+    const draw = (props: PanelProps) => {
+      title.textContent = `Hello, ${nameOf(props)}!`;
+    };
+    draw(ctx.props);
+    // the app opens the panel again with new properties
+    const stopProps = ctx.onProps(draw);
+
+    // the window is light or dark; the element is inside it
+    const paint = ({ dark }: { dark: boolean }) => {
+      el.dataset.dark = String(dark);
+    };
+    paint(ctx.theme);
+    const stopTheme = ctx.onTheme(paint);
+
+    // the server part answers a contract; an error is shown in place of the panel
+    const ask = () => {
+      ctx.callRpc(sayHello, { name: nameOf(ctx.props) }).then(
+        (answer) => {
+          if (!ctx.signal.aborted) text.textContent = answer.text;
+        },
+        (error: unknown) => ctx.reportError(error),
+      );
+    };
+    button.addEventListener('click', ask);
+
+    return () => {
+      stopProps();
+      stopTheme();
+      button.removeEventListener('click', ask);
+      el.replaceChildren();
+    };
+  },
+);
+```
+
+File `src/client.ts` (mountable):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { HelloPanel } from './hello-panel.ts';
+
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.counter.view',
+    title: 'Hello',
+    component: HelloPanel,
+  });
+});
+```
+
+- `defineMountable<Props, Handle>(mount)` builds the object and gives it the
+  brand that `isMountable(value)` checks. `mount(el, ctx)` may return the
+  cleanup or a promise of it. The app calls the cleanup when it removes the
+  element: a route change, an extension turned off or removed, an injection
+  whose target is gone.
+- `Props` is the type of `ctx.props`: `PanelProps` (`panelId`, `props`,
+  `context`) in a panel, `InjectionProps` (`target`, `position`) in an injection,
+  `AnswerViewProps` in an answer view and `MarkdownBlockProps` (`source`,
+  `language`) in a markdown renderer. `Handle` is the type of `ctx.handle`:
+  `PanelHandle` in a panel, `InjectionHandle` in an injection and `undefined`
+  elsewhere.
+- The same component fits `client.addPanel`, `client.addInjection`,
+  `client.addAnswerView` and `client.addMarkdownRenderer` as its `component`,
+  where a Vue component fits.
+
+## The context
+
+`ctx` (`MountContext`) is everything a Vue component gets from `usePanel`,
+`useApp`, `useEngine` and `useRpc`, without Vue:
+
+| Field                   | What it is                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `props`, `onProps(fn)`  | The current props, a snapshot that is never changed in place, and a listener for the next one.          |
+| `theme`, `onTheme(fn)`  | `{ id, dark }` of the window and a listener for a change.                                              |
+| `locale`, `onLocale(fn)` | `'en'` or `'ru'` and a listener for a change.                                                        |
+| `emit(event, payload?)` | Sends an event to the app. Only an answer view has events (see below); elsewhere it does nothing.       |
+| `app`, `engine`         | The window API (`AppApi`) and the engine client, the same objects as `client.app` and `client.engine`. |
+| `callRpc(contract, input)` | Calls the server part: validates the input and the answer with the contract; a failure rejects.      |
+| `extensionId`           | The id of this extension.                                                                              |
+| `signal`                | An `AbortSignal` aborted when the element is removed: pass it to `fetch`, check it after an `await`.  |
+| `reportError(error)`    | Shows the card "Extension <name>: <error>" with a "Retry" button in place of the component.            |
+| `handle`                | The panel handle (`panelId`, `props`, `context`, `call(commandId, args?)`) or the injection handle.    |
+
+Every `on…` returns the function that stops listening; call it in the cleanup.
+An exception that `mount` throws is reported the same way as `reportError`.
+
+An answer view tells the app about the answer with `emit`:
+
+<!-- fragment -->
+
+```ts
+import { defineMountable } from '@dolphy-app/extension-sdk';
+import type { AnswerChange, AnswerViewProps } from '@dolphy-app/extension-api';
+
+export const Choice = defineMountable<AnswerViewProps<string[], string>>(
+  (el, ctx) => {
+    const select = document.createElement('select');
+    select.append(...ctx.props.view.map((option) => new Option(option)));
+    select.disabled = ctx.props.disabled;
+    select.addEventListener('change', () => {
+      const change: AnswerChange<string> = {
+        value: select.value,
+        complete: true,
+      };
+      ctx.emit('change', change);
+    });
+    el.append(select);
+    return () => el.replaceChildren();
+  },
+);
+```
+
+`emit('change', { value, complete })` reports the current answer and
+`emit('submit')` asks the app to check it.
+
+## The tests
+
+File `test/index.test.ts` (mountable):
+
+```ts
+// @vitest-environment happy-dom
+import { isMountable } from '@dolphy-app/extension-sdk';
+import type { ExtensionEngine, PanelProps } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+  mountForTest,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { client, server } from '../src/index.ts';
+import { HelloPanel } from '../src/hello-panel.ts';
+import { sayHello } from '../src/shared/rpc.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+describe('acme.counter: server', () => {
+  it('answers the contract', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.counter',
+    });
+    disposables.push(running);
+    expect(await running.rpc(sayHello, { name: 'Ada' })).toEqual({
+      text: 'Hello, Ada!',
+    });
+  });
+});
+
+describe('acme.counter: client', () => {
+  it('adds the panel as a mountable', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.counter',
+    });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual([
+      'acme.counter.view',
+    ]);
+    expect(isMountable(running.panels[0]?.component)).toBe(true);
+  });
+});
+
+const panelProps = (props: PanelProps['props']): PanelProps => ({
+  panelId: 'acme.counter.view',
+  props,
+  context: { courseId: null },
+});
+
+// the engine of the window: `ctx.callRpc` goes through `extensions.invokeRpc`
+const engineAnswering = (
+  answer: (request: { name: string; input: unknown }) => Promise<unknown>,
+) => ({ extensions: { invokeRpc: answer } }) as unknown as ExtensionEngine;
+
+const mountPanel = async (
+  props: PanelProps['props'],
+  engine: ExtensionEngine,
+) => {
+  const mounted = await mountForTest(HelloPanel, {
+    props: panelProps(props),
+    handle: { ...panelProps(props), call: async () => undefined },
+    engine,
+    extensionId: 'acme.counter',
+  });
+  disposables.push({ dispose: () => mounted.unmount() });
+  return mounted;
+};
+
+describe('acme.counter: panel', () => {
+  it('greets, follows the props and the theme, asks the server', async () => {
+    const asked: unknown[] = [];
+    const mounted = await mountPanel(
+      'Ada',
+      engineAnswering(async (request) => {
+        asked.push(request.input);
+        return { text: 'Hello from the server' };
+      }),
+    );
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Ada!');
+    expect(mounted.el.dataset.dark).toBe('false');
+
+    mounted.setProps(panelProps('Grace'));
+    mounted.setTheme({ id: 'night', dark: true });
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Grace!');
+    expect(mounted.el.dataset.dark).toBe('true');
+
+    mounted.el.querySelector('button')?.click();
+    await vi.waitFor(() =>
+      expect(mounted.el.querySelector('p')?.textContent).toBe(
+        'Hello from the server',
+      ),
+    );
+    expect(asked).toEqual([{ name: 'Grace' }]);
+  });
+
+  it('reports a failed call and cleans up on unmount', async () => {
+    const mounted = await mountPanel(
+      undefined,
+      engineAnswering(async () => {
+        throw new Error('server is down');
+      }),
+    );
+    mounted.el.querySelector('button')?.click();
+    await vi.waitFor(() => expect(mounted.errors).toHaveLength(1));
+
+    await mounted.unmount();
+    expect(mounted.ctx.signal.aborted).toBe(true);
+    expect(mounted.el.childElementCount).toBe(0);
+  });
+});
+```
+
+`mountForTest(mountable, { props, handle, engine, … })` mounts the component
+into a new `<div>` on a context the test controls. `setProps`, `setTheme` and
+`setLocale` change the context and call the `on…` listeners; `emitted` lists
+the `ctx.emit` calls as `[event, payload]`, `errors` the `ctx.reportError`
+calls; `unmount()` aborts `ctx.signal` and runs the cleanup. Without `app` and
+`engine` any use of them throws, so pass the ones the component touches. The
+`engine` is also what `ctx.callRpc` talks to, as `useRpc` does in a window.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS` and open the "Hello"
+panel from the sidebar menu.