@appsoftwareltd/etherpk-extension-api 0.12.0 → 0.13.0

package/dist/assets.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Images an extension hands to the open graph (ADR 0147): made smaller the way a pasted image is,
+ * and kept as one of the graph's assets, so a document can show it.
+ */
+/**
+ * The open graph's assets, as far as an extension may add to them.
+ *
+ * @beta
+ */
+export interface ExtensionAssets {
+    /**
+     * An image made ready to send or keep, as a pasted image is: a large photo or screenshot is
+     * scaled down and re-encoded, and an image that is small enough comes back as it was. Rejects
+     * when the bytes are not an image the browser can read.
+     */
+    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.
+     */
+    saveImage(image: Blob, name: string): Promise<string | null>;
+}

package/dist/assets.js

@@ -0,0 +1,5 @@
+/**
+ * Images an extension hands to the open graph (ADR 0147): made smaller the way a pasted image is,
+ * and kept as one of the graph's assets, so a document can show it.
+ */
+export {};

package/dist/context.d.ts

@@ -7,14 +7,18 @@
  * 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 { ExtensionAssets } from './assets';
 import type { ExtensionAuth } from './auth';
 import type { ExtensionDialogs } from './dialogs';
+import type { ExtensionDocuments } from './documents';
 import type { ExtensionEditor } from './editor';
 import type { ExtensionEmbeds } from './embeds';
 import type { ExtensionEvents } from './events';
 import type { ExtensionIndex } from './graph-index';
 import type { ExtensionJournalPanels } from './journal';
-import type { CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
+import type { CommandBarButton, CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
+import type { ExtensionGraphRecords } from './records';
+import type { SettingsSection } from './settings-sections';
 import type { ViewContribution, ViewRef } from './views';
 /**
  * A Command's handler. What it returns, or resolves to, is what `execute` resolves to.
@@ -73,6 +77,16 @@ export interface ExtensionCommandMenu {
     /** Add a row, its id under the extension's id. */
     register(item: CommandMenuItem): () => void;
 }
+/**
+ * Adding buttons to the Command Bar, the row of buttons across the bottom of a phone's screen:
+ * after the editing buttons that scroll, or in the pinned group at its right end.
+ *
+ * @beta
+ */
+export interface ExtensionCommandBar {
+    /** Add a button, its id under the extension's id. */
+    register(button: CommandBarButton): () => void;
+}
 /**
  * Adding buttons to the Graph Sidebar's group of action buttons, after Search and today's date.
  *
@@ -146,6 +160,26 @@ export interface ExtensionLayout {
     activeDocument(): string | null;
     /** True while the desktop presenter is showing, 1024 pixels wide and more. */
     isDesktop(): boolean;
+    /**
+     * Draw something over the whole EtherPK window, with a heading and a close button the Client
+     * draws, as a fence's widget opens over the window. One at a time: opening another closes the
+     * one before. The close button, Escape and `close` all close it, and `onClose` is told once.
+     *
+     * @beta
+     */
+    openWindow(options: {
+        /** The heading the Client draws beside the close button. */
+        title: string;
+        /** Draw into `host`, which fills the window under the heading. */
+        mount(host: HTMLElement, window: {
+            close(): void;
+        }): {
+            destroy(): void;
+        };
+        onClose?(): void;
+    }): {
+        close(): void;
+    };
 }
 /**
  * The rules for naming a concept, which every index answer follows.
@@ -203,15 +237,15 @@ export interface ExtensionSettings {
 }
 /**
  * The extension's own records, kept with the person (ADR 0140): on this device, and where the
- * person's account syncs a graph, in that account's vault too, encrypted on the device so only the
- * person's own devices can read them. So a record follows the person to their other devices, as
+ * person's account syncs a graph, in that account's Settings Vault too, encrypted on the device so
+ * only the person's own devices can read them. So a record follows the person to their other devices, as
  * Extension Settings do, such as what signing in to another service gave the extension. The person
  * never sees these records, and uninstalling the extension clears them on every device.
  *
  * Each record is kept as JSON, at most 64 KB of it. Between two devices the later change to a
  * record wins, record by record. A record is readable on the device by any code in the page, as
- * localStorage is, and by a Headless Client given an agent token for the same account, which opens
- * the account's vault.
+ * localStorage is. A Headless Client signed in to the same account cannot read it: the Sync Server
+ * never gives an agent token the Settings Vault (ADR 0148).
  *
  * @public
  */
@@ -335,6 +369,12 @@ export interface ExtensionContext {
     readonly commandMenu: ExtensionCommandMenu;
     /** Adding buttons to the Graph Sidebar. */
     readonly graphSidebar: ExtensionGraphSidebar;
+    /**
+     * Adding buttons to the phone's Command Bar.
+     *
+     * @beta
+     */
+    readonly commandBar: ExtensionCommandBar;
     /** Adding panels beneath each Journal Entry. */
     readonly journalPanels: ExtensionJournalPanels;
     /**
@@ -357,6 +397,24 @@ export interface ExtensionContext {
      * @beta
      */
     readonly index: ExtensionIndex;
+    /**
+     * Reading the open graph's documents, with every Protected Document left out, name and all.
+     *
+     * @beta
+     */
+    readonly documents: ExtensionDocuments;
+    /**
+     * The extension's records for the open graph, kept on this device only.
+     *
+     * @beta
+     */
+    readonly records: ExtensionGraphRecords;
+    /**
+     * Images kept as the open graph's assets.
+     *
+     * @beta
+     */
+    readonly assets: ExtensionAssets;
     /** Opening Views and documents. */
     readonly layout: ExtensionLayout;
     /**
@@ -402,4 +460,11 @@ export interface ExtensionModule {
      * called after that, for anything else the extension holds.
      */
     activate(context: ExtensionContext): void | (() => void);
+    /**
+     * Sections the extension adds to the Client's settings tabs, which the Client mounts while the
+     * extension is switched on, whether or not a graph is open.
+     *
+     * @beta
+     */
+    settingsSections?: readonly SettingsSection[];
 }

