@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/docs/debugging.md

@@ -0,0 +1,228 @@
+# Debugging
+
+Where to look when an extension does not do what you expect, from the cheapest
+check to the running app. Commands are those of a generated project; see the
+[quick start](quick-start.md).
+
+## 1. Reproduce it in a test
+
+`createTestServer` and `createTestClient` of `@dolphy-app/extension-sdk/testing`
+run your entries in plain Node, with a debugger and `console.log` available.
+Most mistakes (a wrong result shape, a setting read before it is set, a handler
+that throws, an id without the extension prefix) show up there.
+
+- `createTestServer(server, { extensionId, logger })` takes a `logger` option:
+  pass an object with `debug`, `info`, `warn` and `error` methods to see what
+  `server.logger` receives.
+- With `extensionId` set the harness checks that every id you register is the
+  extension id or starts with `<id>.`, the way the host does. It also checks what
+  the host checks about a result: the shape of a verdict, a grade of 1–5 or
+  `null`, a command result (`notify` text of 1–500 characters, a JSON value of
+  at most 64 KiB), an importer's or exporter's result. A message from the harness
+  usually names the rule.
+- An error in `server` fails `createTestServer` itself, as it fails the load in
+  the app: nothing is registered. A handler's failure is not swallowed but
+  rejects the promise.
+- The harness does not count the host's time limits, so a test that passes does
+  not prove a handler is fast enough: an event handler gets 2 seconds, a command
+  or a schedule handler 10, an importer or an exporter 30, and the registration
+  (`server`) 10.
+
+## 2. Run the checks
+
+```sh
+pnpm typecheck   # tsc
+pnpm validate    # the manifest the way the app parses it
+pnpm lint        # metadata and bundle findings the catalog review also sees
+```
+
+`pnpm validate` parses the built manifest with the same code as the app and
+exits with code 1 on a problem; a key the manifest does not have (a command, a
+setting, a panel written into `extension.json`) is one: the manifest holds the
+identity of the extension, and the code registers everything else. The build
+also fails when `server` imports `vue`, `vuetify` or a component, or `client`
+imports a `node:*` module, and names the file.
+`pnpm lint` prints `warning <id> <RULE> <field>: <message>` lines; a rule that
+looks wrong for your code (for example `eval` in a bundled dependency) is a hint
+for the reviewer, not a failure.
+
+## 3. The app: development loop
+
+`dolphy-ext dev` builds the project in watch mode and starts the installed
+Dolphy app on the result:
+
+```sh
+pnpm exec dolphy-ext dev            # the project in the current directory
+pnpm exec dolphy-ext dev ../my-ext  # another project
+```
+
+It prints the path of the app it started and the directory it passes to it
+(`DOLPHY_DEV_EXTENSIONS=<project>/dist-ext`). Press Ctrl+C to stop the build and
+the app; the exit code is 0. The app is looked up in this order:
+
+1. `--app <path>`: a macOS `.app` bundle or an executable file.
+2. The `DOLPHY_APP` environment variable (same kind of path).
+3. The standard place of your system: macOS `/Applications/Dolphy.app`, then
+   `~/Applications/Dolphy.app`; Windows
+   `%LOCALAPPDATA%\Programs\Dolphy\Dolphy.exe`; Linux the newest
+   `~/Applications/Dolphy-Linux-*.AppImage` (Linux has no fixed place: keep the
+   AppImage there or use `--app`).
+
+When none exists the command exits with code 2 and lists the places it looked
+at. A path given with `--app` or `DOLPHY_APP` that does not exist is an error as
+well, not a silent fallback.
+
+If you prefer to run the two parts yourself, start `pnpm dev`
+(`dolphy-ext build --watch`) and start Dolphy with
+`DOLPHY_DEV_EXTENSIONS=<project>/dist-ext`; from a checkout of the Dolphy
+repository that is `DOLPHY_DEV_EXTENSIONS=<project>/dist-ext pnpm dev`. The app
+rereads the extensions on every file change and applies the change live: the
+extension host runs `server` again and the window loads `client.mjs` again, and
+the window itself does not reload. Things to know:
+
+- The app has one instance. If Dolphy is already running, a second start exits
+  at once and the variable is lost. `dolphy-ext dev` notices an app that quits
+  within 5 seconds and prints "Dolphy is probably already running: quit it and
+  run again" (exit code 1): quit the running app and start again.
+- The extension appears in Settings → Extensions with the origin
+  "Development". A manifest or load problem is shown there next to the
+  extension instead of the extension working: start with that text.
+- If the id is also in the bundled set or installed from the catalog, the
+  development copy wins.
+- The components of extensions in development are redrawn on a change, so their
+  state can be lost.
+
+### `load-failed`
+
+When `server` throws, registers something invalid (an id that is taken or does
+not carry the extension prefix, a bad `when`, an invalid setting definition), or
+does not finish in 10 seconds, the extension host registers
+nothing from it. Registration is all or nothing: the commands, settings and
+event handlers `server` managed to add before the failure are removed too. The
+extension row in Settings → Extensions shows the diagnostic "Could not load the
+extension: {reason}" with the message of the error, and the log has the entry
+`extension registration failed` with the cause (`activation-failed`, or
+`activation-timeout` for the 10 seconds). `server` is called once per load, so
+do slow work (a network request, a big file) in a handler and not in `server`
+itself.
+
+The client part has its own failure. When `client.mjs` does not import, `client`
+throws, or a registration is refused (an id that is taken, a bad injection
+target), the window shows "The extension client part failed to load" on the
+extension and keeps no contribution of the client part; the other extensions
+and the server part of this one keep working. The reason is in the DevTools
+console of section 4. After you fix the file, the next rebuild loads it again.
+
+## 4. DevTools
+
+While `DOLPHY_DEV_EXTENSIONS` is set (so under `dolphy-ext dev` too), in any
+build of the app, including an installed one, these keys toggle the DevTools of
+the main window: `F12`, `Cmd+Alt+I` (macOS) and `Ctrl+Shift+I`. Without the
+variable the keys do nothing and an installed app has no DevTools.
+
+- Panels, injected components, answer views and markdown blocks of an extension
+  are Vue components in the page of the app window itself. "Elements" shows
+  their markup in the page and the Vue DevTools show the component tree; the
+  console evaluates in the same page as the app and shows what the client part
+  and its components print with `console`.
+- `dolphy-ext dev` and `dolphy-ext build --watch` put an inline source map
+  (`//# sourceMappingURL=data:application/json…`) into every bundle, so
+  "Sources" shows your TypeScript (`src/client.ts` and the files it imports)
+  for the client part: set a breakpoint there, `debugger;` works too. A plain
+  `dolphy-ext build` (`pnpm build`) and the catalog build never write source
+  maps, and the catalog check rejects a submission that has one.
+- The code that runs in the extension host (`main.mjs`: `server`, command and
+  event handlers, schedules, importers and exporters) is not in this window: see
+  section 6 and the log.
+
+## 5. The log
+
+`server.logger` has `debug`, `info`, `warn` and `error`; each takes an object of
+fields and an optional message:
+
+```text
+s.logger.info({ id: change.id, value: change.value }, 'setting changed');
+```
+
+The output goes to the log of the app, not to a console of the window. Log
+structured fields, not secrets or the learner's answers. The host writes to the
+same log: an exception in a handler, a handler that outlives its time limit, an
+event dropped from a full queue, and the failure of a registration. The client
+part has no logger: use `console` and the DevTools.
+
+### Reading the log in the app
+
+1. Open Settings → Extensions. In the "Diagnostics" block press "Log" to see
+   everything, or press "Log" in the row of your extension to see only its
+   entries (the dialog opens with the id of the extension in the filter).
+2. The dialog lists the last 500 entries, the newest at the bottom. Each entry
+   shows the time, the level, the source (`main`, `engine` or `ext-host`), the
+   id of the extension that wrote it and the message. "Details" opens the other
+   fields of the entry as JSON.
+3. Filter by extension: type or pick an id in "Extension" (an id that is not in
+   the list is accepted). Filter by level: "Minimum level" hides entries below
+   it; the default, "Debug", shows all of them.
+4. The dialog does not update by itself: press "Refresh" after you triggered
+   the code you are watching. "No entries match the filters." means the filters
+   hide everything, or nothing was logged yet.
+
+The labels the dialog shows, with the keys of the app's messages (ru and en):
+
+| Where                      | English                          | Русский                       | Message key                                |
+| -------------------------- | -------------------------------- | ----------------------------- | ------------------------------------------ |
+| Settings section           | Extensions                       | Расширения                    | `settings.extensions.title`                |
+| Origin of a dev extension  | Development                      | Разработка                    | `settings.extensions.origin.dev`           |
+| Load failure of the client part | The extension client part failed to load | Клиентская часть расширения не загрузилась | `settings.extensions.clientFailed.title` |
+| Block with the log button  | Diagnostics                      | Диагностика                   | `settings.extensions.support.title`        |
+| Button of the block        | Log                              | Журнал                        | `settings.extensions.support.openLog`      |
+| Action in an extension row | Log                              | Журнал                        | `settings.extensions.log.rowAction`        |
+| Dialog title               | Log                              | Журнал                        | `settings.extensions.log.title`            |
+| Extension filter           | Extension                        | Расширение                    | `settings.extensions.log.filterExtension`  |
+| Extension filter, empty    | All extensions                   | Все расширения                | `settings.extensions.log.filterExtensionHint` |
+| Level filter               | Minimum level                    | Минимальный уровень           | `settings.extensions.log.filterLevel`      |
+| Level                      | Debug                            | Отладка                       | `settings.extensions.log.level.debug`      |
+| Level                      | Info                             | Инфо                          | `settings.extensions.log.level.info`       |
+| Level                      | Warning                          | Предупреждение                | `settings.extensions.log.level.warn`       |
+| Level                      | Error                            | Ошибка                        | `settings.extensions.log.level.error`      |
+| Other fields of an entry   | Details                          | Подробности                   | `settings.extensions.log.details`          |
+| Reread the log             | Refresh                          | Обновить                      | `settings.extensions.log.refresh`          |
+| Filters match nothing      | No entries match the filters.    | Нет записей, подходящих под условия. | `settings.extensions.log.empty`     |
+
+### Output of the extension host
+
+What `server` and its handlers print with `console.log`, `console.error` or an
+uncaught error goes to the log as `warn` entries of the extension host in
+"Details". Use `s.logger` for anything you want to filter by level (its entries
+carry the extension id); use `console` only for a quick look.
+
+### The file
+
+The entries are also in `logs/dolphy-YYYY-MM-DD.log` in the app's data folder,
+one JSON object per line (`level`, `source`, `message`, `at` and the other
+fields). A new file starts every day and at 2 MiB; files older than 7 days are
+removed, and the oldest go first while the folder is over 10 MiB. Attach the
+relevant lines, or the text of "Copy diagnostics" in the "Diagnostics" block (it
+has no paths of your home folder, library content or learning data), to a bug
+report.
+
+## 6. Reading a stack trace
+
+The code of the extension host is `dist-ext/<id>/main.mjs`, readable and not
+minified. A watch build (`dolphy-ext dev`, `dolphy-ext build --watch`) appends
+an inline source map to it, but the app does not turn on source maps for that
+process, so a stack trace in the log still points to lines of `main.mjs`: open
+that file to find the place and search it for the name from the trace. The
+map is for the browser file of section 4. A plain `dolphy-ext build` writes no
+maps at all.
+
+## Which limit did I hit?
+
+| Symptom                                         | Limit                                                    |
+| ----------------------------------------------- | -------------------------------------------------------- |
+| the extension shows `load-failed` with a timeout | `server` must finish in 10 seconds                       |
+| an event handler stops mid-way                  | 2 seconds per event; the queue holds 100 events          |
+| a command or a schedule handler stops mid-way   | 10 seconds                                               |
+| an importer or an exporter stops mid-way        | 30 seconds                                               |
+| `StorageQuotaError`                             | key 128 characters, value 64 KiB, 256 keys, 1 MiB total  |
+| a command result is rejected                    | `notify` text 1–500 characters; a result up to 64 KiB    |
+| a panel or a view fails while it draws          | the card "Retry" replaces it; the window stays up        |

