@dolphy-app/extension-sdk 0.4.0 → 0.5.0

package/dist/testing.js

@@ -1,7 +1,94 @@
-import { t as createAnswerElementClass } from "./answer-element-BOQcuxYh.js";
-import { ANSWER_EVENT, COLOR_SETTING_PATTERN, EXTENSION_COMMAND_LIMITS, EXTENSION_NOTIFICATION_LIMITS, EXTENSION_SECRET_LIMITS, EXTENSION_STATS_LIMITS, EXTENSION_STORAGE_LIMITS, EXTENSION_TRANSFER_LIMITS, InvalidCommandResultError, InvalidTransferResultError, NotificationRateLimitError, PermissionError, SETTING_LIMITS, SecretsUnavailableError, StorageQuotaError, normalizeCommandResult, normalizeExportResult, normalizeImportResult } from "@dolphy-app/extension-api";
+import { callRpc } from "./rpc.js";
+import { COLOR_SETTING_PATTERN, DEFAULT_EXTENSION_ICON, EXTENSION_COMMAND_LIMITS, EXTENSION_HOOK_LIMITS, EXTENSION_HOOK_NAMES, EXTENSION_NOTIFICATION_LIMITS, EXTENSION_RPC_LIMITS, EXTENSION_SCHEDULE_LIMITS, EXTENSION_SECRET_LIMITS, EXTENSION_STATS_LIMITS, EXTENSION_STORAGE_LIMITS, EXTENSION_TRANSFER_LIMITS, INJECTION_LIMITS, INJECTION_POSITIONS, InvalidCommandResultError, InvalidTransferResultError, MARKDOWN_LANGUAGE_PATTERN, NotificationRateLimitError, RPC_NAME_PATTERN, SETTING_LIMITS, SecretsUnavailableError, StorageQuotaError, normalizeCommandResult, normalizeExportResult, normalizeImportResult } from "@dolphy-app/extension-api";
+import { z } from "zod";
 import { Ajv2020 } from "ajv/dist/2020.js";
 
+//#region packages/extension-api/src/hooks.ts
+/** Limits on hooks; the host and the engine check the same numbers. */
+const EXTENSION_HOOK_LIMITS$1 = 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/hook-schemas.ts
+/**
+* Request and response schemas of the hooks in `hooks.ts`. They live apart
+* from the names and types so that code which only registers or types a hook
+* (every browser bundle imports this package) does not pull `zod` in; the host,
+* the engine and the test server import them from
+* `@dolphy-app/extension-api/hook-schemas`.
+*/
+const itemReason = z.enum([
+	"review",
+	"new",
+	"remediation"
+]);
+/** `null` fields: the exercise has no attempts yet, so there is no memory state. */
+const exerciseMemory = z.object({
+	/** Probability of recall right now, 0..1. */
+	retrievability: z.number().nullable(),
+	/** Unix epoch milliseconds of the newest attempt. */
+	lastAttemptAt: z.number().nullable(),
+	/** Attempts that count (cancelled ones excluded). */
+	attempts: z.number(),
+	/** FSRS stability in days. */
+	stability: z.number().nullable(),
+	/** FSRS difficulty. */
+	difficulty: z.number().nullable()
+});
+/**
+* Request and response schema of every hook. The handlers of the extensions
+* that registered a hook run one after another in ascending order of the
+* extension id; each gets the response of the previous one (for a hook
+* without a response, the same request). A thrown error, an invalid
+* response or a handler exceeding `EXTENSION_HOOK_LIMITS.timeoutMs` cancels
+* the operation and the error message reaches the user.
+*/
+const EXTENSION_HOOKS = Object.freeze({
+	/**
+	* A learning session is about to start. The handler can only cancel the
+	* start by throwing.
+	*/
+	"session.start": {
+		request: z.object({ 
+		/** Unix epoch milliseconds. */
+now: z.number() }),
+		response: z.void()
+	},
+	/**
+	* A batch of exercises or a day plan is about to be handed to the learner.
+	* `exerciseIds` and `reasons` are parallel arrays; the response can
+	* reorder, remove and add exercises (every id must exist in the library;
+	* `exerciseIds` and `reasons` keep the same length, at most
+	* `EXTENSION_HOOK_LIMITS.maxExercises`).
+	*/
+	"practice.batch": {
+		request: z.object({
+			/** The open session; `null` while none has started. */
+			sessionId: z.string().nullable(),
+			/** `batch` — `practice.getBatch`, `plan` — `plan.getDay`. */
+			source: z.enum(["batch", "plan"]),
+			exerciseIds: z.array(z.string()),
+			reasons: z.array(itemReason),
+			/**
+			* Parallel to `exerciseIds`: what the engine remembers of each
+			* exercise. Read-only; the FSRS state is not changed by the hook.
+			*/
+			memory: z.array(exerciseMemory)
+		}),
+		response: z.object({
+			exerciseIds: z.array(z.string()).max(EXTENSION_HOOK_LIMITS$1.maxExercises),
+			reasons: z.array(itemReason).max(EXTENSION_HOOK_LIMITS$1.maxExercises)
+		}).refine(({ exerciseIds, reasons }) => exerciseIds.length === reasons.length, { message: "exerciseIds and reasons must have the same length" })
+	}
+});
+
+//#endregion
 //#region packages/extension-sdk/src/testing.ts
 const MAX_MESSAGES = 6;
 const MAX_REASON_CHARS = 100;
@@ -14,6 +101,10 @@ const silentLogger = {
 	warn: () => void 0,
 	error: () => void 0
 };
