@dolphy-app/extension-sdk 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,116 +1,12 @@
-import { a as defineAnswerView, i as MountAnswerView, n as AnswerViewApi, r as AnswerViewInstance, t as AnswerView } from "./answer-view-D6wnyThb.js";
-import { CommandHandler, ExerciseTypeHandler, ExporterHandler, ExtensionContext as ExtensionContext$1, ExtensionIdSet, ExtensionModule, GradePolicyHandler, ImporterHandler, JsonValue, LearningEventHandler, MarkdownRenderContext, MarkdownRendererModule, NotifyEffect, OpenPanelEffect, PanelContext as PanelContext$1, PanelModule, ScheduleHandler, WidgetContext as WidgetContext$1, WidgetModule } from "@dolphy-app/extension-api";
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { a as MountContext, c as ServerContext, d as defineExerciseType, f as defineMountable, i as InjectionRegistration, l as ServerEntry, n as ClientContext, o as Mountable, p as defineServer, r as ClientEntry, s as PanelRegistration, t as AppApi, u as defineClient } from "./define-entry-lsuxzKdD.js";
+import { RpcTarget, callRpc, defineRpc } from "./rpc.js";
+import { JsonValue, NotifyEffect, OpenPanelEffect } 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']>;
-/** Context of a widget module; `call` accepts the declared command ids only. */
-type WidgetContext = WidgetContext$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 widgets = { … } satisfies ExtensionWidgets`: one `defineExtensionWidget` per declared widget. */
-type ExtensionWidgets = Exact<ResolvedIds['widgets'], WidgetModule<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.importers.register`, `ctx.exporters.register`, `ctx.schedule.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`,
- * `commands`, `schedules`, `importers` and `exporters` 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; }> & Section<'schedules', Ids['schedules'], { readonly [K in Ids['schedules']]: ScheduleHandler | InActivate; }> & Section<'importers', Ids['importers'], { readonly [K in Ids['importers']]: ImporterHandler | InActivate; }> & Section<'exporters', Ids['exporters'], { readonly [K in Ids['exporters']]: ExporterHandler | 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"]>;
-/** An entry of `widgets[<widget id>]` in `src/index.ts` (`contributes.widgets`); `ctx.call` accepts the declared command ids. */
-export declare const defineExtensionWidget: (module: WidgetModule<HTMLElement, ResolvedIds["commands"]>) => WidgetModule<HTMLElement, ResolvedIds["commands"]>;
+/** A command result: the app opens a panel of this extension (a panel id of `client.addPanel`); `props` reach the panel as `usePanel().props`. */
+export declare const openPanel: (panelId: string, props?: JsonValue) => OpenPanelEffect;
 //#endregion
-export { type AnswerView, type AnswerViewApi, type AnswerViewInstance, type EventHandlers, type ExtensionContext, type ExtensionDefinition, type ExtensionIds, type ExtensionMarkdown, type ExtensionPanels, type ExtensionViews, type ExtensionWidgets, type InActivate, type MountAnswerView, type PanelContext, type WidgetContext, defineAnswerView };
+export { type AppApi, type ClientContext, type ClientEntry, type ExtensionEngine, type InjectionRegistration, type MountContext, type Mountable, type PanelRegistration, type RpcTarget, type ServerContext, type ServerEntry, callRpc, defineClient, defineExerciseType, defineMountable, defineRpc, defineServer };

package/dist/index.js

@@ -1,97 +1,16 @@
+import { i as defineServer, n as defineExerciseType, r as defineMountable, t as defineClient } from "./define-entry-BTz2F3qv.js";
+import { callRpc, defineRpc } from "./rpc.js";
+
 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`. */
+/** A command result: the app opens a panel of this extension (a panel id of `client.addPanel`); `props` reach the panel as `usePanel().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.importers.register`, `ctx.exporters.register`, `ctx.schedule.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));
-		for (const [id, handler] of handlersOf(definition.schedules)) registrations.push(context.schedule.on(id, handler));
-		for (const [id, handler] of handlersOf(definition.importers)) registrations.push(context.importers.register(id, handler));
-		for (const [id, handler] of handlersOf(definition.exporters)) registrations.push(context.exporters.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;
-/** An entry of `widgets[<widget id>]` in `src/index.ts` (`contributes.widgets`); `ctx.call` accepts the declared command ids. */
-const defineExtensionWidget = /* @__NO_SIDE_EFFECTS__ */ (module) => module;
-
-//#endregion
-export { defineAnswerView, defineExerciseType, defineExtension, defineExtensionPanel, defineExtensionWidget, defineMarkdownRenderer, inActivate, notify, openPanel };
+export { callRpc, defineClient, defineExerciseType, defineMountable, defineRpc, defineServer, notify, openPanel };

package/dist/react.d.ts

@@ -0,0 +1,51 @@
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { a as MountContext$1, o as Mountable, t as AppApi$1 } from "./define-entry-lsuxzKdD.js";
+import { AppLocale, AppTheme, InjectionHandle, PanelHandle, RpcContract } from "@dolphy-app/extension-api";
+import { ComponentType } from "react";
+//#region packages/extension-sdk/src/react.d.ts
+/**
+ * The `MountContext` of the component drawn by `reactComponent`. `Props` and
+ * `Handle` are the ones of the surface: pick them by the way the component is
+ * registered. Only inside a component that `reactComponent` draws.
+ */
+export declare const useMountContext: <Props = unknown, Handle = undefined>() => MountContext$1<Props, Handle>;
+/** The window API, the same object as `useApp()` of a Vue component. Only inside a component that `reactComponent` draws. */
+export declare const useApp: () => AppApi$1;
+/** The engine client of the window, the same object as `useEngine()` of a Vue component. Only inside a component that `reactComponent` draws. */
+export declare const useEngine: () => ExtensionEngine;
+/**
+ * Binds the contract to the server part of this extension, as `useRpc` of a
+ * Vue component does: the returned function validates the input and the
+ * answer with the contract and rejects with an `Error` on a failure. The
+ * function is stable while the contract is. Only inside a component that
+ * `reactComponent` draws.
+ */
+export declare const useRpc: <Input, Output>(contract: RpcContract<Input, Output>) => ((input: Input) => Promise<Output>);
+/**
+ * The handle of the panel the component is drawn for: `panelId`, `props`,
+ * `context` (the current values; the component renders again when they change)
+ * and `call` for the commands of this extension. Only inside a panel.
+ */
+export declare const usePanel: <Commands extends string = string>() => PanelHandle<Commands>;
+/** The handle of the injected component: the `target` element and the `position`. Only inside a component that `client.addInjection` registered. */
+export declare const useInjection: () => InjectionHandle;
+/** The theme the window shows; the component renders again when it changes. Only inside a component that `reactComponent` draws. */
+export declare const useTheme: () => AppTheme;
+/** The language of the window; the component renders again when it changes. Only inside a component that `reactComponent` draws. */
+export declare const useLocale: () => AppLocale;
+export interface ReactComponentOptions {
+  /** Draws the component inside `React.StrictMode`; default `false`. */
+  strictMode?: boolean;
+}
+/**
+ * Wraps a React component into a `Mountable`: the app gives it an element, the
+ * adapter draws `<Component {...ctx.props} />` into it with `createRoot`, draws
+ * it again when the props, the theme or the language change and unmounts the
+ * root on cleanup. An error of the render goes to `ctx.reportError`. Inside
+ * the component `useApp`, `useEngine`, `useRpc`, `usePanel`, `useInjection`,
+ * `useTheme`, `useLocale` and `useMountContext` work. `Props` and `Handle` are
+ * those of the surface the component is registered for, such as
+ * `PanelProps` and `PanelHandle`.
+ */
+export declare const reactComponent: <Props extends object, Handle = undefined>(component: ComponentType<Props>, options?: ReactComponentOptions) => Mountable<Props, Handle>;
+//#endregion

package/dist/react.js

@@ -0,0 +1,112 @@
+import { r as defineMountable } from "./define-entry-BTz2F3qv.js";
+import { Component, StrictMode, createContext, createElement, useContext, useMemo } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+
+//#region packages/extension-sdk/src/react.ts
+const DolphyContext = createContext(null);
+const useDolphyState = (hook) => {
+	const state = useContext(DolphyContext);
+	if (state === null) throw new Error(`${hook}() works inside a component that reactComponent() draws, there is no Dolphy context here`);
+	return state;
+};
+/**
+* The `MountContext` of the component drawn by `reactComponent`. `Props` and
+* `Handle` are the ones of the surface: pick them by the way the component is
+* registered. Only inside a component that `reactComponent` draws.
+*/
+const useMountContext = () => {
+	const { ctx } = useDolphyState("useMountContext");
+	return ctx;
+};
+/** The window API, the same object as `useApp()` of a Vue component. Only inside a component that `reactComponent` draws. */
+const useApp = () => useDolphyState("useApp").ctx.app;
+/** The engine client of the window, the same object as `useEngine()` of a Vue component. Only inside a component that `reactComponent` draws. */
+const useEngine = () => useDolphyState("useEngine").ctx.engine;
+/**
+* Binds the contract to the server part of this extension, as `useRpc` of a
+* Vue component does: the returned function validates the input and the
+* answer with the contract and rejects with an `Error` on a failure. The
+* function is stable while the contract is. Only inside a component that
+* `reactComponent` draws.
+*/
+const useRpc = (contract) => {
+	const { ctx } = useDolphyState("useRpc");
+	return useMemo(() => (input) => ctx.callRpc(contract, input), [ctx, contract]);
+};
+/**
+* The handle of the panel the component is drawn for: `panelId`, `props`,
+* `context` (the current values; the component renders again when they change)
+* and `call` for the commands of this extension. Only inside a panel.
+*/
+const usePanel = () => {
+	const { handle } = useDolphyState("usePanel").ctx;
+	if (typeof handle !== "object" || handle === null || !("panelId" in handle)) throw new Error("usePanel() works inside a panel component that the app draws, there is no panel here");
+	return handle;
+};
+/** The handle of the injected component: the `target` element and the `position`. Only inside a component that `client.addInjection` registered. */
+const useInjection = () => {
+	const { handle } = useDolphyState("useInjection").ctx;
+	if (typeof handle !== "object" || handle === null || !("target" in handle) || !("position" in handle)) throw new Error("useInjection() works inside an injected component that the app draws, there is no injection here");
+	return handle;
+};
+/** The theme the window shows; the component renders again when it changes. Only inside a component that `reactComponent` draws. */
+const useTheme = () => useDolphyState("useTheme").theme;
+/** The language of the window; the component renders again when it changes. Only inside a component that `reactComponent` draws. */
+const useLocale = () => useDolphyState("useLocale").locale;
+/** Catches the errors of the render, reports them to the app and draws nothing: the app shows its own card in place of the element. */
+var ErrorBoundary = class extends Component {
+	state = { failed: false };
+	static getDerivedStateFromError() {
+		return { failed: true };
+	}
+	componentDidCatch(error) {
+		this.props.onError(error);
+	}
+	render() {
+		return this.state.failed ? null : this.props.children;
+	}
+};
+/**
+* Wraps a React component into a `Mountable`: the app gives it an element, the
+* adapter draws `<Component {...ctx.props} />` into it with `createRoot`, draws
+* it again when the props, the theme or the language change and unmounts the
+* root on cleanup. An error of the render goes to `ctx.reportError`. Inside
+* the component `useApp`, `useEngine`, `useRpc`, `usePanel`, `useInjection`,
+* `useTheme`, `useLocale` and `useMountContext` work. `Props` and `Handle` are
+* those of the surface the component is registered for, such as
+* `PanelProps` and `PanelHandle`.
+*/
+const reactComponent = /* @__NO_SIDE_EFFECTS__ */ (component, options = {}) => /* @__PURE__ */ defineMountable((el, ctx) => {
+	let alive = true;
+	const root = createRoot(el, {
+		onCaughtError: () => void 0,
+		onUncaughtError: (error) => ctx.reportError(error)
+	});
+	const render = () => {
+		if (!alive) return;
+		const state = {
+			ctx,
+			theme: ctx.theme,
+			locale: ctx.locale
+		};
+		const tree = createElement(DolphyContext.Provider, { value: state }, createElement(ErrorBoundary, { onError: ctx.reportError }, createElement(component, ctx.props)));
+		flushSync(() => {
+			root.render(options.strictMode === true ? createElement(StrictMode, null, tree) : tree);
+		});
+	};
+	render();
+	const stops = [
+		ctx.onProps(render),
+		ctx.onTheme(render),
+		ctx.onLocale(render)
+	];
+	return () => {
+		alive = false;
+		for (const stop of stops) stop();
+		root.unmount();
+	};
+});
+
+//#endregion
+export { reactComponent, useApp, useEngine, useInjection, useLocale, useMountContext, usePanel, useRpc, useTheme };

package/dist/rpc.d.ts

@@ -0,0 +1,28 @@
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { RpcContract } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/rpc.d.ts
+/**
+ * `export const sayHello = defineRpc({ name, input, output })`: a typed call
+ * between the client and the server part of an extension. Put the contract in a
+ * module both parts import; the server answers it with `server.handle`, a
+ * component calls it with `useRpc`. Returns `contract` as is; it checks the
+ * types and that `name` matches `RPC_NAME_PATTERN` and is at most
+ * `EXTENSION_RPC_LIMITS.nameLength` characters. Needs neither Vue nor the
+ * engine, so server code imports it.
+ */
+export declare const defineRpc: <Input, Output>(contract: RpcContract<Input, Output>) => RpcContract<Input, Output>;
+/** What `callRpc` needs from a context: `ClientContext` and `MountContext` have it. */
+export interface RpcTarget {
+  readonly extensionId: string;
+  readonly engine: ExtensionEngine;
+}
+/**
+ * Calls the server part of the extension without Vue: validates `input` with
+ * `contract.input`, calls the handler of `server.handle` through
+ * `engine.extensions.invokeRpc` and validates the answer with
+ * `contract.output`. A schema violation, an error of the handler and an
+ * unavailable server reject the promise with an `Error` that carries the
+ * message. `useRpc` and `MountContext.callRpc` do the same.
+ */
+export declare const callRpc: <Input, Output>({ engine, extensionId }: RpcTarget, contract: RpcContract<Input, Output>, input: Input) => Promise<Output>;
+//#endregion

package/dist/rpc.js

@@ -0,0 +1,37 @@
+import { EXTENSION_RPC_LIMITS, RPC_NAME_PATTERN } from "@dolphy-app/extension-api";
+
+//#region packages/extension-sdk/src/rpc.ts
+/**
+* `export const sayHello = defineRpc({ name, input, output })`: a typed call
+* between the client and the server part of an extension. Put the contract in a
+* module both parts import; the server answers it with `server.handle`, a
+* component calls it with `useRpc`. Returns `contract` as is; it checks the
+* types and that `name` matches `RPC_NAME_PATTERN` and is at most
+* `EXTENSION_RPC_LIMITS.nameLength` characters. Needs neither Vue nor the
+* engine, so server code imports it.
+*/
+const defineRpc = (contract) => {
+	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)}' must match ${RPC_NAME_PATTERN.source} and be at most ${EXTENSION_RPC_LIMITS.nameLength} characters`);
+	return contract;
+};
+/**
+* Calls the server part of the extension without Vue: validates `input` with
+* `contract.input`, calls the handler of `server.handle` through
+* `engine.extensions.invokeRpc` and validates the answer with
+* `contract.output`. A schema violation, an error of the handler and an
+* unavailable server reject the promise with an `Error` that carries the
+* message. `useRpc` and `MountContext.callRpc` do the same.
+*/
+const callRpc = async ({ engine, extensionId }, contract, input) => {
+	contract.input.parse(input);
+	const result = await engine.extensions.invokeRpc({
+		extensionId,
+		name: contract.name,
+		input
+	});
+	return contract.output.parse(result);
+};
+
+//#endregion
+export { callRpc, defineRpc };