@appsoftwareltd/etherpk-extension-api 0.13.0 → 0.14.0

package/README.md

@@ -54,7 +54,8 @@ documentation says which, with `@public` for Stable and `@beta` for Proposed.
   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.
+Since 0.14.0 every part is Stable but `contributions` (see *Proposed parts* below). 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.
@@ -91,6 +92,18 @@ A row can have a `detail` line, an `icon`, `keywords` that find it, a `group` an
 `when(menu)` says whether it is offered at the caret, from what `menu` reports: `bodyWritable`,
 `inTable` and `protectedDocument`.
 
+`context.commands.execute(id, arg)` runs a Command, and `context.commands.has(id)` says whether there
+is one. An extension may run three kinds of Command, by `execute` or as the Command of a row or a
+button it adds:
+
+- Its own.
+- Another running extension's, by its id (`kanban.open`).
+- One of the Client's that `CLIENT_COMMANDS` names. Each keeps its id and argument in every release.
+
+The Client's other Commands may change, so `execute` rejects for them, and a row or button naming one
+is refused. `CLIENT_COMMANDS` holds `agents.settings` (open Settings at the Agents tab), and more are
+added as extensions need them.
+
 ### Notices
 
 `context.notify(text)` shows a short notice, as the Client's own notices do.
@@ -212,6 +225,13 @@ keep the buttons readable together:
 
 - `context.layout.openDocument(concept)` opens a document as following a wikilink does. A day's
   name, `YYYY-MM-DD`, opens its journal entry.
+- `context.layout.activeDocument()` names the document the person is working in, as its tab names
+  it, or null.
+- `context.layout.openWindow({ title, mount })` draws something over the whole window, with a heading
+  and a close button the Client draws. One is open at a time: opening another closes it, even
+  another extension's.
+- `context.layout.reveal(kind)` brings one of the extension's own Sidebar Views to the front (see
+  *Views* below). It does nothing for any other kind.
 - `context.theme.isDark()` says whether the dark theme shows, and the `theme:changed` Event reports a
   switch. EtherPK's `--gk-*` colour tokens reach into a shadow root and change with the theme by
   themselves.
@@ -272,6 +292,91 @@ The third argument to `registerFence` adds options:
 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.
 
