@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/dist/testing.js

@@ -1,7 +1,94 @@
-import { t as createAnswerElementClass } from "./answer-element-BOQcuxYh.js";
-import { ANSWER_EVENT, EXTENSION_COMMAND_LIMITS, EXTENSION_STORAGE_LIMITS, InvalidCommandResultError, PermissionError, StorageQuotaError, normalizeCommandResult } 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 {
@@ -69,10 +160,59 @@ const createMemoryStorage = () => {
 		keys: async () => [...entries.keys()].sort(compareKeys)
 	};
 };
+/**
+* In-memory secrets with the engine's limits and errors
+* (`EXTENSION_SECRET_LIMITS`, `StorageQuotaError`, `SecretsUnavailableError`):
+* without a key store `set` and `get` of an existing key throw, `get` of a
+* missing key gives `undefined` and `delete` works.
+*/
+const createMemorySecrets = (options = {}) => {
+	const limits = EXTENSION_SECRET_LIMITS;
+	const entries = /* @__PURE__ */ new Map();
+	let available = options.available ?? true;
+	const requireStore = () => {
+		if (!available) throw new SecretsUnavailableError();
+	};
+	return {
+		setAvailable: (value) => {
+			available = value;
+		},
+		get: async (key) => {
+			const value = entries.get(key);
+			if (value !== void 0) requireStore();
+			return value;
+		},
+		set: async (key, value) => {
+			if (typeof key !== "string" || key.length === 0) throw new Error("secret key must be a non-empty string");
+			if (typeof value !== "string") throw new Error("secret value must be a string");
+			if (key.length > limits.keyLength) throw new StorageQuotaError("key-length", limits.keyLength);
+			if (Buffer.byteLength(value) > limits.valueBytes) throw new StorageQuotaError("value-size", limits.valueBytes);
+			requireStore();
+			if (!entries.has(key) && entries.size >= limits.keys) throw new StorageQuotaError("key-count", limits.keys);
+			entries.set(key, value);
+		},
+		delete: async (key) => entries.delete(key)
+	};
+};
+/** The value as the host stores it: a color in lower case, a list copied. */
+const storedForm = (definition, value) => {
+	if (definition.type === "color" && typeof value === "string") return value.toLowerCase();
+	return Array.isArray(value) ? [...value] : value;
+};
+const sameSettingValue = (a, b) => Array.isArray(a) && Array.isArray(b) ? a.length === b.length && a.every((item, index) => item === b[index]) : Object.is(a, b);
 /** Why a value does not fit the setting definition; `null` if it fits. */
 const findSettingProblem = (definition, value) => {
 	switch (definition.type) {
 		case "boolean": return typeof value === "boolean" ? null : "must be a boolean";
+		case "color": return typeof value === "string" && COLOR_SETTING_PATTERN.test(value) ? null : "must be a color #rrggbb";
+		case "list": {
+			if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return "must be an array of strings";
+			const maxItems = definition.maxItems ?? SETTING_LIMITS.listItems;
+			if (value.length > maxItems) return `has more than ${maxItems} items`;
+			const itemMax = definition.itemMaxLength ?? SETTING_LIMITS.listItemLength;
+			return value.some((item) => item.length > itemMax) ? `has an item longer than ${itemMax} characters` : null;
+		}
+		case "text":
 		case "string":
 			if (typeof value !== "string") return "must be a string";
 			return definition.maxLength !== void 0 && value.length > definition.maxLength ? `is longer than ${definition.maxLength} characters` : null;
@@ -84,34 +224,51 @@ 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, 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) => {
 		const problem = findSettingProblem(known(id), value);
 		if (problem !== null) throw new Error(`setting '${id}' ${problem}`);
-		return value;
+		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 {
-		get: (id) => {
-			known(id);
-			return values.get(id);
-		},
+		register,
+		get: (id) => storedForm(known(id), values.get(id)),
 		onDidChange(handler) {
 			handlers.add(handler);
 			return { dispose: () => void handlers.delete(handler) };
 		},
 		async set(id, value) {
 			const next = checked(id, value);
-			if (Object.is(values.get(id), next)) return;
+			if (sameSettingValue(values.get(id), next)) return;
 			values.set(id, next);
 			for (const handler of [...handlers]) await handler({
 				id,
@@ -120,61 +277,161 @@ 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();
+const DAY_MS = 864e5;
+const STATS_CORRECT_GRADE_MIN = 3;
+const dayNumberOf = (year, month, day) => {
+	const date = /* @__PURE__ */ new Date(0);
+	date.setUTCFullYear(year, month - 1, day);
+	return Math.floor(date.getTime() / DAY_MS);
+};
+const dayLabelOf = (dayNumber) => (/* @__PURE__ */ new Date(dayNumber * DAY_MS)).toISOString().slice(0, 10);
+const parseDay = (field, value) => {
+	const match = typeof value === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(value) : null;
+	const day = match === null ? null : dayNumberOf(Number(match[1]), Number(match[2]), Number(match[3]));
+	if (day === null || dayLabelOf(day) !== value) throw new Error(`'${field}' must be a date as YYYY-MM-DD`);
+	return day;
+};
+/**
+* In-memory statistics with the semantics of the app: local days in a time zone,
+* correct at grade 3 or higher, `current` streak not broken while today has no
+* attempts yet, one `daily` entry per date (at most `EXTENSION_STATS_LIMITS.dailyDays`).
+*/
+const createMemoryStats = (options = {}) => {
+	const timeZone = options.timeZone ?? new Intl.DateTimeFormat().resolvedOptions().timeZone;
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		calendar: "gregory",
+		numberingSystem: "latn",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit"
+	});
+	const localDay = (at) => {
+		const parts = Object.fromEntries(formatter.formatToParts(at).map(({ type, value }) => [type, value]));
+		return dayNumberOf(Number(parts.year), Number(parts.month), Number(parts.day));
+	};
+	const attempts = [];
+	const record = (attempt) => {
+		const at = new Date(attempt.at).getTime();
+		if (Number.isNaN(at)) throw new Error("attempt.at is not a valid time");
+		attempts.push({
+			day: localDay(at),
+			correct: attempt.grade >= STATS_CORRECT_GRADE_MIN,
+			...attempt.courseId !== void 0 && { courseId: attempt.courseId }
+		});
+	};
+	for (const attempt of options.attempts ?? []) record(attempt);
+	const countsOf = (courseId) => {
+		const days = /* @__PURE__ */ new Map();
+		for (const item of attempts) {
+			if (courseId !== void 0 && item.courseId !== courseId) continue;
+			const counts = days.get(item.day) ?? {
+				attempts: 0,
+				correct: 0
+			};
+			counts.attempts += 1;
+			if (item.correct) counts.correct += 1;
+			days.set(item.day, counts);
+		}
+		return days;
+	};
 	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);
-			} };
+		record,
+		async streak(streakOptions) {
+			const days = countsOf(streakOptions?.courseId);
+			const today = localDay((options.now ?? Date.now)());
+			let longest = 0;
+			let run = 0;
+			let previous = NaN;
+			for (const day of [...days.keys()].sort((a, b) => a - b)) {
+				run = day === previous + 1 ? run + 1 : 1;
+				longest = Math.max(longest, run);
+				previous = day;
+			}
+			let cursor = days.has(today) ? today : today - 1;
+			let current = 0;
+			while (days.has(cursor)) {
+				current += 1;
+				cursor -= 1;
+			}
+			return {
+				current,
+				longest
+			};
 		},
-		async emit(name, payload) {
-			await handlers.get(name)?.(payload);
+		async daily({ from, to, courseId }) {
+			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`);
+			const days = countsOf(courseId);
+			const result = [];
+			for (let day = first; day <= last; day += 1) {
+				const { attempts: made, correct } = days.get(day) ?? {
+					attempts: 0,
+					correct: 0
+				};
+				result.push({
+					date: dayLabelOf(day),
+					attempts: made,
+					correct,
+					accuracy: made === 0 ? null : correct / made
+				});
+			}
+			return result;
 		}
 	};
 };
-/** In-memory commands: the same registration rules and result parsing as the host. */
-const createMemoryCommands = (options = {}) => {
-	const handlers = /* @__PURE__ */ new Map();
+/** Control characters (except the line feed), line and paragraph separators and text direction marks. */
+const NOTIFICATION_CONTROL = /[\u0000-\u0009\u000B-\u001F\u007F-\u009F\u2028\u2029\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
+const notificationText = (field, value, max) => {
+	if (typeof value !== "string") throw new Error(`notification ${field} must be a string`);
+	const unified = value.replace(/\r\n?/gu, "\n").replace(/\t/gu, " ");
+	const text = (field === "body" ? unified : unified.replace(/\n/gu, " ")).replace(NOTIFICATION_CONTROL, "").trim();
+	if (field === "title" && text === "" || [...text].length > max) throw new Error(`notification ${field} must be ${field === "title" ? "1 to " : "up to "}${max} characters`);
+	return text;
+};
+/**
+* In-memory notifications with the engine's rules: the text is sanitized and
+* limited, `perMinute`/`perHour` windows throw `NotificationRateLimitError`,
+* a switched-off extension or an unsupporting system resolves `false` (and
+* does not use the rate limit). `shown` is the log the app's fake notifier
+* would keep.
+*/
+const createMemoryNotifications = (options = {}) => {
+	const now = options.now ?? Date.now;
+	let enabled = options.enabled !== false;
+	let supported = options.supported !== false;
+	const shown = [];
+	const times = [];
+	const limits = EXTENSION_NOTIFICATION_LIMITS;
 	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);
-			} };
+		shown,
+		setEnabled: (value) => {
+			enabled = value;
 		},
-		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;
-			}
+		setSupported: (value) => {
+			supported = value;
 		},
-		ids: () => [...handlers.keys()]
+		async show(notification) {
+			const title = notificationText("title", notification?.title, limits.titleLength);
+			const body = notificationText("body", notification?.body, limits.bodyLength);
+			if (!enabled) return false;
+			const at = now();
+			const recent = times.filter((time) => at - time < 36e5);
+			times.length = 0;
+			times.push(...recent);
+			if (recent.filter((time) => at - time < 6e4).length >= limits.perMinute) throw new NotificationRateLimitError("minute", limits.perMinute);
+			if (recent.length >= limits.perHour) throw new NotificationRateLimitError("hour", limits.perHour);
+			times.push(at);
+			if (!supported) return false;
+			shown.push({
+				title,
+				body
+			});
+			return true;
+		}
 	};
 };
-const contextOf = (options, registrars) => ({
-	extensionId: "test",
-	logger: options.logger ?? silentLogger,
-	library: options.library ?? createMemoryLibrary({}),
-	storage: options.storage ?? createMemoryStorage(),
-	settings: options.settings ?? createMemorySettings([]),
-	events: options.events ?? createMemoryEvents(),
-	commands: options.commands ?? createMemoryCommands(),
-	...registrars
-});
 const createSchemaValidator = (schema) => {
 	const validate = new Ajv2020({
 		allErrors: true,
@@ -228,219 +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 settings = createMemorySettings(options.settings ?? [], options.settingValues);
-	const context = contextOf({
-		...options.library !== void 0 && { library: options.library },
-		...options.logger !== void 0 && { logger: options.logger },
+	const secrets = options.secrets ?? createMemorySecrets();
+	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?.();
-		}
-	};
-};
-/** 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.settings !== void 0 && { settings: options.settings },
-		...options.events !== void 0 && { events: options.events },
-		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?.();
+		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();
 		}
 	};
 };
-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).
+* 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 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 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}.'`);
+	};
+	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) };
+	};
+	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) };
 		},