package/docs/no-build.md

@@ -0,0 +1,135 @@
+# Without a build
+
+An extension is a directory with an `extension.json` and, if it has code, one or
+two ES modules: `main.mjs` for the `server` entry and `client.mjs` for the
+`client` entry. `dolphy-ext build` only produces such a directory from a
+TypeScript project; you can write it by hand. You do not need TypeScript, a
+`package.json` or `dolphy-ext` for that. This page shows the smallest case: one
+palette command and a panel, three hand-written files. Use it for a quick
+experiment or when the code is a few lines; switch to the
+[quick start](quick-start.md) layout when you want types, tests and bundling.
+
+## The files
+
+File `extension.json` (no build):
+
+```json
+{
+  "id": "acme.plain",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "main": "./main.mjs",
+  "client": "./client.mjs",
+  "name": "Plain hello",
+  "description": "A palette command and a panel written by hand, without a build step.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+```
+
+File `main.mjs` (no build):
+
+```js
+export const server = (s) => {
+  s.registerCommand({
+    id: 'acme.plain.hello',
+    title: 'Say hello',
+    run: () => ({ notify: `Hello from ${s.extensionId}!` }),
+  });
+  s.registerCommand({
+    id: 'acme.plain.open',
+    title: 'Open the plain panel',
+    run: () => ({ openPanel: 'acme.plain.view' }),
+  });
+};
+```
+
+File `client.mjs` (no build):
+
+```js
+// `vue` is the app's own instance: the window gives it through globalThis.__dolphy
+const { defineComponent, h } = await globalThis.__dolphy.require('vue');
+
+export const client = (c) => {
+  c.addPanel({
+    id: 'acme.plain.view',
+    title: 'Plain hello',
+    component: defineComponent({
+      setup: () => () => h('p', 'Hello from a panel'),
+    }),
+  });
+};
+```
+
+- `main` and `client` are written in the manifest: nothing fills them in. A part
+  that is left out (`null` or no key) does not exist, so an extension may have
+  only `main.mjs` or only `client.mjs`. Each is a path inside the directory that
+  ends with `.mjs`.
+- The contract of `main.mjs` is `export const server = (s) => { … }`, the same
+  function `defineServer` takes in a project; `s` is the `ServerContext`
+  (`registerCommand`, `registerSettings`, `on`, `storage`, `logger`, …). The
+  contract of `client.mjs` is `export const client = (c) => { … }`
+  (`addPanel`, `addInjection`, `addAnswerView`, `addMarkdownRenderer`,
+  `addTheme`, `addCommand`). Either may return a cleanup function. `async`
+  functions work. `server` is called when the host loads the extension; if it
+  throws or takes more than 10 seconds the extension shows `load-failed` and
+  registers nothing.
+- Without a build there is no `import 'vue'`: `client.mjs` reads `vue` (and
+  `vuetify`, `vuetify/components`, `vuetify/directives`) from
+  `globalThis.__dolphy.require(name)`, which resolves to the app's own instance.
+  Write the components with `h` or a render function: there is no template
+  compiler. `main.mjs` never needs `vue`.
+- There are no helpers, so a command returns the result object itself:
+  `{ notify: text }` is what `notify(text)` makes and `{ openPanel: id, props }`
+  is what `openPanel(id, props)` makes. Ids are written in the code and must be
+  the extension id or start with `<id>.`.
+- The modules must be plain JavaScript that the app runs as it is: no
+  TypeScript, no bare imports of packages (nothing is installed next to them),
+  and no `node:*` imports in `client.mjs`.
+
+## Check and try
+
+Put the files into a directory named exactly as the extension id,
+`acme.plain/` (the app takes the id from the directory name and rejects a
+manifest that disagrees), and check it:
+
+```sh
+npx --package @dolphy-app/extension-tools dolphy-ext validate ./acme.plain
+```
+
+`validate` parses the manifest the way the app does, checks that `main` and
+`client` are files, and exits with code 1 on a problem. To try the extension,
+put the directory into a folder and start the app with `DOLPHY_DEV_EXTENSIONS`
+pointing at that folder (the folder, not the extension directory: it holds one
+directory per extension), or copy the directory to `<userData>/extensions/` and
+restart the app. Edits to the files are picked up without a restart when you use
+`DOLPHY_DEV_EXTENSIONS`.
+
+To test the server module without the app, run its entry with the SDK helper:
+
+```sh
+npm install --save-dev @dolphy-app/extension-sdk vitest
+```
+
+<!-- fragment -->
+
+```js
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
+import { server } from './main.mjs';
+
+const running = await createTestServer(server, { extensionId: 'acme.plain' });
+console.log(await running.commands.run('acme.plain.hello'));
+// { kind: 'notify', text: 'Hello from acme.plain!' }
+```
+
+`createTestServer` accepts the export of the module as it is, because it has the
+shape of a server entry. `createTestClient(client, { extensionId })` does the
+same for `client.mjs` and lists the panels it added.
+
+## Publishing
+
+The extension catalog reviews a project, not a bare directory: it requires a
+`package.json` with a lock file and a `README.md` that explains what the
+extension does (`dolphy-ext catalog check`). A hand-written directory is for
+yourself or for handing a folder to someone. To publish, generate a project with
+`create-dolphy-extension` and move the code into it.

