@hodi-app/plugin-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# Writing a Hodi plugin
 
-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.
+A plugin adds to Hodi without changing its code: a server part with its own routes and tables, a web part drawn with
+Hodi's own components, settings that Hodi draws for it, and its own texts. The admin installs it from
+Réglages › Plugins with a `.hodi-plugin` file. Start from
+[`hodi-plugin-template`](https://github.com/leclaudeur/hodi-plugin-template).
+
+## A plugin's folder
+
+```text
+my-plugin/
+  plugin.json        what it is: id, name, version, api, who it is for, its settings
+  server/index.ts    optional: its server part, bundled into server.js
+  web/index.tsx      optional: its web part, bundled into web.js (and web.css from the CSS it imports)
+  locales/fr.json    its texts, one file per language (fr is the fallback)
+  assets/            optional: pictures and other files its web part asks for
+```
+
+## Two ways to write one
+
+**In its own repository** (the usual way): start from
+[`hodi-plugin-template`](https://github.com/leclaudeur/hodi-plugin-template), which depends on this package,
+`@hodi-app/plugin-sdk`:
+
+```bash
+npm install --save-dev @hodi-app/plugin-sdk
+npx hodi-plugin build                       # the current folder into dist/<id>-<version>.hodi-plugin
+```
+
+Its `tsconfig.json` lists `"@hodi-app/plugin-sdk/hodi-sdk"` in `"types"`, so `import … from 'hodi:sdk'` is typed, and the
+server part takes its types from `@hodi-app/plugin-sdk/server`.
+
+**Inside a clone of Hodi**, as the test plugin `plugin-sdk/test/hello-world` is: `tsconfig.plugins.json` maps `hodi:sdk` to its source, and
+
+```bash
+npm run plugin:build -- path/to/my-plugin
+```
+
+## Signing
+
+A package is unsigned unless a key is given: `hodi-plugin build --key private.pem` (an ed25519 key, PEM). Hodi says
+"Vérifié" only when the key that signed it is one of the keys it trusts (`TRUSTED_KEYS` in
+`server/plugins/package.ts`): that is the maintainer's key, for Hodi's official plugins. Every other plugin installs as
+"Code non vérifié", after a second question. Keep a private key out of every repository and plugin folder.
+
+## `plugin.json`
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My plugin",
+  "version": "1.0.0",
+  "description": "One sentence, shown in Réglages › Plugins.",
+  "api": 1,
+  "audience": "all",
+  "settings": [{ "key": "greeting", "type": "text", "default": "Bonjour" }]
+}
+```
+
+- `id`: lowercase letters, digits and dashes. It names the plugin's folder, its routes (`/api/plugins/<id>/…`) and its
+  tables (`plugin_<id>_…`, with dashes as underscores).
+- `api`: the plugin API it is written for. Hodi does not load a plugin written for another major version.
+- `audience`: `all` (every profile) or `admin` (the household's admin only): who sees its pages and reaches its routes.
+- `settings`: `boolean`, `number` (`min`, `max`), `text` (`maxLength`) or `choice` (`options`), each with a `default`.
+  Hodi draws them on the plugin's page; their labels are `settings.<key>`, `settings.<key>Hint` and
+  `settings.<key>Options.<option>` in the plugin's locales.
+
+`server/plugins/manifest.ts` is the full reference.
+
+## The server part
+
+`server/index.ts` exports a `ServerPlugin` by default (types in `@hodi-app/plugin-sdk/server`, `plugin-sdk/server.ts` here):
+
+- `migrations`: its own `CREATE TABLE`/`ALTER TABLE` steps, in order. Each runs once. Never edit or reorder one
+  that is released: add a new one.
+- `routes(router, ctx)`: an Express router served at `/api/plugins/<id>/`, to the signed-in profiles the plugin is
+  for, while it is on.
+
+- `onArticle(article, ctx)`: told of each article Hodi reads from its site for the first time (in the reader or in
+  the background), while the plugin is on. It must return at once; slow work goes in the background.
+
+It never imports Hodi's modules. Its context gives it what it may use: `ctx.db` (its own tables only), `ctx.settings()`,
+`ctx.fetchText` (Hodi's guarded outgoing requests), `ctx.log`, `ctx.dataDir` (a folder of its own, kept in backups) and
+`ctx.articles`:
+
+- `ctx.articles.get(id)`: an article a source listed, with its reader text when it has one (`status` `ok`,
+  `unreadable` or `failed`); `null` for an id Hodi never listed.
+- `ctx.articles.page(id)`: its page as the site serves it now, fetched again from the source's own domains; `null`
+  when it cannot be had.
+
+A JSON body sent to the plugin's routes is read for it, up to 64 KB. Anything else, such as an image, reaches the
+route unread: read the request stream yourself and set your own size limit.
+
+## The web part
+
+`web/index.tsx` imports React and `hodi:sdk`, which the page gives it, and calls `definePlugin()` once:
+
+```tsx
+import { Button, definePlugin, usePluginApi, usePluginTranslation } from 'hodi:sdk'
+
+const Page = () => {
+  const { t } = usePluginTranslation()
+  const api = usePluginApi() // api('/hello') asks /api/plugins/<id>/hello
+  return <Button onClick={() => void api('/hello', { method: 'POST' })}>{t('say')}</Button>
+}
+
+definePlugin({ settingsPage: Page })
+```
+
+`definePlugin()` takes:
+
+- `settingsPage`: drawn under the plugin's options in Réglages › Plugins.
+- `page`: a page of its own, an entry of Réglages placed by the manifest's `menu` (`group`: `reading`, `subjects`, `you`,
+  `household`, `device` or `about`; `after`: the entry it follows, such as `ai`). An unknown group or entry puts it at the end of the
+  household's group. It gets `layout` (`desktop` or `phone`): draw it with `SectionPage`, as Hodi's own pages.
+- `menuIcon`: that entry's icon, drawn at 18 px (a Lucide icon the plugin bundles); a puzzle piece without one.
+- `menuHint`: the line under the entry's name, as Hodi's entries say what they hold ("12 articles signalés"); the
+  plugin's description without one.
+- `readerAction`: drawn at the end of an article beside "Lire l'original". It gets `article` (`id`, `title`, `url`,
+  `sourceId`, `sourceName`) and usually draws a `ReaderButton`, which looks like that link, with `done` once the action
+  is done for this article.
+
+`hodi:sdk` (`web/src/plugins/sdk.ts`) has Hodi's components (`Button`, `Dialog`, `FilterChip`, `SettingsCard`,
+`SettingRow`, `SourceAvatar`, `Toggle`, …), `shortAgo` to date an article as cards do, its
+confirmations and toasts, and hooks scoped to the plugin. Use Hodi's CSS variables for colours, and prefix your class
+names with the plugin's id: its styles share the page with Hodi's.
+
+### Links and screens
+
+A plugin never writes one of Hodi's addresses (`#/article/…`, `#/settings/…`): Hodi's routes may change, and a plugin
+built against them would break. It asks Hodi for them instead, and they follow Hodi:
+
+```tsx
+import { Button, navigate, usePluginLinks, usePluginPath } from 'hodi:sdk'
+
+const Page = () => {
+  const links = usePluginLinks()
+  // Its own screens live under its page: #/settings/plugin/<id>/<path>, '' at the root.
+  const path = usePluginPath()
+  return path === 'history' ? (
+    <a href={links.page()}>Back</a>
+  ) : (
+    <>
+      <a href={links.article(articleId)}>Open the article</a>
+      <Button onClick={() => navigate(links.page('history'))}>History</Button>
+    </>
+  )
+}
+```
+
+`usePluginLinks()` gives `frontPage`, `article(id)`, `settings`, `plugins` (Réglages › Plugins) and `page(path?)`, the
+plugin's own page or one of its screens. `navigate(href)` goes there from a button or after an action.
+
+Hodi's rules hold for plugins too: no AI call without a click, every text in the locales, French says « tu ».
+
+## The package itself
+
+`@hodi-app/plugin-sdk` is built from this folder with `npm run plugin-sdk:build` (tsdown): the build command with the parts of
+Hodi it needs bundled in, and the types of the server part and of `hodi:sdk` generated from Hodi's own code, so they
+never drift from it. To publish a version, raise `version` in `plugin-sdk/package.json` in a pull request, then, once
+it is merged, push a tag `sdk-v<version>` on main (`git tag sdk-v0.2.0 && git push origin sdk-v0.2.0`): the "Publish
+plugin SDK" workflow checks, builds and publishes it. Removing or changing anything in `hodi:sdk` or the server context needs a new
+major version of the plugin API.

package/dist/bin.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { t as buildPlugin } from "./build-KyLGWV-_.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+// cli.ts
+const usage = "Usage: hodi-plugin build [plugin folder] [--key private.pem]";
+const run = async (args) => {
+	const rest = args[0] === "build" ? args.slice(1) : args;
+	const keyAt = rest.indexOf("--key");
+	const keyFile = keyAt === -1 ? void 0 : rest[keyAt + 1];
+	if (keyAt !== -1 && !keyFile) throw new Error(usage);
+	const folders = rest.filter((_arg, index) => keyAt === -1 || index !== keyAt && index !== keyAt + 1);
+	if (folders.length > 1 || folders.some((folder) => folder.startsWith("-"))) throw new Error(usage);
+	const built = await buildPlugin(path.resolve(folders[0] ?? "."), { key: keyFile ? readFileSync(keyFile, "utf8") : void 0 });
+	console.log(`${built.signed ? "Signed" : "Unsigned"} package: ${path.relative(process.cwd(), built.file)}`);
+};
+// bin.ts
+await run(process.argv.slice(2)).catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exit(1);
+});
+export {};