+`context.editor.openPanel({ mount, at })` draws a panel of the extension's own in the document,
+beneath the caret's line, or beneath the document's last line with `at: 'end'`, without changing
+the text. It returns null where no panel can go, by the same rules as `insertBlock`. A panel closes
+when the extension stops.
+
+### Context Menu rows and Command Bar buttons
+
+`context.contextMenu.register({ id, label, command, when })` adds a row to the menu raised on a
+document's tab, a Favourite, a Recent, an All Documents row, any other tab, or a wikilink. The row's
+Command is given the target, and its `when(target)` says whether it applies. More kinds of target may
+be added, and when the Client stops raising a menu on one, the rows for it are no longer shown, so a
+`when` answers false for any kind it does not check. A row that deletes or removes something for good
+sets `danger: true`, and is drawn in the danger colour.
+
+`context.commandBar.register({ id, title, icon, command, pinned })` adds a button to the row of
+buttons across the bottom of a phone's screen: after the editing buttons that scroll, or with
+`pinned`, at the bar's right end, where it never scrolls away.
+
+### Key chords
+
+`context.keybindings.register({ key, command, label })` binds a chord such as `Alt+M` to one of the
+extension's own Commands. `Mod` is Cmd on Apple devices and Ctrl elsewhere. When the Client or another
+extension binds the chord already, the chord stays theirs: the call still succeeds, the binding is
+left out, and the browser's console says so. So a shortcut the Client adds in a later release never
+stops an extension from starting.
+
+### The graph's index and the names of concepts
+
+- `context.index.allConcepts()` lists the graph's concepts, `context.index.linkGraph()` gives every
+  concept and the links between them, and `context.index.onUpdated(listener)` hears each change to
+  the index.
+- `context.concepts.canonicalName(name)` gives the name a concept resolves to: an alias's page, a
+  page's own title, or the name itself. `context.concepts.key(name)` gives the key the Client tells
+  two names apart by. The way the key is made may change, so compare keys from `key`, and never make
+  one another way.
+
+### Reading documents
+
+`context.documents` reads the graph's documents for the person, for example for a language model they
+use: `list`, `read`, `links`, `search`, `backlinks` and `tasks`. Every answer leaves out each Protected
+Document, its name included, and a document holding an encrypted fence. Answers are bounded. A page
+of a listing holds at most 200 documents or tasks, and a page of a search 50 results, and a
+document's text is cut after 200,000 characters, saying so. `formatGuide()` describes how the
+graph's documents are written, in the words the Client gives agents. Its wording changes as the
+format does, so pass it on rather than read meaning into it.
+
+### Records for one graph
+
+`context.records` keeps the extension's records for the open graph on this device alone, such as a
+chat the person has not saved: `get`, `set`, `remove` and `keys`. They are never synced, and they go
+when the graph's data leaves the device. A record may hold a `Blob`, an `ArrayBuffer`, a `Date` or
+plain data, at most 4 MB of it, and a larger one is refused. A write the browser refuses, such as on
+a full disk, rejects.
+
+### Images as assets
+
+`context.assets.prepareImage(blob)` makes an image smaller, as a pasted image is.
+`context.assets.saveImage(blob, name)` keeps it as one of the graph's assets and answers the markdown
+that shows it, such as `![photo](assets/photo.3f9a1c2e.webp)`. The file's name ends in a hash of its
+bytes, so two images never take the same name, and the same image kept twice is one file. An asset
+is part of the graph: it syncs, and every member of a shared graph can see it.
+
+### Icons
+
+`context.icons.svg(name)` draws one of the extension's own icons or one of the Client's, as markup the
+Client trusts. The Client's icons, which every `icon` field may name too, are `alias`, `backlinks`, `bold`, `bullet`, `calendar`, `check`, `clock`, `close`, `code`, `copy`, `download`, `fit`, `flag`, `fold`, `frontmatter`, `globe`, `graph`, `grip`, `headless-client`, `highlight`, `image`, `import`, `indent`, `italic`, `list`, `lock`, `lock-open`, `more`, `move`, `move-down`, `move-up`, `new-page`, `open-external`, `outdent`, `page`, `pageless`, `pin`, `redo`, `rename`, `reset`, `search`, `slash`, `spell-check`, `table`, `table-add-column`, `table-add-row`, `table-format`, `table-remove-column`, `table-remove-row`, `task`, `template`, `text-lines`, `today`, `todays-journal`, `trash`, `undo`, `wikilink-close`, `wikilink-open`, `zoom-in`, `zoom-out`. An
+icon may be added in a later release, never taken away. An unknown name draws a small dot.
+
+### Settings sections
+
+The main module can export `settingsSections`, for settings that need more than the fields a
+manifest declares, such as a list of accounts with a button that connects one. Each section has an
+`id`, a `tab` and a `mount(element, context)` that draws it. The context holds the extension's
+settings, its records kept with the person, signing in, the theme and `notify`, and nothing from a
+graph.
+
+```ts
+export const settingsSections: SettingsSection[] = [{ id: 'hello.accounts', tab: 'extension', mount: drawAccounts }]
+```
+
+`tab: 'extension'` draws the section under the extension's own entry in Settings and Extensions,
+beside its declared settings, and `tab: 'agents'` in the Agents tab. The Client draws an extension's
+sections in a graph's settings while the extension runs there. An extension's code is loaded only
+once a graph opens, so its sections are not drawn on the Graphs page.
+
 ### Dialogs
 
 `context.dialogs.prompt(options)` asks for one line of text in a dialog the Client draws. Its
@@ -313,6 +418,10 @@ 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.
 