+/** What a test did not provide: every property read throws an error that names the option to pass. */
+const unprovided = (name, option) => new Proxy({}, { get: (_target, property) => {
+	throw new Error(`${name}.${String(property)} is not available: pass options.${option}`);
+} });
 const createMemoryLibrary = (files) => {
 	const entries = new Map(Object.entries(files));
 	return {
@@ -133,14 +224,18 @@ const findSettingProblem = (definition, value) => {
 		default: return typeof value === "string" && definition.options.some((option) => option.value === value) ? null : "must be one of the options";
 	}
 };
-/** In-memory settings from manifest definitions; `initial` provides user values in place of `default`. */
-const createMemorySettings = (definitions, initial = {}) => {
-	const byId = new Map(definitions.map((definition) => [definition.id, definition]));
-	const values = new Map(definitions.map((definition) => [definition.id, storedForm(definition, definition.default)]));
+/**
+* In-memory settings. `definitions` are registered at once, more come through
+* `register`; `initial` provides user values in place of `default`, applied
+* when the setting with that id is registered.
+*/
+const createMemorySettings = (definitions = [], initial = {}) => {
+	const byId = /* @__PURE__ */ new Map();
+	const values = /* @__PURE__ */ new Map();
 	const handlers = /* @__PURE__ */ new Set();
 	const known = (id) => {
 		const definition = byId.get(id);
-		if (definition === void 0) throw new Error(`setting '${id}' is not declared in the manifest`);
+		if (definition === void 0) throw new Error(`setting '${id}' is not registered`);
 		return definition;
 	};
 	const checked = (id, value) => {
@@ -148,8 +243,24 @@ const createMemorySettings = (definitions, initial = {}) => {
 		if (problem !== null) throw new Error(`setting '${id}' ${problem}`);
 		return storedForm(known(id), value);
 	};
-	for (const [id, value] of Object.entries(initial)) values.set(id, checked(id, value));
+	const register = (added) => {
+		for (const definition of added) {
+			if (byId.has(definition.id)) throw new Error(`setting '${definition.id}' is already registered`);
+			byId.set(definition.id, definition);
+			values.set(definition.id, storedForm(definition, definition.default));
+			const user = initial[definition.id];
+			if (user !== void 0) values.set(definition.id, checked(definition.id, user));
+		}
+		return { dispose: () => {
+			for (const definition of added) {
+				byId.delete(definition.id);
+				values.delete(definition.id);
+			}
+		} };
+	};
+	register(definitions);
 	return {
+		register,
 		get: (id) => storedForm(known(id), values.get(id)),
 		onDidChange(handler) {
 			handlers.add(handler);
@@ -166,141 +277,6 @@ const createMemorySettings = (definitions, initial = {}) => {
 		}
 	};
 };
-/** In-memory learning event subscriptions: one handler per event, as in the host. */
-const createMemoryEvents = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	return {
-		on(name, handler) {
-			if (options.permitted === false) throw new PermissionError("learning.events");
-			if (options.declared !== void 0 && !options.declared.includes(name)) throw new Error(`event '${name}' is not declared in the manifest`);
-			if (handlers.has(name)) throw new Error(`event '${name}' is already subscribed`);
-			handlers.set(name, handler);
-			return { dispose: () => {
-				if (handlers.get(name) === handler) handlers.delete(name);
-			} };
-		},
-		async emit(name, payload) {
-			await handlers.get(name)?.(payload);
-		}
-	};
-};
-/** In-memory commands: the same registration rules and result parsing as the host. */
-const createMemoryCommands = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	return {
-		register(id, handler) {
-			if (options.declaredCommands !== void 0 && !options.declaredCommands.includes(id)) throw new Error(`command '${id}' is not declared in the manifest`);
-			if (handlers.has(id)) throw new Error(`command '${id}' is already registered`);
-			handlers.set(id, handler);
-			return { dispose: () => {
-				if (handlers.get(id) === handler) handlers.delete(id);
-			} };
-		},
-		async run(id, args) {
-			const handler = handlers.get(id);
-			if (handler === void 0) throw new Error(`command '${id}' was not registered`);
-			if ((JSON.stringify(args)?.length ?? 0) > EXTENSION_COMMAND_LIMITS.argsChars) throw new Error(`args are longer than ${EXTENSION_COMMAND_LIMITS.argsChars} characters`);
-			const result = await handler(args);
-			try {
-				return normalizeCommandResult(result, options.declaredPanels);
-			} catch (error) {
-				if (error instanceof InvalidCommandResultError) throw new Error(`invalid command result: ${error.message}`);
-				throw error;
-			}
-		},
-		ids: () => [...handlers.keys()]
-	};
-};
-/** In-memory schedule subscriptions: one handler per schedule and no overlapping firings, as in the host. */
-const createMemorySchedule = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	const running = /* @__PURE__ */ new Set();
-	return {
-		on(id, handler) {
-			if (options.declared !== void 0 && !options.declared.includes(id)) throw new Error(`schedule '${id}' is not declared in the manifest`);
-			if (handlers.has(id)) throw new Error(`schedule '${id}' is already subscribed`);
-			handlers.set(id, handler);
-			return { dispose: () => {
-				if (handlers.get(id) === handler) handlers.delete(id);
-			} };
-		},
-		async fire(id) {
-			const handler = handlers.get(id);
-			if (handler === void 0 || running.has(id)) return false;
-			running.add(id);
-			try {
-				await handler();
-				return true;
-			} finally {
-				running.delete(id);
-			}
-		},
-		ids: () => [...handlers.keys()]
-	};
-};
-/** In-memory importers: the same registration rules and result checks as the host. */
-const createMemoryImporters = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	const declaredOf = (id) => options.declaredImporters?.find((entry) => entry.id === id);
-	return {
-		register(id, handler) {
-			if (options.declaredImporters !== void 0 && declaredOf(id) === void 0) throw new Error(`importer '${id}' is not declared in the manifest`);
-			if (handlers.has(id)) throw new Error(`importer '${id}' is already registered`);
-			handlers.set(id, handler);
-			return { dispose: () => {
-				if (handlers.get(id) === handler) handlers.delete(id);
-			} };
-		},
-		async run(id, input) {
-			const handler = handlers.get(id);
-			if (handler === void 0) throw new Error(`importer '${id}' was not registered`);
-			const expected = declaredOf(id)?.input ?? "text";
-			if (options.declaredImporters !== void 0 && ("text" in input ? "text" : "bytes") !== expected) throw new Error(`importer '${id}' takes ${expected} input`);
-			if (("text" in input ? new TextEncoder().encode(input.text).length : input.bytes.byteLength) > EXTENSION_TRANSFER_LIMITS.inputBytes) throw new Error(`the file is longer than ${EXTENSION_TRANSFER_LIMITS.inputBytes} bytes`);
-			const result = await handler(input);
-			try {
-				return normalizeImportResult(result);
-			} catch (error) {
-				if (error instanceof InvalidTransferResultError) throw new Error(`invalid import result: ${error.message}`);
-				throw error;
-			}
-		},
-		ids: () => [...handlers.keys()]
-	};
-};
-/** In-memory exporters: the same registration rules and result checks as the host. */
-const createMemoryExporters = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	const declaredOf = (id) => options.declaredExporters?.find((entry) => entry.id === id);
-	return {
-		register(id, handler) {
-			if (options.declaredExporters !== void 0 && declaredOf(id) === void 0) throw new Error(`exporter '${id}' is not declared in the manifest`);
-			if (handlers.has(id)) throw new Error(`exporter '${id}' is already registered`);
-			handlers.set(id, handler);
-			return { dispose: () => {
-				if (handlers.get(id) === handler) handlers.delete(id);
-			} };
-		},
-		async run(id, input) {
-			const handler = handlers.get(id);
-			if (handler === void 0) throw new Error(`exporter '${id}' was not registered`);
-			const declared = declaredOf(id);
-			if (declared !== void 0 && declared.scope !== input.scope) throw new Error(`exporter '${id}' takes the ${declared.scope} scope`);
-			if (input.scope === "course") {
-				const encoder = new TextEncoder();
-				if (Object.values(input.files).reduce((sum, text) => sum + encoder.encode(text).length, 0) > EXTENSION_TRANSFER_LIMITS.totalBytes) throw new Error(`the course files are longer than ${EXTENSION_TRANSFER_LIMITS.totalBytes} bytes`);
-			}
-			const result = await handler(input);
-			try {
-				return normalizeExportResult(result);
-			} catch (error) {
-				if (error instanceof InvalidTransferResultError) throw new Error(`invalid export result: ${error.message}`);
-				throw error;
-			}
-		},
-		ids: () => [...handlers.keys()]
-	};
-};
 const DAY_MS = 864e5;
 const STATS_CORRECT_GRADE_MIN = 3;
 const dayNumberOf = (year, month, day) => {
@@ -345,9 +321,6 @@ const createMemoryStats = (options = {}) => {
 		});
 	};
 	for (const attempt of options.attempts ?? []) record(attempt);
