@dolphy-app/extension-sdk 0.4.0 → 0.5.0

package/docs/recipe-theme.md

@@ -1,7 +1,8 @@
 # Recipe: a theme
 
-A theme is data: no TypeScript, no `main.mjs`. This recipe is the `theme`
-template (`npx @dolphy-app/create-extension <dir> --id acme.hello --template theme`).
+A theme is data that the client part registers: no server part, no `main.mjs`.
+This recipe is the `theme` template
+(`npx @dolphy-app/create-extension <dir> --id acme.hello --template theme`).
 The files below are exactly what the generator writes for the id `acme.hello`.
 See [quick-start.md](quick-start.md) for the commands.
 
@@ -18,49 +19,74 @@ File `extension.json` (theme):
   "name": "Midnight",
   "description": "A dark color theme with an amber accent for the Dolphy app.",
   "author": "your-github-login",
-  "tags": ["theme"],
-  "contributes": {
-    "themes": [
-      {
-        "id": "acme.hello",
-        "label": "Midnight",
-        "dark": true,
-        "colors": {
-          "background": "#101820",
-          "surface": "#1B2733",
-          "on-background": "#E6EDF3",
-          "on-surface": "#E6EDF3",
-          "primary": "#FFB000",
-          "on-primary": "#101820"
-        },
-        "variables": { "border-opacity": 0.2 }
-      }
-    ]
-  }
+  "tags": ["theme"]
 }
 ```
 
-- `contributes.themes[]` has an `id` (not `system`, `light` or `dark`), a
-  `label` of 1–60 characters and `dark`, which says whether the theme is dark
-  and so picks the base colors of the interface that `colors` then override.
+The manifest holds the identity only; the colors are in the code.
+
+## The code
+
+File `src/theme.ts` (theme):
+
+```ts
+import type { ThemeRegistration } from '@dolphy-app/extension-sdk';
+
+// the allowed color and variable keys are `THEME_COLOR_KEYS` and
+// `THEME_VARIABLE_KEYS` of '@dolphy-app/extension-sdk'
+export const midnight: ThemeRegistration = {
+  id: 'acme.hello',
+  label: 'Midnight',
+  dark: true,
+  colors: {
+    background: '#101820',
+    surface: '#1B2733',
+    'on-background': '#E6EDF3',
+    'on-surface': '#E6EDF3',
+    primary: '#FFB000',
+    'on-primary': '#101820',
+  },
+  variables: { 'border-opacity': 0.2 },
+};
+```
+
+File `src/index.ts` (theme):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { midnight } from './theme.ts';
+
+// runs in the app window: a theme is data, there is no server part
+export const client = defineClient((c) => {
+  c.addTheme(midnight);
+});
+```
+
+- `client.addTheme(registration)` adds a tile to Settings → Appearance next to
+  System, Light and Dark. `id` is the extension id or starts with it and a dot,
+  and is not `system`, `light` or `dark`; `label` is a `LocalizedText` of 1–60
+  characters; `dark` says whether the theme is dark, which picks the base colors
+  of the interface that `colors` then override.
 - `colors` are `#rrggbb` or `#rrggbbaa` values for a fixed list of roles
   (`background`, `surface`, `primary`, the `on-…` colors for text drawn on them,
-  `error`, `success`…). A key outside the list is rejected by `pnpm validate`.
-  Pair every background with a readable text color.
-- `variables` are optional tokens from a fixed list; here `border-opacity`, a
-  number from 0 to 1.
-- `build` of a project with no code writes only `extension.json` to `dist-ext`.
+  `error`, `success`…). The list is `THEME_COLOR_KEYS` of the SDK; a key outside
+  it fails the registration. Pair every background with a readable text color.
+- `variables` are optional tokens from `THEME_VARIABLE_KEYS`; here
+  `border-opacity`, a number from 0 to 1.
+- The build of this project writes `extension.json` and `client.mjs` to
+  `dist-ext`: there is no `server` export, so no `main.mjs`.
 
 ## The test
 
 File `test/theme.test.ts` (theme):
 
 ```ts
+import { createTestClient } from '@dolphy-app/extension-sdk/testing';
 import { describe, expect, it } from 'vitest';
-import manifest from '../extension.json';
+import { client } from '../src/index.ts';
+import { midnight } from '../src/theme.ts';
 
-const [theme] = manifest.contributes.themes;
-const colors: Record<string, string> = theme.colors;
+const colors = midnight.colors;
 
 // WCAG relative luminance of a #rrggbb color
 const luminance = (hex: string): number => {
@@ -79,6 +105,12 @@ const contrast = (foreground: string, background: string): number => {
 };
 
 describe('acme.hello: theme', () => {
+  it('the client adds the theme', async () => {
+    const running = await createTestClient(client, { extensionId: 'acme.hello' });
+    expect(running.themes).toEqual([midnight]);
+    await running.dispose();
+  });
+
   it.each([
     ['on-surface', 'surface'],
     ['on-background', 'background'],
@@ -91,16 +123,16 @@ describe('acme.hello: theme', () => {
   it('a dark theme has a dark background and a light text', () => {
     const background = luminance(colors['background'] as string);
     const text = luminance(colors['on-background'] as string);
-    expect(theme.dark ? background < text : background > text).toBe(true);
+    expect(midnight.dark ? background < text : background > text).toBe(true);
   });
 });
 ```
 