package/docs/quick-start.md

@@ -0,0 +1,194 @@
+# Quick start
+
+This guide takes you from nothing to a working Dolphy extension: a command in
+the command palette that shows a notification. It is the smallest project the
+generator makes (`--template blank`); the recipes next to this file build on the
+same layout:
+
+- [Exercise type](recipe-exercise-type.md): a new kind of task with its own answer input.
+- [Theme](recipe-theme.md): colors, registered by the client part.
+- [Command and panel](recipe-command-panel.md): palette commands and a panel, a Vue single-file component (`.vue`) in the app window.
+- [A panel in React](recipe-react.md): the same panel drawn with React: `"frameworks": ["react"]`, `reactComponent`, hooks, tests with `mountForTest`.
+- [A component of any framework](recipe-mountable.md): `defineMountable` on plain DOM, the base for Svelte, Solid or Lit, and what `ctx` gives it.
+- [Events and storage](recipe-event-storage.md): react to learning events and keep data.
+- [Hooks](recipe-hooks.md): change or cancel a session start and the batch of exercises before the engine acts.
+- [Settings](recipe-settings.md): let the user configure the extension.
+- [Visibility conditions and dependencies](recipe-when-dependencies.md): show a command only where it makes sense, a widget in the daily plan, require another extension.
+- [Importer and exporter](recipe-import-export.md): bring a file in as a course, write a course out.
+- [Calls, engine and window](recipe-rpc-and-app.md): `defineRpc` between the parts, `engine` access, `useApp`.
+- [Without a build](no-build.md): a hand-written `extension.json`, `main.mjs` and `client.mjs`, no TypeScript.
+- [Debugging](debugging.md): where to look when something does not work.
+
+## What you need
+
+- Node.js 22.12 or newer and pnpm.
+- The Dolphy app, to see the extension work. Everything else (build, type
+  check, tests) runs without it.
+
+## 1. Create the project
+
+```sh
+npx @dolphy-app/create-extension my-extension --id acme.hello --template blank
+cd my-extension
+pnpm install
+```
+
+`--id` is the extension id: lowercase letters, digits, dots and hyphens. Every
+id the extension registers (commands, panels, settings…) is the extension id or
+starts with it and a dot, so pick one that is yours (a publisher prefix, then a
+name). Without `--id` the id is the directory name in kebab-case. The
+`--template` values:
+
+| Template        | What you get                                                      |
+| --------------- | ----------------------------------------------------------------- |
+| `exercise`      | a task type with an answer input and a setting (the default)      |
+| `theme`         | a color theme                                                     |
+| `command-panel` | palette commands and a panel as a Vue single-file component      |
+| `react-panel`   | palette commands and a panel drawn with React                     |
+| `events`        | a learning event handler, storage, commands and a panel           |
+| `blank`         | one palette command                                               |
+
+An unknown name exits with code 2 and lists the available ones.
+
+## 2. The files
+
+The project is two files that matter. The manifest says who the extension is,
+the code says what it adds.
+
+File `extension.json` (quick start):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello command",
+  "description": "A command-palette command that shows a notification.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+```
+
+`$schema` gives editors completion and checking. `id` is the identity of the
+extension in the app and the catalog; it never changes after the first release.
+Replace `your-github-login` in `author` with your GitHub login before you
+publish. The manifest declares no commands, panels or settings: the code
+registers them. The other keys are `platforms`, `minAppVersion`, `icon` and
+`dependencies`. `main` and `client` are written by the build.
+
+File `src/index.ts` (quick start):
+
+```ts
+import { defineServer, notify } from '@dolphy-app/extension-sdk';
+
+// runs in the extension host: every call registers a contribution
+export const server = defineServer((s) => {
+  s.registerCommand({
+    id: 'acme.hello.hello',
+    title: { en: 'Say hello', ru: 'Поздороваться' },
+    run: () => notify('Hello from acme.hello!'),
+  });
+});
+```
+
+`src/index.ts` exports up to two entries. `server` runs in the extension host
+(Node) and registers commands, exercise types, settings, event handlers,
+schedules, importers and exporters; `client` runs in the app window and adds
+panels, injected components, answer views, markdown renderers, themes and
+client commands. This project has only `server`. The host calls it when it
+loads the extension; if it throws, or does not finish in 10 seconds, the
+extension shows `load-failed` in Settings → Extensions and registers nothing
+(see [debugging](debugging.md)).
+
+`notify` returns a notification to the app. A text the user sees is a
+`LocalizedText`: a plain string, or `{ en, ru }` as here. An id is written in
+the code and must be the extension id or start with `acme.hello.`; the host
+refuses an id that is taken or does not carry the prefix.
+
+When both entries exist, keep each in its own file and re-export them from
+`src/index.ts` (the recipes do): `server` must not import `vue`, `vuetify` or a
+component, `client` must not import `node:*` modules, and the build reports a
+violation with the file and the rule.
+
+File `test/index.test.ts` (quick start):
+
+```ts
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
+import { expect, it } from 'vitest';
+import { server } from '../src/index.ts';
+
+it('the hello command notifies', async () => {
+  const running = await createTestServer(server, { extensionId: 'acme.hello' });
+  expect(await running.commands.run('acme.hello.hello')).toEqual({
+    kind: 'notify',
+    text: 'Hello from acme.hello!',
+  });
+  await running.dispose();
+});
+```
+
+The test runs the command the way the host does, without the app:
+`createTestServer` from `@dolphy-app/extension-sdk/testing` starts `server` on
+in-memory storage, settings and library, and `running.commands.run` applies the
+rules the host applies to a command result. `createTestClient` does the same for
+`client` (see the [command and panel recipe](recipe-command-panel.md)).
+
+## 3. Build, check, test
+
+```sh
+pnpm build       # dolphy-ext build: writes dist-ext/acme.hello
+pnpm validate    # parses the built manifest the way the app does
+pnpm lint        # metadata and bundle checks the catalog review also runs
+pnpm typecheck   # tsc
+pnpm test        # vitest
+```
+
+`pnpm build` turns `src/index.ts` into the files the app loads. With this
+template that is `dist-ext/acme.hello/extension.json` and `main.mjs`; the built
+manifest names it in `main`. A project that exports `client` also gets
+`client.mjs` and the `client` key. Keep `dist-ext` out of git; the generated
+`.gitignore` does it.
+
+## 4. Try it in the app
+
+One command builds the project in watch mode and starts the installed Dolphy
+app on the result:
+
+```sh
+pnpm exec dolphy-ext dev
+```
+
+The extension appears in Settings → Extensions with the origin "Development",
+and the command appears in the command palette. Press Ctrl+C to stop the build
+and the app. Quit a running Dolphy first: the app has one instance, a second
+start does not pick up the extension directory. Where the app is looked up and
+what to do when it is not found: [debugging](debugging.md), section 3.
+
+To run the two parts yourself, start the build in watch mode with `pnpm dev`
+(`dolphy-ext build --watch`) and start Dolphy with the variable
+`DOLPHY_DEV_EXTENSIONS` set to the absolute path of `dist-ext` of your project.
+It adds a developer root with the highest priority.
+
+```sh
+# from a checkout of the Dolphy repository
+DOLPHY_DEV_EXTENSIONS=/path/to/my-extension/dist-ext pnpm dev
+```
+
+Save a file: the build writes the new files and the app applies them without a
+restart. The window does not reload; the components of extensions in
+development are recreated, so their state can be lost.
+
+The extension code runs without restrictions: files, processes, threads and the
+network are available. The test helpers run a handler in your process and do not
+reproduce the host (time limits, the process boundary); try such code in the
+app.
+
+## 5. Next
+
+- Pick the recipe closest to your task and generate that template.
+- Before a pull request to the extension catalog run `pnpm build`,
+  `pnpm validate`, `pnpm lint`, `pnpm typecheck` and `pnpm test`: all must pass.
+  The generated `.github/workflows/ci.yml` runs the same steps on every push.
+- Write in `README.md` what the extension does; the catalog
+  review reads it.