-		update: async (props) => {
-			Object.assign(element, props);
-			await microtask();
+		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);
 		},
-		query: (selector) => root.querySelector(selector),
-		queryAll: (selector) => [...root.querySelectorAll(selector)],
-		dispose: () => {
-			element.remove();
-			if (options.container === void 0) container.remove();
+		addTheme: (reg) => addTo(themes, "theme", reg),
+		addCommand: (reg) => addTo(commands, "command", reg)
+	});
+	return {
+		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();
 		}
 	};
 };
-/** 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 calls = [];
+const createNotifier = () => {
 	const listeners = /* @__PURE__ */ new Set();
-	const controller = new AbortController();
-	const container = options.container ?? doc.body.appendChild(doc.createElement("div"));
-	await panel.mount(container, {
-		panelId: id,
-		props: options.props,
-		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);
-		},
-		onProps: (listener) => {
+	return {
+		subscribe: (listener) => {
 			listeners.add(listener);
 			return () => void listeners.delete(listener);
+		},
+		notify: (value) => {
+			for (const listener of [...listeners]) listener(value);
 		}
-	});
+	};
+};
+/**
+* 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 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;
+		},
+		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;
+		},
+		onTheme: themeListeners.subscribe,
+		get locale() {
+			return locale;
+		},
+		onLocale: localeListeners.subscribe,
+		extensionId,
+		signal: abort.signal,
+		reportError: (error) => void errors.push(error),
+		handle
+	};
+	const unmountComponent = await mountable.mount(el, ctx);
+	let unmounted = false;
 	return {
-		container,
-		calls,
-		get aborted() {
-			return controller.signal.aborted;
+		el,
+		ctx,
+		setProps(next) {
+			props = next;
+			propsListeners.notify(next);
+		},
+		setTheme(next) {
+			theme = next;
+			themeListeners.notify(next);
 		},
-		setProps: (props) => {
-			for (const listener of [...listeners]) listener(props);
+		setLocale(next) {
+			locale = next;
+			localeListeners.notify(next);
 		},
-		dispose: () => {
-			controller.abort();
-			if (options.container === void 0) container.remove();
+		emitted,
+		errors,
+		async unmount() {
+			if (unmounted) return;
+			unmounted = true;
+			abort.abort();
+			await unmountComponent();
 		}
 	};
 };
 
 //#endregion
-export { createMemoryCommands, createMemoryEvents, createMemoryLibrary, createMemorySettings, createMemoryStorage, createSchemaValidator, loadCommands, loadEvents, loadExerciseType, loadGradePolicy, loadPanel, loadView };
+export { createMemoryLibrary, createMemoryNotifications, createMemorySecrets, createMemorySettings, createMemoryStats, createMemoryStorage, createSchemaValidator, createTestClient, createTestServer, mountForTest };