-A project with no code still has something worth testing. The test reads the
-manifest and checks the WCAG contrast of each text color against its background
-(at least 4.5:1) and that `dark` agrees with the colors. A failing contrast is a
-real bug the learner would see, and the test also gives `vitest run` a file to
-run. Keep the test when you change the colors.
+`createTestClient(client, { extensionId })` runs `client` on a context that
+records what it adds, so the test sees the theme in `running.themes`. The rest
+checks the WCAG contrast of each text color against its background (at least
+4.5:1) and that `dark` agrees with the colors. A failing contrast is a real bug
+the learner would see. Keep the test when you change the colors.
 
 ## Try and ship
 
@@ -111,6 +143,6 @@ pnpm dev
 ```
 
 With `DOLPHY_DEV_EXTENSIONS` pointing at `dist-ext` (see the quick start) the
-theme appears as a tile in Settings → Appearance next to System, Light and
-Dark; saving `extension.json` is picked up by the running app. Change the id, the label and the colors; change `tags` and
+theme appears as a tile in Settings → Appearance; saving a file is picked up by
+the running app. Change the id, the label and the colors; change `tags` and
 `description` too, the catalog shows them.

package/docs/recipe-when-dependencies.md

@@ -1,11 +1,10 @@
-# Recipe: visibility conditions and dependencies
+# Recipe: visibility conditions, a widget and dependencies
 
-Show a command, a panel or a widget only where it makes sense (`when`), and
-require another extension (`dependencies`). Both are manifest data, so this
-recipe is a small project whose test reads the manifest. This recipe has no
-template of its own: start from `blank` and replace the three files below,
-which are checked as a whole project. See [quick-start.md](quick-start.md) for
-the commands.
+Show a command or a panel only where it makes sense (`when`), draw a component
+into a screen of the app (an injection), and require another extension
+(`dependencies`). This recipe has no template of its own: start from `blank`
+and replace the files below, which are checked as a whole project. See
+[quick-start.md](quick-start.md) for the commands.
 
 ## The manifest
 
@@ -24,83 +23,146 @@ File `extension.json` (when-dependencies):
   "dependencies": [
     { "id": "acme.cards", "range": ">=1.0.0 <2.0.0" },
     { "id": "dolphy.choice" }
-  ],
-  "contributes": {
-    "commands": [
-      {
-        "id": "acme.hello.report",
-        "title": "Course report",
-        "when": "route == 'courses' && course.active"
-      }
-    ],
-    "panels": [
-      {
-        "id": "acme.hello.board",
-        "title": "Course board",
-        "when": "course.active && !session.active"
-      }
-    ]
-  }
+  ]
 }
 ```
 
