@dolphy-app/create-extension 0.3.0 → 0.5.0

package/dist/cli/main.js

@@ -2,10 +2,134 @@
 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/hooks.ts
+/** Limits on hooks; the host and the engine check the same numbers. */
+const EXTENSION_HOOK_LIMITS = Object.freeze({
+	/** Budget of one handler call, ms. */
+	timeoutMs: 3e4,
+	/** Hooks registered by one extension. */
+	hooks: 8,
+	/** Exercises in a `practice.batch` response. */
+	maxExercises: 500
+});
+
+//#endregion
 //#region packages/extension-api/src/index.ts
 const EXTENSION_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
-/** Limits on commands and panels (R1, R3); they match those checked by the manifest, host, and engine. */
+/** Limits on injections; the app enforces them. */
+const INJECTION_LIMITS = Object.freeze({ 
+/** Characters in `InjectionRegistration.target`. */
+selectorLength: 200 });
+/** Limits on schedules; the host, 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`, `enum`, `group`, `order`); they match those checked by the host 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,
+	/** Length of a label, in UTF-16 code units; also of an option's label. */
+	labelLength: 60,
+	/** Length of a help text. */
+	descriptionLength: 500,
+	groupLength: 60,
+	orderMax: 1e3,
+	/** Options of one `enum`. */
+	options: 64,
+	/** Length of an option's value. */
+	optionValueLength: 100
+});
+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 host and the engine. */
 const EXTENSION_COMMAND_LIMITS = Object.freeze({
+	/** Keybinding entries (`keybindings`) per command. */
+	keybindingsPerCommand: 4,
+	/** Length of a `when` condition (of a command, panel or `keybindings[]` entry). */
+	whenLength: 200,
 	/** Commands per extension. */
 	commands: 64,
 	/** Panels per extension. */
@@ -22,6 +146,42 @@ const EXTENSION_COMMAND_LIMITS = Object.freeze({
 	/** Handler budget, ms. */
 	handlerMs: 1e4
 });
+/** Limits on importers and exporters; the host and the 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
+});
+/** Limits on RPC between the client and the server part of an extension; the host and the engine check the same numbers. */
+const EXTENSION_RPC_LIMITS = Object.freeze({
+	/** Characters in the name of a contract. */
+	nameLength: 120,
+	/** Handlers (`server.handle`) per extension. */
+	rpcs: 64,
+	/** `JSON.stringify(input).length` at the engine boundary. */
+	inputChars: 2e5,
+	/** Handler budget, ms. */
+	handlerMs: 1e4
+});
 /** 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. */
@@ -33,35 +193,89 @@ const EXTENSION_STORAGE_LIMITS = Object.freeze({
 	/** 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 `server.stats`; the engine enforces them. */
+const EXTENSION_STATS_LIMITS = Object.freeze({ 
+/** Most dates in one `daily` range (both ends included). */
+dailyDays: 366 });
+/** Limits of `server.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
+});
+/** Registration of an extension without a server part, or before it has registered anything. */
+const EMPTY_SERVER_REGISTRATION = Object.freeze({
+	exerciseTypes: Object.freeze([]),
+	gradePolicies: Object.freeze([]),
+	settings: Object.freeze([]),
+	events: Object.freeze([]),
+	commands: Object.freeze([]),
+	schedules: Object.freeze([]),
+	importers: Object.freeze([]),
+	exporters: Object.freeze([]),
+	rpcs: Object.freeze([]),
+	hooks: Object.freeze([])
+});
 
 //#endregion
-//#region packages/create-extension/src/template.ts
+//#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",
+	"react-panel",
+	"events",
+	"blank"
+];
+const DEFAULT_TEMPLATE = "exercise";
 const lines = (parts) => `${parts.join("\n")}\n`;
-const packageJson = ({ id, dependencies }) => `${JSON.stringify({
+/** `typecheck` script command (default `tsc`). */
+const typecheckCommand = (module) => module.typecheck ?? "tsc";
+/** The `pnpm` scripts of every generated project. */
+const scripts = (id, module) => ({
+	build: "dolphy-ext build",
+	dev: "dolphy-ext build --watch",
+	typecheck: typecheckCommand(module),
+	validate: `dolphy-ext validate dist-ext/${id}`,
+	lint: "dolphy-ext lint",
+	test: "vitest run"
+});
+const packageJson = ({ id, dependencies }, module) => `${JSON.stringify({
 	name: id,
 	version: INITIAL_VERSION,
 	private: true,
 	type: "module",
-	scripts: {
-		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}`,
-		test: "vitest run"
-	},
-	devDependencies: {
+	scripts: scripts(id, module),
+	devDependencies: Object.fromEntries(Object.entries({
+		"@dolphy-app/extension-api": dependencies.api,
 		"@dolphy-app/extension-sdk": dependencies.sdk,
 		"@dolphy-app/extension-tools": dependencies.tools,
 		"@types/node": "^22.20.4",
 		"happy-dom": "^20.14.5",
 		typescript: "^6.0.3",
-		vitest: "^5.0.2"
-	}
+		vitest: "^5.0.2",
+		vue: "^3.5.35",
+		vuetify: "^4.0.1",
+		...module.devDependencies
+	}).sort(([a], [b]) => a < b ? -1 : 1))
 }, null, 2)}\n`;
-const tsconfigJson = () => lines([
+const tsconfigJson = (module) => lines([
 	"{",
 	"  \"compilerOptions\": {",
 	"    \"target\": \"ES2023\",",
@@ -75,80 +289,832 @@ const tsconfigJson = () => lines([
 	"    \"verbatimModuleSyntax\": true,",
 	"    \"isolatedModules\": true,",
 	"    \"skipLibCheck\": true,",
+	...Object.entries(module.compilerOptions ?? {}).map(([name, value]) => `    "${name}": ${value},`),
 	"    \"noEmit\": true",
 	"  },",
-	"  \"include\": [\"src\", \"test\", \".dolphy/ids.d.ts\"]",
+	"  \"include\": [\"src\", \"test\"]",
 	"}"
 ]);
-const manifestJson = (id) => `{
+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, the components on screen are redrawn. 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  # ${typecheckCommand(module)}`,
+	"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 (any build of the app",
+	"reads it, packaged or not; `dolphy-ext dev` relies on this)."
+]);
+const gitignore = () => lines(["node_modules", "dist-ext"]);
+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 typecheck\` — \`${typecheckCommand(module)}\`;`,
+	"- `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` holds the identity of the extension only (id, version,",
+	"  name, author, tags). Contributions are registered by code: `src/index.ts`",
+	"  exports `server` (`defineServer`, runs in the extension host) and/or",
+	"  `client` (`defineClient`, runs in the app window). `pnpm build` writes",
+	"  `main` and `client` into the built manifest; never edit `dist-ext/`.",
+	`- Write ids in the code, prefixed with the extension id (\`${id}\`): a`,
+	"  command, an exercise type, a setting, a panel. The host and the window",
+	"  refuse an id that is taken or does not carry the prefix.",
+	"- The server part (`server`) must not import `vue`, `vuetify` or any",
+	"  component. The client part (`client`) is components registered with",
+	"  `addPanel`, `addInjection`, `addAnswerView`, `addMarkdownRenderer`: a Vue",
+	"  component (`.vue` single-file components and `defineComponent` both work;",
+	"  `<v-btn>` and the other Vuetify components in a template need no import)",
+	"  or a `Mountable` (`defineMountable` from `@dolphy-app/extension-sdk`):",
+	"  an object with `mount(el, ctx)` that draws into `el` with any framework",
+	"  and returns the cleanup. The client part must not import `node:*`",
+	"  modules. The app gives the client code its own `vue` and `vuetify`:",
+	"  import them as usual, they stay out of the bundle. Any other framework",
+	"  is a bundled dependency of this extension and is switched on by",
+	"  `\"frameworks\": [\"react\"]` in `dolphy-ext.config.json` (React is the only",
+	"  one so far; `@dolphy-app/extension-sdk/react` has `reactComponent`).",
+	"  Keep both parts in separate files that `src/index.ts` re-exports, so the",
+	"  build of one never pulls in the other.",
+	"- A `<style>` of a single-file component goes into the whole window",
+	"  document as a `<style data-dolphy-ext>` tag: write `<style scoped>`.",
+	"  `<style module>` and `.vue` files in the server part are not supported.",
+	"- Before publishing replace `your-github-login` in the `author` field of",
+	"  `extension.json` with the GitHub login of the publisher.",
+	"- No `eval`, no `new Function`, no minified or obfuscated sources:",
+	"  `pnpm lint` and the catalog review flag them.",
+	"- Keep tests next to the behaviour: `createTestServer` from",
+	"  `@dolphy-app/extension-sdk/testing` starts `server` on in-memory fakes and",
+	"  runs commands, events, schedules, exercise types, importers and",
+	"  exporters; `createTestClient` records what `client` adds; mount a Vue",
+	"  component with `createApp` from `vue` in `happy-dom`, a `Mountable` with",
+	"  `mountForTest`.",
+	"",
+	"## 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$5 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
   "id": "${id}",
   "version": "${INITIAL_VERSION}",
   "apiVersion": 1,
-  "tags": ["learning"],
-  "contributes": {
-    "exerciseTypes": [
-      {
-        "id": "${id}",
-        "specSchema": {
-          "type": "object",
-          "required": ["expected"],
-          "additionalProperties": false,
-          "properties": {
-            "expected": { "type": "string", "minLength": 1 },
-            "ignoreCase": { "type": "boolean" }
-          }
-        },
-        "answerSchema": { "type": "string" }
-      }
-    ],
-    "settings": [
-      {
-        "id": "${id}.trim",
-        "type": "boolean",
-        "label": "Ignore spaces around the answer",
-        "default": true
+  "name": "Hello command",
+  "description": "A command-palette command that shows a notification.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+`;
+const indexTs$5 = (id) => `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: '${id}.hello',
+    title: { en: 'Say hello', ru: 'Поздороваться' },
+    run: () => notify('Hello from ${id}!'),
+  });
+});
+`;
+const indexTestTs$4 = (id) => `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: '${id}' });
+  expect(await running.commands.run('${id}.hello')).toEqual({
+    kind: 'notify',
+    text: 'Hello from ${id}!',
+  });
+  await running.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: identity only, the build adds `main`;",
+		"- `src/index.ts` — all the extension code: `server` (`defineServer`),",
+		"  which registers the command; the build writes it to `main.mjs`;",
+		"- `test/index.test.ts` — tests (`vitest`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$5(id),
+		"src/index.ts": indexTs$5(id),
+		"test/index.test.ts": indexTestTs$4(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/command-panel.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 panel",
+  "description": "Palette commands that greet the learner and open a small panel.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+`;
+const indexTs$4 = () => `export { client } from './client.ts';
+export { server } from './server.ts';
+`;
+const serverTs$2 = (id) => `import { defineServer, notify, openPanel } from '@dolphy-app/extension-sdk';
+
+// runs in the extension host: every call registers a contribution
+export const server = defineServer((s) => {
+  // palette command: shows a notification
+  s.registerCommand({
+    id: '${id}.hello',
+    title: { en: 'Say hello', ru: 'Поздороваться' },
+    category: 'Hello',
+    run: (args) => {
+      const name = typeof args === 'string' ? args : 'world';
+      return notify(\`Hello, \${name}!\`);
+    },
+  });
+
+  // palette command: opens the panel (registered by the client) with properties
+  s.registerCommand({
+    id: '${id}.open',
+    title: { en: 'Open the hello panel', ru: 'Открыть панель' },
+    category: 'Hello',
+    run: () => openPanel('${id}.view', { name: 'Dolphy' }),
+  });
+
+  // hidden from the palette (palette: false): the panel asks for data
+  s.registerCommand({
+    id: '${id}.data',
+    title: 'Hello panel data',
+    palette: false,
+    run: () => ({ message: 'Hello from ${id}' }),
+  });
+});
+`;
+const clientTs$2 = (id) => `import { defineClient } from '@dolphy-app/extension-sdk';
+import StatusPanel from './StatusPanel.vue';
+
+// runs in the app window: the panel is a Vue component the app draws
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: '${id}.view',
+    title: { en: 'Hello', ru: 'Привет' },
+    component: StatusPanel,
+  });
+});
+`;
+const statusPanelVue = (id) => `<script setup lang="ts">
+import { usePanel } from '@dolphy-app/extension-sdk/client';
+import { computed, ref } from 'vue';
+
+// \`usePanel()\` gives the panel the properties it was opened with and \`call\`
+// for the commands of the extension
+const panel = usePanel();
+const message = ref('');
+// the app opens the panel again with new properties: \`panel.props\` is
+// reactive, the title follows it
+const name = computed(() => {
+  const { props } = panel;
+  return typeof props === 'object' && props !== null && 'name' in props
+    ? String(props.name)
+    : 'world';
+});
+
+const load = async () => {
+  const data = await panel.call('${id}.data');
+  message.value = (data as { message: string }).message;
+};
+void load();
+<\/script>
+
+<template>
+  <section class="status-panel">
+    <h2>Hello, {{ name }}!</h2>
+    <p>{{ message }}</p>
+    <v-btn color="primary" @click="load">Reload</v-btn>
+  </section>
+</template>
+
+<style scoped>
+.status-panel {
+  padding: 16px;
+}
+</style>
+`;
+const vitestConfigTs = () => `import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({ plugins: [vue()] });
+`;
+/** The tests of the server part: the same for every template with these commands. */
+const serverTestsTs = (id) => `const start = async () => {
+  const running = await createTestServer(server, { extensionId: '${id}' });
+  disposables.push(running);
+  return running;
+};
+
+describe('${id}: server', () => {
+  it('hello greets the name from the arguments, "world" without them', async () => {
+    const running = await start();
+    expect(await running.commands.run('${id}.hello', 'Ada')).toEqual({
+      kind: 'notify',
+      text: 'Hello, Ada!',
+    });
+    expect(await running.commands.run('${id}.hello')).toEqual({
+      kind: 'notify',
+      text: 'Hello, world!',
+    });
+  });
+
+  it('open asks the app to open the panel with properties', async () => {
+    const running = await start();
+    expect(await running.commands.run('${id}.open')).toEqual({
+      kind: 'openPanel',
+      panelId: '${id}.view',
+      props: { name: 'Dolphy' },
+    });
+  });
+
+  it('data returns what the panel shows and stays out of the palette', async () => {
+    const running = await start();
+    expect(await running.commands.run('${id}.data')).toEqual({
+      kind: 'data',
+      value: { message: 'Hello from ${id}' },
+    });
+    const hidden = running.registration.commands.find(
+      (command) => command.id === '${id}.data',
+    );
+    expect(hidden?.palette).toBe(false);
+  });
+});`;
+const indexTestTs$3 = (id) => `// @vitest-environment happy-dom
+import { PANEL_HANDLE_KEY } from '@dolphy-app/extension-sdk';
+import type { JsonValue, PanelHandle } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createApp, defineComponent, h, nextTick, shallowReactive } from 'vue';
+import { client, server } from '../src/index.ts';
+import StatusPanel from '../src/StatusPanel.vue';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+${serverTestsTs(id)}
+
+describe('${id}: client', () => {
+  it('adds the panel that the open command points to', async () => {
+    const running = await createTestClient(client, { extensionId: '${id}' });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual(['${id}.view']);
+    expect(running.panels[0]?.component).toBe(StatusPanel);
+  });
+});
+
+// the app draws \`<v-btn>\` with its Vuetify; the test gives the panel a plain button
+const VBtn = defineComponent({
+  setup: (_props, { slots }) => () => h('button', slots['default']?.()),
+});
+
+// draws the panel the way the app does: the handle is provided to the component
+const mountPanel = async (
+  props: JsonValue | undefined,
+  call: PanelHandle['call'],
+) => {
+  const handle = shallowReactive({
+    panelId: '${id}.view',
+    props,
+    context: { courseId: null },
+    call,
+  });
+  const host = document.createElement('div');
+  document.body.append(host);
+  const app = createApp({ render: () => h(StatusPanel) });
+  app.component('v-btn', VBtn);
+  app.provide(PANEL_HANDLE_KEY, handle);
+  app.mount(host);
+  disposables.push({
+    dispose: () => {
+      app.unmount();
+      host.remove();
+    },
+  });
+  // the panel asks a command: wait for the reply, then for the redraw
+  const settle = async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await nextTick();
+  };
+  await settle();
+  return {
+    host,
+    reopen: async (next: JsonValue) => {
+      handle.props = next;
+      await settle();
+    },
+  };
+};
+
+describe('${id}: panel', () => {
+  it('shows the data command reply and follows new properties', async () => {
+    const calls: string[] = [];
+    const panel = await mountPanel({ name: 'Ada' }, async (commandId) => {
+      calls.push(commandId);
+      return { message: 'Hello from the test' };
+    });
+    expect(panel.host.querySelector('h2')?.textContent).toBe('Hello, Ada!');
+    expect(panel.host.querySelector('p')?.textContent).toBe(
+      'Hello from the test',
+    );
+    expect(calls).toEqual(['${id}.data']);
+
+    await panel.reopen({ name: 'Grace' });
+    expect(panel.host.querySelector('h2')?.textContent).toBe('Hello, Grace!');
+  });
+
+  it('asks the data command again when the button is pressed', async () => {
+    const calls: string[] = [];
+    const panel = await mountPanel(undefined, async (commandId) => {
+      calls.push(commandId);
+      return { message: 'x' };
+    });
+    panel.host.querySelector('button')?.click();
+    await panel.reopen({});
+    expect(calls).toEqual(['${id}.data', '${id}.data']);
+  });
+
+  it('greets the world when it is opened without properties', async () => {
+    const panel = await mountPanel(undefined, async () => ({ message: 'x' }));
+    expect(panel.host.querySelector('h2')?.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: identity only, the build adds `main` and",
+		"  `client`;",
+		"- `src/server.ts` — `server` (`defineServer`): the command handlers; the",
+		"  build writes it to `main.mjs`;",
+		"- `src/client.ts` — `client` (`defineClient`): registers the panel with",
+		"  `addPanel`; `src/StatusPanel.vue` is the single-file Vue component the",
+		"  app draws; the build writes them to `client.mjs`;",
+		"- `vitest.config.ts` — `@vitejs/plugin-vue`, so a test can import `.vue`;",
+		"- `src/index.ts` — re-exports `server` and `client`;",
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$4(id),
+		"src/index.ts": indexTs$4(),
+		"src/server.ts": serverTs$2(id),
+		"src/client.ts": clientTs$2(id),
+		"src/StatusPanel.vue": statusPanelVue(id),
+		"vitest.config.ts": vitestConfigTs(),
+		"test/index.test.ts": indexTestTs$3(id)
+	}),
+	devDependencies: {
+		"@vitejs/plugin-vue": "^6.0.7",
+		"vue-tsc": "^3.3.3"
+	},
+	typecheck: "vue-tsc --noEmit"
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/events.ts
+const manifestJson$3 = (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",
+  "tags": ["learning"]
+}
+`;
+const indexTs$3 = () => `export { client } from './client.ts';
+export { server } from './server.ts';
+`;
+const streakTs = () => `// a \`type\`, not an \`interface\`: an interface has no index signature and is
+// not JSON for \`server.storage\`
+export type Streak = {
+  days: number;
+  last: string;
+};
+
+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 };
+};
+`;
+const serverTs$1 = (id) => `import { defineServer, notify, openPanel } from '@dolphy-app/extension-sdk';
+import { advance } from './streak.ts';
+import type { Streak } from './streak.ts';
+
+const KEY = 'streak';
+
+// runs in the extension host: every call registers a contribution
+export const server = defineServer((s) => {
+  // delivered asynchronously, once per recorded attempt
+  s.on('attempt.closed', async ({ at, outcome }) => {
+    if (outcome === 'gave-up') return;
+    const streak = await s.storage.get<Streak>(KEY);
+    await s.storage.set(KEY, advance(streak, at));
+  });
+
+  // data for the panel: hidden from the palette, the panel calls it
+  s.registerCommand({
+    id: '${id}.data',
+    title: 'Streak data',
+    palette: false,
+    run: async () =>
+      (await s.storage.get<Streak>(KEY)) ?? { days: 0, last: '' },
+  });
+
+  s.registerCommand({
+    id: '${id}.show',
+    title: { en: 'Show the streak', ru: 'Показать серию' },
+    category: 'Streak',
+    run: async () => {
+      const streak = await s.storage.get<Streak>(KEY);
+      if (streak === undefined) {
+        return notify('No streak yet: finish your first exercise.');
       }
-    ],
-    "commands": [
-      { "id": "${id}.status", "title": "Show how answers are compared" }
-    ]
-  }
+      return openPanel('${id}.view', { days: streak.days });
+    },
+  });
+});
+`;
+const clientTs$1 = (id) => `import { defineClient } from '@dolphy-app/extension-sdk';
+import { StreakPanel } from './streak-panel.ts';
+
+// runs in the app window: the panel is a Vue component the app draws
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: '${id}.view',
+    title: { en: 'Streak', ru: 'Серия' },
+    component: StreakPanel,
+  });
+});
+`;
+const streakPanelTs = (id) => `import { usePanel } from '@dolphy-app/extension-sdk/client';
+import { defineComponent, h, ref, watchEffect } from 'vue';
+import type { Streak } from './streak.ts';
+
+// the only way to the data is \`panel.call\` to the commands of the server
+export const StreakPanel = defineComponent({
+  setup() {
+    const panel = usePanel();
+    const text = ref('');
+    // the command opens the panel again with new properties: ask again
+    watchEffect(async () => {
+      void panel.props;
+      const streak = (await panel.call('${id}.data')) as Streak;
+      text.value =
+        streak.days === 0
+          ? 'No streak yet.'
+          : \`Streak: \${streak.days} days, last day \${streak.last}\`;
+    });
+    return () => h('p', text.value);
+  },
+});
+`;
+const indexTestTs$2 = (id) => `// @vitest-environment happy-dom
+import { PANEL_HANDLE_KEY } from '@dolphy-app/extension-sdk';
+import type {
+  JsonValue,
+  LearningEventPayloads,
+  PanelHandle,
+} from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createApp, h, nextTick, shallowReactive } from 'vue';
+import { client, server } from '../src/index.ts';
+import { StreakPanel } from '../src/streak-panel.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 start = async () => {
+  const running = await createTestServer(server, { extensionId: '${id}' });
+  disposables.push(running);
+  return running;
+};
+
+// draws the panel the way the app does: the handle is provided to the component
+const mountPanel = async (call: PanelHandle['call']) => {
+  const handle = shallowReactive({
+    panelId: '${id}.view',
+    props: undefined as JsonValue | undefined,
+    context: { courseId: null },
+    call,
+  });
+  const host = document.createElement('div');
+  document.body.append(host);
+  const app = createApp({ render: () => h(StreakPanel) });
+  app.provide(PANEL_HANDLE_KEY, handle);
+  app.mount(host);
+  disposables.push({
+    dispose: () => {
+      app.unmount();
+      host.remove();
+    },
+  });
+  // the panel asks a command: wait for the reply, then for the redraw
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+  return host;
+};
+
+describe('${id}: events and storage', () => {
+  it('subscribes to attempt.closed', async () => {
+    const running = await start();
+    expect(running.registration.events).toEqual(['attempt.closed']);
+  });
+
+  it('counts consecutive days, ignores a repeat on the same day', async () => {
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-02'));
+    expect(await running.storage.get('streak')).toEqual({
+      days: 2,
+      last: '2026-10-02',
+    });
+  });
+
+  it('a skipped day starts over; giving up leaves the streak alone', async () => {
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-02'));
+    await running.events.emit('attempt.closed', attempt('2026-10-03', 'gave-up'));
+    expect(await running.storage.get('streak')).toEqual({
+      days: 2,
+      last: '2026-10-02',
+    });
+    await running.events.emit('attempt.closed', attempt('2026-10-05'));
+    expect(await running.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 running = await start();
+    expect(await running.commands.run('${id}.show')).toMatchObject({
+      kind: 'notify',
+    });
+    expect(await running.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 running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    expect(await running.commands.run('${id}.show')).toEqual({
+      kind: 'openPanel',
+      panelId: '${id}.view',
+      props: { days: 1 },
+    });
+  });
+
+  it('the client adds the panel the show command opens', async () => {
+    const running = await createTestClient(client, { extensionId: '${id}' });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual(['${id}.view']);
+  });
+
+  it('the panel shows what the data command returns', async () => {
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    const panel = await mountPanel(async (commandId) => {
+      const result = await running.commands.run(commandId);
+      return result.kind === 'data' ? (result.value as JsonValue) : undefined;
+    });
+    expect(panel.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 `server.storage`, and shows it with a command and a panel."],
+	layout: [
+		"- `extension.json` — the manifest: identity only, the build adds `main` and",
+		"  `client`;",
+		"- `src/server.ts` — `server` (`defineServer`): the event handler, the",
+		"  commands, `server.storage`; `src/streak.ts` is the streak arithmetic; the",
+		"  build writes them to `main.mjs`;",
+		"- `src/client.ts` — `client` (`defineClient`): registers the panel with",
+		"  `addPanel`; `src/streak-panel.ts` is the Vue component the app draws; the",
+		"  build writes them to `client.mjs`;",
+		"- `src/index.ts` — re-exports `server` and `client`;",
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$3(id),
+		"src/index.ts": indexTs$3(),
+		"src/streak.ts": streakTs(),
+		"src/server.ts": serverTs$1(id),
+		"src/client.ts": clientTs$1(id),
+		"src/streak-panel.ts": streakPanelTs(id),
+		"test/index.test.ts": indexTestTs$2(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/exercise.ts
+const manifestJson$2 = (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"]
 }
 `;
-const indexTs = (id) => `import {
-  defineAnswerView,
+const indexTs$2 = () => `export { client } from './client.ts';
+export { server } from './server.ts';
+`;
+const serverTs = (id) => `import {
   defineExerciseType,
-  defineExtension,
-  inActivate,
+  defineServer,
   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 };
+// runs in the extension host: every call registers a contribution
+export const server = defineServer((s) => {
+  s.registerSettings([
+    {
+      id: '${id}.trim',
+      type: 'boolean',
+      label: { en: 'Ignore spaces around the answer', ru: 'Игнорировать пробелы вокруг ответа' },
+      default: true,
+    },
+  ]);
 
-const matches = (answer: string, spec: Spec): boolean => {
-  const given = options.trim ? answer.trim() : answer;
-  if (spec.ignoreCase === true) {
-    return given.toLowerCase() === spec.expected.toLowerCase();
-  }
-  return given === spec.expected;
-};
+  // read when the handler runs, so a change in the settings applies at once
+  const trims = (): boolean => s.settings.get('${id}.trim') === true;
 
-// 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>>({
+  const matches = (answer: string, spec: Spec): boolean => {
+    const given = trims() ? answer.trim() : answer;
+    if (spec.ignoreCase === true) {
+      return given.toLowerCase() === spec.expected.toLowerCase();
+    }
+    return given === spec.expected;
+  };
+
+  // the app checks \`spec\` and the answer against the schemas before the
+  // handlers run
+  s.registerExerciseType(
+    defineExerciseType<Spec, string, Record<string, never>>({
+      id: '${id}',
+      title: 'Text match',
+      specSchema: {
+        type: 'object',
+        required: ['expected'],
+        additionalProperties: false,
+        properties: {
+          expected: { type: 'string', minLength: 1 },
+          ignoreCase: { type: 'boolean' },
+        },
+      },
+      answerSchema: { type: 'string' },
       project: () => ({}),
       grade: ({ spec, answer }) =>
         matches(answer, spec)
@@ -156,77 +1122,88 @@ export const host = defineExtension({
           : { outcome: 'failed', reason: 'mismatch' },
       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', () =>
+  );
+
+  s.registerCommand({
+    id: '${id}.status',
+    title: { en: 'Show how answers are compared', ru: 'Показать способ сравнения' },
+    run: () =>
       notify(
-        options.trim
+        trims()
           ? 'Answers are compared without the spaces around them.'
           : 'Answers are compared exactly as typed.',
       ),
-    );
-  },
+  });
 });
+`;
+const clientTs = (id) => `import { defineClient } from '@dolphy-app/extension-sdk';
+import { TextAnswer } from './text-answer.ts';
 
-// 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);
+// runs in the app window: the answer view is a Vue component for the exercise
+// type that \`server\` registers
+export const client = defineClient((c) => {
+  c.addAnswerView('${id}', TextAnswer);
+});
+`;
+const textAnswerTs = () => `import type { AnswerChange } from '@dolphy-app/extension-sdk';
+import { defineComponent, h, ref, watch } from 'vue';
+import type { PropType } from 'vue';
 
-    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);
-        }
+// the answer input: a Vue component the app draws in its own window tree. It
+// takes the props of \`AnswerViewProps\` and reports the answer with \`change\`;
+// \`submit\` asks the app to check it
+export const TextAnswer = defineComponent({
+  props: {
+    view: { type: null },
+    value: { type: null },
+    disabled: Boolean,
+    verdict: { type: null },
+    label: { type: String as PropType<string | null>, default: null },
+  },
+  emits: ['change', 'submit'],
+  setup(props, { emit }) {
+    const asText = (value: unknown): string =>
+      typeof value === 'string' ? value : '';
+    // what is typed stays on screen even if the app never returns \`value\`
+    const text = ref(asText(props.value));
+    watch(
+      () => props.value,
+      (value) => {
+        text.value = asText(value);
       },
-    };
-  }),
-} satisfies ExtensionViews;
+    );
+    return () =>
+      h('input', {
+        type: 'text',
+        spellcheck: false,
+        value: text.value,
+        disabled: props.disabled,
+        'aria-label': props.label ?? undefined,
+        onInput: (event: Event) => {
+          text.value = (event.target as HTMLInputElement).value;
+          const change: AnswerChange<string> = {
+            value: text.value,
+            complete: text.value.trim().length > 0,
+          };
+          emit('change', change);
+        },
+        onKeydown: (event: KeyboardEvent) => {
+          if (event.key === 'Enter') emit('submit');
+        },
+      });
+  },
+});
 `;
-const indexTestTs = (id) => `// @vitest-environment happy-dom
-import type { SettingContribution } from '@dolphy-app/extension-sdk';
+const indexTestTs$1 = (id) => `// @vitest-environment happy-dom
 import {
-  createMemorySettings,
   createSchemaValidator,
-  loadCommands,
-  loadExerciseType,
-  loadView,
+  createTestClient,
+  createTestServer,
 } from '@dolphy-app/extension-sdk/testing';
 import { afterEach, describe, expect, it } from 'vitest';
-import manifest from '../extension.json';
-import { host, views } from '../src/index.ts';
-
-const [contribution] = manifest.contributes.exerciseTypes;
-const validateSpec = createSchemaValidator(contribution.specSchema);
-const validateAnswer = createSchemaValidator(contribution.answerSchema);
+import { createApp, h, nextTick, reactive } from 'vue';
+import { client, server } from '../src/index.ts';
+import { TextAnswer } from '../src/text-answer.ts';
 
 const spec = { expected: 'Hello' };
 
@@ -235,31 +1212,66 @@ afterEach(async () => {
   await Promise.all(disposables.splice(0).map((item) => item.dispose()));
 });
 
-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;
+const start = async (settingValues = {}) => {
+  const running = await createTestServer(server, {
+    extensionId: '${id}',
+    settingValues,
+  });
+  disposables.push(running);
+  return running;
 };
 
+// mounts the answer view the way the app does: the props of \`AnswerViewProps\`
+// in, the \`change\` and \`submit\` events out
 const mount = async (label?: string) => {
-  const view = await loadView(views, '${id}', label === undefined ? {} : { label });
-  disposables.push(view);
-  const input = view.query<HTMLInputElement>('input');
+  const props = reactive<Record<string, unknown>>({
+    view: {},
+    value: undefined,
+    disabled: false,
+    verdict: null,
+    label: label ?? null,
+  });
+  const changes: unknown[] = [];
+  let submissions = 0;
+  const host = document.createElement('div');
+  document.body.append(host);
+  const app = createApp({
+    render: () =>
+      h(TextAnswer, {
+        ...props,
+        onChange: (change: unknown) => changes.push(change),
+        onSubmit: () => (submissions += 1),
+      }),
+  });
+  app.mount(host);
+  disposables.push({
+    dispose: () => {
+      app.unmount();
+      host.remove();
+    },
+  });
+  await nextTick();
+  const input = host.querySelector('input');
   if (input === null) throw new Error('no input');
-  return { view, input };
+  return {
+    input,
+    changes,
+    submissions: () => submissions,
+    update: async (next: Record<string, unknown>) => {
+      Object.assign(props, next);
+      await nextTick();
+    },
+  };
 };
 
 describe('${id}: handler', () => {
   it('project does not reveal the reference', async () => {
-    const type = await load();
+    const type = (await start()).exerciseType('${id}');
     expect(await type.project(spec)).toEqual({});
   });
 
   it('grade: a match passes, a mismatch does not', async () => {
-    const type = await load();
+    const type = (await start()).exerciseType('${id}');
     expect(await type.grade({ spec, answer: 'Hello' })).toEqual({
       outcome: 'passed',
     });
@@ -270,7 +1282,7 @@ describe('${id}: handler', () => {
   });
 
   it('grade: ignoreCase turns case sensitivity off', async () => {
-    const type = await load();
+    const type = (await start()).exerciseType('${id}');
     const relaxed = { ...spec, ignoreCase: true };
     expect(await type.grade({ spec: relaxed, answer: 'hELLO' })).toEqual({
       outcome: 'passed',
@@ -278,7 +1290,7 @@ describe('${id}: handler', () => {
   });
 
   it('referenceAnswer passes the check itself', async () => {
-    const type = await load();
+    const type = (await start()).exerciseType('${id}');
     const reference = await type.referenceAnswer(spec);
     expect(reference).toEqual({ found: true, answer: 'Hello' });
     if (!reference.found) throw new Error('reference expected');
@@ -290,12 +1302,12 @@ describe('${id}: handler', () => {
 
 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);
+    const running = await start();
+    const type = running.exerciseType('${id}');
     expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
       outcome: 'passed',
     });
-    await settings.set('${id}.trim', false);
+    await running.settings.set('${id}.trim', false);
     expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
       outcome: 'failed',
       reason: 'mismatch',
@@ -303,29 +1315,40 @@ describe('${id}: settings and commands', () => {
   });
 
   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({
+    const running = await start();
+    expect(await running.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({
+    await running.settings.set('${id}.trim', false);
+    expect(await running.commands.run('${id}.status')).toEqual({
       kind: 'notify',
       text: 'Answers are compared exactly as typed.',
     });
   });
+
+  it('a user value of the setting replaces the default', async () => {
+    const running = await start({ '${id}.trim': false });
+    expect(await running.commands.run('${id}.status')).toMatchObject({
+      text: 'Answers are compared exactly as typed.',
+    });
+  });
 });
 
 describe('${id}: schemas', () => {
+  const registered = async () => {
+    const [type] = (await start()).registration.exerciseTypes;
+    if (type === undefined) throw new Error('exercise type expected');
+    return {
+      validateSpec: createSchemaValidator(type.specSchema),
+      validateAnswer: createSchemaValidator(type.answerSchema),
+    };
+  };
+
   it.each([[{ expected: 'a' }], [{ expected: 'a', ignoreCase: true }]])(
     'spec %j is valid',
-    (value) => {
-      expect(validateSpec(value)).toEqual([]);
+    async (value) => {
+      expect((await registered()).validateSpec(value)).toEqual([]);
     },
   );
 
@@ -334,120 +1357,395 @@ describe('${id}: schemas', () => {
     ['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([]);
+  ])('spec: %s is rejected', async (_name, value) => {
+    expect((await registered()).validateSpec(value)).not.toEqual([]);
   });
 
-  it('answer: a string is valid, a number is not', () => {
+  it('answer: a string is valid, a number is not', async () => {
+    const { validateAnswer } = await registered();
     expect(validateAnswer('text')).toEqual([]);
     expect(validateAnswer(42)).not.toEqual([]);
   });
 });
 
+describe('${id}: client', () => {
+  it('adds the answer view for the exercise type', async () => {
+    const running = await createTestClient(client, { extensionId: '${id}' });
+    disposables.push(running);
+    expect(running.answerViews.get('${id}')).toBe(TextAnswer);
+  });
+});
+
 describe('${id}: view', () => {
   it('typing reports the answer; an empty input is incomplete', async () => {
-    const { view, input } = await mount();
+    const { changes, input } = await mount();
     input.value = 'Hello';
     input.dispatchEvent(new Event('input'));
     input.value = '  ';
     input.dispatchEvent(new Event('input'));
-    expect(view.changes).toEqual([
+    expect(changes).toEqual([
       { value: 'Hello', complete: true },
       { value: '  ', complete: false },
     ]);
   });
 
   it('Enter submits the answer', async () => {
-    const { view, input } = await mount();
+    const { input, submissions } = await mount();
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
-    expect(view.submissions).toBe(1);
+    expect(submissions()).toBe(1);
   });
 
   it('disabled blocks the input', async () => {
-    const { view, input } = await mount();
-    await view.update({ disabled: true });
+    const { input, update } = await mount();
+    await update({ disabled: true });
     expect(input.disabled).toBe(true);
   });
 
   it('value restores the answer without events', async () => {
-    const { view, input } = await mount();
-    await view.update({ value: 'Hello' });
+    const { changes, input, update } = await mount();
+    await update({ value: 'Hello' });
     expect(input.value).toBe('Hello');
-    expect(view.changes).toEqual([]);
+    expect(changes).toEqual([]);
   });
 
-  it('the aria-label of the host goes to the input', async () => {
+  it('the label of the app becomes the aria-label of the input', async () => {
     const { input } = await mount('Your answer');
     expect(input.getAttribute('aria-label')).toBe('Your answer');
   });
 });
 `;
-const readme = (id) => lines([
-	`# ${id}`,
-	"",
-	"A Dolphy extension: the \"text match\" exercise type (the learner types a",
-	"string, it is compared with `spec.expected`), a setting and a command.",
-	"Generated by `create-dolphy-extension`.",
-	"",
-	"## 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`;",
-	"- `.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`;",
-	"- `test/index.test.ts` — tests (`vitest`, `happy-dom`).",
-	"",
-	"## 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 typecheck  # writes .dolphy/ids.d.ts, then tsc",
-	"pnpm test",
-	"```",
-	"",
-	"## Manual installation",
-	"",
-	`Copy the \`dist-ext/${id}\` directory to \`<userData>/extensions/\``,
-	"and restart the app. There is no installation from the app yet."
-]);
-const gitignore = () => lines([
-	"node_modules",
-	"dist-ext",
-	".dolphy"
-]);
+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: identity only, the build adds `main` and",
+		"  `client`;",
+		"- `src/server.ts` — `server` (`defineServer`): the exercise type with the",
+		"  `spec` and answer schemas, the setting and the command; the build writes",
+		"  it to `main.mjs`;",
+		"- `src/client.ts` — `client` (`defineClient`): adds the answer view with",
+		"  `addAnswerView`; `src/text-answer.ts` is the Vue component that is the",
+		"  answer input; the build writes them to `client.mjs`;",
+		"- `src/index.ts` — re-exports `server` and `client`;",
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$2(id),
+		"src/index.ts": indexTs$2(),
+		"src/server.ts": serverTs(id),
+		"src/client.ts": clientTs(id),
+		"src/text-answer.ts": textAnswerTs(),
+		"test/index.test.ts": indexTestTs$1(id)
+	})
+};
+
+//#endregion
+//#region packages/create-extension/src/templates/react-panel.ts
+const manifestJson$1 = (id) => `{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "name": "Hello React panel",
+  "description": "Palette commands that greet the learner and open a panel drawn with React.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+`;
+const configJson = () => `{
+  "frameworks": ["react"]
+}
+`;
+const indexTs$1 = () => `export { client } from './client.tsx';
+export { server } from './server.ts';
+`;
+const clientTsx = (id) => `import { defineClient } from '@dolphy-app/extension-sdk';
+import type { PanelHandle, PanelProps } from '@dolphy-app/extension-sdk';
+import { reactComponent, usePanel } from '@dolphy-app/extension-sdk/react';
+import { useEffect, useState } from 'react';
+
+// \`reactComponent\` draws this component with React and gives it the props of
+// the panel; \`usePanel()\` is the handle with \`call\` for the commands of the
+// extension
+const HelloPanel = ({ props }: PanelProps) => {
+  const panel = usePanel();
+  const [message, setMessage] = useState('');
+  // the app opens the panel again with new properties: the component renders again
+  const name =
+    typeof props === 'object' && props !== null && 'name' in props
+      ? String(props.name)
+      : 'world';
+
+  const load = async () => {
+    const data = await panel.call('${id}.data');
+    setMessage((data as { message: string }).message);
+  };
+  useEffect(() => {
+    void load();
+  }, []);
+
+  return (
+    <section>
+      <h2>Hello, {name}!</h2>
+      <p>{message}</p>
+      <button type="button" onClick={() => void load()}>
+        Reload
+      </button>
+    </section>
+  );
+};
+
+// runs in the app window: the panel is a \`Mountable\` the app draws into its own element
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: '${id}.view',
+    title: { en: 'Hello', ru: 'Привет' },
+    component: reactComponent<PanelProps, PanelHandle>(HelloPanel),
+  });
+});
+`;
+const indexTestTs = (id) => `// @vitest-environment happy-dom
+import { isMountable } from '@dolphy-app/extension-sdk';
+import type { PanelHandle, 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';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+${serverTestsTs(id)}
+
+describe('${id}: client', () => {
+  it('adds the panel that the open command points to', async () => {
+    const running = await createTestClient(client, { extensionId: '${id}' });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual(['${id}.view']);
+    expect(isMountable(running.panels[0]?.component)).toBe(true);
+  });
+});
+
+// draws the panel the way the app does: into an element, on a context the test controls
+const mountPanel = async (
+  props: PanelProps['props'],
+  call: PanelHandle['call'],
+) => {
+  const running = await createTestClient(client, { extensionId: '${id}' });
+  disposables.push(running);
+  const component = running.panels[0]?.component;
+  if (!isMountable(component)) throw new Error('the panel is not a Mountable');
+  const panelProps: PanelProps = {
+    panelId: '${id}.view',
+    props,
+    context: { courseId: null },
+  };
+  const mounted = await mountForTest(component, {
+    props: panelProps,
+    handle: { ...panelProps, call },
+  });
+  disposables.push({ dispose: () => mounted.unmount() });
+  return { mounted, panelProps };
+};
+
+describe('${id}: panel', () => {
+  it('shows the data command reply and follows new properties', async () => {
+    const calls: string[] = [];
+    const { mounted, panelProps } = await mountPanel(
+      { name: 'Ada' },
+      async (commandId) => {
+        calls.push(commandId);
+        return { message: 'Hello from the test' };
+      },
+    );
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Ada!');
+    await vi.waitFor(() =>
+      expect(mounted.el.querySelector('p')?.textContent).toBe(
+        'Hello from the test',
+      ),
+    );
+    expect(calls).toEqual(['${id}.data']);
+
+    mounted.setProps({ ...panelProps, props: { name: 'Grace' } });
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Grace!');
+  });
+
+  it('greets the world when it is opened without properties', async () => {
+    const { mounted } = await mountPanel(undefined, async () => ({
+      message: 'x',
+    }));
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, world!');
+  });
+
+  it('asks the data command again when the button is pressed', async () => {
+    const calls: string[] = [];
+    const { mounted } = await mountPanel(undefined, async (commandId) => {
+      calls.push(commandId);
+      return { message: 'x' };
+    });
+    mounted.el.querySelector('button')?.click();
+    await vi.waitFor(() => expect(calls).toEqual(['${id}.data', '${id}.data']));
+  });
+});
+`;
+const reactPanel = {
+	summary: ["A Dolphy extension: two commands in the command palette (Ctrl/⌘+K), a hidden", "data command and a panel drawn with React instead of Vue."],
+	layout: [
+		"- `extension.json` — the manifest: identity only, the build adds `main` and",
+		"  `client`;",
+		"- `dolphy-ext.config.json` — `\"frameworks\": [\"react\"]` switches the React",
+		"  build on (`.tsx` files, `react` and `react-dom` go into `client.mjs`);",
+		"- `src/server.ts` — `server` (`defineServer`): the command handlers; the",
+		"  build writes it to `main.mjs`;",
+		"- `src/client.tsx` — `client` (`defineClient`): registers the panel with",
+		"  `addPanel`; `reactComponent` from `@dolphy-app/extension-sdk/react` turns",
+		"  the React component into what the app draws; the build writes it to",
+		"  `client.mjs`;",
+		"- `src/index.ts` — re-exports `server` and `client`;",
+		"- `test/index.test.ts` — tests (`vitest`, `happy-dom`, `mountForTest`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson$1(id),
+		"dolphy-ext.config.json": configJson(),
+		"src/index.ts": indexTs$1(),
+		"src/server.ts": serverTs$2(id),
+		"src/client.tsx": clientTsx(id),
+		"test/index.test.ts": indexTestTs(id)
+	}),
+	devDependencies: {
+		"@types/react": "^19.3.0",
+		"@types/react-dom": "^19.3.0",
+		react: "^19.3.0",
+		"react-dom": "^19.3.0"
+	},
+	compilerOptions: { jsx: "\"react-jsx\"" }
+};
+
+//#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"]
+}
+`;
+const themeTs = (id) => `import type { ThemeRegistration } from '@dolphy-app/extension-sdk';
+
+// the allowed color and variable keys are \`THEME_COLOR_KEYS\` and
+// \`THEME_VARIABLE_KEYS\` of '@dolphy-app/extension-sdk'
+export const midnight: ThemeRegistration = {
+  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 indexTs = () => `import { defineClient } from '@dolphy-app/extension-sdk';
+import { midnight } from './theme.ts';
+
+// runs in the app window: a theme is data, there is no server part
+export const client = defineClient((c) => {
+  c.addTheme(midnight);
+});
+`;
+const themeTestTs = (id) => `import { createTestClient } from '@dolphy-app/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { client } from '../src/index.ts';
+import { midnight } from '../src/theme.ts';
+
+const colors = midnight.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('the client adds the theme', async () => {
+    const running = await createTestClient(client, { extensionId: '${id}' });
+    expect(running.themes).toEqual([midnight]);
+    await running.dispose();
+  });
+
+  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(midnight.dark ? background < text : background > text).toBe(true);
+  });
+});
+`;
+const theme = {
+	summary: ["A Dolphy extension: a color theme (\"Midnight\"). A theme is data the client", "part registers with `addTheme`; the test checks the text contrast."],
+	layout: [
+		"- `extension.json` — the manifest: identity only, the build adds `client`;",
+		"- `src/theme.ts` — the theme: `colors` (the allowed keys are listed in the",
+		"  Dolphy extension guide) and `variables`;",
+		"- `src/index.ts` — `client` (`defineClient`), which adds the theme; the",
+		"  build writes it to `client.mjs`; there is no server part;",
+		"- `test/theme.test.ts` — checks the registration and the contrast of the",
+		"  text colors (`vitest`)."
+	],
+	files: (id) => ({
+		"extension.json": manifestJson(id),
+		"src/theme.ts": themeTs(id),
+		"src/index.ts": indexTs(),
+		"test/theme.test.ts": themeTestTs(id)
+	})
+};
 
 //#endregion
 //#region packages/create-extension/src/generate.ts
+const TEMPLATES = {
+	exercise,
+	theme,
+	"command-panel": commandPanel,
+	"react-panel": reactPanel,
+	events,
+	blank
+};
+const isTemplateName = (name) => TEMPLATE_NAMES.includes(name);
 /** Matches the manifest limit (`parseManifest`). */
 const MAX_ID_CHARS = 64;
 /** Without a build (sources, `--local`) the package version is a placeholder. */
 const UNPUBLISHED_VERSION = "^0.0.0";
-const builtPackageVersion = () => "0.3.0";
+const builtPackageVersion = () => "0.5.0";
 var GenerateError = class extends Error {
 	code;
 	constructor(code, message) {
@@ -470,6 +1768,7 @@ const dependencySpecs = async (localRoot, packageVersion) => {
 		const range = packageVersion === null ? UNPUBLISHED_VERSION : `^${packageVersion}`;
 		return {
 			dependencies: {
+				api: range,
 				sdk: range,
 				tools: range
 			},
@@ -477,11 +1776,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}`
 		},
@@ -495,25 +1800,30 @@ const assertEmpty = async (dir) => {
 };
 /** Project files: relative path → content. */
 const renderProject = (input) => {
-	const { id } = input;
-	return /* @__PURE__ */ new Map([
-		["package.json", packageJson(input)],
-		["tsconfig.json", tsconfigJson()],
-		["extension.json", manifestJson(id)],
-		["src/index.ts", indexTs(id)],
-		["test/index.test.ts", indexTestTs(id)],
-		["README.md", readme(id)],
-		[".gitignore", gitignore()]
+	const { id, template = DEFAULT_TEMPLATE } = input;
+	const module = TEMPLATES[template];
+	return new Map([
+		["package.json", packageJson(input, module)],
+		["tsconfig.json", tsconfigJson(module)],
+		...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) {
@@ -535,10 +1845,12 @@ 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>              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,
+                     react-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
@@ -549,7 +1861,7 @@ 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} requires a value` };
 			values.set(arg, value);
@@ -562,7 +1874,8 @@ const parseArgs = (argv) => {
 	return {
 		dir,
 		id: values.get("--id"),
-		local: values.get("--local")
+		local: values.get("--local"),
+		template: values.get("--template")
 	};
 };
 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";
@@ -600,6 +1913,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`);