@dolphy-app/extension-sdk 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @dolphy-app/extension-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK for extension authors: defineExtension, defineAnswerView, test helpers
+
+The package version equals the version of the Dolphy app release it was published from (0.3.0).
+
+`@dolphy-app/extension-sdk` — extension code (`defineExtension`,
+`defineExerciseType`), answer views (`defineAnswerView`), panels,
+markdown renderers and test helpers (`@dolphy-app/extension-sdk/testing`).
+The package has no side effects: an extension `src/index.ts` can be
+imported in plain Node. Ids declared in `extension.json` become types
+through `.dolphy/ids.d.ts`, which `dolphy-ext types` generates.
+
+```ts
+import { defineExtension } from '@dolphy-app/extension-sdk';
+import { loadExerciseType } from '@dolphy-app/extension-sdk/testing';
+```
+
+## Installation
+
+```sh
+npm install @dolphy-app/extension-sdk
+```
+
+## Documentation
+
+[Dolphy extensions](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).

package/dist/answer-element-BOQcuxYh.js

@@ -0,0 +1,114 @@
+import { ANSWER_EVENT, ELEMENT_NAME_PATTERN } from "@dolphy-app/extension-api";
+
+//#region packages/extension-sdk/src/answer-element.ts
+const logFailure = (tag, message, error) => {
+	console.error({
+		error,
+		tag
+	}, message);
+};
+const createAnswerElementClass = (tag, answerView) => class AnswerElement extends HTMLElement {
+	#root = this.attachShadow({ mode: "open" });
+	#props = {
+		view: void 0,
+		value: void 0,
+		disabled: false,
+		verdict: null
+	};
+	#instance = null;
+	#isFlushScheduled = false;
+	get view() {
+		return this.#props.view;
+	}
+	set view(view) {
+		this.#change({ view });
+	}
+	get value() {
+		return this.#props.value;
+	}
+	set value(value) {
+		this.#change({ value });
+	}
+	get disabled() {
+		return this.#props.disabled;
+	}
+	set disabled(disabled) {
+		this.#change({ disabled });
+	}
+	get verdict() {
+		return this.#props.verdict;
+	}
+	set verdict(verdict) {
+		this.#change({ verdict });
+	}
+	connectedCallback() {
+		if (this.#instance !== null) return;
+		const readLabel = () => this.getAttribute("aria-label");
+		const api = {
+			root: this.#root,
+			get label() {
+				return readLabel();
+			},
+			setAnswer: (value, complete) => {
+				const detail = {
+					value,
+					complete
+				};
+				this.#emit(ANSWER_EVENT.change, detail);
+			},
+			submit: () => this.#emit(ANSWER_EVENT.submit, void 0)
+		};
+		try {
+			this.#instance = answerView.mount(api, Object.freeze({ ...this.#props }));
+		} catch (error) {
+			logFailure(tag, "answer element failed to mount", error);
+		}
+	}
+	disconnectedCallback() {
+		const instance = this.#instance;
+		this.#instance = null;
+		if (instance === null) return;
+		try {
+			instance.destroy?.();
+		} catch (error) {
+			logFailure(tag, "answer element failed to destroy", error);
+		}
+		this.#root.replaceChildren();
+	}
+	#change(patch) {
+		this.#props = {
+			...this.#props,
+			...patch
+		};
+		if (this.#instance === null || this.#isFlushScheduled) return;
+		this.#isFlushScheduled = true;
+		queueMicrotask(() => this.#flush());
+	}
+	#flush() {
+		this.#isFlushScheduled = false;
+		const instance = this.#instance;
+		if (instance === null) return;
+		try {
+			instance.update(Object.freeze({ ...this.#props }));
+		} catch (error) {
+			logFailure(tag, "answer element failed to update", error);
+		}
+	}
+	#emit(name, detail) {
+		this.dispatchEvent(new CustomEvent(name, {
+			detail,
+			bubbles: true,
+			composed: true
+		}));
+	}
+};
+/** Defines the kind's custom element; calling again with the same tag changes nothing. */
+const registerAnswerView = (tag, view) => {
+	if (!ELEMENT_NAME_PATTERN.test(tag)) throw new TypeError(`invalid custom element name '${tag}'`);
+	if (typeof view?.mount !== "function") throw new TypeError(`answer view for '${tag}' has no mount()`);
+	if (customElements.get(tag) !== void 0) return;
+	customElements.define(tag, createAnswerElementClass(tag, view));
+};
+
+//#endregion
+export { registerAnswerView as n, createAnswerElementClass as t };

package/dist/answer-view-D6wnyThb.d.ts

@@ -0,0 +1,28 @@
+import { AnswerElementProps } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/answer-view.d.ts
+interface AnswerViewApi {
+  readonly root: ShadowRoot;
+  /** `aria-label` of the host element set by the app; `null` if none. */
+  readonly label: string | null;
+  /** Reports the current answer to the app: the `dolphy-answer-change` event. */
+  setAnswer(value: unknown, complete: boolean): void;
+  /** Asks the app to submit the answer: the `dolphy-answer-submit` event. */
+  submit(): void;
+}
+interface AnswerViewInstance {
+  /** Called when `view`/`value`/`disabled`/`verdict` change. */
+  update(props: AnswerElementProps): void;
+  destroy?(): void;
+}
+type MountAnswerView = (api: AnswerViewApi, props: AnswerElementProps) => AnswerViewInstance;
+/** Description of an answer input view: side-effect-free data; the build registers the element. */
+interface AnswerView {
+  readonly mount: MountAnswerView;
+}
+/**
+ * Entry `views[<exercise kind id>]` in `src/index.ts`. Registers nothing:
+ * the custom element with the manifest tag is defined by the build's browser file.
+ */
+declare const defineAnswerView: (mount: MountAnswerView) => AnswerView;
+//#endregion
+export { defineAnswerView as a, MountAnswerView as i, AnswerViewApi as n, AnswerViewInstance as r, AnswerView as t };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { a as defineAnswerView, i as MountAnswerView, n as AnswerViewApi, r as AnswerViewInstance, t as AnswerView } from "./answer-view-D6wnyThb.js";
+import { CommandHandler, ExerciseTypeHandler, ExtensionContext as ExtensionContext$1, ExtensionIdSet, ExtensionModule, GradePolicyHandler, JsonValue, LearningEventHandler, MarkdownRenderContext, MarkdownRendererModule, NotifyEffect, OpenPanelEffect, PanelContext as PanelContext$1, PanelModule } from "@dolphy-app/extension-api";
+export * from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/ids.d.ts
+/**
+ * The ids declared in `extension.json`. Empty here: `dolphy-ext types` (and
+ * every `dolphy-ext build`) writes `.dolphy/ids.d.ts`, which augments this
+ * interface with one key per kind of id:
+ *
+ * ```ts
+ * declare module '@dolphy-app/extension-sdk' {
+ *   interface ExtensionIds {
+ *     exerciseTypes: 'acme.echo';
+ *     commands: 'acme.a' | 'acme.b';
+ *     settings: { 'acme.goal': number };
+ *     // …
+ *   }
+ * }
+ * ```
+ *
+ * While the interface is empty (no generated file) every id is a plain
+ * `string` and `defineExtension` does not require any record.
+ */
+interface ExtensionIds {}
+type Declared<K extends keyof ExtensionIdSet> = K extends keyof ExtensionIds ? ExtensionIds[K] extends ExtensionIdSet[K] ? ExtensionIds[K] : ExtensionIdSet[K] : ExtensionIdSet[K];
+/** `ExtensionIds` with the plain-string fallback for the kinds it does not declare. */
+type ResolvedIds = { [K in keyof ExtensionIdSet]: Declared<K>; };
+/** Whether the generated declarations are part of the program. */
+type HasGeneratedIds = [keyof ExtensionIds] extends [never] ? false : true;
+/**
+ * `ExtensionContext` of this extension: `settings`, `events`, `commands` and
+ * the `register…` methods accept the declared ids only.
+ */
+type ExtensionContext = ExtensionContext$1<ResolvedIds>;
+/** Context of a panel module; `call` accepts the declared command ids only. */
+type PanelContext = PanelContext$1<ResolvedIds['commands']>;
+/**
+ * A record that holds exactly the declared ids: a missing and an extra key are
+ * both compile errors. With no generated declarations any keys are accepted;
+ * with none declared of this kind no key is accepted.
+ */
+type Exact<Id extends string, Value> = [HasGeneratedIds] extends [false] ? {
+  readonly [key: string]: Value;
+} : [Id] extends [never] ? {
+  readonly [key: string]: never;
+} : { readonly [K in Id]: Value; };
+/** `export const views = { … } satisfies ExtensionViews`: one `defineAnswerView` per declared exercise type. */
+type ExtensionViews = Exact<ResolvedIds['exerciseTypes'], AnswerView>;
+/** `export const panels = { … } satisfies ExtensionPanels`: one `defineExtensionPanel` per declared panel. */
+type ExtensionPanels = Exact<ResolvedIds['panels'], PanelModule<HTMLElement, ResolvedIds['commands']>>;
+/** `export const markdown = { … } satisfies ExtensionMarkdown`: one `defineMarkdownRenderer` per declared language. */
+type ExtensionMarkdown = Exact<ResolvedIds['markdownLanguages'], MarkdownRendererModule<HTMLElement>>;
+//#endregion
+//#region packages/extension-sdk/src/commands.d.ts
+/** A command result: the app shows a notification (1–500 characters, as is, no markup). */
+export declare const notify: (text: string) => NotifyEffect;
+/** A command result: the app opens a panel of this extension (a declared panel id); `props` reach the panel as `ctx.props`. */
+export declare const openPanel: (panelId: ResolvedIds["panels"], props?: JsonValue) => OpenPanelEffect;
+//#endregion
+//#region packages/extension-sdk/src/define-extension.d.ts
+declare const inActivateBrand: unique symbol;
+/** Type of `inActivate`. */
+interface InActivate {
+  readonly [inActivateBrand]: true;
+}
+/**
+ * A record value in `defineExtension` that says "this id is registered in
+ * `activate`" (`ctx.commands.register`, `ctx.events.on`,
+ * `ctx.registerExerciseType`, `ctx.registerGradePolicy`) rather than by a
+ * handler in the record. Needed because the records must name every declared
+ * id: a handler that needs `ctx` is written in `activate`, and its id gets this
+ * marker in the record.
+ */
+export declare const inActivate: InActivate;
+/** Without generated declarations a record may name any subset: an index signature already does, a record keyed by the event names needs `Partial`. */
+type Lenient<Entries> = string extends keyof Entries ? Entries : Partial<Entries>;
+/**
+ * The definition record of one kind of id. With generated declarations the
+ * record is required (when the manifest declares any id of the kind) and holds
+ * exactly the declared ids: a missing and an extra key are compile errors.
+ * Without them every key is accepted and the record is optional.
+ */
+type Section<Name extends string, Id extends string, Entries> = [HasGeneratedIds] extends [false] ? { readonly [N in Name]?: Lenient<Entries>; } : [Id] extends [never] ? { readonly [N in Name]?: never; } : { readonly [N in Name]: Entries; };
+type Ids = ResolvedIds;
+/** Learning-event handlers by event name; the events must be declared in `contributes.events`, the `learning.events` permission is needed. */
+type EventHandlers = { readonly [N in Ids['events']]: LearningEventHandler<N> | InActivate; };
+/**
+ * What `defineExtension` takes. `exerciseTypes`, `gradePolicies`, `events` and
+ * `commands` name every id `extension.json` declares for them, exactly: a
+ * handler, or `inActivate` for an id that `activate` registers.
+ */
+type ExtensionDefinition = Section<'exerciseTypes', Ids['exerciseTypes'], { readonly [K in Ids['exerciseTypes']]: ExerciseTypeHandler | InActivate; }> & Section<'gradePolicies', Ids['gradePolicies'], { readonly [K in Ids['gradePolicies']]: GradePolicyHandler | InActivate; }> & Section<'events', Ids['events'], EventHandlers> & Section<'commands', Ids['commands'], { readonly [K in Ids['commands']]: CommandHandler | InActivate; }> & {
+  /** Runs after the records are registered. */
+  activate?(context: ExtensionContext): void | Promise<void>;
+  deactivate?(): void | Promise<void>;
+};
+export declare const defineExerciseType: <Spec, Answer, View>(handler: ExerciseTypeHandler<Spec, Answer, View>) => ExerciseTypeHandler<Spec, Answer, View>;
+export declare const defineExtension: (declared: ExtensionDefinition) => ExtensionModule;
+//#endregion
+//#region packages/extension-sdk/src/markdown-renderer.d.ts
+/** Entry `markdown[<language>]` in `src/index.ts` (`contributes.markdownRenderers`). */
+export declare const defineMarkdownRenderer: (render: (source: string, container: HTMLElement, context: MarkdownRenderContext) => void | Promise<void>) => MarkdownRendererModule<HTMLElement>;
+//#endregion
+//#region packages/extension-sdk/src/panel.d.ts
+/** An entry of `panels[<panel id>]` in `src/index.ts` (`contributes.panels`); `ctx.call` accepts the declared command ids. */
+export declare const defineExtensionPanel: (module: PanelModule<HTMLElement, ResolvedIds["commands"]>) => PanelModule<HTMLElement, ResolvedIds["commands"]>;
+//#endregion
+export { type AnswerView, type AnswerViewApi, type AnswerViewInstance, type EventHandlers, type ExtensionContext, type ExtensionDefinition, type ExtensionIds, type ExtensionMarkdown, type ExtensionPanels, type ExtensionViews, type InActivate, type MountAnswerView, type PanelContext, defineAnswerView };

package/dist/index.js

@@ -0,0 +1,91 @@
+export * from "@dolphy-app/extension-api"
+
+//#region packages/extension-sdk/src/commands.ts
+/** A command result: the app shows a notification (1–500 characters, as is, no markup). */
+const notify = (text) => ({ notify: text });
+/** A command result: the app opens a panel of this extension (a declared panel id); `props` reach the panel as `ctx.props`. */
+const openPanel = (panelId, props) => props === void 0 ? { openPanel: panelId } : {
+	openPanel: panelId,
+	props
+};
+
+//#endregion
+//#region packages/extension-sdk/src/define-extension.ts
+/**
+* A record value in `defineExtension` that says "this id is registered in
+* `activate`" (`ctx.commands.register`, `ctx.events.on`,
+* `ctx.registerExerciseType`, `ctx.registerGradePolicy`) rather than by a
+* handler in the record. Needed because the records must name every declared
+* id: a handler that needs `ctx` is written in `activate`, and its id gets this
+* marker in the record.
+*/
+const inActivate = /*#__PURE__*/ Object.freeze({});
+const defineExerciseType = /* @__NO_SIDE_EFFECTS__ */ (handler) => handler;
+const disposeInReverse = async (registrations) => {
+	const errors = [];
+	for (const registration of registrations.splice(0).reverse()) try {
+		await registration.dispose();
+	} catch (error) {
+		errors.push(error);
+	}
+	return errors;
+};
+/** The entries of a record that carry a handler (not `inActivate`). */
+const handlersOf = (record) => Object.entries(record ?? {}).filter((entry) => entry[1] !== inActivate);
+const defineExtension = /* @__NO_SIDE_EFFECTS__ */ (declared) => {
+	const definition = declared;
+	const registrations = [];
+	const register = (context) => {
+		for (const [type, handler] of handlersOf(definition.exerciseTypes)) registrations.push(context.registerExerciseType(type, handler));
+		for (const [id, handler] of handlersOf(definition.gradePolicies)) registrations.push(context.registerGradePolicy(id, handler));
+		for (const [name, handler] of handlersOf(definition.events)) registrations.push(context.events.on(name, handler));
+		for (const [id, handler] of handlersOf(definition.commands)) registrations.push(context.commands.register(id, handler));
+	};
+	const activate = async (context) => {
+		try {
+			register(context);
+			await definition.activate?.(context);
+		} catch (error) {
+			const disposalErrors = await disposeInReverse(registrations);
+			if (disposalErrors.length === 0) throw error;
+			throw new AggregateError([error, ...disposalErrors], "activation failed and rollback was incomplete");
+		}
+	};
+	const deactivate = async () => {
+		const failures = [];
+		try {
+			await definition.deactivate?.();
+		} catch (error) {
+			failures.push(error);
+		}
+		const disposalErrors = await disposeInReverse(registrations);
+		if (disposalErrors.length > 0) failures.push(new AggregateError(disposalErrors, "failed to dispose contributions"));
+		if (failures.length === 1) throw failures[0];
+		if (failures.length > 1) throw new AggregateError(failures, "failed to deactivate extension");
+	};
+	return {
+		activate,
+		deactivate
+	};
+};
+
+//#endregion
+//#region packages/extension-sdk/src/answer-view.ts
+/**
+* Entry `views[<exercise kind id>]` in `src/index.ts`. Registers nothing:
+* the custom element with the manifest tag is defined by the build's browser file.
+*/
+const defineAnswerView = /* @__NO_SIDE_EFFECTS__ */ (mount) => ({ mount });
+
+//#endregion
+//#region packages/extension-sdk/src/markdown-renderer.ts
+/** Entry `markdown[<language>]` in `src/index.ts` (`contributes.markdownRenderers`). */
+const defineMarkdownRenderer = /* @__NO_SIDE_EFFECTS__ */ (render) => ({ render });
+
+//#endregion
+//#region packages/extension-sdk/src/panel.ts
+/** An entry of `panels[<panel id>]` in `src/index.ts` (`contributes.panels`); `ctx.call` accepts the declared command ids. */
+const defineExtensionPanel = /* @__NO_SIDE_EFFECTS__ */ (module) => module;
+
+//#endregion
+export { defineAnswerView, defineExerciseType, defineExtension, defineExtensionPanel, defineMarkdownRenderer, inActivate, notify, openPanel };

package/dist/runtime.d.ts

@@ -0,0 +1,14 @@
+import { t as AnswerView } from "./answer-view-D6wnyThb.js";
+import { MarkdownRendererModule, PanelModule } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/answer-element.d.ts
+/** Defines the kind's custom element; calling again with the same tag changes nothing. */
+export declare const registerAnswerView: (tag: string, view: AnswerView) => void;
+//#endregion
+//#region packages/extension-sdk/src/runtime.d.ts
+type PanelEntry = PanelModule<HTMLElement>;
+type MarkdownEntry = MarkdownRendererModule<HTMLElement>;
+/** Panel module that selects the `panels` entry by `ctx.panelId` (for a file shared by several panels). */
+export declare const dispatchPanels: (panels: Readonly<Record<string, PanelEntry>>) => PanelEntry;
+/** Renderer module that selects the `markdown` entry by block language. */
+export declare const dispatchMarkdown: (renderers: Readonly<Record<string, MarkdownEntry>>) => MarkdownEntry;
+//#endregion

package/dist/runtime.js

@@ -0,0 +1,18 @@
+import { n as registerAnswerView } from "./answer-element-BOQcuxYh.js";
+
+//#region packages/extension-sdk/src/runtime.ts
+/** Panel module that selects the `panels` entry by `ctx.panelId` (for a file shared by several panels). */
+const dispatchPanels = (panels) => ({ mount(container, context) {
+	const panel = panels[context.panelId];
+	if (panel === void 0) throw new Error(`panel '${context.panelId}' is not exported`);
+	return panel.mount(container, context);
+} });
+/** Renderer module that selects the `markdown` entry by block language. */
+const dispatchMarkdown = (renderers) => ({ render(source, container, context) {
+	const renderer = renderers[context.language];
+	if (renderer === void 0) throw new Error(`markdown renderer '${context.language}' is not exported`);
+	return renderer.render(source, container, context);
+} });
+
+//#endregion
+export { dispatchMarkdown, dispatchPanels, registerAnswerView };

package/dist/testing.d.ts

@@ -0,0 +1,175 @@
+import { t as AnswerView } from "./answer-view-D6wnyThb.js";
+import { AnswerChangeDetail, AnswerElementProps, CommandOutcome, ExtensionCommands, ExtensionEvents, ExtensionLogger, ExtensionModule, ExtensionSettings, ExtensionStorage, GradePolicyInput, GradeResult, GradeValue, JsonSchema, JsonValue, LearningEventName, LearningEventPayloads, LibraryReader, PanelModule, SettingContribution, SettingValue } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/testing.d.ts
+export declare const createMemoryLibrary: (files: Readonly<Record<string, string>>) => LibraryReader;
+/**
+ * In-memory storage with the same limits and errors as the engine
+ * (`EXTENSION_STORAGE_LIMITS`, `StorageQuotaError`): values are stored as
+ * JSON text and returned as copies; on rejection nothing changes.
+ */
+export declare const createMemoryStorage: () => ExtensionStorage;
+export interface MemorySettings extends ExtensionSettings {
+  /**
+   * Changes the value as the user does in the dialog: the value is validated
+   * against the definition, and `onDidChange` subscribers are called if it changed.
+   * Unlike the host, a handler failure is not swallowed but rejects the promise.
+   */
+  set(id: string, value: SettingValue): Promise<void>;
+}
+/** In-memory settings from manifest definitions; `initial` provides user values in place of `default`. */
+export declare const createMemorySettings: (definitions: readonly SettingContribution[], initial?: Readonly<Record<string, SettingValue>>) => MemorySettings;
+export interface MemoryEvents extends ExtensionEvents {
+  /**
+   * Sends the event to the subscribed handler and awaits it. With no subscription,
+   * the event is skipped, as in the host. Unlike the host, a handler failure
+   * is not swallowed but rejects the promise, and the 2 s handler timeout is not applied.
+   */
+  emit<N extends LearningEventName>(name: N, payload: LearningEventPayloads[N]): Promise<void>;
+}
+export interface MemoryEventsOptions {
+  /** Events from `contributes.events`: subscribing to another throws, as in the host. Unset — any are allowed. */
+  declared?: readonly LearningEventName[];
+  /** false — subscribing throws `PermissionError`, as for an extension without `learning.events`. Defaults to true. */
+  permitted?: boolean;
+}
+/** In-memory learning event subscriptions: one handler per event, as in the host. */
+export declare const createMemoryEvents: (options?: MemoryEventsOptions) => MemoryEvents;
+export interface MemoryCommands extends ExtensionCommands {
+  /**
+   * Runs a registered command the way the host does: the same
+   * argument and result bounds, the same result normalization. An unregistered
+   * command and an invalid result reject the promise. The 10 s handler timeout is not applied.
+   */
+  run(id: string, args?: JsonValue): Promise<CommandOutcome>;
+  /** Registered commands in registration order. */
+  ids(): string[];
+}
+export interface MemoryCommandsOptions {
+  /** Commands from `contributes.commands`: registering another throws, as in the host. Unset — any are allowed. */
+  declaredCommands?: readonly string[];
+  /** Panels from `contributes.panels`: `openPanel` on another is invalid, as in the host. Unset — any. */
+  declaredPanels?: readonly string[];
+}
+/** In-memory commands: the same registration rules and result parsing as the host. */
+export declare const createMemoryCommands: (options?: MemoryCommandsOptions) => MemoryCommands;
+/** What a test replaces in the extension context; by default everything is in memory and silent. */
+export interface LoadOptions {
+  library?: LibraryReader;
+  logger?: ExtensionLogger;
+  storage?: ExtensionStorage;
+  settings?: ExtensionSettings;
+  events?: ExtensionEvents;
+  commands?: ExtensionCommands;
+}
+export declare const createSchemaValidator: (schema: JsonSchema) => (value: unknown) => string[];
+export interface LoadedExerciseType {
+  project(spec: unknown, options?: {
+    exerciseId?: string;
+  }): Promise<unknown>;
+  grade(input: {
+    spec: unknown;
+    answer: unknown;
+    exerciseId?: string;
+    timeoutMs?: number;
+    authorMode?: boolean;
+  }): Promise<GradeResult>;
+  referenceAnswer(spec: unknown, options?: {
+    exerciseId?: string;
+  }): Promise<{
+    found: true;
+    answer: unknown;
+  } | {
+    found: false;
+  }>;
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export declare const loadExerciseType: (module: ExtensionModule, type: string, options?: LoadOptions) => Promise<LoadedExerciseType>;
+export interface LoadedGradePolicy {
+  evaluate(input: GradePolicyInput): Promise<GradeValue | null>;
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export declare const loadGradePolicy: (module: ExtensionModule, id: string, options?: LoadOptions) => Promise<LoadedGradePolicy>;
+export interface LoadedEvents {
+  /** Events are delivered as in the host: to the subscribed handler, one at a time. See `MemoryEvents.emit`. */
+  emit: MemoryEvents['emit'];
+  storage: ExtensionStorage;
+  settings: MemorySettings;
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadEventsOptions extends Omit<LoadOptions, 'storage' | 'settings' | 'events'>, MemoryEventsOptions {
+  storage?: ExtensionStorage;
+  /** Definitions from the manifest's `contributes.settings`; values are read and changed through `settings`. */
+  settings?: readonly SettingContribution[];
+  /** User values in place of `default`. */
+  settingValues?: Readonly<Record<string, SettingValue>>;
+}
+/**
+ * Activates the module with in-memory storage, settings, and events, and lets the test
+ * send events and change settings.
+ */
+export declare const loadEvents: (module: ExtensionModule, options?: LoadEventsOptions) => Promise<LoadedEvents>;
+export interface LoadedCommands {
+  run: MemoryCommands['run'];
+  ids: MemoryCommands['ids'];
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadCommandsOptions extends Omit<LoadOptions, 'commands'>, MemoryCommandsOptions {}
+/** Activates the module with in-memory commands and lets the test invoke them like the host. */
+export declare const loadCommands: (module: ExtensionModule, options?: LoadCommandsOptions) => Promise<LoadedCommands>;
+export interface LoadViewOptions extends Partial<AnswerElementProps> {
+  /** `aria-label` of the host element, as the app sets it. */
+  label?: string;
+  /** Where to mount; defaults to a new `div` in `document.body`. */
+  container?: HTMLElement;
+}
+export interface LoadedView {
+  /** The kind's custom element, as the app creates it. */
+  readonly element: HTMLElement;
+  /** The element's shadow root: the view renders its UI here. */
+  readonly root: ShadowRoot;
+  /** `dolphy-answer-change` events in order. */
+  readonly changes: readonly AnswerChangeDetail[];
+  /** How many times the view asked to submit the answer (`dolphy-answer-submit`). */
+  readonly submissions: number;
+  /** Sets element properties and waits for the view to apply the update. */
+  update(props: Partial<AnswerElementProps>): Promise<void>;
+  query<E extends Element = Element>(selector: string): E | null;
+  queryAll<E extends Element = Element>(selector: string): E[];
+  /** Removes the element from the document; the view receives `destroy()`. */
+  dispose(): void;
+}
+/**
+ * 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).
+ */
+export declare const loadView: (views: Readonly<Record<string, AnswerView>>, id: string, options?: LoadViewOptions) => Promise<LoadedView>;
+export interface LoadPanelOptions {
+  /** Properties the panel was opened with (`openPanel(id, props)`). */
+  props?: JsonValue;
+  /** Reply to `ctx.call`; by default the call is rejected. */
+  call?: (commandId: string, args: JsonValue | undefined) => JsonValue | undefined | Promise<JsonValue | undefined>;
+  /** Where to mount; defaults to a new `div` in `document.body`. */
+  container?: HTMLElement;
+}
+export interface LoadedPanel {
+  /** Container the panel received in `mount`. */
+  readonly container: HTMLElement;
+  /** `ctx.call` invocations in order. */
+  readonly calls: readonly {
+    commandId: string;
+    args: JsonValue | undefined;
+  }[];
+  /** Whether `ctx.signal` was aborted (after `dispose()`). */
+  readonly aborted: boolean;
+  /** Sends new properties to the panel (`ctx.onProps`). */
+  setProps(props: JsonValue | undefined): void;
+  /** Closes the frame: aborts `ctx.signal` and removes the container. */
+  dispose(): void;
+}
+/** Mounts a panel from `panels[id]` in the test DOM environment with the same context the frame provides. */
+export declare const loadPanel: (panels: Readonly<Record<string, PanelModule<HTMLElement>>>, id: string, options?: LoadPanelOptions) => Promise<LoadedPanel>;
+//#endregion

package/dist/testing.js

@@ -0,0 +1,446 @@
+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 { Ajv2020 } from "ajv/dist/2020.js";
+
+//#region packages/extension-sdk/src/testing.ts
+const MAX_MESSAGES = 6;
+const MAX_REASON_CHARS = 100;
+const MAX_TEXT_CHARS = 4e3;
+const DEFAULT_EXERCISE_ID = "test::lesson::exercise";
+const DEFAULT_TIMEOUT_MS = 2e3;
+const silentLogger = {
+	debug: () => void 0,
+	info: () => void 0,
+	warn: () => void 0,
+	error: () => void 0
+};
+const createMemoryLibrary = (files) => {
+	const entries = new Map(Object.entries(files));
+	return {
+		readText: async (path) => {
+			const text = entries.get(path);
+			if (text === void 0) throw new Error(`ENOENT: ${path}`);
+			return text;
+		},
+		stat: async (path) => {
+			const text = entries.get(path);
+			if (text === void 0) return null;
+			return {
+				kind: "file",
+				bytes: Buffer.byteLength(text),
+				mtimeMs: 0
+			};
+		}
+	};
+};
+/** UTF-8 byte order matches code point order — this is how the engine sorts keys. */
+const compareKeys = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+/**
+* In-memory storage with the same limits and errors as the engine
+* (`EXTENSION_STORAGE_LIMITS`, `StorageQuotaError`): values are stored as
+* JSON text and returned as copies; on rejection nothing changes.
+*/
+const createMemoryStorage = () => {
+	const limits = EXTENSION_STORAGE_LIMITS;
+	const entries = /* @__PURE__ */ new Map();
+	const totalBytes = () => {
+		let total = 0;
+		for (const text of entries.values()) total += Buffer.byteLength(text);
+		return total;
+	};
+	return {
+		get: async (key) => {
+			const text = entries.get(key);
+			return text === void 0 ? void 0 : JSON.parse(text);
+		},
+		set: async (key, value) => {
+			if (typeof key !== "string" || key.length === 0) throw new Error("storage key must be a non-empty string");
+			const text = JSON.stringify(value);
+			if (text === void 0) throw new Error("storage value must be JSON");
+			const bytes = Buffer.byteLength(text);
+			if (key.length > limits.keyLength) throw new StorageQuotaError("key-length", limits.keyLength);
+			if (bytes > limits.valueBytes) throw new StorageQuotaError("value-size", limits.valueBytes);
+			const existing = entries.get(key);
+			if (existing === void 0 && entries.size >= limits.keys) throw new StorageQuotaError("key-count", limits.keys);
+			if (totalBytes() - (existing === void 0 ? 0 : Buffer.byteLength(existing)) + bytes > limits.totalBytes) throw new StorageQuotaError("total-size", limits.totalBytes);
+			entries.set(key, text);
+		},
+		delete: async (key) => entries.delete(key),
+		keys: async () => [...entries.keys()].sort(compareKeys)
+	};
+};
+/** 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 "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;
+		case "number":
+			if (typeof value !== "number" || !Number.isFinite(value)) return "must be a finite number";
+			if (definition.integer === true && !Number.isInteger(value)) return "must be an integer";
+			if (definition.min !== void 0 && value < definition.min) return `is less than ${definition.min}`;
+			return definition.max !== void 0 && value > definition.max ? `is greater than ${definition.max}` : null;
+		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]));
+	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`);
+		return definition;
+	};
+	const checked = (id, value) => {
+		const problem = findSettingProblem(known(id), value);
+		if (problem !== null) throw new Error(`setting '${id}' ${problem}`);
+		return value;
+	};
+	for (const [id, value] of Object.entries(initial)) values.set(id, checked(id, value));
+	return {
+		get: (id) => {
+			known(id);
+			return 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;
+			values.set(id, next);
+			for (const handler of [...handlers]) await handler({
+				id,
+				value: next
+			});
+		}
+	};
+};
+/** 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()]
+	};
+};
+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,
+		strict: false
+	}).compile(schema);
+	return (value) => {
+		if (validate(value)) return [];
+		return (validate.errors ?? []).slice(0, MAX_MESSAGES).map((error) => `${error.instancePath || "/"} ${error.message}`);
+	};
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const OUTCOME_KEYS = {
+	passed: [
+		"outcome",
+		"feedback",
+		"data"
+	],
+	failed: [
+		"outcome",
+		"reason",
+		"feedback",
+		"detail",
+		"data"
+	],
+	error: [
+		"outcome",
+		"reason",
+		"feedback",
+		"data"
+	]
+};
+const textProblem = (result, key) => {
+	const value = result[key];
+	if (value === void 0) return null;
+	if (typeof value !== "string") return `'${key}' must be a string`;
+	if (value.length > MAX_TEXT_CHARS) return `'${key}' is longer than ${MAX_TEXT_CHARS} characters`;
+	return null;
+};
+const reasonProblem = (result) => {
+	const { reason } = result;
+	if (typeof reason !== "string" || reason.length === 0) return `'reason' must be a non-empty string`;
+	if (reason.length > MAX_REASON_CHARS) return `'reason' is longer than ${MAX_REASON_CHARS} characters`;
+	return null;
+};
+const findGradeResultProblem = (result) => {
+	if (!isRecord(result)) return "result must be an object";
+	const { outcome } = result;
+	if (outcome !== "passed" && outcome !== "failed" && outcome !== "error") return `unknown outcome ${JSON.stringify(outcome)}`;
+	const allowed = OUTCOME_KEYS[outcome];
+	const extra = Object.keys(result).find((key) => !allowed.includes(key));
+	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) => 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?.();
+		}
+	};
+};
+/**
+* Activates the module with in-memory storage, settings, and events, and lets the test
+* send events and change settings.
+*/
+const loadEvents = async (module, options = {}) => {
+	const events = createMemoryEvents(options);
+	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 },
+		storage,
+		settings,
+		events
+	}, {
+		registerExerciseType: () => ({ dispose: () => void 0 }),
+		registerGradePolicy: () => ({ dispose: () => void 0 })
+	});
+	await module.activate(context);
+	return {
+		emit: events.emit,
+		storage,
+		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?.();
+		}
+	};
+};
+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).
+*/
+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;
+		},
+		update: async (props) => {
+			Object.assign(element, props);
+			await microtask();
+		},
+		query: (selector) => root.querySelector(selector),
+		queryAll: (selector) => [...root.querySelectorAll(selector)],
+		dispose: () => {
+			element.remove();
+			if (options.container === void 0) container.remove();
+		}
+	};
+};
+/** 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 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) => {
+			listeners.add(listener);
+			return () => void listeners.delete(listener);
+		}
+	});
+	return {
+		container,
+		calls,
+		get aborted() {
+			return controller.signal.aborted;
+		},
+		setProps: (props) => {
+			for (const listener of [...listeners]) listener(props);
+		},
+		dispose: () => {
+			controller.abort();
+			if (options.container === void 0) container.remove();
+		}
+	};
+};
+
+//#endregion
+export { createMemoryCommands, createMemoryEvents, createMemoryLibrary, createMemorySettings, createMemoryStorage, createSchemaValidator, loadCommands, loadEvents, loadExerciseType, loadGradePolicy, loadPanel, loadView };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@dolphy-app/extension-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "SDK for extension authors: defineExtension, defineAnswerView, test helpers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@dolphy-app/extension-api": "0.3.0",
+    "ajv": "^8"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dolphy-app/dolphy.git",
+    "directory": "packages/extension-sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}