-- `when` is a boolean expression over five keys of the app window: `route`
-  (the name of the current screen), `course.active` (one course is in focus),
-  `session.active` (a study session is open), `locale` (`ru` or `en`) and
-  `theme.dark`. Operators: `==`, `!=`, `in ('a', 'b')`, `&&`, `||`, `!` and
-  parentheses; strings are in single quotes. At most 200 characters. An unknown
-  key or value, a wrong type or a syntax error is a manifest error with the
-  position, so `pnpm validate` catches a typo before the app does.
-- While the condition is false a command is not in the palette and its keys do
-  nothing, a panel's menu item is hidden, and a widget is not drawn. The value
-  follows the route, the course, the session, the language and the theme
-  without a reload. Your own code still reaches the command (`ctx.call`) and
-  the panel (`openPanel`): `when` hides, it does not forbid.
-- `dependencies` lists up to 16 extensions that must be present, enabled,
-  loaded and in the version `range` (comparators separated by a space, such as
-  `>=1.0.0 <2.0.0`; no `^` or `~`). Otherwise the extension is shown as
-  "dependencies not met" in Settings → Extensions, with the missing, disabled
-  or mismatched one named, and contributes nothing. Disabling or enabling a
-  dependency updates the dependents at once.
-- Nothing installs a dependency for the user, and extensions cannot call each
-  other: a dependency only says "this must be there". A repeat and a dependency
-  on yourself are manifest errors; extensions that depend on each other in a
-  circle are not loaded.
+`dependencies` is the only part of this recipe that lives in the manifest: up to
+16 extensions that must be present, enabled, loaded and in the version `range`
+(comparators separated by a space, such as `>=1.0.0 <2.0.0`; no `^` or `~`).
+Otherwise the extension is shown as "dependencies not met" in Settings →
+Extensions, with the missing, disabled or mismatched one named, and contributes
+nothing. Disabling or enabling a dependency updates the dependents at once.
+
+Nothing installs a dependency for the user, and extensions cannot call each
+other: a dependency only says "this must be there". A repeat and a dependency on
+yourself are manifest errors; extensions that depend on each other in a circle
+are not loaded.
 
 ## The code
 
 File `src/index.ts` (when-dependencies):
 
 ```ts
-import { defineExtension, defineExtensionPanel } from '@dolphy-app/extension-sdk';
-import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
+
+File `src/server.ts` (when-dependencies):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+
+export const server = defineServer((s) => {
+  s.registerCommand({
+    id: 'acme.hello.report',
+    title: { en: 'Course report', ru: 'Отчёт по курсу' },
+    when: "route == 'courses' && course.active",
+    run: () => ({ courses: 1 }),
+  });
+});
+```
+
+File `src/client.ts` (when-dependencies):
+
+```ts
+import { anchorSelector, defineClient } from '@dolphy-app/extension-sdk';
+import { Board } from './board.ts';
+import { PlanNote } from './plan-note.ts';
+
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.hello.board',
+    title: { en: 'Course board', ru: 'Доска курса' },
+    when: 'course.active && !session.active',
+    component: Board,
+  });
+
+  // drawn inside the "Daily plan" screen, at the anchor the app keeps stable
+  c.addInjection({
+    id: 'acme.hello.plan-note',
+    target: anchorSelector('dailyPlan'),
+    component: PlanNote,
+  });
+});
+```
+
+File `src/board.ts` (when-dependencies):
+
+```ts
+import { defineComponent, h } from 'vue';
 
-export const host = defineExtension({
-  commands: { 'acme.hello.report': () => ({ courses: 1 }) },
+export const Board = defineComponent({
+  setup: () => () => h('p', 'Board'),
 });
+```
+
+File `src/plan-note.ts` (when-dependencies):
 
-export const panels = {
-  'acme.hello.board': defineExtensionPanel({
-    mount(container) {
-      container.textContent = 'Board';
-    },
-  }),
-} satisfies ExtensionPanels;
+```ts
+import { useInjection } from '@dolphy-app/extension-sdk/client';
+import { defineComponent, h } from 'vue';
+
+// `useInjection()` tells the component where the app drew it
+export const PlanNote = defineComponent({
+  setup() {
+    const injection = useInjection();
+    return () => h('p', `Drawn at the daily plan: ${injection.position}`);
+  },
+});
 ```
 
