@appsoftwareltd/etherpk-extension-api 0.0.0-stage → 0.9.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 App Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# EtherPK Extension API
 
-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.
+The types an [EtherPK](https://etherpk.com) extension is written against, and the function that
+checks an extension's manifest the way the EtherPK Client does. MIT licensed.
+
+An extension is an npm package. Its package.json carries an `etherpk` manifest, and its main
+module exports `activate(context)`, which the Client calls as each graph opens:
+
+```ts
+import type { ExtensionContext } from '@appsoftwareltd/etherpk-extension-api'
+
+export function activate(context: ExtensionContext): void {
+    context.commands.register('hello.greet', () => context.notify('Hello from an extension.'))
+}
+```
+
+```json
+{
+    "name": "etherpk-extension-hello",
+    "version": "1.0.0",
+    "etherpk": {
+        "id": "hello",
+        "displayName": "Hello",
+        "publisher": "You",
+        "minClientVersion": "0.8.54",
+        "main": "./dist/main.js"
+    }
+}
+```
+
+Everything here is Proposed (`@beta` in the type declarations) and may change in any release until
+extensions from other publishers can be installed. From then on, a Stable declaration (`@public`)
+never breaks. `etc/` holds the API reports CI checks every change against.
+
+## Settings
+
+A value the person sets, such as a key for a service, is declared in the manifest, and the Client
+draws it under the extension's entry in Settings and Extensions → Extensions:
+
+```json
+"settings": [
+    {
+        "id": "api-key",
+        "type": "secret",
+        "title": "Weather service key",
+        "description": "Forecasts come from your own account with the weather service.",
+        "placeholder": "wk_…",
+        "link": { "title": "Getting a key", "url": "https://weather.example.com/keys" }
+    }
+]
+```
+
+`type` is `text`, `secret` or `boolean`. A secret stays masked until the person shows it. A
+`boolean` is a switch, which may name its starting position with `"default": true`. The person can
+set them while the extension is switched off. The extension reads the value with
+`context.settings.get('api-key')`, which is undefined until it is set, and hears every change with
+`context.settings.subscribe`. A switch always reads `'true'` or `'false'`, its default until the
+person changes it. Settings belong to the person rather than a graph. Where their
+account syncs a graph, they follow the person to their other devices, encrypted so only those
+devices can read them.
+
+## Writing to the page
+
+The Client enforces [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API),
+and extension code runs under it:
+
+- **An extension cannot create a Trusted Types policy.** The Client's Content Security Policy names
+  the policies it allows, and each belongs to the Client or a library it ships.
+- **Write no HTML.** Build elements with the DOM (`createElement`, `createElementNS`,
+  `textContent`). A string written to an HTML sink such as `innerHTML` is sanitized by the Client's
+  default policy, which may remove what you wrote.
+- **Draw icons with `context.icons.svg`.** It returns `IconMarkup`, which Svelte's `{@html}` takes
+  as it is. The icons your manifest adds are sanitized as SVG before they are drawn, so they can
+  hold only SVG.

package/dist/context.d.ts

@@ -0,0 +1,291 @@
+/**
+ * The context an extension is started with: one open graph, as far as an extension may reach it.
+ *
+ * Everything an extension adds through it sits under the extension's id and is removed when the
+ * graph closes or the extension is switched off, so an extension never has to undo its own
+ * registrations. It holds no document store, no keys and no sync: an extension reads documents
+ * only through the index's answers, and changes them only by running the Client's Commands.
+ */
+import type { ExtensionEvents } from './events';
+import type { ExtensionIndex } from './graph-index';
+import type { CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
+import type { ViewContribution, ViewRef } from './views';
+/**
+ * A Command's handler. What it returns, or resolves to, is what `execute` resolves to.
+ *
+ * @beta
+ */
+export type CommandHandler = (arg?: unknown) => unknown;
+/**
+ * Running and adding Commands.
+ *
+ * @beta
+ */
+export interface ExtensionCommands {
+    /** Add a Command, its id under the extension's id. Throws if the id is taken or outside it. */
+    register(id: string, handler: CommandHandler): () => void;
+    /** Run any Command, the Client's or an extension's. Rejects if no Command has the id. */
+    execute(id: string, arg?: unknown): Promise<unknown>;
+    /** Whether any Command has the id. */
+    has(id: string): boolean;
+}
+/**
+ * Supplying the Views the manifest declares.
+ *
+ * @beta
+ */
+export interface ExtensionViews {
+    /**
+     * Supply the View for a kind the manifest declares, so its tabs draw. Throws for a kind the
+     * manifest does not declare.
+     */
+    register(kind: string, view: ViewContribution): () => void;
+}
+/**
+ * Adding Context Menu rows.
+ *
+ * @beta
+ */
+export interface ExtensionContextMenu {
+    /** Add a row, its id under the extension's id. */
+    register(item: ContextMenuItem): () => void;
+}
+/**
+ * Adding Command Menu rows.
+ *
+ * @beta
+ */
+export interface ExtensionCommandMenu {
+    /** Add a row, its id under the extension's id. */
+    register(item: CommandMenuItem): () => void;
+}
+/**
+ * Adding buttons to the Graph Sidebar, under Today's journal.
+ *
+ * @beta
+ */
+export interface ExtensionGraphSidebar {
+    /** Add a button, its id under the extension's id. */
+    register(button: GraphSidebarButton): () => void;
+}
+/**
+ * A key chord that runs a Command.
+ *
+ * @beta
+ */
+export interface Keybinding {
+    /** `Alt+M`, `Mod+Shift+K`: `Mod` is Cmd on Apple devices and Ctrl elsewhere. */
+    key: string;
+    /** The Command it runs. */
+    command: string;
+    /** What the keyboard shortcuts card lists it as. */
+    label: string;
+    /** The card's heading it is listed under. */
+    group?: string;
+}
+/**
+ * Adding key chords.
+ *
+ * @beta
+ */
+export interface ExtensionKeybindings {
+    /** Add a chord. Throws if the Client or another extension already binds it. */
+    register(binding: Keybinding): () => void;
+}
+/**
+ * Opening Views and documents in the open graph's Layout.
+ *
+ * @beta
+ */
+export interface ExtensionLayout {
+    /**
+     * Open a View. With `inPaneOf`, a panel id, it opens as a tab in that panel's Pane. With
+     * `beside`, it opens in another Pane beside that panel, so both show at once. Otherwise it
+     * opens where its kind belongs, or comes to the front if it is open already.
+     */
+    openView(view: ViewRef, options?: {
+        inPaneOf?: string;
+        beside?: string;
+    }): void;
+    /** Bring a Sidebar resident to the front of its expanded Sidebar. */
+    reveal(kind: string): void;
+    /**
+     * Open the document of a concept, under the name it resolves to, as following a wikilink
+     * does. `line` scrolls to and selects that line, `inPaneOf` and `beside` place it as for
+     * {@link ExtensionLayout.openView}.
+     */
+    openDocument(concept: string, options?: {
+        line?: number;
+        inPaneOf?: string;
+        beside?: string;
+    }): void;
+    /** The document the user is working in, or null. */
+    activeDocument(): string | null;
+    /** True while the desktop presenter is showing, 1024 pixels wide and more. */
+    isDesktop(): boolean;
+}
+/**
+ * The rules for naming a concept, which every index answer follows.
+ *
+ * @beta
+ */
+export interface ExtensionConcepts {
+    /** The case-insensitive key of a name. */
+    key(name: string): string;
+    /** The name a concept resolves to: an alias's page, a page's own title, or the name itself. */
+    canonicalName(name: string): string;
+}
+/**
+ * The extension's own storage on this device, under `etherpk-<extension id>:` in the browser's
+ * localStorage. Values are stored as JSON.
+ *
+ * @beta
+ */
+export interface ExtensionStorage {
+    /** The value stored under `key`, or undefined when there is none or it cannot be read. */
+    get<T>(key: string): T | undefined;
+    /** Store a value. A browser that refuses storage (a private window) keeps nothing, silently. */
+    set(key: string, value: unknown): void;
+    /** Forget the value under `key`. */
+    remove(key: string): void;
+}
+/**
+ * The person's answers to the settings the extension's manifest declares (`settings`, ADR 0134).
+ * The Client draws them under the extension's entry in Settings and Extensions → Extensions, and
+ * keeps them with the person: on this device, and in their account where it syncs a graph, so they
+ * follow the person to their other devices. The extension only reads them.
+ *
+ * @beta
+ */
+export interface ExtensionSettings {
+    /**
+     * A setting's value, by its id in the manifest, or undefined when the person has not set it. A
+     * `boolean` setting is always `'true'` or `'false'`: its manifest's `default` until the person
+     * changes it.
+     */
+    get(id: string): string | undefined;
+    /**
+     * Hear every change to the person's settings, made on this device or arriving from another.
+     * Returns the way to stop.
+     */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * The Client's light or dark theme.
+ *
+ * @beta
+ */
+export interface ExtensionTheme {
+    /** True while the dark theme shows. The `theme:changed` Event reports a switch. */
+    isDark(): boolean;
+}
+/**
+ * SVG markup the Client made, for an HTML sink such as Svelte's `{@html}`. It is not a string, so a
+ * string cannot stand in for it. The Client enforces Trusted Types, and this is trusted markup there:
+ * it goes into the page as it is. A string built from it is a plain string again, which the
+ * Client's default policy sanitizes.
+ *
+ * @beta
+ */
+export interface IconMarkup {
+    /** Never present at run time. It marks the type, so a plain string is not one. */
+    readonly __brand: 'IconMarkup';
+}
+/**
+ * Drawing the Client's icons and the extension's own.
+ *
+ * @beta
+ */
+export interface ExtensionIcons {
+    /**
+     * An icon as SVG markup: the extension's own, by the name its manifest gives it, or one of the
+     * Client's. An unknown name draws a small dot. The Client sanitizes an extension's own icon
+     * before it draws it, so its markup can hold only SVG.
+     */
+    svg(name: string, options?: {
+        size?: number;
+        strokeWidth?: number;
+        label?: string;
+    }): IconMarkup;
+}
+/**
+ * One registry of every Contribution Point, by kind, for the kinds the typed parts of the context
+ * do not cover. Only a Built-in Extension uses it.
+ *
+ * @beta
+ */
+export interface ExtensionContributions {
+    /** Add a contribution. Throws if the kind already holds the id. */
+    register(kind: string, id: string, value: unknown): () => void;
+    /** Remove one of the extension's own contributions. */
+    unregister(kind: string, id: string): void;
+    /** The contribution at (`kind`, `id`), anyone's, or undefined. */
+    get(kind: string, id: string): unknown;
+    /** Whether anyone has a contribution at (`kind`, `id`). */
+    has(kind: string, id: string): boolean;
+    /** Every contribution of a kind, the extension's and everyone else's, in the order added. */
+    list(kind: string): {
+        id: string;
+        value: unknown;
+    }[];
+}
+/**
+ * What an extension is started with, once for each graph that opens.
+ *
+ * @beta
+ */
+export interface ExtensionContext {
+    /** The extension's id, from its manifest. */
+    readonly extensionId: string;
+    /** The open graph. */
+    readonly graphId: string;
+    /** The Client's version, `x.y.z`. */
+    readonly clientVersion: string;
+    /** True in a development build of the Client, where tests may reach in. */
+    readonly dev: boolean;
+    /** Supplying the Views the manifest declares. */
+    readonly views: ExtensionViews;
+    /** Running and adding Commands. */
+    readonly commands: ExtensionCommands;
+    /** Adding Context Menu rows. */
+    readonly contextMenu: ExtensionContextMenu;
+    /** Adding Command Menu rows. */
+    readonly commandMenu: ExtensionCommandMenu;
+    /** Adding buttons to the Graph Sidebar. */
+    readonly graphSidebar: ExtensionGraphSidebar;
+    /** Adding key chords. */
+    readonly keybindings: ExtensionKeybindings;
+    /** Every Contribution Point by kind, for the kinds the parts above do not cover. */
+    readonly contributions: ExtensionContributions;
+    /** Listening to Events. */
+    readonly events: ExtensionEvents;
+    /** Questions to the open graph's index. */
+    readonly index: ExtensionIndex;
+    /** Opening Views and documents. */
+    readonly layout: ExtensionLayout;
+    /** The rules for naming a concept. */
+    readonly concepts: ExtensionConcepts;
+    /** The extension's own storage on this device. */
+    readonly storage: ExtensionStorage;
+    /** The person's answers to the settings the manifest declares. */
+    readonly settings: ExtensionSettings;
+    /** The Client's light or dark theme. */
+    readonly theme: ExtensionTheme;
+    /** The Client's icons and the extension's own. */
+    readonly icons: ExtensionIcons;
+    /** Say something in passing, as the Client's own notices do: "Coordinates copied." */
+    notify(text: string): void;
+}
+/**
+ * What an extension's main module exports.
+ *
+ * @beta
+ */
+export interface ExtensionModule {
+    /**
+     * Called as each graph opens, or when the extension is switched on with a graph open. What the
+     * extension registered through the context is removed by the Client. A returned function is
+     * called after that, for anything else the extension holds.
+     */
+    activate(context: ExtensionContext): void | (() => void);
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The Events an extension may listen to. An Event reports something that happened in the Client.
+ * A listener reacts to it but cannot change it, and a listener that throws harms nothing else.
+ */
+/**
+ * Each Event's name and what it carries. Every Event belongs to the open graph, named by
+ * `graphId`.
+ *
+ * @beta
+ */
+export interface ExtensionEventPayloads {
+    /** The document the user is working in changed, or there is none (`documentId` is null). */
+    'document:active-changed': {
+        graphId: string;
+        documentId: string | null;
+    };
+    /**
+     * A concept was renamed: its page, when it has one, and every wikilink naming it. The Client's
+     * own tabs, and the extension's Views about a concept, follow by themselves; this is for state
+     * an extension keeps under the old name, and it is reported before those Views move.
+     *
+     * A rename that moves concepts scoped by the renamed one reports each concept it moved, once,
+     * under the exact name it now lives on as: the scoped concepts first and the renamed concept
+     * last. A listener that moves what it keeps by exact name, Event by Event, moves each thing
+     * once, even when the new name is one the old name scopes (`Acme` to `[[Acme]] Archive`).
+     */
+    'concept:renamed': {
+        graphId: string;
+        from: string;
+        to: string;
+    };
+    /** A document was deleted. */
+    'document:deleted': {
+        graphId: string;
+        documentId: string;
+    };
+    /** The set of documents changed: one was added, removed or renamed. */
+    'documents:changed': {
+        graphId: string;
+    };
+    /** The light or dark theme was switched on. */
+    'theme:changed': {
+        graphId: string;
+        dark: boolean;
+    };
+}
+/**
+ * An Event's name.
+ *
+ * @beta
+ */
+export type ExtensionEventName = keyof ExtensionEventPayloads;
+/**
+ * Listening to Events.
+ *
+ * @beta
+ */
+export interface ExtensionEvents {
+    /** Listen to one Event until the returned function is called or the extension stops. */
+    on<K extends ExtensionEventName>(name: K, listener: (payload: ExtensionEventPayloads[K]) => void): () => void;
+}

package/dist/events.js

@@ -0,0 +1,5 @@
+/**
+ * The Events an extension may listen to. An Event reports something that happened in the Client.
+ * A listener reacts to it but cannot change it, and a listener that throws harms nothing else.
+ */
+export {};

package/dist/graph-index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * What an extension may ask the Derived Index, the open graph's searchable copy of its documents.
+ * Every question is read-only, and a Protected Document contributes only what it does everywhere:
+ * its name, never its content.
+ */
+/**
+ * What kind of name a concept is.
+ *
+ * @beta
+ */
+export type ConceptKind = 'page' | 'journal' | 'alias' | 'pageless';
+/**
+ * One name the index knows: a page, a journal entry, an alias, or a Pageless Concept (a name
+ * wikilinks use that has no page).
+ *
+ * @beta
+ */
+export interface ConceptCandidate {
+    /** The name as written. */
+    display: string;
+    /** The case-insensitive key every index answer uses for it. */
+    key: string;
+    /** What kind of name it is. */
+    kind: ConceptKind;
+    /** For an alias: the name of the page it resolves to. */
+    canonical?: string;
+    /** For a Pageless Concept: how many wikilinks name it. */
+    references?: number;
+    /** Present, and true, when the name opens a Protected Document. */
+    protected?: true;
+}
+/**
+ * One concept in the link graph.
+ *
+ * @beta
+ */
+export interface LinkGraphConcept {
+    /** The case-insensitive key every other answer uses. */
+    key: string;
+    /** The page's title, or for a Pageless Concept the casing most of its mentions use. */
+    name: string;
+    /** A page, a journal entry, or a name only wikilinks use. */
+    kind: 'page' | 'journal' | 'pageless';
+    /** For a journal entry named for a day that exists: that day, `YYYY-MM-DD`. */
+    day?: string;
+    /** Present, and true, only for a Protected Document. */
+    protected?: true;
+}
+/**
+ * One line, from the document whose text holds the wikilinks to the concept they name. Both ends
+ * are positions in {@link LinkGraph.concepts}.
+ *
+ * @beta
+ */
+export interface LinkGraphLink {
+    /** The document whose text holds the wikilinks, by its position in `concepts`. */
+    source: number;
+    /** The concept they name, by its position in `concepts`. */
+    target: number;
+    /** How many wikilinks in the source name the target, under its name or any alias. */
+    mentions: number;
+    /** Present, and true, when the source's own name is scoped by the target. */
+    inTitle?: true;
+}
+/**
+ * Every concept and every line a wikilink draws between two of them.
+ *
+ * @beta
+ */
+export interface LinkGraph {
+    /** Sorted by key, so two answers over the same index are identical. */
+    concepts: LinkGraphConcept[];
+    /** Sorted by source, then target. A pair linked both ways is two links. */
+    links: LinkGraphLink[];
+}
+/**
+ * What changed in one update the index committed.
+ *
+ * @beta
+ */
+export interface IndexUpdate {
+    /** The whole index was read again, so anything may have changed. */
+    full: boolean;
+    /** The keys of the concepts whose documents changed. */
+    changedConceptKeys: ReadonlySet<string>;
+    /** The keys of the concepts whose backlinks changed. */
+    backlinkTargetsChanged: ReadonlySet<string>;
+    /** A place or route may have changed. Always true for a full update. */
+    mapsChanged: boolean;
+}
+/**
+ * The questions an extension may ask the open graph's index.
+ *
+ * @beta
+ */
+export interface ExtensionIndex {
+    /** Every name the index knows, aliases and Pageless Concepts included. */
+    allConcepts(): readonly ConceptCandidate[];
+    /** Every concept, and every pair a wikilink joins. */
+    linkGraph(): Promise<LinkGraph>;
+    /** Called after each update the index commits. Returns the unsubscribe. */
+    onUpdated(listener: (update: IndexUpdate) => void): () => void;
+}

package/dist/graph-index.js

@@ -0,0 +1,6 @@
+/**
+ * What an extension may ask the Derived Index, the open graph's searchable copy of its documents.
+ * Every question is read-only, and a Protected Document contributes only what it does everywhere:
+ * its name, never its content.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The API an EtherPK extension is written against.
+ *
+ * An extension is an npm package whose package.json carries an `etherpk` manifest and whose main
+ * module exports `activate(context)`. The Client starts it as each graph opens, with an
+ * {@link ExtensionContext} for that graph. This package holds the types of that context, of the
+ * manifest and of the contract a View follows, and {@link readExtensionPackage}, which checks a
+ * manifest the way the Client does. It holds none of the Client's implementation.
+ *
+ * Every declaration is Proposed (`@beta`) until extensions from other publishers can be installed:
+ * until then it may change in any release. Stable declarations (`@public`) will never break.
+ *
+ * @packageDocumentation
+ */
+export type { CommandHandler, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
+export type { ExtensionEventName, ExtensionEventPayloads, ExtensionEvents } from './events';
+export type { ConceptCandidate, ConceptKind, ExtensionIndex, IndexUpdate, LinkGraph, LinkGraphConcept, LinkGraphLink } from './graph-index';
+export type { ExtensionManifest, ExtensionPackage, ReadExtensionPackageResult, SettingDeclaration, ViewDeclaration, ViewRegion, } from './manifest';
+export { readExtensionPackage } from './manifest';
+export type { CommandMenuContext, CommandMenuItem, ContextMenuItem, DocumentMenuTarget, ExtensionMenuTarget, GraphSidebarButton, MenuTarget, TabMenuTarget, WikilinkMenuTarget, } from './menus';
+export type { MountedView, ViewContribution, ViewMountProps, ViewRef, ViewVisibility } from './views';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * The API an EtherPK extension is written against.
+ *
+ * An extension is an npm package whose package.json carries an `etherpk` manifest and whose main
+ * module exports `activate(context)`. The Client starts it as each graph opens, with an
+ * {@link ExtensionContext} for that graph. This package holds the types of that context, of the
+ * manifest and of the contract a View follows, and {@link readExtensionPackage}, which checks a
+ * manifest the way the Client does. It holds none of the Client's implementation.
+ *
+ * Every declaration is Proposed (`@beta`) until extensions from other publishers can be installed:
+ * until then it may change in any release. Stable declarations (`@public`) will never break.
+ *
+ * @packageDocumentation
+ */
+export { readExtensionPackage } from './manifest';

package/dist/manifest.d.ts

@@ -0,0 +1,153 @@
+/**
+ * An extension's manifest: the `etherpk` field of its package.json (ADR 0121), and the one helper
+ * that reads and checks it. The Client reads the same field with the same function, so an author
+ * and the Client never disagree about what a manifest means.
+ */
+/**
+ * Where a View kind opens when nothing says otherwise.
+ *
+ * @beta
+ */
+export type ViewRegion = 'main' | 'left-sidebar' | 'right-sidebar';
+/**
+ * One View kind an extension adds, declared so the Client can show its tabs, titles and loading
+ * state before any of the extension's code has run.
+ *
+ * @beta
+ */
+export interface ViewDeclaration {
+    /** The kind, `<extension id>.<name>`: the key every saved Layout stores it under. */
+    kind: string;
+    /**
+     * The target of a kind with one View per graph, a Sidebar resident or a whole-graph View
+     * (`"whole"`). A kind whose Views differ by target, one board per concept, leaves it out.
+     */
+    target?: string;
+    /**
+     * The tab's title. `{target}` stands for the View's target, so `"Kanban: {target}"` titles a
+     * board by its concept. The text before `{target}` is a fixed label the tab keeps room for.
+     */
+    title: string;
+    /** An icon drawn before the title: one of the extension's own icons, or one of the Client's. */
+    icon?: string;
+    /** Where the kind opens when nothing says otherwise. */
+    region: ViewRegion;
+    /**
+     * The View lives in a Sidebar from the moment a graph opens, beside the Client's own residents,
+     * and the Sidebar's toggle brings it back if it was closed. `desktopOnly` keeps it off a phone.
+     */
+    resident?: {
+        side: 'left' | 'right';
+        desktopOnly?: boolean;
+    };
+    /**
+     * A short address of the View's own: `/g/<graph>/<segment>`, followed by the target when
+     * `target` is `concept`. Only a Built-in Extension may declare one. A View kind whose address
+     * takes a concept follows that concept through a rename.
+     */
+    address?: {
+        segment: string;
+        target?: 'concept';
+    };
+}
+/**
+ * One thing an extension asks the person to set (ADR 0134). The Client draws it under the
+ * extension's entry in Settings and Extensions → Extensions, where it can be set while the extension
+ * is off, and keeps the answer with the person: on this device, and in their account where it syncs
+ * a graph, so it follows them to their other devices. The extension reads it through
+ * `context.settings`.
+ *
+ * @beta
+ */
+export interface SettingDeclaration {
+    /** Unique within the extension: lowercase letters, digits and hyphens, such as `mapbox-token`. */
+    id: string;
+    /**
+     * `text`; `secret` for a key or a password, which is shown masked until the person asks to see
+     * it; or `boolean`, a switch, which `context.settings` reads as `'true'` or `'false'`.
+     */
+    type: 'text' | 'secret' | 'boolean';
+    /** The field's label, or for a switch what it turns on. */
+    title: string;
+    /** A switch's position until the person changes it. Only on a `boolean` setting, and off when left out. */
+    default?: boolean;
+    /** Plain text under the field: what the setting does, and what the person needs for it. */
+    description?: string;
+    /** Example text shown in the empty field. */
+    placeholder?: string;
+    /** A page that explains the setting, linked under its description. An `https` address. */
+    link?: {
+        title: string;
+        url: string;
+    };
+}
+/**
+ * The `etherpk` field of an extension's package.json.
+ *
+ * @beta
+ */
+export interface ExtensionManifest {
+    /**
+     * Lowercase letters, digits and hyphens, starting with a letter. It prefixes every View kind,
+     * Command id, icon name and storage key the extension owns, so it is short.
+     */
+    id: string;
+    /** The name people see, in Settings and wherever the extension is listed. */
+    displayName: string;
+    /** Who made the extension. */
+    publisher: string;
+    /** The lowest Client version the extension runs on, `x.y.z`. Required of a loaded extension. */
+    minClientVersion?: string;
+    /** The module that exports `activate`, relative to the package's root. */
+    main: string;
+    /**
+     * Stylesheets adopted into the shadow root of each of the extension's Views, relative to the
+     * package's root. Only a loaded extension has them: a compiled-in one shares the Client's.
+     */
+    styles?: string[];
+    /** Icons by name: the inner markup of a 16 by 16 SVG drawn with `currentColor` strokes. */
+    icons?: Record<string, string>;
+    /** The View kinds the extension adds. */
+    views?: ViewDeclaration[];
+    /** What the extension asks the person to set, in the order it is shown. */
+    settings?: SettingDeclaration[];
+}
+/**
+ * An extension's package as the Client reads it: the standard package.json fields it uses and the
+ * manifest.
+ *
+ * @beta
+ */
+export interface ExtensionPackage {
+    /** The npm package name. */
+    name: string;
+    /** The package version, which is the extension's version. */
+    version: string;
+    /** The package's description, when it has one. */
+    description?: string;
+    /** The package's licence, an SPDX identifier, when it names one. */
+    license?: string;
+    /** The `etherpk` field. */
+    manifest: ExtensionManifest;
+}
+/**
+ * The answer of {@link readExtensionPackage}: the package, or every way its manifest is wrong.
+ *
+ * @beta
+ */
+export type ReadExtensionPackageResult = {
+    ok: true;
+    extension: ExtensionPackage;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Read an extension's package.json, already parsed, and check its manifest.
+ *
+ * Checks what the Client depends on: names it uses as keys, paths it resolves, and declarations
+ * it registers before any of the extension's code runs. It does not check that files exist.
+ *
+ * @beta
+ */
+export declare function readExtensionPackage(packageJson: unknown): ReadExtensionPackageResult;

package/dist/manifest.js

@@ -0,0 +1,173 @@
+/**
+ * An extension's manifest: the `etherpk` field of its package.json (ADR 0121), and the one helper
+ * that reads and checks it. The Client reads the same field with the same function, so an author
+ * and the Client never disagree about what a manifest means.
+ */
+const NAME = /^[a-z][a-z0-9-]*$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+const REGIONS = ['main', 'left-sidebar', 'right-sidebar'];
+/**
+ * Read an extension's package.json, already parsed, and check its manifest.
+ *
+ * Checks what the Client depends on: names it uses as keys, paths it resolves, and declarations
+ * it registers before any of the extension's code runs. It does not check that files exist.
+ *
+ * @beta
+ */
+export function readExtensionPackage(packageJson) {
+    const errors = [];
+    const json = isRecord(packageJson) ? packageJson : {};
+    const name = json.name;
+    const version = json.version;
+    if (typeof name !== 'string' || name === '')
+        errors.push('package.json has no "name".');
+    if (typeof version !== 'string' || !VERSION.test(version))
+        errors.push('package.json\'s "version" is not x.y.z.');
+    const field = json.etherpk;
+    if (!isRecord(field)) {
+        errors.push('package.json has no "etherpk" field, so it is not an EtherPK extension.');
+        return { ok: false, errors };
+    }
+    const id = field.id;
+    if (typeof id !== 'string' || !NAME.test(id))
+        errors.push('"etherpk.id" must be lowercase letters, digits and hyphens, starting with a letter.');
+    const ownId = typeof id === 'string' ? id : '';
+    for (const key of ['displayName', 'publisher', 'main']) {
+        if (typeof field[key] !== 'string' || field[key].trim() === '')
+            errors.push(`"etherpk.${key}" must be a non-empty string.`);
+    }
+    if (typeof field.main === 'string' && field.main.trim() !== '' && !relativePath(field.main))
+        errors.push('"etherpk.main" must be a path inside the package.');
+    if (field.minClientVersion !== undefined && (typeof field.minClientVersion !== 'string' || !VERSION.test(field.minClientVersion))) {
+        errors.push('"etherpk.minClientVersion" must be x.y.z.');
+    }
+    if (field.styles !== undefined && (!Array.isArray(field.styles) || !field.styles.every((path) => typeof path === 'string' && relativePath(path)))) {
+        errors.push('"etherpk.styles" must be a list of paths inside the package.');
+    }
+    if (field.icons !== undefined) {
+        if (!isRecord(field.icons))
+            errors.push('"etherpk.icons" must map names to SVG markup.');
+        else
+            for (const [iconName, markup] of Object.entries(field.icons)) {
+                if (!NAME.test(iconName))
+                    errors.push(`Icon "${iconName}" must be lowercase letters, digits and hyphens.`);
+                if (typeof markup !== 'string' || markup.trim() === '')
+                    errors.push(`Icon "${iconName}" has no markup.`);
+            }
+    }
+    const views = field.views === undefined ? [] : field.views;
+    if (!Array.isArray(views))
+        errors.push('"etherpk.views" must be a list.');
+    else {
+        const kinds = new Set();
+        const segments = new Set();
+        views.forEach((view, index) => checkView(view, index, ownId, kinds, segments, errors));
+    }
+    const settings = field.settings === undefined ? [] : field.settings;
+    if (!Array.isArray(settings))
+        errors.push('"etherpk.settings" must be a list.');
+    else {
+        const ids = new Set();
+        settings.forEach((setting, index) => checkSetting(setting, index, ids, errors));
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        extension: {
+            name: name,
+            version: version,
+            ...(typeof json.description === 'string' ? { description: json.description } : {}),
+            ...(typeof json.license === 'string' ? { license: json.license } : {}),
+            manifest: field,
+        },
+    };
+}
+const SETTING_TYPES = ['text', 'secret', 'boolean'];
+function checkSetting(setting, index, ids, errors) {
+    const where = `"etherpk.settings[${index}]"`;
+    if (!isRecord(setting)) {
+        errors.push(`${where} must be an object.`);
+        return;
+    }
+    if (typeof setting.id !== 'string' || !NAME.test(setting.id))
+        errors.push(`${where}.id must be lowercase letters, digits and hyphens, starting with a letter.`);
+    else if (ids.has(setting.id))
+        errors.push(`${where}.id "${setting.id}" is declared twice.`);
+    else
+        ids.add(setting.id);
+    if (!SETTING_TYPES.includes(setting.type))
+        errors.push(`${where}.type must be one of ${SETTING_TYPES.join(', ')}.`);
+    if (typeof setting.title !== 'string' || setting.title.trim() === '')
+        errors.push(`${where}.title must be a non-empty string.`);
+    for (const key of ['description', 'placeholder']) {
+        if (setting[key] !== undefined && typeof setting[key] !== 'string')
+            errors.push(`${where}.${key} must be a string.`);
+    }
+    if (setting.default !== undefined && (setting.type !== 'boolean' || typeof setting.default !== 'boolean')) {
+        errors.push(`${where}.default must be true or false, and only on a boolean setting.`);
+    }
+    if (setting.link !== undefined) {
+        const link = setting.link;
+        if (!isRecord(link) || typeof link.title !== 'string' || link.title.trim() === '' || typeof link.url !== 'string' || !httpsUrl(link.url)) {
+            errors.push(`${where}.link must be { title, url }, the url an https address.`);
+        }
+    }
+}
+function httpsUrl(value) {
+    try {
+        return new URL(value).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function checkView(view, index, id, kinds, segments, errors) {
+    const where = `"etherpk.views[${index}]"`;
+    if (!isRecord(view)) {
+        errors.push(`${where} must be an object.`);
+        return;
+    }
+    const kind = view.kind;
+    const prefix = `${id}.`;
+    if (typeof kind !== 'string' || !kind.startsWith(prefix) || !NAME.test(kind.slice(prefix.length))) {
+        errors.push(`${where}.kind must be "${prefix}<name>", the name in lowercase letters, digits and hyphens.`);
+    }
+    else if (kinds.has(kind))
+        errors.push(`${where}.kind "${kind}" is declared twice.`);
+    else
+        kinds.add(kind);
+    if (view.target !== undefined && (typeof view.target !== 'string' || view.target === ''))
+        errors.push(`${where}.target must be a non-empty string.`);
+    if (typeof view.title !== 'string' || view.title.trim() === '')
+        errors.push(`${where}.title must be a non-empty string.`);
+    if (view.icon !== undefined && typeof view.icon !== 'string')
+        errors.push(`${where}.icon must be an icon's name.`);
+    if (!REGIONS.includes(view.region))
+        errors.push(`${where}.region must be one of ${REGIONS.join(', ')}.`);
+    if (view.resident !== undefined) {
+        const resident = view.resident;
+        if (!isRecord(resident) || (resident.side !== 'left' && resident.side !== 'right') || (resident.desktopOnly !== undefined && typeof resident.desktopOnly !== 'boolean')) {
+            errors.push(`${where}.resident must be { side: "left" | "right", desktopOnly?: boolean }.`);
+        }
+    }
+    if (view.address !== undefined) {
+        const address = view.address;
+        if (!isRecord(address) || typeof address.segment !== 'string' || !NAME.test(address.segment)) {
+            errors.push(`${where}.address.segment must be lowercase letters, digits and hyphens.`);
+        }
+        else if (segments.has(address.segment))
+            errors.push(`${where}.address.segment "${address.segment}" is declared twice.`);
+        else
+            segments.add(address.segment);
+        if (isRecord(address) && address.target !== undefined && address.target !== 'concept')
+            errors.push(`${where}.address.target may only be "concept".`);
+    }
+}
+/** A path that stays inside the package: relative, and never climbing out of it. */
+function relativePath(path) {
+    return path !== '' && !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/menus.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Rows an extension adds to the Client's menus. A row runs a Command, so every row is reachable
+ * from code, keybindings and other menus as well.
+ */
+/**
+ * A document, reached from its tab, a Favourite, Recents or an All Documents row.
+ *
+ * @beta
+ */
+export interface DocumentMenuTarget {
+    /** Where the menu was raised: the document's tab, or a row naming it. */
+    kind: 'document-tab' | 'favourite' | 'recent' | 'document-row';
+    /** The concept the document is about. */
+    concept: string;
+    /** The panel it is open in, when the target is a tab. */
+    panelId?: string;
+    /** The tab is a row in a vertical list, as a phone draws its open documents. */
+    vertical?: boolean;
+}
+/**
+ * A tab that is not a document's.
+ *
+ * @beta
+ */
+export interface TabMenuTarget {
+    /** Any tab that is not a document's. */
+    kind: 'tab';
+    /** The panel the tab belongs to. */
+    panelId: string;
+    /** The tab is a row in a vertical list, as a phone draws its open documents. */
+    vertical?: boolean;
+}
+/**
+ * A wikilink in an editor.
+ *
+ * @beta
+ */
+export interface WikilinkMenuTarget {
+    /** A wikilink in an editor. */
+    kind: 'wikilink';
+    /** The concept the link names. */
+    concept: string;
+    /** The editor's panel. */
+    panelId?: string;
+}
+/**
+ * A thing an extension raises a menu on, of a kind the extension names under its own id
+ * (`kanban.card`). Only rows that check for that kind apply to it.
+ *
+ * @beta
+ */
+export interface ExtensionMenuTarget {
+    /** `<extension id>.<name>`. */
+    kind: `${string}.${string}`;
+    /** Whatever the extension's own rows need to know about the thing. */
+    [field: string]: unknown;
+}
+/**
+ * What a Context Menu can be raised on that an extension may add rows to. The Client also raises
+ * menus on things this list does not name, an Asset or a misspelt word, so a row's `when` answers
+ * false for any kind it does not check for.
+ *
+ * @beta
+ */
+export type MenuTarget = DocumentMenuTarget | TabMenuTarget | WikilinkMenuTarget | ExtensionMenuTarget;
+/**
+ * One Context Menu row.
+ *
+ * @beta
+ */
+export interface ContextMenuItem {
+    /** Under the extension's id: `graph-view.showConcept`. */
+    id: string;
+    /** The row's text, which may read the target. */
+    label: string | ((target: MenuTarget) => string);
+    /** Lower sorts earlier. Rows with equal values keep the order they were added in. */
+    order?: number;
+    /** The Command the row runs, given the target. */
+    command: string;
+    /** An icon drawn left of the label: the extension's own or one of the Client's. */
+    icon?: string;
+    /** A separator above the row. */
+    separatorBefore?: boolean | ((target: MenuTarget) => boolean);
+    /** Whether the row applies to a target. Absent means every target. */
+    when?: (target: MenuTarget) => boolean;
+}
+/**
+ * What a Command Menu row's `when` may read about the editor it was opened in.
+ *
+ * @beta
+ */
+export interface CommandMenuContext {
+    /** The caret is in a table. */
+    inTable: boolean;
+    /** A table may be inserted at the caret. */
+    tableInsertable: boolean;
+    /** The document's body may be written: false in a locked Protected Document. */
+    bodyWritable: boolean;
+    /**
+     * The document is a Protected Document, locked or not: where a row whose widget draws no
+     * protected content, such as `/map`, is not offered. Absent reads as false.
+     */
+    protectedDocument?: boolean;
+    /**
+     * The concepts a View about one concept can be opened for from the caret, nearest first: the
+     * caret line's links, the links above it in the outline, the document's own concept, then the
+     * scopes in its name. Names are as written, an alias as the alias. Worked out only when a row
+     * reads it. Absent reads as none.
+     */
+    readonly conceptsAtCaret?: readonly string[];
+}
+/**
+ * One row of the Command Menu, the menu `/` opens in the editor.
+ *
+ * @beta
+ */
+export interface CommandMenuItem {
+    /** Under the extension's id. */
+    id: string;
+    /** The row's text. */
+    title: string;
+    /**
+     * A line under the title, or a function that works it out from the editor the menu opened in,
+     * each time the menu opens. A function that throws shows no line.
+     */
+    detail?: string | ((context: CommandMenuContext) => string | undefined);
+    /** An icon drawn before the title: the extension's own or one of the Client's. */
+    icon?: string;
+    /** Rows are grouped under this heading. */
+    group?: string;
+    /** Lower sorts earlier within the group. */
+    order?: number;
+    /** More words the menu's filter matches. */
+    keywords?: string[];
+    /** Whether the row is offered here. Absent means everywhere. */
+    when?: (context: CommandMenuContext) => boolean;
+    /** The Command the row runs. */
+    command: string;
+    /** What the Command is given. */
+    args?: unknown;
+}
+/**
+ * A button in the Graph Sidebar, under Today's journal: a way in to what the extension shows for
+ * the whole graph, such as the Graph Map View. Pressing it runs `command`.
+ *
+ * @beta
+ */
+export interface GraphSidebarButton {
+    /** Under the extension's id. */
+    id: string;
+    /** The button's text. */
+    title: string;
+    /** An icon drawn before the title: the extension's own or one of the Client's. */
+    icon?: string;
+    /** Lower lists earlier. A button without one lists after every button that has one. */
+    order?: number;
+    /** The Command the button runs. */
+    command: string;
+    /** What the Command is given. */
+    args?: unknown;
+}

package/dist/menus.js

@@ -0,0 +1,5 @@
+/**
+ * Rows an extension adds to the Client's menus. A row runs a Command, so every row is reachable
+ * from code, keybindings and other menus as well.
+ */
+export {};

package/dist/views.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The contract an extension's View follows (ADR 0121): a function that draws into an element the
+ * Client gives it, tied to no framework, so no Svelte or React version is ever part of the API.
+ */
+/**
+ * Which View: its kind and what it is about. A View with no subject has an empty target.
+ *
+ * @beta
+ */
+export interface ViewRef {
+    /** The View kind, `<extension id>.<name>` for an extension's. */
+    kind: string;
+    /** What the View is about: a concept's name for a board or a map, empty for a View with none. */
+    target: string;
+}
+/**
+ * Whether a View can be seen: its tab in front, its Pane given room, and the browser tab showing.
+ * The desktop keeps every tab mounted, so a View that does work while shown (drawing, reading the
+ * index) stops it while this is false.
+ *
+ * @beta
+ */
+export interface ViewVisibility {
+    /** True while the View can be seen. */
+    readonly onScreen: boolean;
+    /** Called with each new value of `onScreen`, never with a repeat. Returns the unsubscribe. */
+    subscribe(listener: (onScreen: boolean) => void): () => void;
+}
+/**
+ * What a View is mounted with.
+ *
+ * @beta
+ */
+export interface ViewMountProps {
+    /** The View being mounted. */
+    view: ViewRef;
+    /**
+     * The id of the panel the View is open in, on a desktop: what a Layout call names to open
+     * something in the same Pane or beside it. A phone passes none.
+     */
+    panelId?: string;
+    /** Whether the View can be seen right now, and when that changes. */
+    visibility: ViewVisibility;
+}
+/**
+ * A View the extension has drawn, as the Client drives it.
+ *
+ * @beta
+ */
+export interface MountedView {
+    /** The same View with new props: a rename re-keyed its target, or it moved to another Pane. */
+    update?(props: ViewMountProps): void;
+    /** The tab closed, the graph closed, or the extension was switched off. */
+    destroy(): void;
+}
+/**
+ * What an extension registers for a View kind its manifest declares.
+ *
+ * @beta
+ */
+export interface ViewContribution {
+    /**
+     * Draw the View into `element`, which is empty and is the extension's alone. For a loaded
+     * extension it sits inside a shadow root that holds the extension's own stylesheets, so its CSS
+     * reaches nothing outside, and nothing of the Client's reaches in but the `--gk-*` tokens and
+     * inherited text styles.
+     */
+    mount(element: HTMLElement, props: ViewMountProps): MountedView;
+}

package/dist/views.js

@@ -0,0 +1,5 @@
+/**
+ * The contract an extension's View follows (ADR 0121): a function that draws into an element the
+ * Client gives it, tied to no framework, so no Svelte or React version is ever part of the API.
+ */
+export {};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@appsoftwareltd/etherpk-extension-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.6",
+  "license": "MIT",
+  "description": "The API an EtherPK extension is written against: the context it is started with, its manifest, and the contract its Views follow.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appsoftwareltd/etherpk-client.git",
+    "directory": "packages/extension-api"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.59.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && pnpm api:check",
+    "build": "tsc -p tsconfig.build.json",
+    "api": "pnpm build && api-extractor run --local",
+    "api:check": "pnpm build && api-extractor run",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }