@dolphy-app/create-extension 0.2.0 → 0.4.0

package/dist/cli/main.js

@@ -2,28 +2,242 @@
 import path from "node:path";
 import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
 
+//#region packages/extension-api/src/when.ts
+/**
+* Visibility conditions (`when`) of commands, panels and widgets. A condition
+* is a small boolean expression over a closed set of typed keys of the app
+* window (`WHEN_KEYS`). The functions are pure: the manifest check, the app
+* window and `dolphy-ext validate` share them, and so can any dispatcher that
+* can supply a `WhenContext`.
+*
+* Grammar (`!` binds tightest, then `&&`, then `||`):
+*
+* ```
+* expr    := term ('||' term)*
+* term    := factor ('&&' factor)*
+* factor  := '!' factor | '(' expr ')' | 'true' | 'false' | boolean-key | comparison
+* comparison := key ('==' | '!=') literal | key 'in' '(' literal (',' literal)* ')'
+* literal := 'text' | true | false
+* ```
+*
+* `!` stands before a boolean key, a group or another `!`; negate a
+* comparison with a group (`!(route == 'courses')`) or use `!=`.
+*/
+/** Names of the screens `route` can have: the route names of the app window. */
+const WHEN_ROUTES = [
+	"daily-plan",
+	"courses",
+	"extension-panel",
+	"placement",
+	"session",
+	"settings",
+	"settings-learning",
+	"settings-library",
+	"settings-appearance",
+	"settings-shortcuts",
+	"settings-extensions",
+	"settings-extension-details",
+	"settings-about"
+];
+/** Interface languages a `locale` condition can name. */
+const WHEN_LOCALES = ["ru", "en"];
+/**
+* Closed set of keys with their types.
+*
+* - `route`: the screen shown (a value of `WHEN_ROUTES`).
+* - `course.active`: a course is in focus (the course switcher is not on "all courses").
+* - `session.active`: the learning session screen is open.
+* - `locale`: the interface language after resolving the "system" mode.
+* - `theme.dark`: the current theme is dark.
+*/
+const WHEN_KEYS = Object.freeze({
+	route: {
+		type: "string",
+		values: WHEN_ROUTES
+	},
+	"course.active": { type: "boolean" },
+	"session.active": { type: "boolean" },
+	locale: {
+		type: "string",
+		values: WHEN_LOCALES
+	},
+	"theme.dark": { type: "boolean" }
+});
+
+//#endregion
+//#region packages/extension-api/src/locale.ts
+/** Limits of a translation file; the values are checked at discovery and by the tools. */
+const LOCALE_LIMITS = Object.freeze({
+	/** Size of the file in bytes. */
+	fileBytes: 65536,
+	keys: 500,
+	/** Longest value in UTF-16 code units. */
+	valueLength: 500
+});
+
+//#endregion
 //#region packages/extension-api/src/index.ts
+/**
+* Public extension API. The package depends on neither the engine nor the DOM: it is imported
+* by extension code (`main.mjs`), by the answer element (`view.mjs`), and by the engine itself.
+*/
 const EXTENSION_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
-/** Тег элемента по умолчанию: `dolphy.sql` → `dolphy-sql-answer`. */
-const defaultElementName = (id) => `${id.replaceAll(".", "-")}-answer`;
+/** Limits on widgets; the manifest and the app enforce them. */
+const EXTENSION_WIDGET_LIMITS = Object.freeze({
+	/** Widgets per extension. */
+	widgets: 3,
+	/** Smallest allowed `minHeight`, px. */
+	minHeight: 80,
+	/** Largest allowed `maxHeight`, px. */
+	maxHeight: 320
+});
+/** Limits on schedules; the manifest, the scheduler, and the runtime enforce them. */
+const EXTENSION_SCHEDULE_LIMITS = Object.freeze({
+	/** Schedules per extension. */
+	schedules: 4,
+	/** Handler budget, ms. */
+	handlerMs: 1e4,
+	/** A firing found later than this after its moment (the app was closed or asleep) is skipped, ms. */
+	lateMs: 12e4,
+	/** How often the app looks for due firings, ms. */
+	tickMs: 3e4
+});
+/** Limits of the settings types (`text`, `color`, `list`, `group`, `order`); they match those checked by the manifest and the engine. */
+const SETTING_LIMITS = Object.freeze({
+	/** `maxLength` of `string` and `text`. */
+	stringLength: 1e4,
+	/** `maxItems` of `list`. */
+	listItems: 50,
+	/** `itemMaxLength` of `list`. */
+	listItemLength: 200,
+	groupLength: 60,
+	orderMax: 1e3
+});
+const KEYBINDING_STROKE = `(?:(?:Mod|Ctrl|Control|Alt|Option|Shift|Cmd|Command|Meta|Win|Super)\\+){0,3}(?:[A-Z0-9]|F(?:[1-9]|1[0-9]|2[0-4])|Enter|Return|Space|Tab|Escape|Esc|Backspace|Delete|Insert|Arrow(?:Up|Down|Left|Right)|Home|End|Page(?:Up|Down)|Plus|\\[[A-Za-z][A-Za-z0-9]*\\]|[\`\\-=\\[\\]\\\\;',./+])`;
+/**
+* Key notation: one stroke or two strokes separated by a space
+* (`Mod+K Mod+S`). A stroke is up to three modifiers (`Mod`, `Ctrl`, `Alt`,
+* `Shift`, `Cmd`, `Meta`, `Win`, `Super`, `Option`, ...) and a key joined with
+* `+`: a letter or digit, `F1`–`F24`, a punctuation mark, a physical key
+* (`[KeyK]`) or a name (`Enter`, `Space`, `Tab`, `Escape`, `Insert`, arrows,
+* `Home`, `End`, `PageUp`, `PageDown`). A superset for the JSON Schema; the
+* host validates every string authoritatively with `@dolphy-app/keybindings`.
+*/
+const KEYBINDING_PATTERN = new RegExp(`^${KEYBINDING_STROKE}(?: ${KEYBINDING_STROKE})?$`);
+/** Limits on commands and panels (R1, R3); they match those checked by the manifest, host, and engine. */
+const EXTENSION_COMMAND_LIMITS = Object.freeze({
+	/** Keybinding entries (`keybindings`) per command. */
+	keybindingsPerCommand: 4,
+	/** Length of a `when` condition (of a command, panel, widget or `keybindings[]` entry). */
+	whenLength: 200,
+	/** Commands per extension. */
+	commands: 64,
+	/** Panels per extension. */
+	panels: 8,
+	titleLength: 60,
+	categoryLength: 40,
+	descriptionLength: 200,
+	/** `JSON.stringify(args).length` at the engine boundary. */
+	argsChars: 2e5,
+	/** JSON text of the result in UTF-8 bytes. */
+	resultBytes: 65536,
+	/** Length of `notify` in UTF-16 code units. */
+	notifyChars: 500,
+	/** Handler budget, ms. */
+	handlerMs: 1e4
+});
+/** Limits on importers and exporters; the manifest, host, and engine check the same numbers. */
+const EXTENSION_TRANSFER_LIMITS = Object.freeze({
+	/** Importers per extension. */
+	importers: 8,
+	/** Exporters per extension. */
+	exporters: 8,
+	/** Entries in `accept` of one importer. */
+	acceptExtensions: 8,
+	/** Handler budget, ms (import and export). */
+	handlerMs: 3e4,
+	/** Size of the file the user picks for an importer, bytes. */
+	inputBytes: 20971520,
+	/** Files in the directory an importer returns. */
+	files: 5e3,
+	/** One file of the returned directory, UTF-8 bytes. */
+	fileBytes: 2097152,
+	/** All files of the returned directory (and of a course snapshot), UTF-8 bytes. */
+	totalBytes: 20971520,
+	/** Size of the file an exporter returns, bytes. */
+	outputBytes: 20971520,
+	/** Length of the file name an exporter returns. */
+	filenameChars: 120,
+	/** One path of the returned directory, UTF-8 bytes. */
+	pathBytes: 1024
+});
+/** Extension storage limits (R2); they match the engine's limits, which enforces them. */
+const EXTENSION_STORAGE_LIMITS = Object.freeze({
+	/** Key length in UTF-16 code units. */
+	keyLength: 128,
+	/** JSON text of a single value in UTF-8 bytes. */
+	valueBytes: 65536,
+	/** Number of keys. */
+	keys: 256,
+	/** Sum of JSON texts of all values in UTF-8 bytes. */
+	totalBytes: 1048576
+});
+/** Secret limits; the engine enforces them (`StorageQuotaError`, kinds `key-length`, `value-size`, `key-count`). */
+const EXTENSION_SECRET_LIMITS = Object.freeze({
+	/** Key length in UTF-16 code units. */
+	keyLength: 128,
+	/** Value size in UTF-8 bytes. */
+	valueBytes: 4096,
+	/** Number of keys. */
+	keys: 32
+});
+/** Limits of `ctx.stats`; the engine enforces them. */
+const EXTENSION_STATS_LIMITS = Object.freeze({ 
+/** Most dates in one `daily` range (both ends included). */
+dailyDays: 366 });
+/** Limits of `ctx.notifications`; the engine enforces them. */
+const EXTENSION_NOTIFICATION_LIMITS = Object.freeze({
+	/** Title length in characters (code points). */
+	titleLength: 80,
+	/** Body length in characters (code points). */
+	bodyLength: 300,
+	/** Notifications per rolling minute and extension. */
+	perMinute: 3,
+	/** Notifications per rolling hour and extension. */
+	perHour: 30
+});
 
 //#endregion