package/dist/build-KyLGWV-_.mjs

@@ -0,0 +1,188 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createHash, sign } from "node:crypto";
+import { create } from "tar";
+import { build } from "vite";
+const CAPABILITIES = [
+	"profile-kind:child",
+	"shell:child",
+	"speech"
+];
+const AUDIENCES = ["admin", "all"];
+const ID = /^[a-z][a-z0-9-]{1,31}$/;
+const RESERVED_IDS = ["packages"];
+const KEY = /^[a-zA-Z][a-zA-Z0-9]{0,31}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const MAX_SETTINGS = 32;
+const MAX_TEXT = 2e3;
+var ManifestError = class extends Error {};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value, field, max) => {
+	if (typeof value !== "string" || !value.trim() || value.length > max) throw new ManifestError(`${field} must be a non-empty text of at most ${max} characters`);
+	return value.trim();
+};
+const parseSetting = (value, index) => {
+	if (!isRecord(value)) throw new ManifestError(`settings[${index}] must be an object`);
+	const { key, type } = value;
+	if (typeof key !== "string" || !KEY.test(key)) throw new ManifestError(`settings[${index}].key is not a valid key`);
+	if (type === "boolean" && typeof value.default === "boolean") return {
+		key,
+		type,
+		default: value.default
+	};
+	if (type === "number" && typeof value.default === "number" && Number.isFinite(value.default)) {
+		const min = typeof value.min === "number" ? value.min : void 0;
+		const max = typeof value.max === "number" ? value.max : void 0;
+		if (min !== void 0 && value.default < min || max !== void 0 && value.default > max) throw new ManifestError(`settings[${index}].default is out of its range`);
+		return {
+			key,
+			type,
+			default: value.default,
+			min,
+			max
+		};
+	}
+	if (type === "text" && typeof value.default === "string") {
+		const maxLength = typeof value.maxLength === "number" ? Math.min(value.maxLength, MAX_TEXT) : MAX_TEXT;
+		if (value.default.length > maxLength) throw new ManifestError(`settings[${index}].default is too long`);
+		return {
+			key,
+			type,
+			default: value.default,
+			maxLength
+		};
+	}
+	if (type === "choice" && Array.isArray(value.options) && value.options.length > 0 && value.options.every((option) => typeof option === "string" && KEY.test(option)) && value.options.includes(value.default)) return {
+		key,
+		type,
+		default: value.default,
+		options: value.options
+	};
+	throw new ManifestError(`settings[${index}] has an unknown type or a default that does not fit it`);
+};
+const parseManifest = (value) => {
+	if (!isRecord(value)) throw new ManifestError("plugin.json must hold an object");
+	const { id, version, api } = value;
+	if (typeof id !== "string" || !ID.test(id)) throw new ManifestError("id must be lowercase letters, digits and dashes");
+	if (RESERVED_IDS.includes(id)) throw new ManifestError(`${id} is a name Hodi keeps for itself`);
+	if (typeof version !== "string" || !VERSION.test(version)) throw new ManifestError("version must be like 1.2.3");
+	if (api !== 1) throw new ManifestError(`api must be 1, this plugin was written for ${api}`);
+	const audience = value.audience ?? "all";
+	if (!AUDIENCES.includes(audience)) throw new ManifestError("audience must be admin or all");
+	const provides = value.provides ?? [];
+	if (!Array.isArray(provides) || !provides.every((entry) => CAPABILITIES.includes(entry))) throw new ManifestError(`provides may only hold ${CAPABILITIES.join(", ")}`);
+	let menu = null;
+	if (value.menu !== void 0) {
+		if (!isRecord(value.menu) || typeof value.menu.group !== "string" || !KEY.test(value.menu.group)) throw new ManifestError("menu.group must name a group of Réglages");
+		const { after, icon } = value.menu;
+		if (after !== void 0 && (typeof after !== "string" || !KEY.test(after))) throw new ManifestError("menu.after must name an entry of Réglages");
+		if (icon !== void 0 && (typeof icon !== "string" || !/^[A-Z][A-Za-z0-9]{0,47}$/.test(icon))) throw new ManifestError("menu.icon must be the name of a Lucide icon");
+		menu = {
+			group: value.menu.group,
+			...after ? { after } : {},
+			...icon ? { icon } : {}
+		};
+	}
+	const settings = value.settings ?? [];
+	if (!Array.isArray(settings) || settings.length > MAX_SETTINGS) throw new ManifestError(`settings must be a list of at most ${MAX_SETTINGS}`);
+	const specs = settings.map(parseSetting);
+	if (new Set(specs.map((spec) => spec.key)).size !== specs.length) throw new ManifestError("settings keys must differ");
+	return {
+		id,
+		name: text(value.name, "name", 60),
+		version,
+		description: text(value.description, "description", 280),
+		api,
+		audience,
+		provides: [...new Set(provides)],
+		menu,
+		settings: specs
+	};
+};
+// ../server/plugins/package.ts
+const SIGNATURE_FILE = "signature";
+const packageDigest = (root) => {
+	const lines = [];
+	const walk = (dir) => {
+		for (const name of readdirSync(dir).sort()) {
+			const file = path.join(dir, name);
+			const relative = path.relative(root, file).split(path.sep).join("/");
+			if (lstatSync(file).isDirectory()) walk(file);
+			else if (relative !== SIGNATURE_FILE) lines.push(`${relative}\t${createHash("sha256").update(readFileSync(file)).digest("hex")}`);
+		}
+	};
+	walk(root);
+	return Buffer.from(lines.join("\n"));
+};
+// build.ts
+const WEB_GLOBALS = {
+	react: "__hodi.react",
+	"react/jsx-runtime": "__hodi.jsxRuntime",
+	"react-dom": "__hodi.reactDom",
+	"hodi:sdk": "__hodi.sdk"
+};
+const firstOf = (dir, names) => names.map((name) => path.join(dir, name)).find((file) => existsSync(file)) ?? null;
+const buildPlugin = async (source, { out = path.join(source, "dist"), key } = {}) => {
+	const manifest = parseManifest(JSON.parse(readFileSync(path.join(source, "plugin.json"), "utf8")));
+	const stage = path.join(out, manifest.id);
+	rmSync(stage, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(stage, { recursive: true });
+	cpSync(path.join(source, "plugin.json"), path.join(stage, "plugin.json"));
+	const server = firstOf(source, ["server/index.ts", "server/index.js"]);
+	if (server) await build({
+		configFile: false,
+		logLevel: "warn",
+		ssr: { noExternal: true },
+		build: {
+			ssr: server,
+			outDir: stage,
+			emptyOutDir: false,
+			minify: false,
+			rollupOptions: { output: {
+				format: "es",
+				entryFileNames: "server.js"
+			} }
+		}
+	});
+	const web = firstOf(source, ["web/index.tsx", "web/index.ts"]);
+	if (web) await build({
+		configFile: false,
+		logLevel: "warn",
+		define: { "process.env.NODE_ENV": "\"production\"" },
+		build: {
+			outDir: stage,
+			emptyOutDir: false,
+			cssCodeSplit: false,
+			lib: {
+				entry: web,
+				formats: ["iife"],
+				name: "__hodiPlugin",
+				fileName: () => "web.js",
+				cssFileName: "web"
+			},
+			rollupOptions: {
+				external: Object.keys(WEB_GLOBALS),
+				output: { globals: WEB_GLOBALS }
+			}
+		}
+	});
+	for (const folder of ["locales", "assets"]) if (existsSync(path.join(source, folder))) cpSync(path.join(source, folder), path.join(stage, folder), { recursive: true });
+	if (key) writeFileSync(path.join(stage, "signature"), sign(null, packageDigest(stage), key).toString("base64"));
+	const file = path.join(out, `${manifest.id}-${manifest.version}.hodi-plugin`);
+	await create({
+		gzip: true,
+		file,
+		cwd: stage,
+		portable: true
+	}, ["."]);
+	return {
+		id: manifest.id,
+		version: manifest.version,
+		file,
+		signed: Boolean(key)
+	};
+};
+export { buildPlugin as t };

package/dist/build.d.mts

@@ -0,0 +1,10 @@
+export interface BuiltPlugin {
+  id: string;
+  version: string;
+  file: string;
+  signed: boolean;
+}
+export declare const buildPlugin: (source: string, { out, key }?: {
+  out?: string;
+  key?: string;
+}) => Promise<BuiltPlugin>;

package/dist/build.mjs

@@ -0,0 +1 @@
+export { t as buildPlugin } from "./build-KyLGWV-_.mjs";

package/dist/server.d.mts

@@ -0,0 +1,91 @@
+import { Router } from "express";
+import { DatabaseSync } from "node:sqlite";
+type Database = DatabaseSync;
+interface FetchedText {
+  url: string;
+  text: string;
+}
+type FetchText = (url: string, options?: {
+  userAgent?: string;
+  headers?: Record<string, string>;
+}) => Promise<FetchedText>;
+interface PluginArticle {
+  id: string;
+  title: string;
+  url: string;
+  sourceId: string;
+  sourceName: string;
+  publishedAt: string | null;
+  status: 'ok' | 'unreadable' | 'failed';
+  text: {
+    title: string | null;
+    byline: string | null;
+    contentHtml: string;
+    textLength: number;
+  } | null;
+}
+interface PluginArticles {
+  get: (id: string) => Promise<PluginArticle | null>;
+  page: (id: string) => Promise<{
+    url: string;
+    html: string;
+  } | null>;
+}
+declare const CAPABILITIES: readonly ["profile-kind:child", "shell:child", "speech"];
+type Capability = (typeof CAPABILITIES)[number];
+declare const AUDIENCES: readonly ["admin", "all"];
+type Audience = (typeof AUDIENCES)[number];
+type SettingSpec = {
+  key: string;
+  type: 'boolean';
+  default: boolean;
+} | {
+  key: string;
+  type: 'number';
+  default: number;
+  min?: number;
+  max?: number;
+} | {
+  key: string;
+  type: 'text';
+  default: string;
+  maxLength?: number;
+} | {
+  key: string;
+  type: 'choice';
+  default: string;
+  options: string[];
+};
+type SettingValue = boolean | number | string;
+type SettingValues = Record<string, SettingValue>;
+interface MenuPlacement {
+  group: string;
+  after?: string;
+  icon?: string;
+}
+interface Manifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  api: number;
+  audience: Audience;
+  provides: Capability[];
+  menu: MenuPlacement | null;
+  settings: SettingSpec[];
+}
+interface PluginContext {
+  id: string;
+  db: Database;
+  settings: () => SettingValues;
+  fetchText: FetchText;
+  log: (message: string) => void;
+  dataDir: string;
+  articles: PluginArticles;
+}
+interface ServerPlugin {
+  migrations?: readonly string[];
+  routes?: (router: Router, context: PluginContext) => void;
+  onArticle?: (article: PluginArticle, context: PluginContext) => void;
+}
+export type { Manifest, PluginArticle, PluginArticles, PluginContext, ServerPlugin, SettingSpec, SettingValues };