package/dist/documents.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Reading the open graph's documents, as a language model may read them for a person (ADR 0147).
+ *
+ * Every answer leaves out a [[Protected Document]] entirely: not its content, and not its name
+ * either, even while the person holds the Protection Key. That is stricter than the index's
+ * answers (`context.index`), which list a Protected Document by name, because what an extension
+ * reads here may be sent to a model provider. A document whose text holds an encrypted fence
+ * anywhere counts as protected here too.
+ *
+ * Every answer is bounded: a list is paged, and a document's text is cut at a cap and says so.
+ */
+/**
+ * A document as a listing names it.
+ *
+ * @beta
+ */
+export interface DocumentSummary {
+    /** The document's name: a page's title, or a journal entry's day, `YYYY-MM-DD`. */
+    name: string;
+    /** A page or a journal entry. */
+    kind: 'page' | 'journal';
+    /** The page's other names. */
+    aliases: string[];
+}
+/**
+ * A document's text, as {@link ExtensionDocuments.read} answers.
+ *
+ * @beta
+ */
+export interface DocumentText extends DocumentSummary {
+    /** The body: the text after the frontmatter block, cut at the cap. */
+    text: string;
+    /** True when the text was cut at the cap. */
+    truncated: boolean;
+}
+/**
+ * One document a search matched, with the lines that matched.
+ *
+ * @beta
+ */
+export interface DocumentSearchResult extends Omit<DocumentSummary, 'aliases'> {
+    /** How many lines matched. */
+    matches: number;
+    /** The matching lines, best first. */
+    hits: {
+        /** The line's number in the document's text, from 0. */
+        line: number;
+        /** The labels of the blocks the line sits under, outermost first. */
+        breadcrumb: string[];
+        /** The line's text around the match. */
+        snippet: string;
+    }[];
+}
+/**
+ * One document whose text links to the concept asked about, with each place it does.
+ *
+ * @beta
+ */
+export interface DocumentBacklink extends Omit<DocumentSummary, 'aliases'> {
+    references: {
+        /** The line's number in the source's text, from 0. */
+        line: number;
+        /** The labels of the blocks the reference sits under, outermost first. */
+        breadcrumb: string[];
+        /** The block holding the link with its children, or the prose around it. */
+        text: string;
+    }[];
+}
+/**
+ * One task, as the Tasks View lists it.
+ *
+ * @beta
+ */
+export interface DocumentTask extends Omit<DocumentSummary, 'aliases'> {
+    /** The task's line in the document's text, from 0. */
+    line: number;
+    /** The task's words, without the checkbox. */
+    text: string;
+    status: 'open' | 'doing' | 'waiting' | 'done' | 'cancelled';
+    /** 1 is the highest; null when the task has none. */
+    priority: 1 | 2 | 3 | null;
+    /** `YYYY-MM-DD`, or null. */
+    due: string | null;
+    /** `YYYY-MM-DD`, or null. */
+    scheduled: string | null;
+    /** The labels of the blocks the task sits under, outermost first. */
+    breadcrumb: string[];
+}
+/**
+ * Reading the open graph's documents.
+ *
+ * @beta
+ */
+export interface ExtensionDocuments {
+    /** Pages and journal entries, journals newest first and then pages by name, a page at a time. */
+    list(options?: {
+        kind?: 'page' | 'journal';
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        documents: DocumentSummary[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * A document's text by its name or an alias, or null when there is no such document or it is
+     * protected. The text is the document as it is now, edits not yet saved included.
+     */
+    read(name: string): Promise<DocumentText | null>;
+    /**
+     * The names of the documents a document's wikilinks name directly, in the order they first
+     * appear, each once. Names with no document, and protected documents, are left out. Null when
+     * the document cannot be read.
+     */
+    links(name: string): Promise<string[] | null>;
+    /** The documents whose text matches the words, best first, a page at a time. */
+    search(query: string, options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        results: DocumentSearchResult[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /** The documents that link to a concept, or null when the concept is a protected document. */
+    backlinks(name: string): Promise<DocumentBacklink[] | null>;
+    /**
+     * How the graph's documents are written, as the Client describes it to agents: names and
+     * wikilinks, the outline, tasks and the rest of the syntax, in markdown. The same words the
+     * `AGENTS.md` of a graph folder carries, less what is about files on a disk, so a model reading
+     * the graph's text understands it and names documents as `[[Name]]`.
+     */
+    formatGuide(): string;
+    /** Tasks, open ones unless asked otherwise, of one concept or of the whole graph, a page at a time. */
+    tasks(options?: {
+        /** Only the tasks that answer to this concept. */
+        concept?: string;
+        statuses?: DocumentTask['status'][];
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        tasks: DocumentTask[];
+        total: number;
+        hasMore: boolean;
+    }>;
+}

package/dist/documents.js

@@ -0,0 +1,12 @@
+/**
+ * Reading the open graph's documents, as a language model may read them for a person (ADR 0147).
+ *
+ * Every answer leaves out a [[Protected Document]] entirely: not its content, and not its name
+ * either, even while the person holds the Protection Key. That is stricter than the index's
+ * answers (`context.index`), which list a Protected Document by name, because what an extension
+ * reads here may be sent to a model provider. A document whose text holds an encrypted fence
+ * anywhere counts as protected here too.
+ *
+ * Every answer is bounded: a list is paged, and a document's text is cut at a cap and says so.
+ */
+export {};

package/dist/editor.d.ts

@@ -236,6 +236,72 @@ export interface FenceOptions {
      */
     keepsHistory?: boolean;
 }
+/**
+ * A panel an extension draws in a document, beneath one of its lines, which is not part of the
+ * document's text: nothing of it is saved, synced or seen on another device (ADR 0147).
+ *
+ * The panel follows its line as the document changes, here or on another device, and moves with
+ * the editor when the editor is rebuilt (a Draft becoming a document, say). It closes when the
+ * person closes it, or when the document's editor closes for good: the panel lasts for the visit.
+ *
+ * @beta
+ */
+export interface InlinePanel {
+    /** The document the panel is in, by its concept. */
+    readonly document: string | null;
+    /** False once the panel has closed. */
+    readonly isOpen: boolean;
+    /**
+     * Put a block at the panel's line, by the rule {@link ExtensionEditor.insertBlock} follows at the
+     * caret: an empty line is replaced, an empty bullet takes an outline's place at its own
+     * indentation (or any other block as its content), and after any other line the block goes on new
+     * lines beneath at the line's content column. The panel then sits beneath the block, and the next
+     * block goes after it at the indentation of its first line. One undoable change. False where
+     * nothing was put in: the panel is closed, its editor has closed, or its line is now in the
+     * frontmatter, a fenced block or a table.
+     */
+    insertBlock(text: string): boolean;
+    /** Bring the panel into view. */
+    focus(): void;
+    /**
+     * Give the panel a new height in CSS pixels, which its content scrolls inside: the lines below
+     * it move once. Grow it when there is more to show, rather than on every change.
+     */
+    resize(height: number): void;
+    /**
+     * The outline around the panel's line, as the document writes it: the line's ancestors, each its
+     * own lines without its other children, and its siblings with their branches, the line's own
+     * branch among them while the line has text. A block the panel put in is left out. Null when
+     * the line is not a bullet, or the panel is closed or under the document's last line.
+     */
+    outline(): string | null;
+    /** Close the panel. Its `onClose` is told. */
+    close(): void;
+}
+/**
+ * What an inline panel is drawn with.
+ *
+ * @beta
+ */
+export interface InlinePanelOptions {
+    /**
+     * The panel's height in CSS pixels, which its content scrolls inside, so the lines below never
+     * move as its content grows. {@link InlinePanel.resize} changes it.
+     */
+    height?: number;
+    /**
+     * Draw the panel into `host`, which the Client owns and places. Called once, when the panel is
+     * first drawn: the host keeps its content while the panel is scrolled out of view and when the
+     * editor is rebuilt, and `destroy` is called when the panel closes. Events inside the host are
+     * the panel's own: the editor neither types nor moves its caret for them, but Mod+Z and Mod+Y
+     * outside a text field undo and redo in the document.
+     */
+    mount(host: HTMLElement, panel: InlinePanel): {
+        destroy(): void;
+    };
+    /** Told once, when the panel closes for any reason. */
+    onClose?(): void;
+}
 /**
  * The document editor, as far as an extension may reach it.
  *
@@ -263,4 +329,18 @@ export interface ExtensionEditor {
     insertBlock(text: string, options?: {
         focus?: boolean;
     }): boolean;
+    /**
+     * Draw a panel beneath the caret's line in the editor the person is working in, from where the
+     * line's text starts, or beside the dot of an empty bullet, as a code block opened there is. With
+     * `at` `end`, it is drawn beneath the document's last line, at the editor's left edge, a line's
+     * height clear of it. With `caret-or-end`, at the caret while the person is typing in the
+     * document (the editor has the keyboard, as a Command Bar button leaves it), else at the end: for
+     * a button pressed from outside the text. Null where no panel can go: no editor, a Protected
+     * Document, or a caret in the frontmatter, a fenced block or a table.
+     *
+     * @beta
+     */
+    openPanel(options: InlinePanelOptions & {
+        at?: 'caret' | 'end' | 'caret-or-end';
+    }): InlinePanel | null;
 }

package/dist/index.d.ts

@@ -14,15 +14,19 @@
  *
  * @packageDocumentation
  */
-export type { CommandHandler, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
+export type { CommandHandler, ExtensionCommandBar, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
+export type { ExtensionAssets } from './assets';
 export type { AuthorizeOptions, ExtensionAuth } from './auth';
 export type { ExtensionDialogs, PromptOptions } from './dialogs';
-export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } from './editor';
+export type { DocumentBacklink, DocumentSearchResult, DocumentSummary, DocumentTask, DocumentText, ExtensionDocuments } from './documents';
+export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, InlinePanel, InlinePanelOptions, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } 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 { ExtensionJournalPanels, JournalPanel, JournalPanelProps, MountedJournalPanel } from './journal';
 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 { CommandBarButton, CommandMenuContext, CommandMenuItem, ContextMenuItem, DocumentMenuTarget, ExtensionMenuTarget, GraphSidebarButton, MenuTarget, TabMenuTarget, WikilinkMenuTarget, } from './menus';
+export type { ExtensionGraphRecords } from './records';
+export type { MountedSettingsSection, SettingsSection, SettingsSectionContext, SettingsSectionTab } from './settings-sections';
 export type { MountedView, ViewContribution, ViewMountProps, ViewRef, ViewVisibility } from './views';

package/dist/menus.d.ts

@@ -149,6 +149,30 @@ export interface CommandMenuItem {
      */
     args?: unknown;
 }
+/**
+ * A button on the Command Bar, the row of buttons across the bottom of a phone's screen. Pressing
+ * it runs `command` and leaves the keyboard where it was, so a Command can tell whether the caret
+ * is in the document.
+ *
+ * @beta
+ */
+export interface CommandBarButton {
+    /** Under the extension's id. */
+    id: string;
+    /** The button's name, said to a screen reader and shown as its tooltip: the bar shows icons only. */
+    title: string;
+    /** Its icon: the extension's own or one of the Client's. */
+    icon: string;
+    /**
+     * In the bar's pinned group at its right end, which never scrolls away, rather than after the
+     * editing buttons that scroll. For an action a person reaches for often.
+     */
+    pinned?: boolean;
+    /** The Command the button runs. */
+    command: string;
+    /** What the Command is given. */
+    args?: unknown;
+}
 /**
  * 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

package/dist/records.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Records an extension keeps on this device for the open graph alone (ADR 0147): never synced,
+ * never seen by another device or another member, and deleted when the graph's data is removed
+ * from the device. For what is the person's work on this device, such as a chat they have not
+ * saved, rather than a preference that should follow them (`personStorage`).
+ */
+/**
+ * The extension's records for the open graph on this device.
+ *
+ * Each record is stored as the browser's structured clone of the value, so it may hold a `Blob`,
+ * an `ArrayBuffer`, a `Date` or plain data, but no function. Records live in the browser's
+ * IndexedDB, which a private window or a full disk may refuse: a refused write rejects, and a
+ * refused read answers as if there were nothing.
+ *
+ * @beta
+ */
+export interface ExtensionGraphRecords {
+    /** The record under `key`, or undefined when there is none. */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Keep a record under `key`: letters, digits, `.`, `_`, `:` and `-`, at most 200 of them.
+     * Rejects when the key is not one of those or the browser refuses the write.
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /** Remove the record under `key`. */
+    remove(key: string): Promise<void>;
+    /** The keys of every record the extension keeps for the open graph, sorted. */
+    keys(): Promise<string[]>;
+}

package/dist/records.js

@@ -0,0 +1,7 @@
+/**
+ * Records an extension keeps on this device for the open graph alone (ADR 0147): never synced,
+ * never seen by another device or another member, and deleted when the graph's data is removed
+ * from the device. For what is the person's work on this device, such as a chat they have not
+ * saved, rather than a preference that should follow them (`personStorage`).
+ */
+export {};

package/dist/settings-sections.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An extension's own section in one of the Client's settings tabs (ADR 0134, amended 2026-10-15),
+ * which the Client mounts with or without a graph open: on the Graphs page, and in a graph's
+ * settings. For settings that belong to the person and need more than the fields a manifest can
+ * declare, such as a list of accounts with a button that connects one.
+ */
+import type { ExtensionAuth } from './auth';
+import type { ExtensionPersonStorage, ExtensionSettings, ExtensionTheme } from './context';
+/**
+ * The tabs an extension's settings section can go in.
+ *
+ * @beta
+ */
+export type SettingsSectionTab = 'agents';
+/**
+ * What a settings section is mounted with: what belongs to the person, and nothing from a graph,
+ * since there may be no graph open.
+ *
+ * @beta
+ */
+export interface SettingsSectionContext {
+    /** The extension's id, from its manifest. */
+    readonly extensionId: string;
+    /** The person's answers to the settings the manifest declares. */
+    readonly settings: ExtensionSettings;
+    /** The extension's records kept with the person. */
+    readonly personStorage: ExtensionPersonStorage;
+    /** Signing in to another service. */
+    readonly auth: ExtensionAuth;
+    /** The Client's light or dark theme. */
+    readonly theme: ExtensionTheme;
+    /** Say something in passing, as the Client's own notices do. */
+    notify(text: string): void;
+}
+/**
+ * A section the section's host element shows, as the Client drives it.
+ *
+ * @beta
+ */
+export interface MountedSettingsSection {
+    /** The tab closed, or the extension was switched off. */
+    destroy(): void;
+}
+/**
+ * One settings section an extension adds.
+ *
+ * @beta
+ */
+export interface SettingsSection {
+    /** Unique within the extension. */
+    id: string;
+    /** The tab it goes in. */
+    tab: SettingsSectionTab;
+    /** Draw the section into `element`, which is empty and is the extension's alone. */
+    mount(element: HTMLElement, context: SettingsSectionContext): MountedSettingsSection;
+}

package/dist/settings-sections.js

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

package/package.json

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