@appsoftwareltd/etherpk-extension-api 0.9.5 → 0.10.0

package/README.md

@@ -1,41 +1,104 @@
 # EtherPK Extension API
 
-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.
+This package holds the types an [EtherPK](https://etherpk.com) extension is written against, and
+`readExtensionPackage`, which checks an extension's manifest the way the EtherPK Client does. It
+holds no code that the Client runs. 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:
+```bash
+npm install --save-dev @appsoftwareltd/etherpk-extension-api
+```
 
-```ts
-import type { ExtensionContext } from '@appsoftwareltd/etherpk-extension-api'
+It is a development dependency, because the Client supplies everything at run time.
 
-export function activate(context: ExtensionContext): void {
-    context.commands.register('hello.greet', () => context.notify('Hello from an extension.'))
-}
-```
+## What an extension is
+
+An extension is an npm package. Its `package.json` has an `etherpk` manifest, which says what the
+extension is and what it adds, and its main module exports `activate(context)`. The Client calls
+`activate` each time a graph opens, with a context for that graph. When the graph closes, the Client
+removes everything the extension registered through the context, and calls the function `activate`
+returned, if it returned one, for anything else the extension holds.
 
 ```json
 {
     "name": "etherpk-extension-hello",
     "version": "1.0.0",
+    "type": "module",
+    "files": ["dist"],
     "etherpk": {
         "id": "hello",
         "displayName": "Hello",
-        "publisher": "You",
-        "minClientVersion": "0.8.54",
+        "publisher": "you",
+        "minClientVersion": "0.10.0",
         "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.
+```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.'))
+    context.commandMenu.register({ id: 'hello.greet', title: 'Say hello', command: 'hello.greet' })
+}
+```
+
+## Stable and Proposed parts
+
+Each declaration in this package, and each member of one, is either Stable or Proposed. Its
+documentation says which, with `@public` for Stable and `@beta` for Proposed.
+
+- **A Stable part never breaks.** A change can add to it. Anything a change replaces is marked
+  deprecated and kept working.
+- **A Proposed part may change in any release.** Only the extensions that come with EtherPK may use
+  it. In an extension installed from the Extension Directory, a call to a Proposed member throws an
+  error that names it.
+
+An extension listed in the Extension Directory uses only the Stable part.
+[`etc/etherpk-extension-api.public.api.md`](etc/etherpk-extension-api.public.api.md) lists the
+Stable part, and [`etc/etherpk-extension-api.beta.api.md`](etc/etherpk-extension-api.beta.api.md)
+lists everything. A Proposed part becomes Stable when an extension from another publisher needs it.
+To ask for one, open an issue on
+[the EtherPK Client repository](https://github.com/appsoftwareltd/etherpk-client/issues).
+
+## The manifest
 
-## Settings
+| Field | What it is |
+| --- | --- |
+| `id` | The extension's id: lowercase letters, digits and hyphens, starting with a letter. The ids of everything it registers start with it. An extension in the Extension Directory can't use `map`, `math`, `mermaid` or `etherpk-cipher`, the words of blocks the Client draws itself. |
+| `displayName` | The name Settings shows, and the name a dialog it opens gives. |
+| `publisher` | Who publishes the extension. |
+| `minClientVersion` | The oldest Client version the extension runs on, as `x.y.z`. An extension in the Extension Directory must give one. |
+| `main` | The main module, an ES module. |
+| `styles` | The extension's stylesheets (see *Styles* below). |
+| `isolation` | `"shadow"`, the default, or `"page"` (see *Styles* below). |
+| `icons` | Icons by name, each the SVG elements of a 16 by 16 picture. A Command Menu row or a View refers to an icon by its name. |
+| `views` | The View kinds the extension supplies (see *Views* below). |
+| `settings` | What the person can set (see *Settings* below). |
 
-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:
+`readExtensionPackage(packageJson)` checks a manifest as the Client does, and lists every problem
+it finds.
+
+## What an extension can do
+
+These are the Stable parts of the context.
+
+### Commands and the `/` menu
+
+`context.commands.register(id, handler)` adds a Command, whose id starts with the extension's id
+(`hello.greet`). `context.commandMenu.register(item)` adds a row to the `/` menu that runs a Command.
+A row can have a `detail` line, an `icon`, `keywords` that find it, a `group` and an `order`. Its
+`when(menu)` says whether it is offered at the caret, from what `menu` reports: `bodyWritable`,
+`inTable` and `protectedDocument`.
+
+### Notices
+
+`context.notify(text)` shows a short notice, as the Client's own notices do.
+
+### Settings
+
+A value the person sets, such as a key for a service, is declared in the manifest. The Client draws
+it under the extension's entry in Settings, in the Extensions area.
 
 ```json
 "settings": [
@@ -50,25 +113,197 @@ draws it under the extension's entry in Settings and Extensions → Extensions:
 ]
 ```
 
-`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.
+`type` is `text`, `secret` or `boolean`. A secret stays hidden until the person shows it. A
+`boolean` is a switch, and `"default": true` starts it on. The person can change settings while the
+extension is switched off.
+
+The extension reads a setting with `context.settings.get('api-key')`, which is undefined until the
+person sets it, and hears every change with `context.settings.subscribe`. A switch always reads
+`'true'` or `'false'`. Settings belong to the person, not to a graph. Once their account syncs a
+graph, the settings follow them to their other devices, encrypted so that only those devices can read
+them.
+
+### Storage
+
+`context.storage` keeps the extension's own values on the device, as JSON, with `get`, `set` and
+`remove`. It is for what the extension works out or caches, not for what the person sets.
+
+### Fence widgets
+
+A fence widget draws over a fenced block in a document, in place of its text. The extension
+registers one for an info word, which is either its id or `<id>.<name>`:
+
+- **Its id** (```` ```hello ````) makes an ordinary fence. Without the extension it shows as a code
+  block, so the document reads well anywhere.
+- **`<id>.<name>`** (```` ```hello.board ````) makes an Extension Fence, which holds the extension's
+  data. EtherPK never searches its lines and never publishes them as code. The caret passes over it,
+  and where the extension is not running, a note says so.
+
+```ts
+context.editor.registerFence('hello', {
+    height: () => 40,
+    mount(host, initial) {
+        const line = document.createElement('p')
+        const show = (fence: { body: readonly string[] }) => {
+            line.textContent = `${fence.body.length} lines`
+        }
+        show(initial)
+        host.append(line)
+        return { update: show, destroy: () => line.remove() }
+    },
+})
+```
+
+`height` must answer before the widget is drawn, so the lines below never move as it loads. The
+context a widget is given has the fence's lines (`body`), whether the document can be written
+(`writable`), and the theme. It can also:
+
+- Change the lines (`edit`), as one change that Mod+Z undoes.
+- Show the fence as text (`editAsText`), or delete it (`remove`).
+- Open the fence in a tab of its own, or over the whole window.
+
+The third argument to `registerFence` adds options:
+
+- `title`, what the fence is called in its tab.
+- `fromPaste`, which turns text pasted on a line of its own into the fence. A line it answers with
+  that would end the fence is changed so it can't.
+- `publish`, which says how a published site shows the fence, as a picture or a link card. An SVG
+  picture is cleaned of scripts, event handlers and links that run code before the site gets it.
+- `identify`, which finds a fence again by an id in its body, so it can open in a tab.
+- `keepsHistory`, which leaves Mod+Z to the widget while it has the keyboard.
+
+### A block at the caret
+
+`context.editor.insertBlock(text, { focus })` puts lines at the caret, as a code block or a table
+goes in. It returns false where nothing went in, such as a document that cannot be written, a
+Protected Document, or a caret in the frontmatter, in a fence or in a table.
+
+### Dialogs
+
+`context.dialogs.prompt(options)` asks for one line of text in a dialog the Client draws. Its
+`validate` function can refuse an answer by returning a message, and the dialog stays open with the
+text kept. It resolves to the text, trimmed, or undefined when the person cancels. The dialog names
+the extension, and shows every string it is given as text.
+
+### Frames
+
+`context.embeds.frame({ src, title })` builds a frame showing a page from a host the Client allows,
+and throws for any other host. `context.embeds.frameHosts` lists the hosts: the video players of
+YouTube (`www.youtube-nocookie.com`) and Vimeo (`player.vimeo.com`).
+
+### Views
+
+A View is the content of a tab. The manifest declares each View kind, and the extension supplies it
+with `context.views.register(kind, view)` as the graph opens.
+
+```json
+"views": [
+    {
+        "kind": "hello.board",
+        "title": "Board: {target}",
+        "region": "main",
+        "address": { "segment": "board", "target": "concept" }
+    }
+]
+```
+
+`kind` starts with the extension's id. `{target}` in the title stands for the View's target, here a
+concept. `region` is where the kind opens: `main`, `left-sidebar` or `right-sidebar`. A kind with
+one View per graph gives a fixed `target` instead.
+
+An `address` gives the View a URL. For an extension from the Extension Directory, the URL is
+`/g/<graph>/x/<extension id>/<segment>`, followed by the concept when `target` is `concept`. A link
+to it opens the View. On a device without the extension, it opens a page that names the extension
+and offers to install it, if the directory lists it.
+
+`context.layout.openView({ kind, target })` opens a View. `context.layout.isDesktop()` says whether
+the desktop layout is showing, which it is at 1024 pixels wide and more.
+
+## Styles
+
+The manifest's `styles` are the extension's stylesheets. By default, each widget and View the
+extension draws is mounted in a shadow root with them, so the extension's styles and the Client's
+stay apart.
+
+Some libraries can't run in a shadow root. An extension that uses one can set
+`"isolation": "page"` to mount in the page instead. Then every rule in its stylesheets must style
+only elements with a class that starts with the extension's id, or elements inside one. The Client
+refuses any other stylesheet. The colours of the Client's theme are CSS variables (`--gk-*`) that
+reach into a shadow root as well, so an extension can follow the light and dark themes either way.
+An extension's stylesheet can't register one of them with `@property`.
+
+Either way, the shadow root and the check keep styles apart, and nothing more. They don't limit
+what the extension's code can do in the page.
 
 ## 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:
+The Client enforces
+[Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API), and extension
+code runs under them.
 
-- **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.
+- **An extension can't create a Trusted Types policy.** The Client's Content Security Policy names
+  the policies it allows, and each one belongs to the Client or to a library it ships.
+- **Icons come from the manifest.** The Client sanitizes the icons a manifest declares as SVG, so
+  they can hold only SVG.
+
+## Proposed parts
+
+The Proposed parts are for the extensions that come with EtherPK, and may change in any release.
+They include:
+
+- Context Menu rows (`contextMenu`), key chords (`keybindings`) and Graph Sidebar buttons
+  (`graphSidebar`).
+- Events (`events`), questions to the graph's index (`index`) and the rules for naming a concept
+  (`concepts`).
+- The theme (`theme`), the Client's icons (`icons`) and a View that lives in a Sidebar (`resident`).
+- Running another extension's Commands (`commands.execute`) and opening documents
+  (`layout.openDocument`).
+
+`contributions`, which reaches the Client's own registries, stays Proposed for good, since its
+shape is the Client's internals.
+
+### Graph Sidebar buttons
+
+A button in the Graph Sidebar, below Search and today's date, runs a Command. These rules keep the
+buttons readable together:
+
+- **`title`** is short. Two buttons sit side by side in the sidebar at its default width of 304
+  pixels, and "Graph Kanban", with its icon, is about the widest that fits.
+- **`description`** says what the button does, such as "Open a map of every place and route in this
+  graph". The Client shows it as the button's help text. Don't write a keyboard shortcut in it: the
+  Client adds the key chords bound to the button's Command itself.
+- **`icon`** is clear on its own. On a phone the buttons show their icons only.
+- **`when`** hides the button where it does not apply. A button for the desktop alone passes
+  `when: () => context.layout.isDesktop()`. A `when` that throws hides the button too.
+- **`order`** places the button among the others. The Graph Map's is 20 and the Graph Kanban's is
+  30.
+
+## Trying an extension
+
+To try an extension, build it, and start a development copy of the EtherPK Client with the
+extension's folder named in `ETHERPK_DEV_EXTENSIONS`. Separate several folders with commas. The
+Client loads each one as it loads the extensions it comes with, and one with the same id replaces
+it.
+
+```bash
+ETHERPK_DEV_EXTENSIONS=/path/to/my-extension pnpm dev
+```
+
+[The EtherPK Client repository](https://github.com/appsoftwareltd/etherpk-client) says how to run
+the Client.
+
+## Listing an extension
+
+The [Extension Directory](https://github.com/appsoftwareltd/etherpk-extension-directory) lists the
+extensions people can install from inside EtherPK. Each release is a pull request there. It is
+rebuilt from its tagged source and compared with its npm package, and a person reviews it before it
+is listed. Installed extensions update by themselves to the newest listed release the person's
+EtherPK can run. The directory's contributing guide says what a release needs, including the size
+limits.
+
+## Licence
+
+MIT.

package/dist/context.d.ts

@@ -4,8 +4,12 @@
  * 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.
+ * only through the index's answers and its own fences, and changes them only through its fences,
+ * the blocks it puts at the caret and the Client's Commands.
  */
+import type { ExtensionDialogs } from './dialogs';
+import type { ExtensionEditor } from './editor';
+import type { ExtensionEmbeds } from './embeds';
 import type { ExtensionEvents } from './events';
 import type { ExtensionIndex } from './graph-index';
 import type { CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
@@ -13,26 +17,34 @@ import type { ViewContribution, ViewRef } from './views';
 /**
  * A Command's handler. What it returns, or resolves to, is what `execute` resolves to.
  *
- * @beta
+ * @public
  */
 export type CommandHandler = (arg?: unknown) => unknown;
 /**
  * Running and adding Commands.
  *
- * @beta
+ * @public
  */
 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. */
+    /**
+     * Run any Command, the Client's or an extension's. Rejects if no Command has the id.
+     *
+     * @beta
+     */
     execute(id: string, arg?: unknown): Promise<unknown>;
-    /** Whether any Command has the id. */
+    /**
+     * Whether any Command has the id.
+     *
+     * @beta
+     */
     has(id: string): boolean;
 }
 /**
  * Supplying the Views the manifest declares.
  *
- * @beta
+ * @public
  */
 export interface ExtensionViews {
     /**
@@ -53,14 +65,14 @@ export interface ExtensionContextMenu {
 /**
  * Adding Command Menu rows.
  *
- * @beta
+ * @public
  */
 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.
+ * Adding buttons to the Graph Sidebar's group of action buttons, after Search and today's date.
  *
  * @beta
  */
@@ -95,7 +107,7 @@ export interface ExtensionKeybindings {
 /**
  * Opening Views and documents in the open graph's Layout.
  *
- * @beta
+ * @public
  */
 export interface ExtensionLayout {
     /**
@@ -107,19 +119,29 @@ export interface ExtensionLayout {
         inPaneOf?: string;
         beside?: string;
     }): void;
-    /** Bring a Sidebar resident to the front of its expanded Sidebar. */
+    /**
+     * Bring a Sidebar resident to the front of its expanded Sidebar.
+     *
+     * @beta
+     */
     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}.
+     *
+     * @beta
      */
     openDocument(concept: string, options?: {
         line?: number;
         inPaneOf?: string;
         beside?: string;
     }): void;
-    /** The document the user is working in, or null. */
+    /**
+     * The document the user is working in, or null.
+     *
+     * @beta
+     */
     activeDocument(): string | null;
     /** True while the desktop presenter is showing, 1024 pixels wide and more. */
     isDesktop(): boolean;
@@ -139,7 +161,7 @@ export interface ExtensionConcepts {
  * The extension's own storage on this device, under `etherpk-<extension id>:` in the browser's
  * localStorage. Values are stored as JSON.
  *
- * @beta
+ * @public
  */
 export interface ExtensionStorage {
     /** The value stored under `key`, or undefined when there is none or it cannot be read. */
@@ -155,7 +177,7 @@ export interface ExtensionStorage {
  * 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
+ * @public
  */
 export interface ExtensionSettings {
     /**
@@ -232,54 +254,112 @@ export interface ExtensionContributions {
 /**
  * What an extension is started with, once for each graph that opens.
  *
- * @beta
+ * @public
  */
 export interface ExtensionContext {
-    /** The extension's id, from its manifest. */
+    /**
+     * The extension's id, from its manifest.
+     *
+     * @beta
+     */
     readonly extensionId: string;
-    /** The open graph. */
+    /**
+     * The open graph.
+     *
+     * @beta
+     */
     readonly graphId: string;
-    /** The Client's version, `x.y.z`. */
+    /**
+     * The Client's version, `x.y.z`.
+     *
+     * @beta
+     */
     readonly clientVersion: string;
-    /** True in a development build of the Client, where tests may reach in. */
+    /**
+     * True in a development build of the Client, where tests may reach in.
+     *
+     * @beta
+     */
     readonly dev: boolean;
     /** Supplying the Views the manifest declares. */
     readonly views: ExtensionViews;
     /** Running and adding Commands. */
     readonly commands: ExtensionCommands;
-    /** Adding Context Menu rows. */
+    /**
+     * Adding Context Menu rows.
+     *
+     * @beta
+     */
     readonly contextMenu: ExtensionContextMenu;
     /** Adding Command Menu rows. */
     readonly commandMenu: ExtensionCommandMenu;
-    /** Adding buttons to the Graph Sidebar. */
+    /**
+     * Adding buttons to the Graph Sidebar.
+     *
+     * @beta
+     */
     readonly graphSidebar: ExtensionGraphSidebar;
-    /** Adding key chords. */
+    /**
+     * Adding key chords.
+     *
+     * @beta
+     */
     readonly keybindings: ExtensionKeybindings;
-    /** Every Contribution Point by kind, for the kinds the parts above do not cover. */
+    /**
+     * Every Contribution Point by kind, for the kinds the parts above do not cover.
+     *
+     * @beta
+     */
     readonly contributions: ExtensionContributions;
-    /** Listening to Events. */
+    /**
+     * Listening to Events.
+     *
+     * @beta
+     */
     readonly events: ExtensionEvents;
-    /** Questions to the open graph's index. */
+    /**
+     * Questions to the open graph's index.
+     *
+     * @beta
+     */
     readonly index: ExtensionIndex;
     /** Opening Views and documents. */
     readonly layout: ExtensionLayout;
-    /** The rules for naming a concept. */
+    /**
+     * The rules for naming a concept.
+     *
+     * @beta
+     */
     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. */
+    /**
+     * The Client's light or dark theme.
+     *
+     * @beta
+     */
     readonly theme: ExtensionTheme;
-    /** The Client's icons and the extension's own. */
+    /**
+     * The Client's icons and the extension's own.
+     *
+     * @beta
+     */
     readonly icons: ExtensionIcons;
+    /** Widgets over the extension's own fences, and blocks put at the caret. */
+    readonly editor: ExtensionEditor;
+    /** Dialogs the Client draws. */
+    readonly dialogs: ExtensionDialogs;
+    /** Frames showing content from the hosts the Client allows. */
+    readonly embeds: ExtensionEmbeds;
     /** 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
+ * @public
  */
 export interface ExtensionModule {
     /**

package/dist/dialogs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dialogs the Client draws for an extension, so every extension's questions look and behave like the
+ * Client's own: the keyboard stays inside while one is open, Enter answers, Esc cancels, and the
+ * keyboard returns where it was when one closes. Each dialog names the extension that asks, and
+ * shows every string it is given as plain text, never as markup.
+ */
+/**
+ * A question with one line of text for an answer.
+ *
+ * @public
+ */
+export interface PromptOptions {
+    /** The dialog's heading. */
+    title: string;
+    /** The text field's label. */
+    label: string;
+    /** Example text shown in the empty field. */
+    placeholder?: string;
+    /** The field's text when the dialog opens. */
+    value?: string;
+    /** The button that answers. "OK" when left out. */
+    submitLabel?: string;
+    /**
+     * Checks the answer when it is given: a message saying what is wrong, shown at the field, or
+     * undefined when it is fine. The dialog stays open, with the text kept, until it is fine.
+     */
+    validate?(value: string): string | undefined;
+}
+/**
+ * Dialogs.
+ *
+ * @public
+ */
+export interface ExtensionDialogs {
+    /** Ask for one line of text. Resolves to the text, trimmed, or undefined when it was cancelled. */
+    prompt(options: PromptOptions): Promise<string | undefined>;
+}

package/dist/dialogs.js

@@ -0,0 +1,7 @@
+/**
+ * Dialogs the Client draws for an extension, so every extension's questions look and behave like the
+ * Client's own: the keyboard stays inside while one is open, Enter answers, Esc cancels, and the
+ * keyboard returns where it was when one closes. Each dialog names the extension that asks, and
+ * shows every string it is given as plain text, never as markup.
+ */
+export {};

package/dist/editor.d.ts

@@ -0,0 +1,236 @@
+/**
+ * What an extension may do in the document editor: draw a widget over its own kind of fenced block,
+ * and put a block at the caret.
+ *
+ * A widget never sees the editor. It is told the fence's body as lines of text and asks for changes
+ * to those lines, which the Client writes as ordinary editor changes: undone with the editor's undo,
+ * synced and merged like typing, and refused where the document cannot be written.
+ */
+/**
+ * One change to a fence's body, by line number from 0. A replacement or a removal names the text the
+ * widget last read on that line, and applies only while the line still says it, so a widget acting on
+ * an old reading never lands on someone else's edit.
+ *
+ * @public
+ */
+export type FenceEdit = {
+    kind: 'insert';
+    line: number;
+    text: string;
+} | {
+    kind: 'replace';
+    line: number;
+    expect: string;
+    text: string;
+} | {
+    kind: 'remove';
+    line: number;
+    expect: string;
+};
+/**
+ * What a widget is told about its fence.
+ *
+ * @public
+ */
+export interface FenceInfo {
+    /** The fence's info word, the one the widget was registered for. */
+    readonly info: string;
+    /** The fence's body: its lines between the fences, less their indentation. */
+    readonly body: readonly string[];
+    /** The document the fence is in, by its concept, or null outside a workspace. */
+    readonly document: string | null;
+    /**
+     * How many fences with this info word come before this one in the document. It changes when one
+     * is added or removed above, so it keys only what lasts a moment.
+     */
+    readonly ordinal: number;
+}
+/**
+ * Where a widget is drawn: in the document, in a tab of its own, or filling the EtherPK window.
+ *
+ * @public
+ */
+export type FencePresentation = 'inline' | 'tab' | 'window';
+/**
+ * What a mounted widget can see and ask for.
+ *
+ * @public
+ */
+export interface FenceContext extends FenceInfo {
+    /** Whether the document accepts the widget's changes now: not read-only, not locked. */
+    readonly writable: boolean;
+    /** Whether the dark theme shows. */
+    readonly dark: boolean;
+    /**
+     * Whether anyone can see the widget: false while its tab is behind another, its Pane is collapsed
+     * or the browser tab is hidden. A widget holding something costly lets it go while this is false.
+     */
+    readonly onScreen: boolean;
+    /** Where the widget is drawn. */
+    readonly presentation: FencePresentation;
+    /**
+     * Change the body, as one undoable change: one edit, or several applied together. False when it
+     * was refused (the document cannot be written, the fence is gone, or a line no longer says what an
+     * edit expects), and then nothing changed. The widget hears the current body in an `update`.
+     */
+    edit(change: FenceEdit | readonly FenceEdit[]): boolean;
+    /** Show the fence's text in the editor, with the caret on its first body line. */
+    editAsText(): void;
+    /** Delete the fence, as one undoable change. False when it was refused. */
+    remove(): boolean;
+    /** The widget's height changed: the editor asks `height` again. */
+    resized(): void;
+    /**
+     * True once, when the widget is to take the keyboard: for the widget of a fence `insertBlock` put
+     * in with `focus`, and for a widget drawn in a tab or over the window as it opens. False otherwise.
+     */
+    takeFocus(): boolean;
+    /**
+     * Open the fence in a tab of its own, which draws the same widget with `presentation` `tab`. Only
+     * for a fence the registration can `identify`.
+     */
+    openInTab(): void;
+    /**
+     * Draw the widget again over the whole EtherPK window, with `presentation` `window`, and a Return
+     * button the Client draws. Only for a fence the registration can `identify`.
+     */
+    openWindow(): void;
+    /** Close the window this widget fills. Does nothing for a widget drawn elsewhere. */
+    closeWindow(): void;
+}
+/**
+ * A widget the extension has drawn, as the Client drives it.
+ *
+ * @public
+ */
+export interface MountedFence {
+    /** The body, the theme, whether it can be written or whether it is on screen changed. */
+    update(context: FenceContext): void;
+    /** The widget leaves: scrolled far away, its fence deleted, its tab or the editor closed. */
+    destroy(): void;
+}
+/**
+ * What an extension registers for one info word.
+ *
+ * @public
+ */
+export interface FenceWidget {
+    /**
+     * The widget's height in CSS pixels, before and after it mounts. The editor reserves it so the
+     * lines below never move while the widget loads. It is asked again after `resized`. Not asked for
+     * a widget in a tab or a window, which fills what it is given.
+     */
+    height(info: FenceInfo): number;
+    /** Draw the widget into `host`, which the Client owns and places. */
+    mount(host: HTMLElement, context: FenceContext): MountedFence;
+}
+/**
+ * A fence as the publisher hands it to the extension: already public content.
+ *
+ * @public
+ */
+export interface PublishFenceRequest {
+    /** The fence's info word. */
+    readonly info: string;
+    /** The fence's body lines. */
+    readonly body: readonly string[];
+    /** The document being published, by its concept. */
+    readonly document: string;
+}
+/**
+ * How a published site shows a fence: a picture the site keeps, or a link with an optional picture
+ * from the web. The publisher writes the HTML, so an extension never writes markup into a site.
+ *
+ * @public
+ */
+export type PublishedFence = {
+    kind: 'picture';
+    /** The picture's type. */
+    type: 'image/svg+xml' | 'image/png' | 'image/webp';
+    /** The picture's bytes, written into the site as a file of its own. */
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+    /** What the picture shows, for anyone who cannot see it. */
+    alt: string;
+} | {
+    kind: 'link';
+    /** Where the link goes: an `https` address. */
+    href: string;
+    /** The link's text. */
+    text: string;
+    /** A picture from the web shown in the link: an `https` address. */
+    image?: {
+        src: string;
+        alt: string;
+        width?: number;
+        height?: number;
+    };
+};
+/**
+ * Options for a fence registration.
+ *
+ * @public
+ */
+export interface FenceOptions {
+    /**
+     * A short name for what the fence holds, such as "Drawing": a tab's title and the full window's
+     * heading start with it.
+     */
+    title?: string;
+    /**
+     * What text pasted as plain text on an empty line or bullet becomes: the body lines of a fence of
+     * this kind, or null to leave the paste as it is. A link to a video, say, gives the link as the
+     * one line. The text is the clipboard's own, untrimmed. The Client asks each registration in
+     * turn, and the first that answers takes the paste. Mod+Z straight after it gives back the
+     * text that was pasted.
+     *
+     * The lines are written inside the fence as they are, except that a line which would end the
+     * fence, or start another, is changed so it cannot. A line break inside a line splits it in two.
+     */
+    fromPaste?(text: string): readonly string[] | null;
+    /**
+     * How a published site shows the fence, or null to leave it out. Called only for public content,
+     * in a publish run in the browser. Where it is not called (the Headless Client, or the extension
+     * off), an Extension Fence is left out and an ordinary fence is published as code.
+     */
+    publish?(fence: PublishFenceRequest): PublishedFence | null | Promise<PublishedFence | null>;
+    /**
+     * The fence's own id, read from its body, or null. A fence with an id can be opened in a tab or a
+     * window, where the Client finds it again by the id after every change.
+     */
+    identify?(body: readonly string[]): string | null;
+    /**
+     * True when the widget keeps its own undo: Mod+Z and Mod+Y pressed inside it are its own, rather
+     * than the editor's.
+     */
+    keepsHistory?: boolean;
+}
+/**
+ * The document editor, as far as an extension may reach it.
+ *
+ * @public
+ */
+export interface ExtensionEditor {
+    /**
+     * Draw `widget` over every complete fence whose info word is `info`. The word is the extension's
+     * id (an ordinary fence, whose text stays text) or `<id>.<name>` (an Extension Fence, whose body
+     * is the extension's data and never searched or shown as text). Throws for any other word, or one
+     * that is taken.
+     *
+     * An extension listed in the Extension Directory may not have an id that is one of the words the
+     * Client draws blocks for itself: `map`, `math`, `mermaid` and `etherpk-cipher`.
+     */
+    registerFence(info: string, widget: FenceWidget, options?: FenceOptions): () => void;
+    /**
+     * Put a block at the caret of the editor the person is working in, as a code block or a table
+     * goes in: an empty bullet takes it as its content, an empty line is replaced, and after any other
+     * line it goes on new lines beneath at the line's content column. `text` is the block's lines
+     * without indentation. A block that is a fence leaves the caret outside it, and with `focus` its
+     * widget is told to `takeFocus`. False where nothing was put in: no editor, a body that cannot be
+     * written, or a caret in the frontmatter, a fence or a table.
+     */
+    insertBlock(text: string, options?: {
+        focus?: boolean;
+    }): boolean;
+}

package/dist/editor.js

@@ -0,0 +1,9 @@
+/**
+ * What an extension may do in the document editor: draw a widget over its own kind of fenced block,
+ * and put a block at the caret.
+ *
+ * A widget never sees the editor. It is told the fence's body as lines of text and asks for changes
+ * to those lines, which the Client writes as ordinary editor changes: undone with the editor's undo,
+ * synced and merged like typing, and refused where the document cannot be written.
+ */
+export {};

package/dist/embeds.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Content from another site shown inside the Client (ADR 0137). The Client allows frames from a short
+ * list of hosts only, and builds every frame itself, with the referrer policy, sandbox and
+ * permissions those hosts need, so an extension never writes an `<iframe>`.
+ */
+/**
+ * A frame to build.
+ *
+ * @public
+ */
+export interface FrameOptions {
+    /**
+     * The address to show: an `https` address on a host the Client allows, which today are
+     * `https://www.youtube-nocookie.com` and `https://player.vimeo.com`.
+     */
+    src: string;
+    /** What the frame shows, read out to anyone using a screen reader. Plain text, never markup. */
+    title: string;
+}
+/**
+ * Frames.
+ *
+ * @public
+ */
+export interface ExtensionEmbeds {
+    /** The hosts a frame may show, as origins such as `https://player.vimeo.com`. */
+    readonly frameHosts: readonly string[];
+    /**
+     * A frame the Client built for `src`, to put in the extension's own element. It loads once it is
+     * in the page. Throws for an address on a host the Client does not allow.
+     */
+    frame(options: FrameOptions): HTMLIFrameElement;
+}

package/dist/embeds.js

@@ -0,0 +1,6 @@
+/**
+ * Content from another site shown inside the Client (ADR 0137). The Client allows frames from a short
+ * list of hosts only, and builds every frame itself, with the referrer policy, sandbox and
+ * permissions those hosts need, so an extension never writes an `<iframe>`.
+ */
+export {};

package/dist/index.d.ts

@@ -7,15 +7,20 @@
  * 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.
+ * A declaration, or a member of one, is Stable (`@public`) or Proposed (`@beta`). A Stable one never
+ * breaks: it is deprecated and kept. A Proposed one may change in any release, and only the
+ * extensions that come with EtherPK may use it. An extension from the Extension Directory uses the
+ * Stable part alone, which `etc/etherpk-extension-api.public.api.md` lists.
  *
  * @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 { ExtensionDialogs, PromptOptions } from './dialogs';
+export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, MountedFence, PublishedFence, PublishFenceRequest, } from './editor';
+export type { ExtensionEmbeds, FrameOptions } from './embeds';
 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 type { ExtensionIsolation, 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

@@ -7,8 +7,10 @@
  * 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.
+ * A declaration, or a member of one, is Stable (`@public`) or Proposed (`@beta`). A Stable one never
+ * breaks: it is deprecated and kept. A Proposed one may change in any release, and only the
+ * extensions that come with EtherPK may use it. An extension from the Extension Directory uses the
+ * Stable part alone, which `etc/etherpk-extension-api.public.api.md` lists.
  *
  * @packageDocumentation
  */

package/dist/manifest.d.ts

@@ -6,14 +6,14 @@
 /**
  * Where a View kind opens when nothing says otherwise.
  *
- * @beta
+ * @public
  */
 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
+ * @public
  */
 export interface ViewDeclaration {
     /** The kind, `<extension id>.<name>`: the key every saved Layout stores it under. */
@@ -35,15 +35,18 @@ export interface ViewDeclaration {
     /**
      * 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.
+     *
+     * @beta
      */
     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.
+     * A short address of the View's own, followed by the target when `target` is `concept`: for an
+     * extension from the Extension Directory `/g/<graph>/x/<extension id>/<segment>`, and for one that
+     * comes with EtherPK `/g/<graph>/<segment>`. A View kind whose address takes a concept follows
+     * that concept through a rename.
      */
     address?: {
         segment: string;
@@ -57,7 +60,7 @@ export interface ViewDeclaration {
  * a graph, so it follows them to their other devices. The extension reads it through
  * `context.settings`.
  *
- * @beta
+ * @public
  */
 export interface SettingDeclaration {
     /** Unique within the extension: lowercase letters, digits and hyphens, such as `mapbox-token`. */
@@ -81,10 +84,20 @@ export interface SettingDeclaration {
         url: string;
     };
 }
+/**
+ * Where a loaded extension's Views and fence widgets mount. `shadow`, the default, puts each in a
+ * shadow root holding the extension's stylesheets, so neither side's CSS reaches the other. `page`
+ * mounts them in the page and has the document adopt the stylesheets, for a library that cannot work
+ * in a shadow root. The Client then checks every rule is scoped under a class whose name starts with
+ * the extension's id, and refuses to start the extension otherwise.
+ *
+ * @public
+ */
+export type ExtensionIsolation = 'shadow' | 'page';
 /**
  * The `etherpk` field of an extension's package.json.
  *
- * @beta
+ * @public
  */
 export interface ExtensionManifest {
     /**
@@ -101,10 +114,13 @@ export interface ExtensionManifest {
     /** 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.
+     * Stylesheets adopted into the shadow root of each of the extension's Views and fence widgets, or
+     * by the document with `isolation` `page`, relative to the package's root. Only a loaded extension
+     * has them: a compiled-in one shares the Client's.
      */
     styles?: string[];
+    /** Where a loaded extension's Views and fence widgets mount. `shadow` when left out. */
+    isolation?: ExtensionIsolation;
     /** 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. */

package/dist/manifest.js

@@ -6,6 +6,8 @@
 const NAME = /^[a-z][a-z0-9-]*$/;
 const VERSION = /^\d+\.\d+\.\d+$/;
 const REGIONS = ['main', 'left-sidebar', 'right-sidebar'];
+/** The longest an icon's markup may be: a 16 by 16 picture needs a few hundred characters. */
+const ICON_MARKUP_LIMIT = 4096;
 /**
  * Read an extension's package.json, already parsed, and check its manifest.
  *
@@ -44,6 +46,9 @@ export function readExtensionPackage(packageJson) {
     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.isolation !== undefined && field.isolation !== 'shadow' && field.isolation !== 'page') {
+        errors.push('"etherpk.isolation" must be "shadow" or "page".');
+    }
     if (field.icons !== undefined) {
         if (!isRecord(field.icons))
             errors.push('"etherpk.icons" must map names to SVG markup.');
@@ -53,6 +58,8 @@ export function readExtensionPackage(packageJson) {
                     errors.push(`Icon "${iconName}" must be lowercase letters, digits and hyphens.`);
                 if (typeof markup !== 'string' || markup.trim() === '')
                     errors.push(`Icon "${iconName}" has no markup.`);
+                else if (markup.length > ICON_MARKUP_LIMIT)
+                    errors.push(`Icon "${iconName}" is longer than ${ICON_MARKUP_LIMIT} characters.`);
             }
     }
     const views = field.views === undefined ? [] : field.views;
@@ -164,9 +171,12 @@ function checkView(view, index, id, kinds, segments, errors) {
             errors.push(`${where}.address.target may only be "concept".`);
     }
 }
-/** A path that stays inside the package: relative, and never climbing out of it. */
+/**
+ * A path that stays inside the package: relative, never climbing out of it, and never an address or
+ * a drive (`https:`, `data:`, `C:`), which a URL would read as somewhere else.
+ */
 function relativePath(path) {
-    return path !== '' && !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..');
+    return path !== '' && !path.startsWith('/') && !path.includes('\\') && !/^[a-z][a-z0-9+.-]*:/i.test(path) && !path.split('/').includes('..');
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/menus.d.ts

@@ -87,12 +87,16 @@ export interface ContextMenuItem {
 /**
  * What a Command Menu row's `when` may read about the editor it was opened in.
  *
- * @beta
+ * @public
  */
 export interface CommandMenuContext {
     /** The caret is in a table. */
     inTable: boolean;
-    /** A table may be inserted at the caret. */
+    /**
+     * A table may be inserted at the caret.
+     *
+     * @beta
+     */
     tableInsertable: boolean;
     /** The document's body may be written: false in a locked Protected Document. */
     bodyWritable: boolean;
@@ -106,13 +110,15 @@ export interface CommandMenuContext {
      * 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.
+     *
+     * @beta
      */
     readonly conceptsAtCaret?: readonly string[];
 }
 /**
  * One row of the Command Menu, the menu `/` opens in the editor.
  *
- * @beta
+ * @public
  */
 export interface CommandMenuItem {
     /** Under the extension's id. */
@@ -136,24 +142,41 @@ export interface CommandMenuItem {
     when?: (context: CommandMenuContext) => boolean;
     /** The Command the row runs. */
     command: string;
-    /** What the Command is given. */
+    /**
+     * What the Command is given.
+     *
+     * @beta
+     */
     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`.
+ * A button in the Graph Sidebar's group of action buttons, after Search and today's date: a way in
+ * to what the extension shows for the whole graph, such as the Graph Map. Pressing it runs
+ * `command`.
  *
  * @beta
  */
 export interface GraphSidebarButton {
     /** Under the extension's id. */
     id: string;
-    /** The button's text. */
+    /** The button's text: short, because the Sidebar fits two buttons side by side. */
     title: string;
+    /**
+     * What pressing the button does, shown as its help text: "Open a map of every place and route
+     * in this graph". The Client adds the key chords bound to `command`, so it names none. Without
+     * one, the help text is the title.
+     */
+    description?: 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;
+    /**
+     * Whether the button shows here, asked each time the Sidebar draws, which it does afresh when
+     * the layout changes between desktop and phone. Absent means everywhere. A `when` that throws
+     * hides the button.
+     */
+    when?: () => boolean;
     /** The Command the button runs. */
     command: string;
     /** What the Command is given. */

package/dist/views.d.ts

@@ -5,7 +5,7 @@
 /**
  * Which View: its kind and what it is about. A View with no subject has an empty target.
  *
- * @beta
+ * @public
  */
 export interface ViewRef {
     /** The View kind, `<extension id>.<name>` for an extension's. */
@@ -18,7 +18,7 @@ export interface ViewRef {
  * 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
+ * @public
  */
 export interface ViewVisibility {
     /** True while the View can be seen. */
@@ -29,7 +29,7 @@ export interface ViewVisibility {
 /**
  * What a View is mounted with.
  *
- * @beta
+ * @public
  */
 export interface ViewMountProps {
     /** The View being mounted. */
@@ -45,7 +45,7 @@ export interface ViewMountProps {
 /**
  * A View the extension has drawn, as the Client drives it.
  *
- * @beta
+ * @public
  */
 export interface MountedView {
     /** The same View with new props: a rename re-keyed its target, or it moved to another Pane. */
@@ -56,7 +56,7 @@ export interface MountedView {
 /**
  * What an extension registers for a View kind its manifest declares.
  *
- * @beta
+ * @public
  */
 export interface ViewContribution {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsoftwareltd/etherpk-extension-api",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "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",