-The conditions are in the manifest, so the code is ordinary: it does not check
-where it is shown. The command and the panel are only reachable where the
-condition is true.
+- `when` is a boolean expression over five keys of the app window: `route`
+  (the name of the current screen, one of `WHEN_ROUTES`), `course.active` (one
+  course is in focus), `session.active` (a study session is open), `locale`
+  (`ru` or `en`) and `theme.dark`. Operators: `==`, `!=`, `in ('a', 'b')`, `&&`,
+  `||`, `!` and parentheses; strings are in single quotes. At most 200
+  characters. It goes on a command (`server.registerCommand`, also on one of its
+  `keybindings`), a client command (`client.addCommand`) or a panel
+  (`client.addPanel`). An unknown key or value, a wrong type or a syntax error
+  fails the registration with the position in the message.
+- While the condition is false a command is not in the palette and its keys do
+  nothing, and a panel's menu item is hidden. The value follows the route, the
+  course, the session, the language and the theme without a reload. Your own code
+  still reaches the command (`panel.call`) and the panel (`openPanel`): `when`
+  hides, it does not forbid.
+- `client.addInjection({ id, target, position?, component })` draws the
+  component at every element that matches the CSS selector `target`: `before` or
+  `after` it, or inside it as its first (`prepend`) or last (`append`, the
+  default) child. The window watches its DOM: the component is mounted when a
+  target appears and removed when it goes away or when the extension is
+  unloaded. An injection has no `when`: it exists where the target does.
+- `anchorSelector('dailyPlan')` is `[data-ext-anchor="dailyPlan"]`, the place
+  the app marks in the "Daily plan" screen and keeps stable. Any other selector
+  depends on the markup of the app, which can change between versions, so the
+  injection may silently stop finding its target after an update; prefer an
+  anchor.
+- The injected component runs in the app's own tree: `inject`, Vuetify, the
+  theme and the language work. A failure shows an error card in its place and
+  does not touch the rest of the window.
 
 ## The test
 