+A View kind can live in a Sidebar from the moment a graph opens, beside the Client's own Sidebar
+Views, with `"resident": { "side": "left" }` (or `"right"`, and `"desktopOnly": true` for the desktop
+alone). `context.layout.reveal(kind)` brings it to the front of its Sidebar.
+
 ## Styles
 
 The manifest's `styles` are the extension's stylesheets. By default, each widget and View the
@@ -329,6 +438,54 @@ 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.
 
+## Controls
+
+The Client draws its own buttons, fields, links and menus with a set of classes, and gives the same
+stylesheet to every shadow root an extension draws in, ahead of the extension's own stylesheets. An
+extension mounted in the page has it from the Client's own stylesheet. So an element with one of
+these classes looks like the Client's control, in the light and dark themes alike, and keeps
+looking like it as the Client changes. The classes are Stable, and the Client has them from
+EtherPK 0.14.0. The stylesheet is in this package as `controls.css`, for reference and for an
+extension's own tests.
+
+| Class | Use it on |
+| --- | --- |
+| `gk-button` | A `<button>` or `<a>`, as the Client's everyday button: a thin border, filled faintly on hover. |
+| `gk-button--primary` | With `gk-button`, the one main action of a form or dialog. |
+| `gk-button--danger` | With `gk-button`, an action that removes or ends something. |
+| `gk-button--quiet` | With `gk-button`, a button with no border, in a toolbar or beside other text. |
+| `gk-button--small` | With `gk-button`, a button on the line of a heading or a row, 24px tall. |
+| `gk-button--raised` | With `gk-button` or `gk-icon-button`, a button over content such as a map, a picture or code: a solid surface and a small shadow. |
+| `gk-icon-button` | A square button holding only an icon. Give it an `aria-label`. |
+| `gk-link` | A `<button>` or `<a>` that reads as a link: the accent colour, underlined. |
+| `gk-field` | An element holding a field's label, its control and any hint or error, stacked. |
+| `gk-label` | A field's `<label>`. |
+| `gk-hint` | Help text under a field. |
+| `gk-error` | An error under a field. Set `aria-invalid="true"` on the control too. |
+| `gk-input` | An `<input>` or `<textarea>`, the full width of its column. |
+| `gk-select` | A `<select>`. Where the browser can, it draws the option list in the menu's colours, with `<optgroup>` labels and a tick on the chosen option. Elsewhere it shows the browser's own list. |
+| `gk-checkbox` | An `<input type="checkbox">`. |
+| `gk-menu` | A list of actions, such as a menu a button opens. |
+| `gk-menu-item` | A row of a `gk-menu`. |
+| `gk-menu-item--danger` | With `gk-menu-item`, a row that removes something. |
+| `gk-menu-separator` | A rule between groups of rows in a `gk-menu`. |
+
+A disabled control (`disabled`, or `aria-disabled="true"`) recedes by colour. A toggle button with
+`aria-pressed="true"` is drawn as the primary button while it is on. On a touch screen buttons,
+fields and menu rows are at least 44px tall.
+
+```ts
+const save = document.createElement('button')
+save.className = 'gk-button gk-button--primary'
+save.textContent = 'Save'
+```
+
+The rules are in the `components` cascade layer, after the layer order Tailwind v4 uses
+(`properties`, `theme`, `base`, `components`, `utilities`). So Tailwind's utilities can adjust a control
+(`gk-button w-full`), and Tailwind's preflight doesn't undo one. A rule of yours outside any layer
+wins over every layered rule, so keep element resets such as `button { color: inherit }` in
+`@layer base`, or they will override the controls.
+
 ## Writing to the page
 
 The Client enforces
@@ -345,24 +502,19 @@ code runs under them.
 
 ## 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`) and key chords (`keybindings`).