-	const guard = () => {
-		if (options.permitted === false) throw new PermissionError("learning.stats");
-	};
 	const countsOf = (courseId) => {
 		const days = /* @__PURE__ */ new Map();
 		for (const item of attempts) {
@@ -365,7 +338,6 @@ const createMemoryStats = (options = {}) => {
 	return {
 		record,
 		async streak(streakOptions) {
-			guard();
 			const days = countsOf(streakOptions?.courseId);
 			const today = localDay((options.now ?? Date.now)());
 			let longest = 0;
@@ -388,7 +360,6 @@ const createMemoryStats = (options = {}) => {
 			};
 		},
 		async daily({ from, to, courseId }) {
-			guard();
 			const first = parseDay("from", from);
 			const last = parseDay("to", to);
 			if (last < first || last - first + 1 > EXTENSION_STATS_LIMITS.dailyDays) throw new Error(`the range must be ascending and cover at most ${EXTENSION_STATS_LIMITS.dailyDays} dates`);
@@ -442,7 +413,6 @@ const createMemoryNotifications = (options = {}) => {
 			supported = value;
 		},
 		async show(notification) {
-			if (options.permitted === false) throw new PermissionError("notifications");
 			const title = notificationText("title", notification?.title, limits.titleLength);
 			const body = notificationText("body", notification?.body, limits.bodyLength);
 			if (!enabled) return false;
@@ -462,22 +432,6 @@ const createMemoryNotifications = (options = {}) => {
 		}
 	};
 };
-const contextOf = (options, registrars) => ({
-	extensionId: "test",
-	logger: options.logger ?? silentLogger,
-	library: options.library ?? createMemoryLibrary({}),
-	storage: options.storage ?? createMemoryStorage(),
-	secrets: options.secrets ?? createMemorySecrets(),
-	settings: options.settings ?? createMemorySettings([]),
-	events: options.events ?? createMemoryEvents(),
-	stats: options.stats ?? createMemoryStats(),
-	notifications: options.notifications ?? createMemoryNotifications(),
-	schedule: options.schedule ?? createMemorySchedule(),
-	commands: options.commands ?? createMemoryCommands(),
-	importers: options.importers ?? createMemoryImporters(),
-	exporters: options.exporters ?? createMemoryExporters(),
-	...registrars
-});
 const createSchemaValidator = (schema) => {
 	const validate = new Ajv2020({
 		allErrors: true,
@@ -531,344 +485,500 @@ const findGradeResultProblem = (result) => {
 	if (extra !== void 0) return `unexpected key '${extra}'`;
 	return (outcome === "passed" ? null : reasonProblem(result)) ?? textProblem(result, "feedback") ?? textProblem(result, "detail");
 };
-const loadExerciseType = async (module, type, options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	const context = contextOf(options, {
-		registerExerciseType: (registeredType, handler) => {
-			handlers.set(registeredType, handler);
-			return { dispose: () => void handlers.delete(registeredType) };
-		},
-		registerGradePolicy: () => ({ dispose: () => void 0 })
-	});
-	await module.activate(context);
-	const handler = handlers.get(type);
-	if (handler === void 0) throw new Error(`exercise type '${type}' was not registered`);
-	return {
-		project: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => handler.project({
-			exerciseId,
-			spec
-		}),
-		grade: async ({ spec, answer, exerciseId = DEFAULT_EXERCISE_ID, timeoutMs = DEFAULT_TIMEOUT_MS, authorMode = false }) => {
-			const result = await handler.grade({
-				exerciseId,
-				spec,
-				answer,
-				timeoutMs,
-				authorMode
-			});
-			const problem = findGradeResultProblem(result);
-			if (problem !== null) throw new Error(`invalid grade result: ${problem}`);
-			return result;
-		},
-		referenceAnswer: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => {
-			const answer = await handler.referenceAnswer?.({
-				exerciseId,
-				spec
-			});
-			return answer === void 0 ? { found: false } : {
-				found: true,
-				answer
-			};
-		},
-		dispose: async () => {
-			await module.deactivate?.();
-		}
+const isGradeValue = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 5;
+const registeredSettingOf = (definition) => {
+	const base = {
+		id: definition.id,
+		label: definition.label,
+		description: definition.description ?? null,
+		group: definition.group ?? null,
+		order: definition.order ?? 0,
+		visibleWhen: definition.visibleWhen ?? null
 	};
+	switch (definition.type) {
+		case "boolean":
+		case "color": return {
+			...base,
+			type: definition.type,
+			default: definition.default
+		};
+		case "string":
+		case "text": return {
+			...base,
+			type: definition.type,
+			default: definition.default,
+			maxLength: definition.maxLength ?? null
+		};
+		case "list": return {
+			...base,
+			type: "list",
+			default: [...definition.default],
+			maxItems: definition.maxItems ?? SETTING_LIMITS.listItems,
+			itemMaxLength: definition.itemMaxLength ?? SETTING_LIMITS.listItemLength
+		};
+		case "number": return {
+			...base,
+			type: "number",
+			default: definition.default,
+			min: definition.min ?? null,
+			max: definition.max ?? null,
+			integer: definition.integer ?? false
+		};
+		default: return {
+			...base,
+			type: "enum",
+			default: definition.default,
+			options: definition.options.map((option) => ({ ...option }))
+		};
+	}
 };
-const isGradeValue = (value) => Number.isInteger(value) && value >= 1 && value <= 5;
-const loadGradePolicy = async (module, id, options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
-	const context = contextOf(options, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: (registeredId, handler) => {
-			handlers.set(registeredId, handler);
-			return { dispose: () => void handlers.delete(registeredId) };
-		}
-	});
-	await module.activate(context);
-	const handler = handlers.get(id);
-	if (handler === void 0) throw new Error(`grade policy '${id}' was not registered`);
-	return {
-		evaluate: async (input) => {
-			const result = await handler(input);
-			if (result !== null && !isGradeValue(result)) throw new Error(`invalid grade policy result: ${JSON.stringify(result)} is not an integer 1..5 or null`);
-			return result;
-		},
-		dispose: async () => {
-			await module.deactivate?.();
-		}
-	};
+const registeredKeybindingOf = (binding) => ({
+	key: binding.key,
+	mac: binding.mac ?? null,
+	windows: binding.windows ?? null,
+	linux: binding.linux ?? null,
+	when: binding.when ?? null
+});
+const registered = (map, kind, id) => {
+	const entry = map.get(id);
+	if (entry === void 0) throw new Error(`${kind} '${id}' was not registered`);
+	return entry;
 };
 /**
-* Activates the module with in-memory storage, settings, and events, and lets the test
-* send events and change settings.
+* Starts `entry` (the `server` export of an extension) with in-memory
+* storage, secrets, settings, statistics, notifications and library, and
+* returns a harness to call what it registered. Registration is all or
+* nothing, as in the host: when `entry` throws, so does `createTestServer`.
 */
-const loadEvents = async (module, options = {}) => {
-	const events = createMemoryEvents(options);
+const createTestServer = async (entry, options = {}) => {
+	const extensionId = options.extensionId ?? "test";
+	const library = options.library ?? createMemoryLibrary({});
 	const storage = options.storage ?? createMemoryStorage();
 	const secrets = options.secrets ?? createMemorySecrets();
-	const settings = createMemorySettings(options.settings ?? [], options.settingValues);
-	const context = contextOf({
-		...options.library !== void 0 && { library: options.library },
-		...options.logger !== void 0 && { logger: options.logger },
-		...options.stats !== void 0 && { stats: options.stats },
-		...options.notifications !== void 0 && { notifications: options.notifications },
-		...options.schedule !== void 0 && { schedule: options.schedule },
+	const stats = options.stats ?? createMemoryStats();
+	const notifications = options.notifications ?? createMemoryNotifications();
+	const settings = createMemorySettings([], options.settingValues);
+	const exerciseTypes = /* @__PURE__ */ new Map();
+	const gradePolicies = /* @__PURE__ */ new Map();
+	const commands = /* @__PURE__ */ new Map();
+	const schedules = /* @__PURE__ */ new Map();
+	const importers = /* @__PURE__ */ new Map();
+	const exporters = /* @__PURE__ */ new Map();
+	const rpcs = /* @__PURE__ */ new Map();
+	const engine = options.engine ?? unprovided("engine", "engine");
+	const events = /* @__PURE__ */ new Map();
+	const hooks = /* @__PURE__ */ new Map();
+	const definitions = [];
+	const running = /* @__PURE__ */ new Set();
+	const add = (map, kind, id, value, max) => {
+		if (typeof id !== "string" || id === "") throw new Error(`${kind} id must be a non-empty string`);
+		if (options.extensionId !== void 0 && id !== extensionId && !id.startsWith(`${extensionId}.`)) throw new Error(`${kind} id '${id}' must be '${extensionId}' or start with '${extensionId}.'`);
+		if (map.has(id)) throw new Error(`${kind} '${id}' is already registered`);
+		if (max !== void 0 && map.size >= max) throw new Error(`more than ${max} ${kind}s`);
+		map.set(id, value);
+		return { dispose: () => {
+			if (map.get(id) === value) map.delete(id);
+		} };
+	};
+	const cleanup = await entry({
+		extensionId,
+		logger: options.logger ?? silentLogger,
+		library,
 		storage,
 		secrets,
 		settings,
-		events
-	}, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: () => ({ dispose: () => void 0 })
+		stats,
+		notifications,
+		engine,
+		registerExerciseType: (reg) => add(exerciseTypes, "exercise type", reg.id, reg),
+		registerGradePolicy: (reg) => add(gradePolicies, "grade policy", reg.id, reg),
+		registerSettings: (added) => {
+			const registeredSettings = settings.register(added);
+			definitions.push(...added);
+			return { dispose: () => {
+				registeredSettings.dispose();
+				for (const definition of added) definitions.splice(definitions.indexOf(definition), 1);
+			} };
+		},
+		on: (name, handler) => {
+			if (events.has(name)) throw new Error(`event '${name}' is already subscribed`);
+			events.set(name, handler);
+			return { dispose: () => {
+				if (events.get(name) === handler) events.delete(name);
+			} };
+		},
+		before: (name, handler) => {
+			if (!EXTENSION_HOOK_NAMES.includes(name)) throw new Error(`hook '${String(name)}' is not a known hook`);
+			if (hooks.has(name)) throw new Error(`hook '${name}' is already registered`);
+			if (hooks.size >= EXTENSION_HOOK_LIMITS.hooks) throw new Error(`more than ${EXTENSION_HOOK_LIMITS.hooks} hooks`);
+			hooks.set(name, handler);
+			return { dispose: () => {
+				if (hooks.get(name) === handler) hooks.delete(name);
+			} };
+		},
+		registerCommand: (reg) => add(commands, "command", reg.id, reg, EXTENSION_COMMAND_LIMITS.commands),
+		schedule: (reg, handler) => add(schedules, "schedule", reg.id, {
+			reg,
+			handler
+		}, EXTENSION_SCHEDULE_LIMITS.schedules),
+		registerImporter: (reg) => add(importers, "importer", reg.id, reg, EXTENSION_TRANSFER_LIMITS.importers),
+		registerExporter: (reg) => add(exporters, "exporter", reg.id, reg, EXTENSION_TRANSFER_LIMITS.exporters),
+		handle: (contract, handler) => {
+			const { name } = contract;
+			if (typeof name !== "string" || name.length > EXTENSION_RPC_LIMITS.nameLength || !RPC_NAME_PATTERN.test(name)) throw new Error(`rpc name '${String(name)}' is not valid`);
+			if (rpcs.has(name)) throw new Error(`rpc '${name}' is already registered`);
+			if (rpcs.size >= EXTENSION_RPC_LIMITS.rpcs) throw new Error(`more than ${EXTENSION_RPC_LIMITS.rpcs} rpcs`);
+			const entry = {
+				contract,
+				handler
+			};
+			rpcs.set(name, entry);
+			return { dispose: () => {
+				if (rpcs.get(name) === entry) rpcs.delete(name);
+			} };
+		}
 	});
-	await module.activate(context);
+	for (const id of Object.keys(options.settingValues ?? {})) if (!definitions.some((definition) => definition.id === id)) throw new Error(`setting '${id}' of settingValues is not registered`);
 	return {
-		emit: events.emit,
+		extensionId,
+		registration: {
+			exerciseTypes: [...exerciseTypes.values()].map((reg) => ({
+				id: reg.id,
+				title: reg.title ?? null,
+				specSchema: reg.specSchema,
+				answerSchema: reg.answerSchema
+			})),
+			gradePolicies: [...gradePolicies.values()].map((reg) => ({
+				id: reg.id,
+				label: reg.label
+			})),
+			settings: definitions.map(registeredSettingOf),
+			events: [...events.keys()],
+			commands: [...commands.values()].map((reg) => ({
+				id: reg.id,
+				title: reg.title,
+				description: reg.description ?? null,
+				category: reg.category ?? null,
+				palette: reg.palette ?? true,
+				icon: reg.icon ?? DEFAULT_EXTENSION_ICON,
+				keybindings: (reg.keybindings ?? []).map(registeredKeybindingOf),
+				when: reg.when ?? null
+			})),
+			schedules: [...schedules.values()].map(({ reg }) => ({
+				id: reg.id,
+				every: reg.every,
+				at: reg.every === "daily" ? reg.at : null
+			})),
+			importers: [...importers.values()].map((reg) => ({
+				id: reg.id,
+				title: reg.title,
+				accept: [...reg.accept],
+				input: reg.input
+			})),
+			exporters: [...exporters.values()].map((reg) => ({
+				id: reg.id,
+				title: reg.title,
+				scope: reg.scope
+			})),
+			rpcs: [...rpcs.keys()],
+			hooks: [...hooks.keys()]
+		},
+		library,
 		storage,
 		secrets,
 		settings,
-		dispose: async () => {
-			await module.deactivate?.();
+		stats,
+		notifications,
+		engine,
+		commands: { async run(id, args) {
+			const { run } = registered(commands, "command", id);
+			if ((JSON.stringify(args)?.length ?? 0) > EXTENSION_COMMAND_LIMITS.argsChars) throw new Error(`args are longer than ${EXTENSION_COMMAND_LIMITS.argsChars} characters`);
+			const result = await run(args);
+			try {
+				return normalizeCommandResult(result, void 0);
+			} catch (error) {
+				if (error instanceof InvalidCommandResultError) throw new Error(`invalid command result: ${error.message}`);
+				throw error;
+			}
+		} },
+		events: { async emit(name, payload) {
+			await events.get(name)?.(payload);
+		} },
+		schedule: { async fire(id) {
+			const { handler } = registered(schedules, "schedule", id);
+			if (running.has(id)) return false;
+			running.add(id);
+			try {
+				await handler();
+				return true;
+			} finally {
+				running.delete(id);
+			}
+		} },
+		async rpc(contract, input) {
+			const { contract: registeredContract, handler } = registered(rpcs, "rpc", contract.name);
+			if ((JSON.stringify(input)?.length ?? 0) > EXTENSION_RPC_LIMITS.inputChars) throw new Error(`input is longer than ${EXTENSION_RPC_LIMITS.inputChars} characters`);
+			const result = await handler(registeredContract.input.parse(input));
+			return registeredContract.output.parse(result);
+		},
+		async hook(name, request) {
+			const handler = registered(hooks, "hook", name);
+			const schemas = EXTENSION_HOOKS[name];
+			const result = await handler(schemas.request.parse(request));
+			return schemas.response.parse(result);
+		},
+		exerciseType(id) {
+			const reg = registered(exerciseTypes, "exercise type", id);
+			return {
+				project: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => reg.project({
+					exerciseId,
+					spec
+				}),
+				grade: async ({ spec, answer, exerciseId = DEFAULT_EXERCISE_ID, timeoutMs = DEFAULT_TIMEOUT_MS, authorMode = false }) => {
+					const result = await reg.grade({
+						exerciseId,
+						spec,
+						answer,
+						timeoutMs,
+						authorMode
+					});
+					const problem = findGradeResultProblem(result);
+					if (problem !== null) throw new Error(`invalid grade result: ${problem}`);
+					return result;
+				},
+				referenceAnswer: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => {
+					const answer = await reg.referenceAnswer?.({
+						exerciseId,
+						spec
+					});
+					return answer === void 0 ? { found: false } : {
+						found: true,
+						answer
+					};
+				}
+			};
+		},
+		gradePolicy(id) {
+			const reg = registered(gradePolicies, "grade policy", id);
+			return { evaluate: async (input) => {
+				const result = await reg.evaluate(input);
+				if (result !== null && !isGradeValue(result)) throw new Error(`invalid grade policy result: ${JSON.stringify(result)} is not an integer 1..5 or null`);
+				return result;
+			} };
+		},
+		importer(id) {
+			const reg = registered(importers, "importer", id);
+			return { async run(input) {
+				if (("text" in input ? "text" : "bytes") !== reg.input) throw new Error(`importer '${id}' takes ${reg.input} input`);
+				if (("text" in input ? new TextEncoder().encode(input.text).length : input.bytes.byteLength) > EXTENSION_TRANSFER_LIMITS.inputBytes) throw new Error(`the file is longer than ${EXTENSION_TRANSFER_LIMITS.inputBytes} bytes`);
+				const result = await reg.run(input);
+				try {
+					return normalizeImportResult(result);
+				} catch (error) {
+					if (error instanceof InvalidTransferResultError) throw new Error(`invalid import result: ${error.message}`);
+					throw error;
+				}
+			} };
+		},
+		exporter(id) {
+			const reg = registered(exporters, "exporter", id);
+			return { async run(input) {
+				if (reg.scope !== input.scope) throw new Error(`exporter '${id}' takes the ${reg.scope} scope`);
+				if (input.scope === "course") {
+					const encoder = new TextEncoder();
+					if (Object.values(input.files).reduce((sum, text) => sum + encoder.encode(text).length, 0) > EXTENSION_TRANSFER_LIMITS.totalBytes) throw new Error(`the course files are longer than ${EXTENSION_TRANSFER_LIMITS.totalBytes} bytes`);
+				}
+				const result = await reg.run(input);
+				try {
+					return normalizeExportResult(result);
+				} catch (error) {
+					if (error instanceof InvalidTransferResultError) throw new Error(`invalid export result: ${error.message}`);
+					throw error;
+				}
+			} };
+		},
+		async dispose() {
+			exerciseTypes.clear();
+			gradePolicies.clear();
+			commands.clear();
+			schedules.clear();
+			importers.clear();
+			exporters.clear();
+			rpcs.clear();
+			events.clear();
+			hooks.clear();
+			if (typeof cleanup === "function") await cleanup();
+			else if (cleanup !== void 0) await cleanup.dispose();
 		}
 	};
 };
-/** Activates the module with in-memory commands and lets the test invoke them like the host. */
-const loadCommands = async (module, options = {}) => {
-	const commands = createMemoryCommands(options);
-	const context = contextOf({
-		...options.library !== void 0 && { library: options.library },
-		...options.logger !== void 0 && { logger: options.logger },
-		...options.storage !== void 0 && { storage: options.storage },
-		...options.secrets !== void 0 && { secrets: options.secrets },
-		...options.settings !== void 0 && { settings: options.settings },
-		...options.events !== void 0 && { events: options.events },
-		...options.stats !== void 0 && { stats: options.stats },
-		...options.notifications !== void 0 && { notifications: options.notifications },
-		...options.schedule !== void 0 && { schedule: options.schedule },
-		commands
-	}, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: () => ({ dispose: () => void 0 })
-	});
-	await module.activate(context);
-	return {
-		run: commands.run,
-		ids: commands.ids,
-		dispose: async () => {
-			await module.deactivate?.();
-		}
+/**
+* Starts `entry` (the `client` export of an extension) on a context that
+* records what it adds, so a test can mount the components and read the
+* themes and commands. An id added twice and an injection with a bad target
+* or position fail like in the window.
+*/
+const createTestClient = async (entry, options = {}) => {
+	const extensionId = options.extensionId ?? "test";
+	const panels = [];
+	const injections = [];
+	const answerViews = /* @__PURE__ */ new Map();
+	const markdownRenderers = /* @__PURE__ */ new Map();
+	const themes = [];
+	const commands = [];
+	const checkId = (kind, id) => {
+		if (options.extensionId !== void 0 && id !== extensionId && !id.startsWith(`${extensionId}.`)) throw new Error(`${kind} id '${id}' must be '${extensionId}' or start with '${extensionId}.'`);
 	};
-};
-/** The context parts a test replaced, without the keys it left unset. */
-const loadOptionsOf = (options) => ({
-	...options.library !== void 0 && { library: options.library },
-	...options.logger !== void 0 && { logger: options.logger },
-	...options.storage !== void 0 && { storage: options.storage },
-	...options.secrets !== void 0 && { secrets: options.secrets },
-	...options.settings !== void 0 && { settings: options.settings },
-	...options.events !== void 0 && { events: options.events },
-	...options.commands !== void 0 && { commands: options.commands },
-	...options.stats !== void 0 && { stats: options.stats },
-	...options.notifications !== void 0 && { notifications: options.notifications },
-	...options.schedule !== void 0 && { schedule: options.schedule }
-});
-/** Activates the module with in-memory importers and lets the test run them like the host. */
-const loadImporters = async (module, options = {}) => {
-	const importers = createMemoryImporters(options);
-	const context = contextOf({
-		...loadOptionsOf(options),
-		importers
-	}, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: () => ({ dispose: () => void 0 })
-	});
-	await module.activate(context);
-	return {
-		run: importers.run,
-		ids: importers.ids,
-		dispose: async () => {
-			await module.deactivate?.();
-		}
+	const addTo = (list, kind, value) => {
+		checkId(kind, value.id);
+		if (list.some((item) => item.id === value.id)) throw new Error(`${kind} '${value.id}' is already added`);
+		list.push(value);
+		return { dispose: () => void list.splice(list.indexOf(value), 1) };
 	};
-};
-/** Activates the module with in-memory exporters and lets the test run them like the host; `stats` feeds `ctx.stats` of a progress exporter. */
-const loadExporters = async (module, options = {}) => {
-	const exporters = createMemoryExporters(options);
-	const context = contextOf({
-		...loadOptionsOf(options),
-		exporters
-	}, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: () => ({ dispose: () => void 0 })
+	const addToMap = (map, kind, key, component) => {
+		if (map.has(key)) throw new Error(`${kind} '${key}' is already added`);
+		map.set(key, component);
+		return { dispose: () => {
+			if (map.get(key) === component) map.delete(key);
+		} };
+	};
+	const cleanup = await entry({
+		extensionId,
+		app: options.app ?? unprovided("app", "app"),
+		engine: options.engine ?? unprovided("engine", "engine"),
+		addPanel: (reg) => addTo(panels, "panel", reg),
+		addInjection: (reg) => {
+			const { target } = reg;
+			if (target.length === 0 || target.length > INJECTION_LIMITS.selectorLength) throw new Error(`injection target must be 1–${INJECTION_LIMITS.selectorLength} characters`);
+			const position = reg.position ?? "append";
+			if (!INJECTION_POSITIONS.includes(position)) throw new Error(`injection position '${position}' is not valid`);
+			if (injections.some(({ id }) => id === reg.id)) throw new Error(`injection '${reg.id}' is already added`);
+			const added = {
+				...reg,
+				position
+			};
+			injections.push(added);
+			return { dispose: () => void injections.splice(injections.indexOf(added), 1) };
+		},
+		addAnswerView: (id, component) => addToMap(answerViews, "answer view", id, component),
+		addMarkdownRenderer: (language, component) => {
+			if (!MARKDOWN_LANGUAGE_PATTERN.test(language)) throw new Error(`markdown language '${language}' is not valid`);
+			return addToMap(markdownRenderers, "markdown renderer", language, component);
+		},
+		addTheme: (reg) => addTo(themes, "theme", reg),
+		addCommand: (reg) => addTo(commands, "command", reg)
 	});
-	await module.activate(context);
 	return {
-		run: exporters.run,
-		ids: exporters.ids,
-		dispose: async () => {
-			await module.deactivate?.();
+		extensionId,
+		panels,
+		injections,
+		answerViews,
+		markdownRenderers,
+		themes,
+		commands,
+		async dispose() {
+			panels.length = 0;
+			injections.length = 0;
+			answerViews.clear();
+			markdownRenderers.clear();
+			themes.length = 0;
+			commands.length = 0;
+			if (typeof cleanup === "function") await cleanup();
+			else if (cleanup !== void 0) await cleanup.dispose();
 		}
 	};
 };
-/** Activates the module with in-memory schedules and lets the test fire them like the host. */
-const loadSchedules = async (module, options = {}) => {
-	const schedule = createMemorySchedule(options);
-	const context = contextOf({
-		...loadOptionsOf(options),
-		schedule
-	}, {
-		registerExerciseType: () => ({ dispose: () => void 0 }),
-		registerGradePolicy: () => ({ dispose: () => void 0 })
-	});
-	await module.activate(context);
+const createNotifier = () => {
+	const listeners = /* @__PURE__ */ new Set();
 	return {
-		fire: schedule.fire,
-		ids: schedule.ids,
-		dispose: async () => {
-			await module.deactivate?.();
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => void listeners.delete(listener);
+		},
+		notify: (value) => {
+			for (const listener of [...listeners]) listener(value);
 		}
 	};
 };
-const requireDocument = (helper) => {
-	if (typeof document === "undefined") throw new Error(`${helper} needs a DOM: run the test in a DOM environment (happy-dom or jsdom)`);
-	return document;
-};
-const microtask = () => Promise.resolve();
-let viewCounter = 0;
 /**
-* Mounts a view from `views[id]` in the test DOM environment with the same element
-* the app creates (test tags are issued; the manifest `element` is not needed).
+* Mounts a `Mountable` into an element on a recording context, so a test can
+* change the props, the theme and the language, read what the component
+* emitted and reported, and unmount it. Rejects with what `mount` throws. Needs
+* a DOM (`document`) or `options.el`.
 */
-const loadView = async (views, id, options = {}) => {
-	const doc = requireDocument("loadView");
-	const view = views[id];
-	if (view === void 0) throw new Error(`view '${id}' was not exported`);
-	const tag = `dolphy-test-view-${++viewCounter}`;
-	customElements.define(tag, createAnswerElementClass(tag, view));
-	const element = doc.createElement(tag);
-	if (options.label !== void 0) element.setAttribute("aria-label", options.label);
-	for (const key of [
-		"view",
-		"value",
-		"disabled",
-		"verdict"
-	]) if (options[key] !== void 0) Object.assign(element, { [key]: options[key] });
-	const changes = [];
-	let submissions = 0;
-	element.addEventListener(ANSWER_EVENT.change, (event) => {
-		changes.push(event.detail);
-	});
-	element.addEventListener(ANSWER_EVENT.submit, () => void (submissions += 1));
-	const container = options.container ?? doc.body.appendChild(doc.createElement("div"));
-	container.append(element);
-	await microtask();
-	const root = element.shadowRoot;
-	return {
-		element,
-		root,
-		changes,
-		get submissions() {
-			return submissions;
+const mountForTest = async (mountable, options) => {
+	let el = options.el;
+	if (el === void 0) {
+		if (typeof document === "undefined") throw new Error("mountForTest needs a DOM: run the test in happy-dom or jsdom, or pass options.el");
+		el = document.createElement("div");
+	}
+	const extensionId = options.extensionId ?? "test";
+	const engine = options.engine ?? unprovided("engine", "engine");
+	const abort = new AbortController();
+	const emitted = [];
+	const errors = [];
+	const propsListeners = createNotifier();
+	const themeListeners = createNotifier();
+	const localeListeners = createNotifier();
+	let props = options.props;
+	let theme = options.theme ?? {
+		id: "light",
+		dark: false
+	};
+	let locale = options.locale ?? "en";
+	const handle = options.handle;
+	const ctx = {
+		get props() {
+			return props;
 		},
-		update: async (props) => {
-			Object.assign(element, props);
-			await microtask();
+		onProps: propsListeners.subscribe,
+		emit: (event, payload) => void emitted.push([event, payload]),
+		app: options.app ?? unprovided("app", "app"),
+		engine,
+		callRpc: (contract, input) => callRpc({
+			engine,
+			extensionId
+		}, contract, input),
+		get theme() {
+			return theme;
 		},
-		query: (selector) => root.querySelector(selector),
-		queryAll: (selector) => [...root.querySelectorAll(selector)],
-		dispose: () => {
-			element.remove();
-			if (options.container === void 0) container.remove();
-		}
+		onTheme: themeListeners.subscribe,
+		get locale() {
+			return locale;
+		},
+		onLocale: localeListeners.subscribe,
+		extensionId,
+		signal: abort.signal,
+		reportError: (error) => void errors.push(error),
+		handle
 	};
-};
-/** The part of the context a panel and a widget share, with the controls a test needs. */
-const createFrameContext = (options, doc) => {
-	const calls = [];
-	const listeners = /* @__PURE__ */ new Set();
-	const controller = new AbortController();
-	const container = options.container ?? doc.body.appendChild(doc.createElement("div"));
-	let current = { courseId: options.context?.courseId ?? null };
+	const unmountComponent = await mountable.mount(el, ctx);
+	let unmounted = false;
 	return {
-		context: {
-			get context() {
-				return current;
-			},
-			signal: controller.signal,
-			call: async (commandId, args) => {
-				calls.push({
-					commandId,
-					args
-				});
-				if (options.call === void 0) throw new Error(`command '${commandId}' is not available in this test`);
-				return options.call(commandId, args);
-			},
-			onContextChange: (listener) => {
-				listeners.add(listener);
-				return () => void listeners.delete(listener);
-			}
+		el,
+		ctx,
+		setProps(next) {
+			props = next;
+			propsListeners.notify(next);
 		},
-		frame: {
-			container,
-			calls,
-			get aborted() {
-				return controller.signal.aborted;
-			},
-			setContext: (next) => {
-				current = { courseId: next.courseId };
-				for (const listener of [...listeners]) listener(current);
-			},
-			dispose: () => {
-				controller.abort();
-				if (options.container === void 0) container.remove();
-			}
+		setTheme(next) {
+			theme = next;
+			themeListeners.notify(next);
 		},
-		container
-	};
-};
-/** Mounts a panel from `panels[id]` in the test DOM environment with the same context the frame provides. */
-const loadPanel = async (panels, id, options = {}) => {
-	const doc = requireDocument("loadPanel");
-	const panel = panels[id];
-	if (panel === void 0) throw new Error(`panel '${id}' was not exported`);
-	const { context, frame, container } = createFrameContext(options, doc);
-	const listeners = /* @__PURE__ */ new Set();
-	await panel.mount(container, {
-		get context() {
-			return context.context;
+		setLocale(next) {
+			locale = next;
+			localeListeners.notify(next);
 		},
-		signal: context.signal,
-		call: context.call,
-		onContextChange: context.onContextChange,
-		panelId: id,
-		props: options.props,
-		onProps: (listener) => {
-			listeners.add(listener);
-			return () => void listeners.delete(listener);
+		emitted,
+		errors,
+		async unmount() {
+			if (unmounted) return;
+			unmounted = true;
+			abort.abort();
+			await unmountComponent();
 		}
-	});
-	return Object.assign(frame, { setProps: (props) => {
-		for (const listener of [...listeners]) listener(props);
-	} });
-};
-/** Mounts a widget from `widgets[id]` in the test DOM environment with the same context the frame provides. */
-const loadWidget = async (widgets, id, options = {}) => {
-	const doc = requireDocument("loadWidget");
-	const widget = widgets[id];
-	if (widget === void 0) throw new Error(`widget '${id}' was not exported`);
-	const { context, frame, container } = createFrameContext(options, doc);
-	await widget.mount(container, {
-		get context() {
-			return context.context;
-		},
-		signal: context.signal,
-		call: context.call,
-		onContextChange: context.onContextChange,
-		widgetId: id
-	});
-	return frame;
+	};
 };
 
 //#endregion
-export { createMemoryCommands, createMemoryEvents, createMemoryExporters, createMemoryImporters, createMemoryLibrary, createMemoryNotifications, createMemorySchedule, createMemorySecrets, createMemorySettings, createMemoryStats, createMemoryStorage, createSchemaValidator, loadCommands, loadEvents, loadExerciseType, loadExporters, loadGradePolicy, loadImporters, loadPanel, loadSchedules, loadView, loadWidget };
+export { createMemoryLibrary, createMemoryNotifications, createMemorySecrets, createMemorySettings, createMemoryStats, createMemoryStorage, createSchemaValidator, createTestClient, createTestServer, mountForTest };