-File `test/when.test.ts` (when-dependencies):
+File `test/index.test.ts` (when-dependencies):
 
 ```ts
-import { evaluateWhen, parseWhen } from '@dolphy-app/extension-sdk';
+// @vitest-environment happy-dom
+import {
+  INJECTION_HANDLE_KEY,
+  anchorSelector,
+  evaluateWhen,
+  parseWhen,
+} from '@dolphy-app/extension-sdk';
 import type { WhenContext } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+} from '@dolphy-app/extension-sdk/testing';
 import { describe, expect, it } from 'vitest';
+import { createApp, h } from 'vue';
 import manifest from '../extension.json';
+import { client, server } from '../src/index.ts';
+import { PlanNote } from '../src/plan-note.ts';
 
 const context = (overrides: Partial<WhenContext> = {}): WhenContext => ({
   route: 'courses',
@@ -111,27 +173,35 @@ const context = (overrides: Partial<WhenContext> = {}): WhenContext => ({
   ...overrides,
 });
 
-const [command] = manifest.contributes.commands;
-const [panel] = manifest.contributes.panels;
+const parsed = (when: string | null | undefined) => {
+  if (when === null || when === undefined) throw new Error('no condition');
+  return parseWhen(when);
+};
 
 describe('acme.hello: when', () => {
-  it('shows the report on the Courses screen with a course in focus', () => {
-    const when = parseWhen(command.when);
-    expect(evaluateWhen(when, context())).toBe(true);
-    expect(evaluateWhen(when, context({ route: 'daily-plan' }))).toBe(
-      false,
+  it('shows the report on the Courses screen with a course in focus', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.hello',
+    });
+    const report = running.registration.commands.find(
+      ({ id }) => id === 'acme.hello.report',
     );
-    expect(
-      evaluateWhen(when, context({ 'course.active': false })),
-    ).toBe(false);
+    const when = parsed(report?.when);
+    expect(evaluateWhen(when, context())).toBe(true);
+    expect(evaluateWhen(when, context({ route: 'daily-plan' }))).toBe(false);
+    expect(evaluateWhen(when, context({ 'course.active': false }))).toBe(false);
+    await running.dispose();
   });
 
-  it('hides the board during a study session', () => {
-    const when = parseWhen(panel.when);
+  it('hides the board during a study session', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.hello',
+    });
+    const board = running.panels.find(({ id }) => id === 'acme.hello.board');
+    const when = parsed(board?.when);
     expect(evaluateWhen(when, context())).toBe(true);
-    expect(
-      evaluateWhen(when, context({ 'session.active': true })),
-    ).toBe(false);
+    expect(evaluateWhen(when, context({ 'session.active': true }))).toBe(false);
+    await running.dispose();
   });
 
   it('reports a typo in a key with its position', () => {
@@ -139,6 +209,35 @@ describe('acme.hello: when', () => {
   });
 });
 
+describe('acme.hello: injection', () => {
+  it('is drawn at the anchor of the daily plan', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.hello',
+    });
+    expect(running.injections).toEqual([
+      {
+        id: 'acme.hello.plan-note',
+        target: anchorSelector('dailyPlan'),
+        position: 'append',
+        component: PlanNote,
+      },
+    ]);
+    await running.dispose();
+  });
+
+  it('the component reads where the app drew it', () => {
+    const host = document.createElement('div');
+    const app = createApp({ render: () => h(PlanNote) });
+    app.provide(INJECTION_HANDLE_KEY, {
+      target: document.createElement('div'),
+      position: 'append',
+    });
+    app.mount(host);
+    expect(host.textContent).toBe('Drawn at the daily plan: append');
+    app.unmount();
+  });
+});
+
 describe('acme.hello: dependencies', () => {
   it('names each required extension once, and not itself', () => {
     const ids = manifest.dependencies.map(({ id }) => id);
@@ -148,11 +247,18 @@ describe('acme.hello: dependencies', () => {
 });
 ```
 
-`parseWhen` and `evaluateWhen` are the functions the app and `dolphy-ext
-validate` use. `evaluateWhen` is pure: pass an object with the five keys.
+`createTestServer` and `createTestClient` hand the test what the code
+registered: `running.registration.commands` for the server (with `when` as
+registered) and `running.panels` and `running.injections` for the client. The
+test feeds that text to `parseWhen` and `evaluateWhen`, the functions the app
+uses; `evaluateWhen` is pure, so pass an object with the five keys. The
+dependencies are manifest data, so the test reads `extension.json`.
 
 ## Try and ship
 
-Run `pnpm validate`: it fails on a bad `when` or a bad `dependencies` entry.
-In the app the extension's row in Settings → Extensions shows "dependencies not
-met" until `acme.cards` is installed and enabled.
+Run `pnpm build` and `pnpm validate`, which fails on a bad `dependencies`
+entry. The test parses every `when`, so `pnpm test` catches a typo before the
+app does (the app fails the registration with the position). In the app the
+extension's row in Settings → Extensions shows "dependencies not met" until
+`acme.cards` is installed and enabled. Open the Daily plan screen to see the
+injected note.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dolphy-app/extension-sdk",
-  "version": "0.4.0",
-  "description": "SDK for extension authors: defineExtension, defineAnswerView, test helpers",
+  "version": "0.5.0",
+  "description": "SDK for extension authors: defineServer, defineClient, defineRpc, usePanel, useInjection, useApp, useEngine, useRpc, defineMountable, callRpc, reactComponent, test harness",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -9,13 +9,21 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "default": "./dist/runtime.js"
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "default": "./dist/rpc.js"
     },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -24,8 +32,22 @@
     "docs"
   ],
   "dependencies": {
-    "@dolphy-app/extension-api": "0.4.0",
-    "ajv": "^8"
+    "@dolphy-app/extension-api": "0.5.0",
+    "ajv": "^8",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "vue": "^3.5",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.12"

package/dist/answer-element-BOQcuxYh.js

@@ -1,114 +0,0 @@
-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 };