-- Questions to the graph's index (`index`) and the rules for naming a concept (`concepts`).
-- The Client's icons (`icons`) and a View that lives in a Sidebar (`resident`).
-- Running another extension's Commands (`commands.execute`), and the document the person is working
-  in (`layout.activeDocument`).
-
-`contributions`, which reaches the Client's own registries, stays Proposed for good, since its
-shape is the Client's internals.
+The one Proposed part is `contributions`, which reaches the Client's own registries by kind. Only
+the extensions that come with EtherPK may use it, and it stays Proposed for good: its kinds and
+their values are the Client's internals, which change between releases, and through it one
+extension could take another's entries. Where an extension from another Publisher needs what a
+registry gives, the Client adds a checked part for it, as it did for fences and Journal Panels.
 
 ## 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.
+it. An extension loaded this way gets what a Directory release gets, the Stable part alone, unless it
+stands in for one that comes with EtherPK, so a Proposed part it calls fails while you test.
 
 ```bash
 ETHERPK_DEV_EXTENSIONS=/path/to/my-extension pnpm dev

package/controls.css

@@ -0,0 +1,391 @@
+/*
+ * EtherPK's controls: the buttons, fields, links and menus the Client draws, as classes an
+ * extension can use (ADR 0151). The Client supplies this stylesheet to every shadow root an
+ * extension draws in, ahead of the extension's own stylesheets, and its own pages import it, so a
+ * `gk-button` in an extension is the Client's own button, in the light and dark themes alike.
+ *
+ * Every colour is one of the Client's `--gk-*` tokens, and no text is under 14px. The class names
+ * are part of the Stable API: none is renamed or removed.
+ *
+ * The rules sit in the `components` layer, after declaring the layer order Tailwind v4 uses, so
+ * in a shadow root that also holds a Tailwind stylesheet the layers keep Tailwind's order:
+ * Tailwind's preflight cannot undo a control, and a utility class can still adjust one
+ * (`gk-button w-full`). A rule outside any layer wins over all of them, so an extension's own
+ * element resets belong in `@layer base`.
+ */
+@layer properties, theme, base, components, utilities;
+
+@layer components {
+    /* ── Buttons ─────────────────────────────────────────────────────────────── */
+
+    /* The everyday button: a thin border, in the control ink, filled faintly on hover. */
+    .gk-button {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.375rem;
+        padding: 0.375rem 0.75rem;
+        border: 1px solid var(--gk-control-border);
+        border-radius: 0.5rem;
+        background: transparent;
+        color: var(--gk-control-text);
+        font-family: inherit;
+        font-size: 0.875rem;
+        font-weight: 500;
+        line-height: 1.25rem;
+        text-align: center;
+        text-decoration: none;
+        white-space: nowrap;
+        cursor: pointer;
+    }
+    .gk-button:hover {
+        background: var(--gk-control-hover);
+    }
+    .gk-button:focus-visible,
+    .gk-icon-button:focus-visible,
+    .gk-link:focus-visible {
+        outline: 2px solid var(--gk-accent);
+        outline-offset: 2px;
+    }
+    /* A button that does nothing yet keeps its shape, and recedes by colour, never by opacity. */
+    .gk-button:disabled,
+    .gk-button[aria-disabled='true'] {
+        background: transparent;
+        color: var(--gk-text-subtle);
+        cursor: not-allowed;
+    }
+
+    /* The one main action of a form or dialog: filled in the darkest ink (the lightest, in dark). */
+    .gk-button--primary {
+        border-color: var(--gk-primary-bg);
+        background: var(--gk-primary-bg);
+        color: var(--gk-primary-text);
+    }
+    .gk-button--primary:hover {
+        border-color: var(--gk-primary-hover);
+        background: var(--gk-primary-hover);
+    }
+    .gk-button--primary:disabled,
+    .gk-button--primary[aria-disabled='true'] {
+        border-color: var(--gk-surface-2);
+        background: var(--gk-surface-2);
+        color: var(--gk-text-muted);
+    }
+
+    /* An action that removes or ends something. */
+    .gk-button--danger {
+        border-color: var(--gk-danger-border);
+        color: var(--gk-text-danger);
+    }
+    .gk-button--danger:hover {
+        background: var(--gk-danger-hover);
+    }
+
+    /* A button with no border, in a toolbar or beside other text. */
+    .gk-button--quiet {
+        padding: 0.25rem 0.5rem;
+        border-color: transparent;
+        border-radius: 0.375rem;
+        color: var(--gk-text-muted);
+    }
+    .gk-button--quiet:hover {
+        background: var(--gk-menu-hover);
+        color: var(--gk-text-strong);
+    }
+
+    /* A button on the line of a heading or a row: 24px tall. */
+    .gk-button--small {
+        padding: 0.0625rem 0.5rem;
+        border-radius: 0.375rem;
+    }
+
+    /* A button or icon button over content, such as a map, a picture or code: a solid surface and
+       a small shadow, so what is under it never shows through. The hover tint is laid over the
+       surface, since it is translucent. */
+    .gk-button--raised,
+    .gk-button--raised:disabled,
+    .gk-button--raised[aria-disabled='true'] {
+        border: 1px solid var(--gk-control-border);
+        background: var(--gk-surface-0);
+        box-shadow: var(--gk-control-shadow);
+    }
+    .gk-button--raised:hover {
+        background: linear-gradient(var(--gk-control-hover), var(--gk-control-hover)), var(--gk-surface-0);
+    }
+    .gk-icon-button.gk-button--raised:hover {
+        background: linear-gradient(var(--gk-menu-hover), var(--gk-menu-hover)), var(--gk-surface-0);
+    }
+
+    /* A toggle that is on (`aria-pressed="true"`) is drawn as the primary button, as the Client's
+       own toggles are. Raised or not: they come after `gk-button--raised`, and outweigh it. */
+    .gk-button[aria-pressed='true'],
+    .gk-icon-button[aria-pressed='true'] {
+        border-color: var(--gk-primary-bg);
+        background: var(--gk-primary-bg);
+        color: var(--gk-primary-text);
+    }
+    .gk-button[aria-pressed='true']:hover,
+    .gk-icon-button[aria-pressed='true']:hover {
+        border-color: var(--gk-primary-hover);
+        background: var(--gk-primary-hover);
+    }
+
+    /* A square button holding only an icon. Give it an accessible name (`aria-label`). */
+    .gk-icon-button {
+        display: inline-flex;
+        flex: none;
+        align-items: center;
+        justify-content: center;
+        width: 2rem;
+        height: 2rem;
+        padding: 0;
+        border: 0;
+        border-radius: 0.5rem;
+        background: transparent;
+        color: var(--gk-text-muted);
+        cursor: pointer;
+    }
+    .gk-icon-button:hover {
+        background: var(--gk-menu-hover);
+        color: var(--gk-text-strong);
+    }
+    .gk-icon-button:disabled,
+    .gk-icon-button[aria-disabled='true'] {
+        background: transparent;
+        color: var(--gk-text-subtle);
+        cursor: not-allowed;
+    }
+
+    /* A button or a link that reads as a link: the accent, underlined, so a link inside a sentence
+       is told from the text around it by more than its colour. */
+    .gk-link {
+        display: inline;
+        padding: 0;
+        border: 0;
+        border-radius: 0.125rem;
+        background: none;
+        color: var(--gk-accent);
+        font: inherit;
+        font-weight: 500;
+        text-decoration: underline;
+        text-underline-offset: 2px;
+        cursor: pointer;
+    }
+    .gk-link:hover {
+        color: var(--gk-accent-hover);
+    }
+
+    /* ── Fields ──────────────────────────────────────────────────────────────── */
+
+    /* A field's name, then its control, then any hint or error, stacked. */
+    .gk-field {
+        display: grid;
+        gap: 0.375rem;
+    }
+    .gk-label {
+        color: var(--gk-text-strong);
+        font-size: 0.875rem;
+        font-weight: 500;
+        line-height: 1.25rem;
+    }
+    .gk-hint {
+        color: var(--gk-text-muted);
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+    }
+    .gk-error {
+        color: var(--gk-text-danger);
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+    }
+
+    /* A text field or text area, the full width of its column. */
+    .gk-input,
+    .gk-select {
+        min-width: 0;
+        max-width: 100%;
+        padding: 0.5rem 0.75rem;
+        border: 1px solid var(--gk-control-border);
+        border-radius: 0.5rem;
+        color: var(--gk-field-text);
+        font-family: inherit;
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+    }
+    .gk-input {
+        display: block;
+        width: 100%;
+        background: var(--gk-field-bg);
+    }
+    textarea.gk-input {
+        resize: vertical;
+    }
+    .gk-input::placeholder {
+        color: var(--gk-text-muted);
+        opacity: 1;
+    }
+    /* A select's background is solid: the browser's own option list takes the select's colours. */
+    .gk-select {
+        background-color: var(--gk-menu-bg);
+    }
+    .gk-input:focus,
+    .gk-select:focus {
+        border-color: var(--gk-field-focus);
+        outline: none;
+        box-shadow: 0 0 0 1px var(--gk-field-focus);
+    }
+    .gk-input[aria-invalid='true'],
+    .gk-select[aria-invalid='true'] {
+        border-color: var(--gk-text-danger);
+    }
+    .gk-input:disabled,
+    .gk-select:disabled {
+        background: var(--gk-surface-1);
+        color: var(--gk-text-muted);
+        cursor: not-allowed;
+    }
+
+    .gk-checkbox {
+        flex: none;
+        width: 1rem;
+        height: 1rem;
+        margin: 0;
+        accent-color: var(--gk-accent);
+        cursor: pointer;
+    }
+
+    /* ── Menus ───────────────────────────────────────────────────────────────── */
+
+    /* A list of actions, as the Client's context menu draws one. Rows are `gk-menu-item`. */
+    .gk-menu {
+        min-width: 12rem;
+        padding: 0.25rem 0;
+        border: 1px solid var(--gk-menu-border);
+        border-radius: 0.5rem;
+        background: var(--gk-menu-bg);
+        color: var(--gk-control-text);
+        box-shadow: var(--gk-menu-shadow);
+    }
+    .gk-menu-item {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        width: 100%;
+        padding: 0.375rem 0.75rem;
+        border: 0;
+        background: transparent;
+        color: var(--gk-control-text);
+        font-family: inherit;
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+        text-align: left;
+        text-decoration: none;
+        cursor: pointer;
+    }
+    .gk-menu-item:hover,
+    .gk-menu-item:focus-visible {
+        background: var(--gk-menu-hover);
+        outline: none;
+    }
+    .gk-menu-item--danger {
+        color: var(--gk-text-danger);
+    }
+    .gk-menu-separator {
+        height: 1px;
+        margin: 0.25rem 0;
+        border: 0;
+        background: var(--gk-menu-border);
+    }
+
+    /* A touch screen gets rows, buttons and fields a finger can hit. */
+    @media (pointer: coarse) {
+        .gk-button,
+        .gk-menu-item,
+        .gk-input,
+        .gk-select {
+            min-height: 2.75rem;
+        }
+        .gk-button--small {
+            min-height: 2.25rem;
+        }
+        .gk-icon-button {
+            width: 2.75rem;
+            height: 2.75rem;
+        }
+    }
+}
+
+/*
+ * A select whose option list is drawn here (the customizable select, `appearance: base-select`),
+ * in the menu's colours: each `<optgroup>` label above its rows, and a tick on the row chosen.
+ * Keyboard use and where the list opens stay the browser's. A browser without it skips this whole
+ * block, since an unknown pseudo-element voids any rule it is in, and shows its own list under the
+ * same closed control.
+ */
+@supports (appearance: base-select) {
+    @layer components {
+        .gk-select,
+        .gk-select::picker(select) {
+            appearance: base-select;
+        }
+        .gk-select {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        /* A chevron drawn from two borders, in the muted ink. */
+        .gk-select::picker-icon {
+            content: '';
+            flex: none;
+            width: 0.4375rem;
+            height: 0.4375rem;
+            margin: 0 0.1875rem 0.1875rem auto;
+            border-right: 1.5px solid var(--gk-text-muted);
+            border-bottom: 1.5px solid var(--gk-text-muted);
+            transform: rotate(45deg);
+        }
+        .gk-select::picker(select) {
+            max-block-size: min(20rem, 60vh);
+            overflow-y: auto;
+            margin-block: 0.25rem;
+            padding: 0.25rem 0;
+            border: 1px solid var(--gk-menu-border);
+            border-radius: 0.5rem;
+            background: var(--gk-menu-bg);
+            color: var(--gk-control-text);
+            box-shadow: var(--gk-menu-shadow);
+        }
+        .gk-select optgroup {
+            padding-block-start: 0.25rem;
+            color: var(--gk-text-muted);
+            font-weight: 600;
+        }
+        .gk-select optgroup + optgroup {
+            margin-block-start: 0.25rem;
+            border-block-start: 1px solid var(--gk-menu-border);
+        }
+        .gk-select option {
+            gap: 0.5rem;
+            padding: 0.375rem 0.75rem;
+            color: var(--gk-control-text);
+            font-weight: 400;
+            line-height: 1.25rem;
+            cursor: pointer;
+        }
+        .gk-select option:hover,
+        .gk-select option:focus-visible {
+            background: var(--gk-menu-hover);
+            outline: none;
+        }
+        .gk-select option:checked {
+            font-weight: 600;
+        }
+        /* The tick, at the end of the row chosen. */
+        .gk-select option::checkmark {
+            order: 1;
+            margin-inline-start: auto;
+            color: var(--gk-accent);
+            line-height: 1;
+        }
+    }
+}

package/dist/assets.d.ts

@@ -5,7 +5,7 @@
 /**
  * The open graph's assets, as far as an extension may add to them.
  *
- * @beta
+ * @public
  */
 export interface ExtensionAssets {
     /**
@@ -15,9 +15,12 @@ export interface ExtensionAssets {
      */
     prepareImage(image: Blob): Promise<Blob>;
     /**
-     * Keep an image as one of the graph's assets, and answer the markdown that shows it in a
-     * document, such as `![photo](assets/photo.webp)`. Null where the graph keeps no assets here,
-     * or the image was refused.
+     * Keep an image as one of the graph's assets, made smaller first as {@link ExtensionAssets.prepareImage}
+     * does, and answer the markdown that shows it in a document, such as
+     * `![photo](assets/photo.3f9a1c2e.webp)`. The file is named from `name` and a short hash of its
+     * bytes, so two images never take the same name, and the same image kept twice is one file.
+     * An asset is part of the graph: it syncs, and every member of a shared graph can see it. Null
+     * where the graph keeps no assets here, or the image was refused.
      */
     saveImage(image: Blob, name: string): Promise<string | null>;
 }

package/dist/client-commands.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Client's own Commands that any extension may run (ADR 0120, amended 2026-10-17): through
+ * `commands.execute`, or as the Command of a menu row or a button it adds. Each one keeps its id
+ * and the argument it takes in every release, as the rest of the Stable API does. An extension may
+ * also run its own Commands and those of the other extensions running, by their ids.
+ *
+ * - `agents.settings`: open Settings and Extensions at the Agents tab. It takes no argument.
+ *
+ * @public
+ */
+export declare const CLIENT_COMMANDS: readonly string[];

package/dist/client-commands.js

@@ -0,0 +1,11 @@
+/**
+ * The Client's own Commands that any extension may run (ADR 0120, amended 2026-10-17): through
+ * `commands.execute`, or as the Command of a menu row or a button it adds. Each one keeps its id
+ * and the argument it takes in every release, as the rest of the Stable API does. An extension may
+ * also run its own Commands and those of the other extensions running, by their ids.
+ *
+ * - `agents.settings`: open Settings and Extensions at the Agents tab. It takes no argument.
+ *
+ * @public
+ */
+export const CLIENT_COMMANDS = ['agents.settings'];