package/dist/web.d.mts

@@ -0,0 +1,190 @@
+import { ButtonHTMLAttributes, ComponentType, ForwardRefExoticComponent, InputHTMLAttributes, ReactNode, RefAttributes, SVGProps } from "react";
+interface ReaderArticle {
+  id: string;
+  title: string;
+  url: string;
+  sourceId: string;
+  sourceName: string;
+}
+interface WebPlugin {
+  readerAction?: ComponentType<{
+    article: ReaderArticle;
+  }>;
+  settingsPage?: ComponentType;
+  page?: ComponentType<{
+    layout: 'desktop' | 'phone';
+  }>;
+  menuIcon?: ComponentType<{
+    size?: number;
+  }>;
+  menuHint?: ComponentType;
+}
+export declare const usePluginCapability: (capability: string) => boolean;
+type ButtonLook = 'neutral' | 'primary' | 'danger' | 'ai' | 'glass';
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  children: ReactNode;
+  look?: ButtonLook;
+  icon?: ComponentType<{
+    size?: number;
+    'aria-hidden'?: boolean | 'true';
+  }>;
+  busy?: boolean;
+  wide?: boolean;
+  compact?: boolean;
+  href?: string;
+  external?: boolean;
+}
+declare const Button: ({ children, look, icon: Icon, busy, wide, compact, href, external, className, disabled, ...props }: ButtonProps) => import("react").JSX.Element;
+declare const Chip: ({ children, label, title, tone, size }: {
+  children: ReactNode;
+  label?: string;
+  title?: string;
+  tone?: "success" | "warning" | "danger" | "accent";
+  size?: "capsule" | "row";
+}) => import("react").JSX.Element;
+interface DialogProps {
+  open: boolean;
+  onClose: () => void;
+  size?: 'compact' | 'wide';
+  title?: ReactNode;
+  onBack?: () => void;
+  labelledBy?: string;
+  describedBy?: string;
+  intro?: ReactNode;
+  className?: string;
+  children: ReactNode;
+}
+declare const Dialog: ({ open, onClose, size, title, onBack, labelledBy, describedBy, intro, className, children }: DialogProps) => import("react").JSX.Element;
+declare const DialogActions: ({ children }: {
+  children: ReactNode;
+}) => import("react").JSX.Element;
+interface EmptyStateProps {
+  icon: ReactNode;
+  title: string;
+  children?: ReactNode;
+  actions?: ReactNode;
+  tone?: 'default' | 'danger';
+  compact?: boolean;
+}
+declare const EmptyState: ({ icon, title, children, actions, tone, compact }: EmptyStateProps) => import("react").JSX.Element;
+type SVGAttributes = Partial<SVGProps<SVGSVGElement>>;
+type ElementAttributes = RefAttributes<SVGSVGElement> & SVGAttributes;
+interface LucideProps extends ElementAttributes {
+  size?: string | number;
+  /**
+   * @deprecated Use `nonScalingStroke` instead.
+   */
+  absoluteStrokeWidth?: boolean;
+  nonScalingStroke?: boolean;
+}
+type LucideIcon = ForwardRefExoticComponent<Omit<LucideProps, 'ref'> & RefAttributes<SVGSVGElement>>;
+interface FilterChipProps {
+  selected: boolean;
+  onClick?: () => void;
+  href?: string;
+  count?: number;
+  icon?: LucideIcon;
+  disabled?: boolean;
+  children: ReactNode;
+}
+declare const FilterChip: ({ selected, onClick, href, count, icon: Icon, disabled, children }: FilterChipProps) => import("react").JSX.Element;
+type RoundVariant = 'default' | 'on' | 'glass' | 'image' | 'ai' | 'danger' | 'primary';
+interface RoundButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  icon: LucideIcon;
+  label: string;
+  variant?: RoundVariant;
+  size?: 28 | 34 | 44;
+  filled?: boolean;
+  busy?: boolean;
+  href?: string;
+  external?: boolean;
+  children?: ReactNode;
+}
+declare const RoundButton: ({ icon: Icon, label, variant, size, filled, busy, href, external, className, ...props }: RoundButtonProps) => import("react").JSX.Element;
+interface SourceAvatarProps {
+  sourceId: string;
+  sourceName: string;
+  size?: 18 | 20 | 22 | 26 | 44;
+}
+declare const SourceAvatar: ({ sourceId, sourceName, size }: SourceAvatarProps) => import("react").JSX.Element;
+interface StatusLineProps {
+  tone: 'info' | 'error';
+  children: string;
+  className?: string;
+}
+declare const StatusLine: ({ tone, children, className }: StatusLineProps) => import("react").JSX.Element;
+interface TextFieldProps extends InputHTMLAttributes<HTMLInputElement> {
+  icon: LucideIcon;
+  'aria-label': string;
+  onClear?: () => void;
+}
+declare const TextField: ({ icon: Icon, type, onClear, ...props }: TextFieldProps) => import("react").JSX.Element;
+interface ToggleProps {
+  checked: boolean;
+  label: string;
+  disabled?: boolean;
+  onChange: (checked: boolean) => void;
+}
+declare const Toggle: ({ checked, label, disabled, onChange }: ToggleProps) => import("react").JSX.Element;
+interface SectionPageProps {
+  title: string;
+  intro?: ReactNode;
+  aside?: ReactNode;
+  layout: 'desktop' | 'phone';
+  children: ReactNode;
+}
+declare const SectionPage: ({ title, intro, aside, layout, children }: SectionPageProps) => import("react").JSX.Element;
+interface ReaderButtonProps {
+  children: ReactNode;
+  icon?: ReactNode;
+  onClick: () => void;
+  done?: boolean;
+  label?: string;
+}
+declare const ReaderButton: ({ children, icon, onClick, done, label }: ReaderButtonProps) => import("react").JSX.Element;
+interface SettingRowProps {
+  label: ReactNode;
+  meta?: ReactNode;
+  hint?: ReactNode;
+  lead?: ReactNode;
+  as?: 'div' | 'li';
+  className?: string;
+  children?: ReactNode;
+}
+declare const SettingRow: ({ label, meta, hint, lead, as: Tag, className, children }: SettingRowProps) => import("react").JSX.Element;
+declare const SettingsCard: ({ label, children }: {
+  label?: string;
+  children: ReactNode;
+}) => import("react").JSX.Element;
+interface Confirmation {
+  title: string;
+  message: ReactNode;
+  label: string;
+  onConfirm: () => void;
+}
+export declare const askToConfirm: (confirmation: Confirmation) => void;
+interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+export declare const showDone: (message: string, undo?: () => void) => undefined;
+export declare const showSaved: (message?: string) => undefined;
+export declare const showError: (message: string, action?: ToastAction, id?: string) => undefined;
+export declare const shortAgo: (iso: string | null, now?: number) => string | null;
+interface PluginLinks {
+  frontPage: string;
+  article: (id: string) => string;
+  settings: string;
+  plugins: string;
+  page: (path?: string) => string;
+}
+export declare const usePluginLinks: () => PluginLinks;
+export declare const navigate: (href: string) => void;
+export declare const usePluginPath: () => string;
+export declare const definePlugin: (definition: WebPlugin) => void;
+export declare const usePluginTranslation: () => {
+  t: (key: string, options?: Record<string, unknown>) => string;
+  language: string;
+};
+export declare const usePluginApi: () => (path: string, init?: RequestInit) => Promise<Response>;
+export { Button, Chip, Dialog, DialogActions, EmptyState, FilterChip, type PluginLinks, type ReaderArticle, ReaderButton, RoundButton, SectionPage, SettingRow, SettingsCard, SourceAvatar, StatusLine, TextField, Toggle };

package/hodi-sdk.d.ts

@@ -0,0 +1,5 @@
+// A plugin imports Hodi's components from 'hodi:sdk', a name the build reads from the page. This gives that name the
+// types of @hodi-app/plugin-sdk/web: a plugin lists "@hodi-app/plugin-sdk/hodi-sdk" in its tsconfig's "types".
+declare module 'hodi:sdk' {
+  export * from '@hodi-app/plugin-sdk/web'
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@hodi-app/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Build and type plugins for Hodi, the self-hosted news reader for a household.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leclaudeur/hodi.git",
+    "directory": "plugin-sdk"
+  },
+  "homepage": "https://github.com/leclaudeur/hodi/tree/main/plugin-sdk#readme",
+  "type": "module",
+  "bin": {
+    "hodi-plugin": "dist/bin.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/build.d.mts",
+      "default": "./dist/build.mjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.mts"
+    },
+    "./web": {
+      "types": "./dist/web.d.mts"
+    },
+    "./hodi-sdk": {
+      "types": "./hodi-sdk.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "hodi-sdk.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "tsdown"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "tar": "^7.5.22",
+    "vite": "^8.3.5"
+  },
+  "peerDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    },
+    "@types/node": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    }
+  }
+}