@dolphy-app/create-extension 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Extension project generator: create-dolphy-extension <directory>
 
-The package version equals the version of the Dolphy app release it was published from (0.3.0).
+The package version equals the version of the Dolphy app release it was published from (0.4.0).
 
 Generator of an extension project: `src/index.ts` with the host and a
 view, a manifest, tests, and typed ids (`.dolphy/ids.d.ts`, generated from

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/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-]*)*$/;
+/** 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. */
@@ -22,6 +146,31 @@ const EXTENSION_COMMAND_LIMITS = Object.freeze({
 	/** 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. */
@@ -33,26 +182,62 @@ 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 `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
+//#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",
-		types: "dolphy-ext types",
-		typecheck: "dolphy-ext types && tsc",
-		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",
@@ -80,10 +265,626 @@ const tsconfigJson = () => lines([
 	"  \"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": [
@@ -382,72 +1183,123 @@ describe('${id}: view', () => {
   });
 });
 `;
-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 (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)
+	})
+};
 
 //#endregion
 //#region packages/create-extension/src/generate.ts
+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;
 /** 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.4.0";
 var GenerateError = class extends Error {
 	code;
 	constructor(code, message) {
@@ -470,6 +1322,7 @@ const dependencySpecs = async (localRoot, packageVersion) => {
 		const range = packageVersion === null ? UNPUBLISHED_VERSION : `^${packageVersion}`;
 		return {
 			dependencies: {
+				api: range,
 				sdk: range,
 				tools: range
 			},
@@ -477,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}`
 		},
@@ -495,25 +1354,30 @@ const assertEmpty = async (dir) => {
 };
 /** 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/index.ts", indexTs(id)],
-		["test/index.test.ts", indexTestTs(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) {
@@ -535,10 +1399,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,
+                     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 +1415,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 +1428,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 +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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolphy-app/create-extension",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Extension project generator: create-dolphy-extension <directory>",
   "type": "module",
   "bin": {