-//#region packages/create-extension/src/template.ts
-/** Версия расширения в шаблоне и его умолчание для `apiVersion`. */
+//#region packages/create-extension/src/templates/common.ts
+/** Extension version in the template and its default for `apiVersion`. */
 const INITIAL_VERSION = "0.1.0";
+const TEMPLATE_NAMES = [
+	"exercise",
+	"theme",
+	"command-panel",
+	"events",
+	"blank"
+];
+const DEFAULT_TEMPLATE = "exercise";
 const lines = (parts) => `${parts.join("\n")}\n`;
+/** The `pnpm` scripts of every generated project. */
+const scripts = (id) => ({
+	build: "dolphy-ext build",
+	dev: "dolphy-ext build --watch",
+	types: "dolphy-ext types",
+	typecheck: "dolphy-ext types && tsc",
+	validate: `dolphy-ext validate dist-ext/${id}`,
+	lint: "dolphy-ext lint",
+	test: "vitest run"
+});
 const packageJson = ({ id, dependencies }) => `${JSON.stringify({
 	name: id,
 	version: INITIAL_VERSION,
 	private: true,
 	type: "module",
-	scripts: {
-		build: "dolphy-ext build",
-		dev: "dolphy-ext build --watch",
-		validate: `dolphy-ext validate dist-ext/${id}`,
-		test: "vitest run"
-	},
+	scripts: scripts(id),
 	devDependencies: {
+		"@dolphy-app/extension-api": dependencies.api,
 		"@dolphy-app/extension-sdk": dependencies.sdk,
 		"@dolphy-app/extension-tools": dependencies.tools,
 		"@types/node": "^22.20.4",
@@ -48,13 +262,630 @@ const tsconfigJson = () => lines([
 	"    \"skipLibCheck\": true,",
 	"    \"noEmit\": true",
 	"  },",
-	"  \"include\": [\"src\", \"test\"]",
+	"  \"include\": [\"src\", \"test\", \".dolphy/ids.d.ts\"]",
 	"}"
 ]);
-const manifestJson = (id) => `{
+const idsBullet = [
+	"- `.dolphy/ids.d.ts` — generated from `extension.json` by",
+	"  `dolphy-ext types` (and by every build): the ids the manifest declares,",
+	"  as TypeScript types. Not committed. A misspelt id, a declared id without",
+	"  a handler or a view, or `ctx.settings.get` of an undeclared setting fails",
+	"  `pnpm typecheck`;"
+];
+const readme = (id, module) => lines([
+	`# ${id}`,
+	"",
+	...module.summary,
+	"Generated by `create-dolphy-extension`.",
+	"",
+	"## Layout",
+	"",
+	...module.layout,
+	"",
+	"## Development loop",
+	"",
+	"```sh",
+	"pnpm install",
+	`pnpm dev # dolphy-ext build --watch: rebuilds into dist-ext/${id}`,
+	"```",
+	"",
+	"Start the app with the developer root pointing at the `dist-ext` directory",
+	"of this project (an absolute path):",
+	"",
+	"```sh",
+	"DOLPHY_DEV_EXTENSIONS=<path to the project>/dist-ext pnpm dev # from the Dolphy repository",
+	"```",
+	"",
+	"A change to a file in `dist-ext` is applied live: the window does not",
+	"reload, mounted answer inputs are recreated. Load errors are shown in",
+	"\"Settings → Extensions\".",
+	"",
+	"## Build, check, test",
+	"",
+	"```sh",
+	`pnpm build      # dist-ext/${id}`,
+	"pnpm validate   # the same manifest parsing the app does",
+	"pnpm lint       # metadata and bundle checks before a catalog pull request",
+	"pnpm typecheck  # writes .dolphy/ids.d.ts, then tsc",
+	"pnpm test",
+	"```",
+	"",
+	"`.github/workflows/ci.yml` runs the same steps on every push and pull",
+	"request.",
+	"",
+	"## Installation",
+	"",
+	"From the catalog: Settings → Extensions → Catalog.",
+	"",
+	`By hand: copy the \`dist-ext/${id}\` directory to`,
+	"`<userData>/extensions/` and restart the app.",
+	"",
+	"To try the extension while developing, set `DOLPHY_DEV_EXTENSIONS` to the",
+	"project `dist-ext` directory when starting the app (read only by an",
+	"unpackaged app)."
+]);
+const gitignore = () => lines([
+	"node_modules",
+	"dist-ext",
+	".dolphy"
+]);
+const claudeMd = () => "@AGENTS.md\n";
+const agentsMd = (id, module) => lines([
+	`# ${id}`,
+	"",
+	"A Dolphy extension project made by `create-dolphy-extension`. Write the",
+	"code and the manifest; the build, the checks and the tests are ready.",
+	"",
+	"## Layout",
+	"",
+	...module.layout,
+	"- `.github/workflows/ci.yml` — runs the commands below on every push and",
+	"  pull request.",
+	"",
+	"## Commands",
+	"",
+	"- `pnpm install` — install the toolchain;",
+	`- \`pnpm build\` — build into \`dist-ext/${id}\`;`,
+	"- `pnpm dev` — rebuild on every change (`dolphy-ext build --watch`);",
+	"- `pnpm types` — write `.dolphy/ids.d.ts` from `extension.json`;",
+	"- `pnpm typecheck` — `types`, then `tsc`;",
+	"- `pnpm validate` — parse the built manifest the way the app does;",
+	"- `pnpm lint` — metadata and bundle checks the catalog review also runs;",
+	"- `pnpm test` — `vitest`.",
+	"",
+	"Before a pull request to the catalog run `pnpm build`, `pnpm validate`,",
+	"`pnpm lint`, `pnpm typecheck` and `pnpm test`: all must pass.",
+	"",
+	"## Rules",
+	"",
+	"- `extension.json` is the only declaration: every id the code registers",
+	"  is declared there first. Never edit `.dolphy/ids.d.ts` or `dist-ext/`.",
+	`- Keep ids prefixed with the extension id (\`${id}\`).`,
+	"- Extension code runs in the extension process (`host`), the app window",
+	"  (`views`) or an isolated frame (`panels`, no network). Do not import",
+	"  `node:*` modules into code that runs in the window or a frame.",
+	"- Before publishing replace `your-github-login` in the `author` field of",
+	"  `extension.json` with the GitHub login of the publisher.",
+	"- Ask only for the permissions the extension uses, and say in `README.md`",
+	"  what each one is for.",
+	"- No `eval`, no `new Function`, no minified or obfuscated sources, no",
+	"  `http(s)://` URLs unless the manifest declares the `network`",
+	"  permission: `pnpm lint` and the catalog review flag them.",
+	"- Keep tests next to the behaviour: `@dolphy-app/extension-sdk/testing`",
+	"  runs handlers, commands, events, views and panels without the app.",
+	"",
+	"## Guide",
+	"",
+	"Start with `node_modules/@dolphy-app/extension-sdk/docs/quick-start.md`;",
+	"the recipes next to it show a task type, a theme, a command with a panel,",
+	"and events with storage."
+]);
+const ciYml = () => lines([
+	"name: CI",
+	"",
+	"on:",
+	"  push:",
+	"  pull_request:",
+	"",
+	"jobs:",
+	"  check:",
+	"    runs-on: ubuntu-latest",
+	"    steps:",
+	"      - uses: actions/checkout@v4",
+	"      - uses: pnpm/action-setup@v4",
+	"        with:",
+	"          version: 10",
+	"      - uses: actions/setup-node@v4",
+	"        with:",
+	"          node-version: 22",
+	"      # the project has no lockfile until you commit one",
+	"      - run: pnpm install --no-frozen-lockfile",
+	"      - run: pnpm build",
+	"      - run: pnpm validate",
+	"      - run: pnpm lint",
+	"      - run: pnpm typecheck",
+	"      - run: pnpm test"
+]);
+
+//#endregion
+//#region packages/create-extension/src/templates/blank.ts
+const manifestJson$4 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "name": "Hello command",
+  "description": "A command-palette command that shows a notification.",
+  "author": "your-github-login",
+  "tags": ["productivity"],
+  "contributes": {
+    "commands": [{ "id": "${id}.hello", "title": "Say hello" }]
+  }
+}
+`;
+const indexTs$3 = (id) => `import { defineExtension, notify } from '@dolphy-app/extension-sdk';
+
+// extension code: runs in the extension process of the app
+// the command id comes from extension.json: a misspelt id or a declared id
+// without a handler fails \`pnpm typecheck\`
+export const host = defineExtension({
+  commands: {
+    '${id}.hello': () => notify('Hello from ${id}!'),
+  },
+});
+`;
+const indexTestTs$3 = (id) => `import { loadCommands } from '@dolphy-app/extension-sdk/testing';
+import { expect, it } from 'vitest';
+import { host } from '../src/index.ts';
+
+it('the hello command notifies', async () => {
+  const commands = await loadCommands(host, {
+    declaredCommands: ['${id}.hello'],
+  });
+  expect(await commands.run('${id}.hello')).toEqual({
+    kind: 'notify',
+    text: 'Hello from ${id}!',
+  });
+  await commands.dispose();
+});
+`;
+const blank = {
+	summary: ["A Dolphy extension: the smallest project that does something, one command", "in the command palette (Ctrl/⌘+K) that shows a notification."],
+	layout: [
+		"- `extension.json` — the manifest (the command is declared in it);",
+		"- `src/index.ts` — all the extension code: `host` (`defineExtension`); the",
+		"  build writes it to `main.mjs`;",
+		...idsBullet,
+		"- `test/index.test.ts` — tests (`vitest`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$4(id),
+		"src/index.ts": indexTs$3(id),
+		"test/index.test.ts": indexTestTs$3(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/command-panel.ts
+const manifestJson$3 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "name": "Hello panel",
+  "description": "Palette commands that greet the learner and open a small panel.",
+  "author": "your-github-login",
+  "tags": ["productivity"],
+  "contributes": {
+    "commands": [
+      { "id": "${id}.hello", "title": "Say hello", "category": "Hello" },
+      { "id": "${id}.open", "title": "Open the hello panel", "category": "Hello" },
+      { "id": "${id}.data", "title": "Hello panel data", "palette": false }
+    ],
+    "panels": [{ "id": "${id}.view", "title": "Hello" }]
+  }
+}
+`;
+const indexTs$2 = (id) => `import {
+  defineExtension,
+  defineExtensionPanel,
+  notify,
+  openPanel,
+} from '@dolphy-app/extension-sdk';
+import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+
+// extension code: \`host\` runs in the extension process of the app
+// the ids come from extension.json: a misspelt id or a declared id without a
+// handler fails \`pnpm typecheck\`
+export const host = defineExtension({
+  commands: {
+    // palette command: shows a notification
+    '${id}.hello': (args) => {
+      const name = typeof args === 'string' ? args : 'world';
+      return notify(\`Hello, \${name}!\`);
+    },
+    // palette command: opens the panel with properties
+    '${id}.open': () => openPanel('${id}.view', { name: 'Dolphy' }),
+    // hidden from the palette (palette: false): the panel asks for data
+    '${id}.data': () => ({ message: 'Hello from ${id}' }),
+  },
+});
+
+// the panel runs in an isolated frame of the app window: no network, no
+// window.dolphy; the only way out is \`ctx.call\` to the commands above
+export const panels = {
+  '${id}.view': defineExtensionPanel({
+    async mount(container, ctx) {
+      const doc = container.ownerDocument;
+      const title = doc.createElement('h2');
+      const line = doc.createElement('p');
+      container.append(title, line);
+      const name = (props: unknown): string =>
+        typeof props === 'object' && props !== null && 'name' in props
+          ? String(props.name)
+          : 'world';
+      title.textContent = \`Hello, \${name(ctx.props)}!\`;
+      // the app opens the panel again with new properties: redraw the title
+      ctx.signal.addEventListener(
+        'abort',
+        ctx.onProps((props) => {
+          title.textContent = \`Hello, \${name(props)}!\`;
+        }),
+      );
+      const data = (await ctx.call('${id}.data')) as { message: string };
+      line.textContent = data.message;
+    },
+  }),
+} satisfies ExtensionPanels;
+`;
+const indexTestTs$2 = (id) => `// @vitest-environment happy-dom
+import {
+  loadCommands,
+  loadPanel,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { host, panels } from '../src/index.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+const load = async () => {
+  const commands = await loadCommands(host, {
+    declaredCommands: ['${id}.hello', '${id}.open', '${id}.data'],
+    declaredPanels: ['${id}.view'],
+  });
+  disposables.push(commands);
+  return commands;
+};
+
+describe('${id}: commands', () => {
+  it('hello greets the name from the arguments, "world" without them', async () => {
+    const commands = await load();
+    expect(await commands.run('${id}.hello', 'Ada')).toEqual({
+      kind: 'notify',
+      text: 'Hello, Ada!',
+    });
+    expect(await commands.run('${id}.hello')).toEqual({
+      kind: 'notify',
+      text: 'Hello, world!',
+    });
+  });
+
+  it('open asks the app to open the panel with properties', async () => {
+    const commands = await load();
+    expect(await commands.run('${id}.open')).toEqual({
+      kind: 'openPanel',
+      panelId: '${id}.view',
+      props: { name: 'Dolphy' },
+    });
+  });
+
+  it('data returns what the panel shows', async () => {
+    const commands = await load();
+    expect(await commands.run('${id}.data')).toEqual({
+      kind: 'data',
+      value: { message: 'Hello from ${id}' },
+    });
+  });
+});
+
+describe('${id}: panel', () => {
+  it('shows the data command reply and follows new properties', async () => {
+    const panel = await loadPanel(panels, '${id}.view', {
+      props: { name: 'Ada' },
+      call: () => ({ message: 'Hello from the test' }),
+    });
+    disposables.push(panel);
+    expect(panel.container.querySelector('h2')?.textContent).toBe('Hello, Ada!');
+    expect(panel.container.querySelector('p')?.textContent).toBe(
+      'Hello from the test',
+    );
+    expect(panel.calls).toEqual([{ commandId: '${id}.data', args: undefined }]);
+
+    panel.setProps({ name: 'Grace' });
+    expect(panel.container.querySelector('h2')?.textContent).toBe(
+      'Hello, Grace!',
+    );
+  });
+
+  it('stops listening for properties when the panel closes', async () => {
+    const panel = await loadPanel(panels, '${id}.view', {
+      call: () => ({ message: 'x' }),
+    });
+    const heading = panel.container.querySelector('h2');
+    panel.dispose();
+    expect(panel.aborted).toBe(true);
+    panel.setProps({ name: 'Late' });
+    expect(heading?.textContent).toBe('Hello, world!');
+  });
+});
+`;
+const commandPanel = {
+	summary: ["A Dolphy extension: two commands in the command palette (Ctrl/⌘+K), a hidden", "data command and a panel — a page of the extension inside the app."],
+	layout: [
+		"- `extension.json` — the manifest (commands and the panel are declared in it);",
+		"- `src/index.ts` — all the extension code: `host` (`defineExtension`, the",
+		"  command handlers) and `panels` (`defineExtensionPanel`); the build",
+		"  splits it into `main.mjs` and `panel.mjs`;",
+		...idsBullet,
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$3(id),
+		"src/index.ts": indexTs$2(id),
+		"test/index.test.ts": indexTestTs$2(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/events.ts
+const manifestJson$2 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "name": "Day streak",
+  "description": "Counts the days in a row with a closed attempt and shows the streak.",
+  "author": "your-github-login",
+  "permissions": ["learning.events"],
+  "tags": ["learning"],
+  "contributes": {
+    "events": [{ "event": "attempt.closed" }],
+    "commands": [
+      { "id": "${id}.show", "title": "Show the streak", "category": "Streak" },
+      { "id": "${id}.data", "title": "Streak data", "palette": false }
+    ],
+    "panels": [{ "id": "${id}.view", "title": "Streak" }]
+  }
+}
+`;
+const indexTs$1 = (id) => `import {
+  defineExtension,
+  defineExtensionPanel,
+  inActivate,
+  notify,
+  openPanel,
+} from '@dolphy-app/extension-sdk';
+import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+
+// a \`type\`, not an \`interface\`: an interface has no index signature and is
+// not JSON for \`ctx.storage\`
+export type Streak = {
+  days: number;
+  last: string;
+};
+
+const KEY = 'streak';
+const DAY_MS = 86_400_000;
+
+const dayOf = (at: number): string => new Date(at).toISOString().slice(0, 10);
+
+// the streak grows when an attempt is closed the day after the last one;
+// the same day changes nothing, a skipped day starts over
+export const advance = (streak: Streak | undefined, at: number): Streak => {
+  const day = dayOf(at);
+  if (streak?.last === day) return streak;
+  const continues =
+    streak !== undefined && dayOf(Date.parse(streak.last) + DAY_MS) === day;
+  return { days: continues ? streak.days + 1 : 1, last: day };
+};
+
+// every event and command declared in extension.json is listed here;
+// \`inActivate\` means "registered in \`activate\`": the handlers need \`ctx\`
+export const host = defineExtension({
+  events: { 'attempt.closed': inActivate },
+  commands: { '${id}.show': inActivate, '${id}.data': inActivate },
+  activate(ctx) {
+    // delivered asynchronously, once per recorded attempt
+    ctx.events.on('attempt.closed', async ({ at, outcome }) => {
+      if (outcome === 'gave-up') return;
+      const streak = await ctx.storage.get<Streak>(KEY);
+      await ctx.storage.set(KEY, advance(streak, at));
+    });
+
+    // data for the panel: hidden from the palette, the panel calls it
+    ctx.commands.register(
+      '${id}.data',
+      async () => (await ctx.storage.get<Streak>(KEY)) ?? { days: 0, last: '' },
+    );
+
+    ctx.commands.register('${id}.show', async () => {
+      const streak = await ctx.storage.get<Streak>(KEY);
+      if (streak === undefined) {
+        return notify('No streak yet: finish your first exercise.');
+      }
+      return openPanel('${id}.view', { days: streak.days });
+    });
+  },
+});
+
+// the panel runs in an isolated frame: no network, the only way out is \`ctx.call\`
+export const panels = {
+  '${id}.view': defineExtensionPanel({
+    async mount(container, ctx) {
+      const line = container.ownerDocument.createElement('p');
+      container.append(line);
+      const render = async () => {
+        const streak = (await ctx.call('${id}.data')) as Streak;
+        line.textContent =
+          streak.days === 0
+            ? 'No streak yet.'
+            : \`Streak: \${streak.days} days, last day \${streak.last}\`;
+      };
+      // the command opens the panel again with new properties: redraw
+      ctx.signal.addEventListener(
+        'abort',
+        ctx.onProps(() => void render()),
+      );
+      await render();
+    },
+  }),
+} satisfies ExtensionPanels;
+`;
+const indexTestTs$1 = (id) => `// @vitest-environment happy-dom
+import type { LearningEventPayloads } from '@dolphy-app/extension-api';
+import {
+  createMemoryStorage,
+  loadCommands,
+  loadEvents,
+  loadPanel,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { host, panels } from '../src/index.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+type Attempt = LearningEventPayloads['attempt.closed'];
+
+const attempt = (day: string, outcome: Attempt['outcome'] = 'passed'): Attempt => ({
+  exerciseId: 'e',
+  courseId: 'c',
+  lessonId: 'l',
+  grade: 4,
+  outcome,
+  source: 'runner',
+  at: Date.parse(\`\${day}T12:00:00Z\`),
+});
+
+const load = async () => {
+  const storage = createMemoryStorage();
+  const events = await loadEvents(host, {
+    storage,
+    declared: ['attempt.closed'],
+  });
+  const commands = await loadCommands(host, {
+    storage,
+    declaredCommands: ['${id}.show', '${id}.data'],
+    declaredPanels: ['${id}.view'],
+  });
+  disposables.push(events, commands);
+  return { storage, events, commands };
+};
+
+describe('${id}: events and storage', () => {
+  it('counts consecutive days, ignores a repeat on the same day', async () => {
+    const { storage, events } = await load();
+    await events.emit('attempt.closed', attempt('2026-10-01'));
+    await events.emit('attempt.closed', attempt('2026-10-01'));
+    await events.emit('attempt.closed', attempt('2026-10-02'));
+    expect(await storage.get('streak')).toEqual({
+      days: 2,
+      last: '2026-10-02',
+    });
+  });
+
+  it('a skipped day starts over; giving up leaves the streak alone', async () => {
+    const { storage, events } = await load();
+    await events.emit('attempt.closed', attempt('2026-10-01'));
+    await events.emit('attempt.closed', attempt('2026-10-02'));
+    await events.emit('attempt.closed', attempt('2026-10-03', 'gave-up'));
+    expect(await storage.get('streak')).toEqual({
+      days: 2,
+      last: '2026-10-02',
+    });
+    await events.emit('attempt.closed', attempt('2026-10-05'));
+    expect(await storage.get('streak')).toEqual({
+      days: 1,
+      last: '2026-10-05',
+    });
+  });
+});
+
+describe('${id}: commands and panel', () => {
+  it('without a streak the show command notifies, the data command returns zeros', async () => {
+    const { commands } = await load();
+    expect(await commands.run('${id}.show')).toMatchObject({ kind: 'notify' });
+    expect(await commands.run('${id}.data')).toEqual({
+      kind: 'data',
+      value: { days: 0, last: '' },
+    });
+  });
+
+  it('with a streak the show command opens the panel with the days', async () => {
+    const { events, commands } = await load();
+    await events.emit('attempt.closed', attempt('2026-10-01'));
+    expect(await commands.run('${id}.show')).toEqual({
+      kind: 'openPanel',
+      panelId: '${id}.view',
+      props: { days: 1 },
+    });
+  });
+
+  it('the panel shows what the data command returns', async () => {
+    const { events, commands } = await load();
+    await events.emit('attempt.closed', attempt('2026-10-01'));
+    const panel = await loadPanel(panels, '${id}.view', {
+      call: async (commandId) => {
+        const result = await commands.run(commandId);
+        return result.kind === 'data' ? result.value : undefined;
+      },
+    });
+    disposables.push(panel);
+    expect(panel.container.querySelector('p')?.textContent).toBe(
+      'Streak: 1 days, last day 2026-10-01',
+    );
+  });
+});
+`;
+const events = {
+	summary: [
+		"A Dolphy extension: a day streak. It listens to `attempt.closed`, keeps",
+		"the streak in `ctx.storage`, and shows it with a command and a panel.",
+		"It asks for the `learning.events` permission: without it no event arrives."
+	],
+	layout: [
+		"- `extension.json` — the manifest (the event, the commands, the panel and",
+		"  the `learning.events` permission are declared in it);",
+		"- `src/index.ts` — all the extension code: `host` (`defineExtension`: the",
+		"  event handler, the commands, `ctx.storage`) and `panels`",
+		"  (`defineExtensionPanel`); the build splits it into `main.mjs` and",
+		"  `panel.mjs`;",
+		...idsBullet,
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$2(id),
+		"src/index.ts": indexTs$1(id),
+		"test/index.test.ts": indexTestTs$1(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/exercise.ts
+const manifestJson$1 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
   "id": "${id}",
   "version": "${INITIAL_VERSION}",
   "apiVersion": 1,
+  "name": "Text match",
+  "description": "Exercise type: the learner types a string that is compared with the expected text.",
+  "author": "your-github-login",
+  "tags": ["learning"],
   "contributes": {
     "exerciseTypes": [
       {
@@ -70,26 +901,53 @@ const manifestJson = (id) => `{
         },
         "answerSchema": { "type": "string" }
       }
+    ],
+    "settings": [
+      {
+        "id": "${id}.trim",
+        "type": "boolean",
+        "label": "Ignore spaces around the answer",
+        "default": true
+      }
+    ],
+    "commands": [
+      { "id": "${id}.status", "title": "Show how answers are compared" }
     ]
   }
 }
 `;
-const mainTs = (id) => `import { defineExerciseType, defineExtension } from '@dolphy-app/extension-sdk';
+const indexTs = (id) => `import {
+  defineAnswerView,
+  defineExerciseType,
+  defineExtension,
+  inActivate,
+  notify,
+} from '@dolphy-app/extension-sdk';
+import type { ExtensionViews } from '@dolphy-app/extension-sdk';
 
 interface Spec {
   expected: string;
   ignoreCase?: boolean;
 }
 
+// filled from the setting in \`activate\`, read by the handlers below
+const options = { trim: true };
+
 const matches = (answer: string, spec: Spec): boolean => {
+  const given = options.trim ? answer.trim() : answer;
   if (spec.ignoreCase === true) {
-    return answer.toLowerCase() === spec.expected.toLowerCase();
+    return given.toLowerCase() === spec.expected.toLowerCase();
   }
-  return answer === spec.expected;
+  return given === spec.expected;
 };
 
-// схемы из extension.json уже проверили spec и ответ до вызова обработчиков
-export default defineExtension({
+// extension code: runs in the extension process of the app
+// the schemas from extension.json have already checked \`spec\` and the answer
+// before the handlers run
+// the ids come from extension.json: \`dolphy-ext types\` (and every build)
+// writes them to .dolphy/ids.d.ts, so a misspelt id, a declared id without a
+// handler or an undeclared setting fails \`pnpm typecheck\`
+export const host = defineExtension({
   exerciseTypes: {
     '${id}': defineExerciseType<Spec, string, Record<string, never>>({
       project: () => ({}),
@@ -100,50 +958,72 @@ export default defineExtension({
       referenceAnswer: ({ spec }) => spec.expected,
     }),
   },
+  // this command is registered in \`activate\`: the marker names the id there
+  commands: { '${id}.status': inActivate },
+  activate(ctx) {
+    options.trim = ctx.settings.get('${id}.trim');
+    ctx.settings.onDidChange((change) => {
+      if (change.id === '${id}.trim') options.trim = change.value;
+    });
+    ctx.commands.register('${id}.status', () =>
+      notify(
+        options.trim
+          ? 'Answers are compared without the spaces around them.'
+          : 'Answers are compared exactly as typed.',
+      ),
+    );
+  },
 });
+
+// the answer input: runs in the app window; the build defines the custom
+// element with the tag from extension.json
+export const views = {
+  '${id}': defineAnswerView((api, initial) => {
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.spellcheck = false;
+    if (api.label !== null) input.setAttribute('aria-label', api.label);
+
+    const applyValue = (value: unknown) => {
+      input.value = typeof value === 'string' ? value : '';
+    };
+    let appliedValue = initial.value;
+    applyValue(appliedValue);
+    input.disabled = initial.disabled;
+
+    input.addEventListener('input', () => {
+      api.setAnswer(input.value, input.value.trim().length > 0);
+    });
+    input.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter') api.submit();
+    });
+    api.root.append(input);
+
+    return {
+      update: (props) => {
+        input.disabled = props.disabled;
+        // apply the value only when the app really changed it
+        if (props.value !== appliedValue) {
+          appliedValue = props.value;
+          applyValue(appliedValue);
+        }
+      },
+    };
+  }),
+} satisfies ExtensionViews;
 `;
-const viewTs = (id) => `import { defineAnswerElement } from '@dolphy-app/extension-sdk';
-
-defineAnswerElement('${defaultElementName(id)}', (api, initial) => {
-  const input = document.createElement('input');
-  input.type = 'text';
-  input.spellcheck = false;
-  if (api.label !== null) input.setAttribute('aria-label', api.label);
-
-  const applyValue = (value: unknown) => {
-    input.value = typeof value === 'string' ? value : '';
-  };
-  let appliedValue = initial.value;
-  applyValue(appliedValue);
-  input.disabled = initial.disabled;
-
-  input.addEventListener('input', () => {
-    api.setAnswer(input.value, input.value.trim().length > 0);
-  });
-  input.addEventListener('keydown', (event) => {
-    if (event.key === 'Enter') api.submit();
-  });
-  api.root.append(input);
-
-  return {
-    update: (props) => {
-      input.disabled = props.disabled;
-      // value применяется, только когда приложение его действительно сменило
-      if (props.value !== appliedValue) {
-        appliedValue = props.value;
-        applyValue(appliedValue);
-      }
-    },
-  };
-});
-`;
-const mainTestTs = (id) => `import {
+const indexTestTs = (id) => `// @vitest-environment happy-dom
+import type { SettingContribution } from '@dolphy-app/extension-sdk';
+import {
+  createMemorySettings,
   createSchemaValidator,
+  loadCommands,
   loadExerciseType,
+  loadView,
 } from '@dolphy-app/extension-sdk/testing';
 import { afterEach, describe, expect, it } from 'vitest';
 import manifest from '../extension.json';
-import module from '../src/main.ts';
+import { host, views } from '../src/index.ts';
 
 const [contribution] = manifest.contributes.exerciseTypes;
 const validateSpec = createSchemaValidator(contribution.specSchema);
@@ -151,24 +1031,35 @@ const validateAnswer = createSchemaValidator(contribution.answerSchema);
 
 const spec = { expected: 'Hello' };
 
-const disposables: { dispose(): Promise<void> }[] = [];
+const disposables: { dispose(): unknown }[] = [];
 afterEach(async () => {
   await Promise.all(disposables.splice(0).map((item) => item.dispose()));
 });
 
-const load = async () => {
-  const type = await loadExerciseType(module, '${id}');
+const newSettings = () =>
+  createMemorySettings(manifest.contributes.settings as SettingContribution[]);
+
+const load = async (settings = newSettings()) => {
+  const type = await loadExerciseType(host, '${id}', { settings });
   disposables.push(type);
   return type;
 };
 
-describe('${id}: обработчик', () => {
-  it('project не раскрывает эталон', async () => {
+const mount = async (label?: string) => {
+  const view = await loadView(views, '${id}', label === undefined ? {} : { label });
+  disposables.push(view);
+  const input = view.query<HTMLInputElement>('input');
+  if (input === null) throw new Error('no input');
+  return { view, input };
+};
+
+describe('${id}: handler', () => {
+  it('project does not reveal the reference', async () => {
     const type = await load();
     expect(await type.project(spec)).toEqual({});
   });
 
-  it('grade: совпадение засчитывается, расхождение нет', async () => {
+  it('grade: a match passes, a mismatch does not', async () => {
     const type = await load();
     expect(await type.grade({ spec, answer: 'Hello' })).toEqual({
       outcome: 'passed',
@@ -179,7 +1070,7 @@ describe('${id}: обработчик', () => {
     });
   });
 
-  it('grade: ignoreCase отключает различие регистров', async () => {
+  it('grade: ignoreCase turns case sensitivity off', async () => {
     const type = await load();
     const relaxed = { ...spec, ignoreCase: true };
     expect(await type.grade({ spec: relaxed, answer: 'hELLO' })).toEqual({
@@ -187,7 +1078,7 @@ describe('${id}: обработчик', () => {
     });
   });
 
-  it('referenceAnswer сам проходит проверку', async () => {
+  it('referenceAnswer passes the check itself', async () => {
     const type = await load();
     const reference = await type.referenceAnswer(spec);
     expect(reference).toEqual({ found: true, answer: 'Hello' });
@@ -198,158 +1089,217 @@ describe('${id}: обработчик', () => {
   });
 });
 
-describe('${id}: схемы', () => {
+describe('${id}: settings and commands', () => {
+  it('the trim setting decides whether the spaces around an answer count', async () => {
+    const settings = newSettings();
+    const type = await load(settings);
+    expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
+      outcome: 'passed',
+    });
+    await settings.set('${id}.trim', false);
+    expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
+      outcome: 'failed',
+      reason: 'mismatch',
+    });
+  });
+
+  it('the status command reports the current mode', async () => {
+    const settings = newSettings();
+    const commands = await loadCommands(host, {
+      declaredCommands: ['${id}.status'],
+      settings,
+    });
+    disposables.push(commands);
+    expect(await commands.run('${id}.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared without the spaces around them.',
+    });
+    await settings.set('${id}.trim', false);
+    expect(await commands.run('${id}.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared exactly as typed.',
+    });
+  });
+});
+
+describe('${id}: schemas', () => {
   it.each([[{ expected: 'a' }], [{ expected: 'a', ignoreCase: true }]])(
-    'spec %j допустим',
+    'spec %j is valid',
     (value) => {
       expect(validateSpec(value)).toEqual([]);
     },
   );
 
   it.each([
-    ['нет expected', {}],
-    ['пустой expected', { expected: '' }],
-    ['ignoreCase не boolean', { expected: 'a', ignoreCase: 'yes' }],
-    ['лишнее поле', { expected: 'a', extra: 1 }],
-  ])('spec: %s отклоняется', (_name, value) => {
+    ['no expected', {}],
+    ['empty expected', { expected: '' }],
+    ['ignoreCase is not a boolean', { expected: 'a', ignoreCase: 'yes' }],
+    ['an extra field', { expected: 'a', extra: 1 }],
+  ])('spec: %s is rejected', (_name, value) => {
     expect(validateSpec(value)).not.toEqual([]);
   });
 
-  it('answer: строка допустима, число нет', () => {
+  it('answer: a string is valid, a number is not', () => {
     expect(validateAnswer('text')).toEqual([]);
     expect(validateAnswer(42)).not.toEqual([]);
   });
 });
-`;
-const viewTestTs = (id) => {
-	const tag = defaultElementName(id);
-	return `// @vitest-environment happy-dom
-import { ANSWER_EVENT } from '@dolphy-app/extension-sdk';
-import type { AnswerChangeDetail } from '@dolphy-app/extension-sdk';
-import { afterEach, describe, expect, it } from 'vitest';
-import '../src/view.ts';
-
-interface AnswerElement extends HTMLElement {
-  view: unknown;
-  value: unknown;
-  disabled: boolean;
-}
-
-const flush = () => Promise.resolve();
-
-const mountElement = async (label: string | null = null) => {
-  const element = document.createElement('${tag}') as AnswerElement;
-  if (label !== null) element.setAttribute('aria-label', label);
-  document.body.append(element);
-  await flush();
-  const changes: AnswerChangeDetail[] = [];
-  element.addEventListener(ANSWER_EVENT.change, (event) => {
-    changes.push((event as CustomEvent<AnswerChangeDetail>).detail);
-  });
-  const input = element.shadowRoot?.querySelector('input');
-  if (input === null || input === undefined) throw new Error('no input');
-  return { element, input, changes };
-};
 
-afterEach(() => {
-  document.body.replaceChildren();
-});
-
-describe('${tag}', () => {
-  it('ввод текста сообщает ответ; пустой ввод неполный', async () => {
-    const { input, changes } = await mountElement();
+describe('${id}: view', () => {
+  it('typing reports the answer; an empty input is incomplete', async () => {
+    const { view, input } = await mount();
     input.value = 'Hello';
     input.dispatchEvent(new Event('input'));
     input.value = '  ';
     input.dispatchEvent(new Event('input'));
-    expect(changes).toEqual([
+    expect(view.changes).toEqual([
       { value: 'Hello', complete: true },
       { value: '  ', complete: false },
     ]);
   });
 
-  it('Enter отправляет ответ', async () => {
-    const { element, input } = await mountElement();
-    let submits = 0;
-    element.addEventListener(ANSWER_EVENT.submit, () => void (submits += 1));
+  it('Enter submits the answer', async () => {
+    const { view, input } = await mount();
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
-    expect(submits).toBe(1);
+    expect(view.submissions).toBe(1);
   });
 
-  it('disabled блокирует поле', async () => {
-    const { element, input } = await mountElement();
-    element.disabled = true;
-    await flush();
+  it('disabled blocks the input', async () => {
+    const { view, input } = await mount();
+    await view.update({ disabled: true });
     expect(input.disabled).toBe(true);
   });
 
-  it('value восстанавливает ответ без событий', async () => {
-    const { element, input, changes } = await mountElement();
-    element.value = 'Hello';
-    await flush();
+  it('value restores the answer without events', async () => {
+    const { view, input } = await mount();
+    await view.update({ value: 'Hello' });
     expect(input.value).toBe('Hello');
-    expect(changes).toEqual([]);
+    expect(view.changes).toEqual([]);
   });
 
-  it('aria-label хоста попадает на поле', async () => {
-    const { input } = await mountElement('Ваш ответ');
-    expect(input.getAttribute('aria-label')).toBe('Ваш ответ');
+  it('the aria-label of the host goes to the input', async () => {
+    const { input } = await mount('Your answer');
+    expect(input.getAttribute('aria-label')).toBe('Your answer');
   });
 });
 `;
+const exercise = {
+	summary: ["A Dolphy extension: the \"text match\" exercise type (the learner types a", "string, it is compared with `spec.expected`), a setting and a command."],
+	layout: [
+		"- `extension.json` — the manifest (the `spec` and answer schemas are written",
+		"  in it);",
+		"- `src/index.ts` — all the extension code: `host` (`defineExtension` +",
+		"  `defineExerciseType`) and `views` (`defineAnswerView`); the build splits",
+		"  it into `main.mjs` and `view.mjs`;",
+		...idsBullet,
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$1(id),
+		"src/index.ts": indexTs(id),
+		"test/index.test.ts": indexTestTs(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/theme.ts
+const manifestJson = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "name": "Midnight",
+  "description": "A dark color theme with an amber accent for the Dolphy app.",
+  "author": "your-github-login",
+  "tags": ["theme"],
+  "contributes": {
+    "themes": [
+      {
+        "id": "${id}",
+        "label": "Midnight",
+        "dark": true,
+        "colors": {
+          "background": "#101820",
+          "surface": "#1B2733",
+          "on-background": "#E6EDF3",
+          "on-surface": "#E6EDF3",
+          "primary": "#FFB000",
+          "on-primary": "#101820"
+        },
+        "variables": { "border-opacity": 0.2 }
+      }
+    ]
+  }
+}
+`;
+const themeTestTs = (id) => `import { describe, expect, it } from 'vitest';
+import manifest from '../extension.json';
+
+const [theme] = manifest.contributes.themes;
+const colors: Record<string, string> = theme.colors;
+
+// WCAG relative luminance of a #rrggbb color
+const luminance = (hex: string): number => {
+  const [r, g, b] = [1, 3, 5].map((start) => {
+    const channel = Number.parseInt(hex.slice(start, start + 2), 16) / 255;
+    return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  }) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+const contrast = (foreground: string, background: string): number => {
+  const [light, dark] = [luminance(foreground), luminance(background)].sort(
+    (a, b) => b - a,
+  ) as [number, number];
+  return (light + 0.05) / (dark + 0.05);
+};
+
+describe('${id}: theme', () => {
+  it.each([
+    ['on-surface', 'surface'],
+    ['on-background', 'background'],
+    ['on-primary', 'primary'],
+  ])('%s on %s has a contrast of at least 4.5:1', (foreground, background) => {
+    expect(contrast(colors[foreground] as string, colors[background] as string))
+      .toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('a dark theme has a dark background and a light text', () => {
+    const background = luminance(colors['background'] as string);
+    const text = luminance(colors['on-background'] as string);
+    expect(theme.dark ? background < text : background > text).toBe(true);
+  });
+});
+`;
+const theme = {
+	summary: ["A Dolphy extension: a color theme (\"Midnight\"). A theme is data only, so", "there is no code to build; the test checks the text contrast."],
+	layout: [
+		"- `extension.json` — the manifest: the theme `colors` (allowed keys are",
+		"  listed in the Dolphy extension guide) and `variables`;",
+		"- `test/theme.test.ts` — checks the contrast of the text colors",
+		"  (`vitest`); there is no `src/`, a theme has no code."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson(id),
+		"test/theme.test.ts": themeTestTs(id)
+	})
 };
-const readme = (id) => lines([
-	`# ${id}`,
-	"",
-	"Расширение Dolphy: вид задания «text match» (ученик вводит строку, она",
-	"сравнивается с `spec.expected`). Сгенерировано `create-dolphy-extension`.",
-	"",
-	"## Раскладка",
-	"",
-	"- `extension.json` — манифест (схемы `spec` и ответа записаны прямо в нём);",
-	"- `src/main.ts` — код расширения: `defineExtension` + `defineExerciseType`;",
-	"- `src/view.ts` — элемент ввода ответа: `defineAnswerElement`;",
-	"- `test/` — тесты обработчика и элемента (`vitest`, `happy-dom`).",
-	"",
-	"## Цикл разработки",
-	"",
-	"```sh",
-	"pnpm install",
-	`pnpm dev # dolphy-ext build --watch: пересборка в dist-ext/${id}`,
-	"```",
-	"",
-	"Запустите приложение с корнем режима разработчика — каталогом `dist-ext`",
-	"этого проекта (абсолютный путь):",
-	"",
-	"```sh",
-	"DOLPHY_DEV_EXTENSIONS=<путь к проекту>/dist-ext pnpm dev # из репозитория Dolphy",
-	"```",
-	"",
-	"Правка файла в `dist-ext` перезапускает хосты и перезагружает окно.",
-	"Ошибки загрузки видны в «Настройки → Расширения».",
-	"",
-	"## Сборка, проверка, тесты",
-	"",
-	"```sh",
-	`pnpm build     # dist-ext/${id}`,
-	"pnpm validate  # тот же разбор манифеста, что делает приложение",
-	"pnpm test",
-	"```",
-	"",
-	"## Установка вручную",
-	"",
-	`Скопируйте каталог \`dist-ext/${id}\` в \`<userData>/extensions/\``,
-	"и перезапустите приложение. Установки из приложения пока нет."
-]);
-const gitignore = () => lines(["node_modules", "dist-ext"]);
 
 //#endregion
 //#region packages/create-extension/src/generate.ts
-/** Совпадает с ограничением манифеста (`parseManifest`). */
+const TEMPLATES = {
+	exercise,
+	theme,
+	"command-panel": commandPanel,
+	events,
+	blank
+};
+const isTemplateName = (name) => TEMPLATE_NAMES.includes(name);
+/** Matches the manifest limit (`parseManifest`). */
 const MAX_ID_CHARS = 64;
-/** Без сборки (исходники, `--local`) версия пакетов условная. */
+/** Without a build (sources, `--local`) the package version is a placeholder. */
 const UNPUBLISHED_VERSION = "^0.0.0";
-const builtPackageVersion = () => "0.2.0";
+const builtPackageVersion = () => "0.4.0";
 var GenerateError = class extends Error {
 	code;
 	constructor(code, message) {
@@ -372,6 +1322,7 @@ const dependencySpecs = async (localRoot, packageVersion) => {
 		const range = packageVersion === null ? UNPUBLISHED_VERSION : `^${packageVersion}`;
 		return {
 			dependencies: {
+				api: range,
 				sdk: range,
 				tools: range
 			},
@@ -379,11 +1330,17 @@ const dependencySpecs = async (localRoot, packageVersion) => {
 		};
 	}
 	const root = path.resolve(localRoot);
+	const api = path.join(root, "packages", "extension-api");
 	const sdk = path.join(root, "packages", "extension-sdk");
 	const tools = path.join(root, "packages", "extension-tools");
-	for (const dir of [sdk, tools]) if (!await isDirectory(dir)) throw new GenerateError("invalid-local", `${dir} not found: --local must point to the Dolphy repository root`);
+	for (const dir of [
+		api,
+		sdk,
+		tools
+	]) if (!await isDirectory(dir)) throw new GenerateError("invalid-local", `${dir} not found: --local must point to the Dolphy repository root`);
 	return {
 		dependencies: {
+			api: `link:${api}`,
 			sdk: `link:${sdk}`,
 			tools: `link:${tools}`
 		},
@@ -395,29 +1352,32 @@ const assertEmpty = async (dir) => {
 	if (info === null) return;
 	if ((info.isDirectory() ? await readdir(dir) : ["(file)"]).length > 0) throw new GenerateError("target-not-empty", `${dir} is not empty`);
 };
-/** Файлы проекта: относительный путь → содержимое. */
+/** Project files: relative path → content. */
 const renderProject = (input) => {
-	const { id } = input;
-	return /* @__PURE__ */ new Map([
+	const { id, template = DEFAULT_TEMPLATE } = input;
+	const module = TEMPLATES[template];
+	return new Map([
 		["package.json", packageJson(input)],
 		["tsconfig.json", tsconfigJson()],
-		["extension.json", manifestJson(id)],
-		["src/main.ts", mainTs(id)],
-		["src/view.ts", viewTs(id)],
-		["test/main.test.ts", mainTestTs(id)],
-		["test/view.test.ts", viewTestTs(id)],
-		["README.md", readme(id)],
-		[".gitignore", gitignore()]
+		...Object.entries(module.files(id)),
+		["README.md", readme(id, module)],
+		["AGENTS.md", agentsMd(id, module)],
+		["CLAUDE.md", claudeMd()],
+		[".gitignore", gitignore()],
+		[".github/workflows/ci.yml", ciYml()]
 	]);
 };
 const generateExtension = async (options) => {
 	const dir = path.resolve(options.dir);
 	const id = resolveId(dir, options.id);
+	const template = options.template ?? "exercise";
+	if (!isTemplateName(template)) throw new GenerateError("invalid-template", `unknown template '${template}'; available: ${TEMPLATE_NAMES.join(", ")}`);
 	const { dependencies, isPublished } = await dependencySpecs(options.localRoot, options.packageVersion ?? builtPackageVersion());
 	await assertEmpty(dir);
 	const isLocal = options.localRoot !== void 0;
 	const project = renderProject({
 		id,
+		template,
 		dependencies
 	});
 	for (const [file, content] of project) {
@@ -439,13 +1399,15 @@ const generateExtension = async (options) => {
 const EXIT_OK = 0;
 const EXIT_PROBLEMS = 1;
 const EXIT_USAGE = 2;
-const USAGE = `usage: create-dolphy-extension <dir> [--id <id>] [--local <repoRoot>]
+const USAGE = `usage: create-dolphy-extension <dir> [--id <id>] [--template <name>] [--local <repoRoot>]
 
-  <dir>              каталог нового проекта (должен быть пуст или отсутствовать)
-  --id <id>          id расширения (по умолчанию — kebab-case имени каталога)
-  --local <repoRoot> корень репозитория Dolphy: @dolphy-app/extension-sdk и
-                     @dolphy-app/extension-tools подключаются как link:<repoRoot>/packages/...
-  --help             эта справка
+  <dir>              new project directory (must be empty or not exist)
+  --id <id>          extension id (default: kebab-case of the directory name)
+  --template <name>  project kind: exercise (default), theme, command-panel,
+                     events or blank
+  --local <repoRoot> Dolphy repository root: @dolphy-app/extension-sdk and
+                     @dolphy-app/extension-tools are linked as link:<repoRoot>/packages/...
+  --help             show this help
 `;
 const parseArgs = (argv) => {
 	if (argv.includes("--help") || argv.includes("-h")) return { help: true };
@@ -453,42 +1415,43 @@ const parseArgs = (argv) => {
 	const values = /* @__PURE__ */ new Map();
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
-		if (arg === "--id" || arg === "--local") {
+		if (arg === "--id" || arg === "--local" || arg === "--template") {
 			const value = argv[++i];
-			if (value === void 0) return { usageError: `${arg} требует значение` };
+			if (value === void 0) return { usageError: `${arg} requires a value` };
 			values.set(arg, value);
-		} else if (arg.startsWith("-")) return { usageError: `неизвестный флаг: ${arg}` };
+		} else if (arg.startsWith("-")) return { usageError: `unknown flag: ${arg}` };
 		else positional.push(arg);
 	}
 	const [dir, ...extra] = positional;
-	if (dir === void 0) return { usageError: "не указан каталог" };
-	if (extra.length > 0) return { usageError: `лишние аргументы: ${extra.join(" ")}` };
+	if (dir === void 0) return { usageError: "no directory given" };
+	if (extra.length > 0) return { usageError: `unexpected arguments: ${extra.join(" ")}` };
 	return {
 		dir,
 		id: values.get("--id"),
-		local: values.get("--local")
+		local: values.get("--local"),
+		template: values.get("--template")
 	};
 };
-const PLACEHOLDER_NOTE = "\nЗамечание: @dolphy-app/extension-sdk и @dolphy-app/extension-tools не опубликованы, версия ^0.0.0 не установится.\nУкажите пути к репозиторию Dolphy: create-dolphy-extension <dir> --local <repoRoot>.\n";
+const PLACEHOLDER_NOTE = "\nNote: @dolphy-app/extension-sdk and @dolphy-app/extension-tools are not published, version ^0.0.0 cannot be installed.\nPoint to the Dolphy repository: create-dolphy-extension <dir> --local <repoRoot>.\n";
 const installNote = ({ isLocal, isPublished }) => {
 	if (isLocal) return "";
 	return isPublished ? "" : PLACEHOLDER_NOTE;
 };
 const nextSteps = (result) => {
 	const { dir, id } = result;
-	return `\nДальше:\n${[
+	return `\nNext steps:\n${[
 		`  cd ${dir}`,
 		"  pnpm install",
 		"  pnpm test",
-		`  pnpm dev    # пересборка в dist-ext/${id}`,
+		`  pnpm dev    # rebuilds into dist-ext/${id}`,
 		"",
-		"Запуск приложения с вашим расширением (из репозитория Dolphy):",
+		"Run the app with your extension (from the Dolphy repository):",
 		`  DOLPHY_DEV_EXTENSIONS=${path.join(dir, "dist-ext")} pnpm dev`
 	].join("\n")}\n${installNote(result)}`;
 };
 /**
-* `create-dolphy-extension`; `argv` без `node` и имени скрипта, относительные пути
-* считаются от `cwd`.
+* `create-dolphy-extension`; `argv` without `node` and the script name; relative paths
+* are resolved against `cwd`.
 */
 const runCli = async (argv, io, cwd = process.cwd()) => {
 	const parsed = parseArgs(argv);
@@ -504,6 +1467,7 @@ const runCli = async (argv, io, cwd = process.cwd()) => {
 		const result = await generateExtension({
 			dir: path.resolve(cwd, parsed.dir),
 			...parsed.id === void 0 ? {} : { id: parsed.id },
+			...parsed.template === void 0 ? {} : { template: parsed.template },
 			...parsed.local === void 0 ? {} : { localRoot: path.resolve(cwd, parsed.local) }
 		});
 		io.stdout(`created ${result.id} in ${result.dir} (${result.files.length} files)\n`);